Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs(windows): relay-only host parity — the phone never types shell syntax into a relay host

review845d54bdcd10
diff --git a/CLAUDE.md b/CLAUDE.md
index 640506558..8bbf7db88 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8612,6 +8612,21 @@ unix-socket forward over it. POSIX keeps OpenSSH untouched.
being packaged (#575, shipped by #579): without that bundle `pty.attach` spawns a new plain shell
instead of joining the node's session, while `sessionExists` still answers "warm".
+- **The phone never types shell syntax into a relay host** (relay-only hosts — every Windows
+ pairing — have no SSH, and a Windows pane is pwsh/cmd). `pty.attach { launch: {agentId,
+ sessionId?, cwd?, accountId?, permissionMode?} }` makes the HOST launch, only into a session the
+ attach CREATED, exactly once (`core/relay-launch.ts`, `PtyManager.prepareRelayAttach`): every
+ field re-validated, cwd jailed to the fs roots, cwd/account folded into the SPAWN options of an
+ unrecorded node (a recorded node keeps its records), and the line built for the pane's real
+ parser — `assembleResumeCommand` on POSIX, the trusted Windows planner when its resolver is
+ wired, else only a dialect-neutral line. Reply `launched: true` = "type nothing". Without
+ `launch` the reply is byte-identical. `pty.scroll` writes the wheel only on a tmux /
+ mouse-requesting pane (`PtyManager.scrollRoute`); a session-host / plain stream's reply says
+ `scroll:'local'` and its snapshot is the full buffer. Keyed answers ride `agent.key` (closed key
+ set, host-side state + open-ask guard, hook reply first), read-acks `inbox.ack`
+ (`applyPhoneReadAck`, the ack sweeper's body), plus `fs.browse` (home-jailed, dirs only) and
+ `pty.capture`; `host.info` lists them. All additive — an old phone keeps its old path.
+
## Push webhook (a script or CI job rings the paired phone)
Settings → Phone → **Push webhook** mints a per-host bearer token; anything that can run `curl`
diff --git a/docs/windows-session-host.md b/docs/windows-session-host.md
index 5abf4f1de..f3a000f7b 100644
--- a/docs/windows-session-host.md
+++ b/docs/windows-session-host.md
@@ -143,6 +143,7 @@ long-lived connection (no positional-FIFO fragility, unlike this app's tmux cont
| `sendKeys` | `send-keys -l -- <text>` (+ `Enter`) | full — works with no attached client, exactly like tmux |
| `paneCommand` | `display-message -p '#{pane_current_command}'` | approximated — see `process-tree.ts` |
| `capture` | `capture-pane -p -e [-S -N]` | full, and strictly more (mode restoration — tmux's plain-text capture carries none) |
+| `paneModesV1` | (none — tmux owns the mouse itself) | additive: the pane app's mouse-tracking protocol, for relay scroll routing; an older host answers `unknown command` = "no mouse" |
| `killSession` | `kill-session -t <name>` | full |
| `detach` | a client's own `tmux detach-client` | full |
| `listSessions` | `list-sessions -F '#{session_name}'` | full |
@@ -684,6 +685,16 @@ you chose and why") rather than an oversight.
see the protocol table's "Not implemented" note. Nothing in this app currently calls these for a
session-host-backed node (they are gated behind `this.tmuxPath` being set), so nothing is
silently broken; a future feature that wants one of these on Windows needs a new host verb.
+- **The phone relay has no tmux to drive on this backend.** Over SSH-less (relay-only) pairing the
+ phone used to (a) type a POSIX launch line into a fresh pane and (b) scroll by writing SGR wheel
+ bytes for tmux's copy-mode. Neither holds here: pwsh / cmd reject `2>/dev/null`, `env -u`,
+ `VAR=x cmd`, and a wheel nobody asked for lands in the prompt as text. So the phone sends
+ `pty.attach { launch }` and the HOST launches (`core/relay-launch.ts`: cwd/account ride the spawn
+ options, the line is built for the pane's real parser and typed once), the attach reply says
+ `scroll:'local'` with a full-buffer snapshot, and `pty.scroll` writes a wheel only when
+ `paneModesV1` reports the app asked for the mouse. Keyed Inbox answers (`agent.key`), read-acks
+ (`inbox.ack`), the folder browser (`fs.browse`) and plain capture (`pty.capture`) are relay
+ verbs for the same reason. All additive; `host.info` lists them for feature detection.
- **ConPTY helper teardown can emit `Error: AttachConsole failed`** from
`node-pty/lib/conpty_console_list_agent.js`. The protocol test determines kill success from the
host response and follow-up session state rather than stderr text. Whether this cosmetic