---
openprd: "0.2"
id: "0013"
title: "Add persistent SSH workspaces for humans and agents"
status: "Draft"
authors:
  - "anthony@profullstack.com"
created: "2026-09-03"
updated: "2026-09-03"
repo: "https://github.com/moshcoder/moshcode"
discussion: ""
implementation: "src/ssh.mjs, src/cli-schema.mjs, src/commands.mjs, src/tui.mjs, bin/moshcode.mjs, test/ssh.test.mjs, test/ssh-sshd.test.mjs"
tags:
  - ssh
  - remote
  - runtime
  - agents
  - chovy
  - workspaces
supersedes: ""
superseded-by: ""
---

# Add persistent SSH workspaces for humans and agents

## Problem

MoshCode already has a strong persistent-local-runtime model:

- `herd` keeps local shells and agents alive in tmux or the PTY fallback.
- `herd prompt`, `read`, `wait`, and `--json` make those sessions controllable by another agent.
- `shell()` and the pit's shell execution path deliberately use the user's real shell.
- the project remains zero-dependency ESM and delegates terminal/process behavior to native tools instead of embedding a terminal implementation.

What it does **not** have is a first-class remote-shell/workspace abstraction.

Today a caller such as Chovy can invoke the system `ssh` command repeatedly, but if every file read, file edit, `git status`, test run, or inspection starts a brand-new SSH process with a brand-new transport, it repeatedly pays for:

- TCP setup;
- SSH negotiation;
- host-key negotiation;
- authentication;
- key-agent interaction;
- session setup;
- remote-shell startup.

That is unnecessary. SSH is explicitly capable of carrying many independent channels over one authenticated transport.

The immediate Chovy use case is concrete: an AI coding run may inspect and modify dozens or hundreds of files on one remote workspace. Chovy should not create a completely new authenticated SSH transport for every operation.

A naive `/ssh` command that merely does this:

```sh
ssh user@host
```

would not solve the problem. The user can already type that as a normal shell command.

The useful feature is instead a **persistent SSH workspace manager**:

```text
one authenticated OpenSSH master connection
              │
              ├── exec channel → git status
              ├── exec channel → cat package.json
              ├── exec channel → apply a multi-file patch
              ├── exec channel → pnpm test
              ├── scp/sftp-style file transfer
              └── optional remote tmux shell
```

Each operation remains independently observable and machine-readable while reusing the same authenticated connection.

This is especially useful for AI systems. Models generally work better with discrete tool calls returning bounded stdout/stderr and exit status than by pretending to be a human typing blindly into one long terminal stream. A persistent transport should therefore **not** imply that all AI activity must share one stateful shell.

MoshCode needs both:

1. multiplexed stateless command channels over one SSH connection; and
2. an optional persistent interactive remote shell for workflows that actually require shell state, a REPL, a TUI, a dev server, or a long-running process.

## Source Review / Why This Fits MoshCode

The current codebase already contains most of the concepts needed for this feature.

### Existing shell abstraction

`src/shell.mjs` centralizes how the pit runs shell commands, including interactive rc-file behavior and terminal/job-control details. The proposed SSH implementation should follow the same principle: one authoritative module should own SSH invocation construction and lifecycle behavior.

### Existing persistent runtime

`src/herd.mjs` already:

- detects tmux and PTY capabilities;
- creates named persistent sessions;
- captures output;
- sends literal input;
- attaches a terminal;
- keeps session metadata;
- exposes machine-readable controls.

The SSH feature should reuse the **design philosophy**, not tunnel every SSH command through herd.

### Existing machine interface

The herd intentionally has no separate hidden API: CLI verbs use `--json`, and scripts/agents consume the same concepts. `/ssh` should follow that rule.

### Existing zero-dependency posture

MoshCode is deliberately zero-dependency ESM. Do **not** add `ssh2`, `node-pty`, libssh bindings, or a custom SSH protocol implementation.

Use the installed OpenSSH client and its native connection-multiplexing support.

## Goals

- Allow many remote commands to reuse one authenticated SSH transport.
- Make remote execution dramatically cheaper than reconnecting for every command.
- Give humans a natural `/ssh` pit command and `moshcode ssh` CLI.
- Give AI systems a structured, machine-readable `ssh exec` interface.
- Preserve discrete stdout, stderr, exit status, timeout, and cancellation behavior for each operation.
- Support stdin so an agent can apply a multi-file patch in one remote operation.
- Support an optional truly persistent remote shell when shell state matters.
- Reuse the user's existing OpenSSH configuration, ssh-agent, known_hosts, ProxyJump, identities, and hardware-backed keys.
- Keep credentials and private keys out of MoshCode storage.
- Keep the project zero-dependency ESM.
- Fail soft when OpenSSH or an optional remote capability such as tmux is unavailable.
- Make the feature directly useful to Chovy without making Chovy depend on MoshCode internals.

## Non-Goals

- Implement the SSH protocol in JavaScript.
- Replace OpenSSH.
- Store SSH passwords.
- Store private keys.
- Disable host-key checking.
- Invent a second `~/.ssh/config`.
- Force every remote command through one interactive PTY.
- Require MoshCode to be installed on the remote host.
- Require tmux for normal `ssh exec`.
- Build a remote filesystem/FUSE mount.
- Build an IDE file browser.
- Replace rsync, scp, or sftp.
- Automatically deploy MoshCode to remote machines.
- Make SSH itself an A2A protocol.
- Treat a remote shell as an AI agent when it is not one.

## Users

### Chovy / agentic application backend

Needs to perform many file and shell operations against one remote app workspace during a coding run without opening a new authenticated SSH transport every time.

### MoshCode operator

Wants to type:

```text
/ssh dev
```

and land on a configured remote box, or:

```text
/ssh exec dev -- git status
```

without thinking about connection multiplexing.

### Coding agent

Needs deterministic tools such as:

```sh
moshcode ssh exec dev --json -- git diff --stat
```

rather than scraping an interactive terminal.

### Automation / moshscript

Needs to open a connection, execute several operations, branch on exit codes, and close or leave the connection available for later reuse.

## Product Principle

**Persistent connection, discrete operations.**

The transport stays alive. Commands do not have to share shell state.

This is the default:

```text
AI
 │
 ├─ exec("pwd") ───────────────┐
 ├─ exec("git status") ────────┤
 ├─ exec("git apply -", stdin) ┤
 └─ exec("pnpm test") ─────────┤
                               ▼
                    one OpenSSH master
                               │
                               ▼
                         remote server
```

Use a stateful remote shell only when the task truly needs one:

```text
AI / human
    │
    ▼
remote tmux shell
    │
    ├── cd persists
    ├── exports persist
    ├── dev server persists
    ├── REPL persists
    └── TUI persists
```

## Requirements

### Phase 1 — Named SSH targets

- **R1 [P0]** Add a core `moshcode ssh` command and `/ssh` pit command.

- **R2 [P0]** Support named targets:

  ```sh
  moshcode ssh add dev deploy@example.com
  moshcode ssh add dev deploy@example.com --port 2222
  moshcode ssh add dev deploy@example.com --cwd /srv/app
  moshcode ssh add dev my-ssh-config-host
  ```

- **R3 [P0]** Store only non-secret metadata under:

  ```text
  ~/.moshcode/ssh/targets.json
  ```

  Suggested shape:

  ```json
  {
    "dev": {
      "target": "deploy@example.com",
      "port": 22,
      "cwd": "/srv/app"
    }
  }
  ```

- **R4 [P0]** `targets.json` MUST NOT contain:
  - passwords;
  - private-key contents;
  - passphrases;
  - ssh-agent material;
  - temporary auth tokens.

- **R5 [P0]** Allow normal OpenSSH host aliases as targets so existing `~/.ssh/config` remains authoritative:

  ```sshconfig
  Host devbox
      HostName 203.0.113.10
      User deploy
      IdentityFile ~/.ssh/id_ed25519
      ProxyJump bastion
  ```

  then:

  ```sh
  moshcode ssh add dev devbox
  ```

- **R6 [P0]** Commands:

  ```sh
  moshcode ssh
  moshcode ssh list
  moshcode ssh add <name> <target>
  moshcode ssh remove <name>
  moshcode ssh show <name>
  ```

  Bare `moshcode ssh` lists configured targets and connection state.

- **R7 [P0]** Every non-interactive verb supports `--json`.

### Phase 2 — Persistent OpenSSH transport

- **R8 [P0]** Use native OpenSSH connection multiplexing.

  MoshCode MUST establish a control master rather than keeping a Node child process with a hand-rolled protocol.

  Conceptually:

  ```sh
  ssh \
    -o ControlMaster=yes \
    -o ControlPersist=10m \
    -o ControlPath=<moshcode-control-socket> \
    -N -f \
    devbox
  ```

- **R9 [P0]** Add:

  ```sh
  moshcode ssh open <name>
  moshcode ssh check <name>
  moshcode ssh close <name>
  ```

  Pit equivalents:

  ```text
  /ssh open dev
  /ssh check dev
  /ssh close dev
  ```

- **R10 [P0]** Opening an already-live master is idempotent and returns success with `alreadyOpen: true`.

- **R11 [P0]** Connection state MUST be checked using OpenSSH's control operations where supported, e.g. `ssh -O check`.

- **R12 [P0]** Closing MUST use OpenSSH's control operation, e.g. `ssh -O exit`, rather than killing arbitrary PIDs.

- **R13 [P0]** Default to a finite `ControlPersist` window after the last client disconnects. Initial default: 10 minutes.

  Configurable by:

  ```sh
  --persist 30m
  ```

  and:

  ```text
  MOSHCODE_SSH_PERSIST=30m
  ```

- **R14 [P0]** Use connection keepalives appropriate for unattended agents:

  ```text
  ServerAliveInterval=30
  ServerAliveCountMax=3
  ```

  unless the user has explicitly configured alternatives.

- **R15 [P0]** If the master dies or a control socket becomes stale, the next operation MUST:
  1. detect the failure;
  2. clean up only MoshCode-owned stale state;
  3. establish a new master;
  4. retry the requested operation once.

- **R16 [P0]** Control socket paths MUST avoid Unix-domain-socket path-length failures.

  Do not derive a long socket filename directly from `user@host:/workspace/path`.

  Use a stable short hash:

  ```text
  ~/.moshcode/ssh/control/7f31a8c2
  ```

  If platform socket limits make even that unsafe, use a private runtime directory such as:

  ```text
  /tmp/moshcode-ssh-<uid>/
  ```

- **R17 [P0]** Any runtime/control directory containing sockets MUST be mode `0700`.

### Phase 3 — Discrete command execution

- **R18 [P0]** Add:

  ```sh
  moshcode ssh exec <name> -- <command> [args...]
  ```

  Example:

  ```sh
  moshcode ssh exec dev -- git status --short
  ```

- **R19 [P0]** `ssh exec` MUST automatically reuse the named target's master connection.

- **R20 [P0]** `ssh exec` MUST default to **no PTY**.

  This keeps:
  - stdout deterministic;
  - stderr deterministic;
  - binary-safe stdin possible;
  - automation predictable.

- **R21 [P0]** Add `--tty` for commands that require a terminal:

  ```sh
  moshcode ssh exec dev --tty -- sudo systemctl status nginx
  ```

- **R22 [P0]** Return the command's actual remote exit status.

- **R23 [P0]** `--json` output shape:

  ```json
  {
    "ok": true,
    "target": "dev",
    "connected": true,
    "code": 0,
    "signal": null,
    "stdout": " M src/app.ts\n",
    "stderr": "",
    "durationMs": 84
  }
  ```

- **R24 [P0]** Failed remote commands are not transport failures.

  Example: remote `grep` exits `1`.

  JSON:

  ```json
  {
    "ok": false,
    "transportOk": true,
    "code": 1
  }
  ```

  This distinction matters to agents.

- **R25 [P0]** SSH/network/auth failures MUST be distinguished from remote command failures.

  Example:

  ```json
  {
    "ok": false,
    "transportOk": false,
    "code": 255,
    "error": "ssh authentication failed"
  }
  ```

- **R26 [P0]** Support timeout:

  ```sh
  moshcode ssh exec dev --timeout 2m -- pnpm test
  ```

- **R27 [P0]** Support per-operation cwd:

  ```sh
  moshcode ssh exec dev --cwd /srv/app -- git status
  ```

  If omitted, use the target's configured default cwd.

- **R28 [P1]** Support per-operation environment values:

  ```sh
  moshcode ssh exec dev --env NODE_ENV=test -- pnpm test
  ```

  These values apply to that operation only.

- **R29 [P0]** Do not emulate shell persistence for `exec`.

  This should **not** work by accident:

  ```sh
  moshcode ssh exec dev -- cd /tmp
  moshcode ssh exec dev -- pwd
  ```

  The second command should still use the configured/default cwd.

  Persistent shell state belongs to the shell-session feature.

### Phase 4 — stdin and agent-friendly file editing

- **R30 [P0]** `ssh exec` MUST be able to forward stdin.

  Example:

  ```sh
  printf '%s\n' "$PATCH" |
    moshcode ssh exec dev --stdin --cwd /srv/app -- git apply -
  ```

- **R31 [P0]** stdin MUST remain raw and must not be shell-escaped, JSON-encoded, line-split, or interpreted by MoshCode.

- **R32 [P0]** This is the recommended Chovy multi-file-edit path:

  ```text
  model produces unified diff
           │
           ▼
  one `ssh exec --stdin`
           │
           ▼
       `git apply -`
           │
           ▼
  many files changed atomically-ish in one remote command
  ```

  This is preferable to one SSH operation per changed file when the model already has a patch.

- **R33 [P1]** Add convenience transfer verbs backed by OpenSSH-native tools:

  ```sh
  moshcode ssh put dev ./local-file /srv/app/file
  moshcode ssh get dev /srv/app/file ./local-file
  ```

  Implementation may use `scp` with the same ControlPath.

- **R34 [P1]** `put` SHOULD support atomic replacement for individual files:
  1. copy to a temporary sibling path;
  2. rename on the remote filesystem.

- **R35 [P1]** No custom SFTP implementation.

### Phase 5 — Interactive connection

- **R36 [P0]** Bare named target attaches a normal interactive SSH session:

  ```sh
  moshcode ssh dev
  ```

  pit:

  ```text
  /ssh dev
  ```

- **R37 [P0]** Interactive attach MUST reuse the same ControlMaster when available.

- **R38 [P0]** Interactive mode hands the terminal directly to OpenSSH. MoshCode does not parse or redraw the remote terminal.

- **R39 [P0]** Ctrl-C, terminal resize, colors, mouse input, TUIs, vim, top, btop, and nested agent CLIs should behave as they do under ordinary OpenSSH.

- **R40 [P0]** Exiting the interactive shell does **not** necessarily close the master connection. `ControlPersist` governs transport lifetime.

### Phase 6 — Persistent stateful remote shell

A multiplexed SSH connection avoids repeated authentication, but separate `exec` channels intentionally do not preserve shell state.

Some workflows need actual state:

```sh
cd /srv/app
export DEBUG=1
pnpm dev
```

or an interactive CLI that stays alive.

- **R41 [P1]** Add:

  ```sh
  moshcode ssh shell <target> --name <session>
  ```

  Example:

  ```sh
  moshcode ssh shell dev --name app
  ```

- **R42 [P1]** When remote tmux exists, create-or-attach a namespaced remote tmux session:

  ```text
  moshcode-ssh-<local-target>-<session>
  ```

- **R43 [P1]** The remote shell persists independently of the local terminal and independently of the local SSH transport. If the laptop sleeps, the remote tmux shell remains.

- **R44 [P1]** Add non-attaching machine controls:

  ```sh
  moshcode ssh shell send dev/app "pnpm test"
  moshcode ssh shell read dev/app --lines 80
  moshcode ssh shell kill dev/app
  ```

- **R45 [P1]** `send` MUST write literal text followed by Enter, matching herd's existing literal-input safety model.

- **R46 [P1]** `read` uses remote `tmux capture-pane`, returning terminal text rather than requiring the caller to attach.

- **R47 [P1]** The remote shell feature MUST gracefully report when tmux is unavailable on the remote machine.

  Normal `ssh exec` remains fully functional.

- **R48 [P1]** Do not silently install tmux remotely.

### Phase 7 — Moshscript / agent API

- **R49 [P0]** Expose value-returning moshscript helpers instead of forcing scripts to parse human text.

  Proposed:

  ```js
  sshOpen("dev");
  const r = sshExec("dev", ["git", "status", "--short"], {
    cwd: "/srv/app"
  });

  if (!r.ok) {
    say(r.stderr);
  }

  sshClose("dev");
  ```

- **R50 [P0]** `sshExec()` returns the same conceptual object as CLI `--json`:

  ```js
  {
    ok,
    transportOk,
    code,
    signal,
    stdout,
    stderr,
    durationMs
  }
  ```

- **R51 [P1]** Support stdin in moshscript:

  ```js
  sshExec("dev", ["git", "apply", "-"], {
    cwd: "/srv/app",
    stdin: patch
  });
  ```

- **R52 [P1]** Add shell-session helpers only if Phase 6 is implemented:

  ```js
  sshShellSend("dev/app", "pnpm test");
  const screen = sshShellRead("dev/app", { lines: 50 });
  ```

  (Starting a shell hands the terminal to ssh, so it is a CLI verb rather
  than a script helper; a script drives an existing shell with `send`,
  `read` and `kill`.)

### Phase 8 — Chovy integration contract

The feature should be usable by Chovy strictly through the public CLI. Chovy must not import MoshCode private modules.

Recommended lifecycle:

```sh
# once when a workspace is provisioned
moshcode ssh add chovy-app app@server --cwd /srv/chovy/workspace

# once at the beginning of an active coding run
moshcode ssh open chovy-app --json
```

Then every AI tool operation:

```sh
moshcode ssh exec chovy-app --json -- git status --short
```

Read a file:

```sh
moshcode ssh exec chovy-app --json -- sed -n '1,240p' src/app.ts
```

Apply a model-generated multi-file patch:

```sh
moshcode ssh exec chovy-app \
  --json \
  --stdin \
  --cwd /srv/chovy/workspace \
  -- git apply -
```

Run tests:

```sh
moshcode ssh exec chovy-app \
  --json \
  --timeout 10m \
  --cwd /srv/chovy/workspace \
  -- pnpm test
```

Optional interactive debug:

```sh
moshcode ssh chovy-app
```

Optional persistent remote dev shell:

```sh
moshcode ssh shell chovy-app --name dev
```

At run completion:

```sh
moshcode ssh close chovy-app
```

or simply let `ControlPersist` expire.

- **R53 [P0]** Chovy SHOULD keep using discrete model tool calls.

- **R54 [P0]** Chovy SHOULD NOT force all model actions through a single interactive shell merely to avoid reconnect cost.

- **R55 [P0]** Chovy SHOULD batch model file changes into unified diffs where practical and apply one patch through stdin.

- **R56 [P0]** Chovy MAY run independent commands concurrently over the same master connection. SSH multiplexing should allow several logical channels over one authenticated transport.

- **R57 [P0]** A single Chovy coding run should normally perform one SSH authentication/transport setup, not one per file.

## UX Notes

### Human pit flow

```text
mosh ▸ /ssh add dev deploy@dev.example.com --cwd ~/src/app
✓ dev → deploy@dev.example.com

mosh ▸ /ssh open dev
✓ dev connected

mosh ▸ /ssh exec dev -- git status --short
 M src/app.ts

mosh ▸ /ssh dev
deploy@dev:~/src/app$
```

Leaving the remote shell returns to the pit while the master connection remains reusable.

### Connection list

```text
mosh ▸ /ssh

name       target                    state       cwd
dev        deploy@dev.example.com    connected   ~/src/app
prod       deploy@prod.example.com   closed      /srv/app
```

### JSON list

```json
{
  "targets": [
    {
      "name": "dev",
      "target": "deploy@dev.example.com",
      "connected": true,
      "cwd": "~/src/app"
    }
  ]
}
```

### Shell session

```text
mosh ▸ /ssh shell dev --name app
dev/app ▸ ~/src/app

deploy@dev:~/src/app$ pnpm dev
```

Detach behavior should be documented clearly. If remote tmux is used, detaching must leave the remote process alive.

## CLI Surface

```text
moshcode ssh
moshcode ssh list
moshcode ssh add <name> <target> [--port N] [--cwd PATH]
moshcode ssh remove <name>
moshcode ssh show <name>

moshcode ssh open <name> [--persist 10m]
moshcode ssh check <name>
moshcode ssh close <name>

moshcode ssh <name>
moshcode ssh exec <name> [--cwd PATH] [--env K=V] [--stdin] [--tty] [--timeout DURATION] -- <command...>

moshcode ssh put <name> <local> <remote>
moshcode ssh get <name> <remote> <local>

moshcode ssh shell <name> --name <session>
moshcode ssh shell send <name>/<session> <text>
moshcode ssh shell read <name>/<session> [--lines N]
moshcode ssh shell kill <name>/<session>

moshcode ssh bench <name> [--n 20]
```

Every appropriate verb:

```text
--json
```

Pit facade:

```text
/ssh ...
```

## Architecture

### New module: `src/ssh.mjs`

Own:

- target registry;
- control socket naming;
- OpenSSH capability detection;
- master open/check/close;
- invocation construction;
- exec;
- stdin forwarding;
- output capture;
- timeout;
- interactive attach;
- scp convenience;
- optional remote tmux shell helpers.

No SSH command construction should be duplicated in `cli.mjs`, `commands.mjs`, or Chovy.

### `src/cli-schema.mjs`

Add the canonical help schema for `ssh` and its verbs.

The README command table is generated from the command schema, so `/ssh` must enter through the same canonical command/help path as existing commands.

### `bin/moshcode.mjs`

Dispatch `moshcode ssh ...` into `src/ssh.mjs`.

### `src/commands.mjs`

Expose:

```js
cliVerb("ssh", "connect to and operate persistent remote SSH workspaces")
```

plus value-returning moshscript helpers where required.

### `src/runtime.mjs`

The runtime injects every registered command as a global, so the helpers in
`src/commands.mjs` are the injection; no runtime change is needed.

### Relationship to `src/herd.mjs`

Phase 1 does not change herd.

This is intentional:

- herd owns local persistent processes and agent state;
- ssh owns remote transport and remote command execution.

Future integration may allow a remote SSH shell or an SSH-launched remote agent to appear in `moshcode ps`, but `/ssh` should first work cleanly as an independent transport primitive.

## OpenSSH Invocation Strategy

Implementation builds argv arrays, never a shell string.

### Master

```sh
ssh \
  -o ControlMaster=yes \
  -o ControlPersist=600 \
  -o ControlPath=/private/path/abc123 \
  -o ServerAliveInterval=30 \
  -o ServerAliveCountMax=3 \
  -o ConnectTimeout=20 \
  -N -f \
  devbox
```

Note the absence of `-M`. Found in testing: `-M` together with
`-o ControlMaster=yes` is read by ssh as a *second* request for master mode,
which means **ask** mode — every later client then needs an askpass
confirmation, and headless the answer is "Master refused session request:
Permission denied". One spelling or the other, never both.

### Check

```sh
ssh \
  -o ControlPath=/private/path/abc123 \
  -O check \
  devbox
```

### Close

```sh
ssh \
  -o ControlPath=/private/path/abc123 \
  -O exit \
  devbox
```

### Exec

```sh
ssh \
  -o ControlPath=/private/path/abc123 \
  -o ControlMaster=auto \
  -o ControlPersist=600 \
  -T \
  devbox \
  -- <remote-command>
```

`ControlMaster=auto` on the client is the native stale-socket recovery: a
socket nobody is listening on is unlinked and the client becomes the new
master, so a master that died between two commands costs one reconnect.

The remote command is built from argv with POSIX single-quoting:

```text
cd -- '/srv/app' && NODE_ENV='test' exec 'pnpm' 'test'
```

A `--sh` flag passes a single argument as a shell snippet on purpose; nothing
is ever guessed to be one.

## Security

- **R58 [P0]** Never pass `StrictHostKeyChecking=no`.
- **R59 [P0]** Respect normal OpenSSH `known_hosts` behavior.
- **R60 [P0]** Never persist passwords.
- **R61 [P0]** Never copy private keys into `~/.moshcode`.
- **R62 [P0]** Prefer ssh-agent, OpenSSH config, hardware-backed keys, and standard identity files.
- **R63 [P0]** Redact obvious secret-bearing CLI arguments from debug logs where MoshCode controls logging.
- **R64 [P0]** Do not print full stdin payloads in debug output.
- **R65 [P0]** The socket/control directory must be private to the current OS user.
- **R66 [P0]** Refuse target names containing path separators or traversal components.
- **R67 [P0]** Registry file writes must be atomic and owner-only.
- **R68 [P0]** Remote commands must be built from argv with explicit quoting rules.
- **R69 [P0]** `--env` values must not be echoed in ordinary human output.
- **R70 [P0]** The feature must not weaken the user's existing SSH policy.

## Failure Modes

### OpenSSH missing

```text
✗ ssh not found — install an OpenSSH client
```

No package is auto-installed.

### Authentication requires interaction

Interactive `/ssh dev` may naturally allow OpenSSH to ask.

Headless `ssh exec --json` should fail clearly rather than hang indefinitely.
`BatchMode=yes` is passed whenever stdin is not a terminal or `--batch` is
given; with a terminal attached, OpenSSH may prompt as it normally would.

### Unknown host key

Use native OpenSSH behavior. Do not auto-accept.

### Stale master socket

Detect → clean MoshCode-owned stale socket → reconnect → retry once.

### Remote command exits nonzero

Return command exit status without calling it an SSH failure.

### Remote tmux missing

Only `ssh shell` persistent mode is unavailable. `ssh exec` still works.

### Local process dies

A detached ControlMaster may survive according to OpenSSH behavior and ControlPersist. Remote tmux shells survive regardless of the local master.

## Performance Expectations

The feature exists to remove repeated SSH handshakes from high-churn agent workloads.

### Required measurement

`moshcode ssh bench <name> [--n N]` compares:

```text
N × fresh ssh "true"
```

against:

```text
1 × master connection
N × multiplexed ssh "true"
```

and reports total wall time, median and p95 latency, failures, and the number
of authentications each side performed.

Measured on a loopback sshd on the development box (20 runs each): fresh
~96ms median, multiplexed ~12ms median. Real hosts will differ; the number to
quote is the one `bench` prints for your own host.

## Success Metrics

- A Chovy run that performs 100 remote operations normally authenticates once rather than 100 times.
- Median subsequent `ssh exec` startup latency is materially lower than a fresh SSH connection on the same host.
- File edits can be applied as one multi-file patch over stdin.
- `ssh exec --json` exposes stdout, stderr, exit status, transport status, and duration without terminal scraping.
- Interactive `/ssh <name>` behaves like normal OpenSSH.
- Existing `~/.ssh/config` features continue to work.
- No SSH private key or password is stored by MoshCode.
- No runtime npm dependency is added.
- MoshCode remains usable when tmux is absent.
- Tests cover stale sockets, failed authentication, remote exit codes, stdin, quoting, cwd, and JSON output.

## Test Plan

### Unit (`test/ssh.test.mjs`)

- target-name validation;
- registry read/write;
- control-path hashing;
- OpenSSH argv construction;
- port handling;
- cwd encoding;
- environment encoding;
- remote argv quoting;
- JSON shapes;
- exit-code mapping;
- transport-vs-command failure classification;
- timeout parsing;
- stale-socket recovery decision logic.

### Integration (`test/ssh-sshd.test.mjs`)

An ephemeral, non-root `sshd` on a loopback port with generated keys and a
private `ssh_config` (pointed at through `MOSHCODE_SSH_CONFIG`). Skipped, not
failed, where `sshd` or `ssh-keygen` is unavailable.

1. add target;
2. open master;
3. check master;
4. exec `printf`;
5. exec failing command;
6. stdin round trip;
7. cwd;
8. parallel exec channels;
9. close master;
10. automatic reopen;
11. host-key failure;
12. authentication failure;
13. `scp` reuse via `put`/`get`.

### Remote tmux

When tmux is present in the test image:

1. send `cd` and `pwd`, verify state persists;
2. read the screen;
3. kill.

## Documentation

README section `## SSH workspaces`, leading with:

> `/ssh` keeps the SSH connection alive; `ssh exec` still gives each tool call a clean command channel.

with a Chovy/agent example showing one connection and a multi-file `git apply -`, and `moshcode help ssh`.

## Rollout

### Milestone 1

- target registry;
- `/ssh`;
- open/check/close;
- exec;
- JSON;
- stdin;
- cwd;
- tests.

This alone solves the Chovy reconnect problem.

### Milestone 2

- put/get;
- timeout polish;
- parallel execution tests;
- moshscript value helpers.

### Milestone 3

- persistent remote tmux shell;
- send/read/kill;
- optional herd bridge exploration.

## Future: Herd Bridge

Do not block this PRD on herd integration.

A later PRD may define:

```sh
moshcode herd remote add devbox --kind ssh --target dev
```

or allow:

```sh
moshcode ssh agent dev --engine claude --name api
```

to launch a MoshCode herd/agent on a remote machine.

The clean layering should be:

```text
herd / agent orchestration
          │
          ▼
     ssh workspace
          │
          ▼
       OpenSSH
```

not:

```text
SSH implementation hidden inside herd
```

## Risks & Open Questions

- OpenSSH multiplexing behavior differs slightly across platforms. POSIX/OpenSSH-first is acceptable, but capability checks must be explicit.
- ControlPath socket limits can be surprisingly small; hashed short paths are mandatory.
- Remote argv quoting is security-sensitive and deserves dedicated tests.
- `BatchMode=yes` is on whenever stdin is not a terminal, and `--batch` forces it; a person at a terminal can still be prompted.
- `ControlPersist=10m` is a reasonable default but Chovy may want a master open for the entire coding-run lifetime. Explicit `open` + `close` already handles that.
- `scp` behavior and flags have changed across OpenSSH versions; `put/get` are P1, not required for the core reconnect fix.
- Long-running noninteractive commands are still individual channels. If a command must outlive its caller, use remote tmux/systemd/herd rather than pretending `ssh exec` is a job supervisor.
- A future remote-herd abstraction should decide whether MoshCode is installed remotely or whether local MoshCode drives raw remote tmux. That decision is intentionally outside this PRD.

## Decision

Build `/ssh`, but build it as a **persistent SSH workspace primitive**, not as a convenience alias for `ssh`.

For Chovy, the key win is not "one forever-interactive shell." The key win is:

> **one authenticated SSH transport, many clean AI tool calls, plus an optional persistent remote shell when state is actually needed.**