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.

Merge origin/main into fix/ssh-agent-docs-freshness

review08da81de1ca3
diff --cc CLAUDE.md
index ee7dc1936,424c31324..4e5fad56f
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -3213,13 -3273,71 +3340,76 @@@ command-bearing opens; this does not ad
(`--cmd=--version`), which was previously unexpressible in either direction. Two parsers are in
play and both are tested — the sh loop (`control-shim-parse.test.ts`, real `sh` + a fake `curl`
that records argv) and `parseControlBody` reading what it built (`canvas-control-shim.test.ts`).
- **A new verb must not DEPEND on the fix**: the shim is rewritten locally every app boot but onto
- an SSH host only inside `RemoteHooks.setup()` (on connect), so an already-connected project keeps
- the old loop with no signal on the wire. Give every flag a value and both loops agree.
+ **A new verb must still not DEPEND on the fix.** The shim is rewritten locally at every app boot,
+ and an SSH host's copy is checked on every connect and brought to this build's bytes, so an app
+ update reaches the host on the first connect after the relaunch. A host can still run an older
+ loop for a while: while its tunnel is down (nothing is installed through a dead tunnel), when the
+ file is unreadable (never written over), or while a second desktop on an older build shares the
+ host account (it rewrites its own copy on its connects; ours returns within the hour). Nothing
+ on the wire says which loop is running. Give every flag a value and both loops agree.
+ **A retried call must not open a second node (`--request-id`, `core/control-request-ledger.ts`).**
+ The reply to an open can be lost while the open went through — the agent's own tool call is
+ killed (~2 min for a Bash tool call while a slow host holds the POST), the ssh tunnel drops
+ mid-reply, or the shim's endpoint walk re-posts after a transport that failed AFTER the request
+ was read — and the agent's natural retry used to open a second agent, team or worktree. The
+ verbs that create something (`REQUEST_ID_VERBS`) take `--request-id <id>`, and the shim also
+ sends its own `requestId` form field, generated once per RUN (`od` of `/dev/urandom`, else
+ pid+time), on every POST of that run, so its own re-post is covered for an agent that never read
+ the docs. Rules a refactor must not undo: (1) **the ledger lives in the hook server's `/control/`
+ route** (core), the one place desktop main's forwarder and the Server Edition's
+ `createServerEditionControlHandler` both sit behind — putting it in either shell's handler
+ leaves the other without it; (2) rows are keyed **(verified caller node, id)** only — an
+ unverified caller gets no dedupe rather than a shared bucket, and an explicit id from one is
+ answered with `REQUEST_ID_UNVERIFIED_NOTE`; (3) the row is **claimed before the handler runs**,
+ synchronously after the lookup, so two concurrent POSTs cannot both run; (4) a fingerprint (verb
+ + args minus the id, key order ignored) makes the same id with a different call a
+ `request-id-conflict`; (5) a settled row stores the WHOLE reply and a replay returns it (text:
+ a `replayed:` first line; JSON: `replayed: true`) — a refusal included, so an id never runs
+ twice; (6) a handler that cannot say whether its effect happened answers `indeterminate: true`
+ (desktop main's 120 s wait, now `src/main/control-forward.ts`: the renderer is not cancelled, and
+ an `open-worktree` whose `git worktree add` outlives the wait still completes) or throws, and the
+ row becomes UNKNOWN — refused, never re-run; the forwarder hands a late renderer answer back via
+ the handler's `onLateAnswer`, and settlement only moves up (unknown → answer, never the reverse).
+ **A late answer is finished exactly like an on-time one**: everything main does with a renderer
+ answer (the `open-browser` ownership claim, `browser-open-claim.ts`; the `open-project` grant) is
+ ONE `finishAnswer` step the forwarder runs on whichever answer arrives — replaying a late
+ "opened browser b1" without the claim told the agent it had a browser it could never drive. And
+ **an indeterminate reply names its id**: the route adds a `request id: <id>` line saying to pass
+ it back as `--request-id <id>`, and the in-flight/unknown refusals spell the flag with its value —
+ the shim's per-run id is otherwise never seen, so "retry with the same --request-id" sent agents
+ to re-run the bare command, get a fresh id and open a second one. That reply is not enough on
+ its own: an agent's tool call is typically killed at 120 s — the SAME instant the app gives up —
+ so the shim also prints the per-run id to stderr BEFORE posting an open it carries no caller id
+ for (`requestIdAnnounceLine`, skipped for a caller's own `--request-id` and for `--dry-run`), and
+ both agent bodies say to pass an OWN unique id up front for slow opens (open-worktree,
+ spawn-team, verify) with a tool timeout above 120 s. A `finishAnswer` step that throws never
+ escapes into the IPC listener: on time it resolves indeterminate, late it hands nothing back (the
+ row stays unknown);
+ (7) an explicit id on a verb outside the set is REFUSED (`request-id-unsupported`), like
+ `--dry-run` — an agent believing its `write` is protected when it is not is the failure the flag
+ exists to end — while a malformed or out-of-set per-run id is silently ignored; (8) a dry run
+ neither claims nor replays. The ledger is **process memory** (24 h, 256 per caller, 4096 in total,
+ in-flight rows never evicted): an app restart between the effect and the retry runs the retry
+ again, which is the case that matters least and costs a store with atomic writes on every call
+ to cover. The timeout sentence is verb- and claim-aware (`controlTimeoutError`): only a
+ confirm-gated verb, whose dialog dismisses itself at the same deadline, is still called "safe to
+ retry"; a call with no ledger row (no id, or an unverified caller) is told to check the canvas for
+ its effect before retrying, never pointed at a flag it has no value for. Ids suggested to agents
+ must be UNIQUE (a uuid — `$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)`, since slim
+ Linux lacks `uuidgen` and macOS lacks `/proc` — or a readable name with a random part): rows are per node for 24 h, so a
+ later conversation in the same node reusing a readable id for the same call would be answered
+ with the earlier reply. An SSH
- host keeps the shim it got at its last connect, so until that project reconnects its runs carry
- no per-run id (an explicit `--request-id` still works through the old loop). Agent-facing text
++ host gets the new shim at its first connect after the update (the agent-tools check,
++ `RemoteHooks.refreshAgentTools`); until then — or while its tunnel is down — its runs carry no
++ per-run id (an explicit `--request-id` still works through the old loop). Agent-facing text
+ is rendered from `REQUEST_ID_VERBS` / `REQUEST_ID_RETRYABLE` / `REQUEST_ID_OUTCOME_GLOSS`
+ (`requestIdDocLines`). Tests: the ledger alone, the route (both dialects, in flight, conflict,
+ late answer, throw), the Server Edition handler behind it, and the real shim under `/bin/sh`
+ through a proxy that forwards the request and drops the reply — the re-post case, red before.
+ Deliberately NOT in the set: reads (a replay would serve a stale snapshot, and `browser
+ --cookies` would sit in memory for a day), the idempotent-by-nature verbs, and the
+ human-confirmed / rate-limited ones (`write`, `send`, `settings`, `report-issue`) — widening it
+ to those is a separate decision.
**WHICH CANVAS ANSWERS, and why an open never moves the camera** (`renderer/lib/controlRouting.ts`
+ `renderer/lib/coldOpen.ts`). React Flow holds only the ACTIVE project's nodes, but every other
open project's tmux sessions keep running, so a control call routinely arrives from a node the
@@@ -3751,8 -3869,8 +3941,8 @@@
`release:false`: the attached client is what keeps even a plain shell reachable there.
**Settings (`settings`, 2026-09):** `settings [--project <id>]` lists, `settings --get <key>`
reads, `settings --set <key> --value <v> [--project <id>]` asks to change — flags only, because the
-- shim drops a positional sub-action for an unlisted verb and an SSH host keeps the shim it got at
-- connect. The pure `@shared/settings-verb` is the whole rule set, shared by the desktop dispatch, the
++ shim drops a positional sub-action for an unlisted verb and an SSH host can still be running an
++ older shim. The pure `@shared/settings-verb` is the whole rule set, shared by the desktop dispatch, the
Server Edition and main's `parseControlRequest`: an **allowlist** (`agentMessaging` per project;
`snapToGrid`/`gridSize`/`defaultNodeWidth`/`defaultNodeHeight` machine-wide, bounds = the UI's) with
a required `why` per entry, and a **forbidden set + name pattern that outranks it** (permission
diff --cc src/core/canvas-control-core.ts
index 60f6fc73d,dc1d5d28f..022ce276a
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@@ -848,10 -898,10 +913,10 @@@ export function buildCanvasControlInstr
// could not be made safe.
//
// INSTALL LIFECYCLE, and why a verb must not depend on this parser's fixes: the shim is rewritten
--// locally at every app boot, but onto an SSH host ONLY inside RemoteHooks.setup(), i.e. on connect.
--// An already-connected SSH project keeps the shim it was handed. So a parsing improvement reaches
--// remote agent nodes only after a reconnect, with no signal on the wire — the same shape as the
--// managed hook script's stale window. Verbs are therefore designed to parse identically under both
++// locally at every app boot, and an SSH host's copy is checked on every connect and brought to this
++// build's bytes (RemoteHooks.refreshAgentTools). A host can still run an older loop for a while —
++// its tunnel is down, the file is unreadable, or a second desktop on an older build shares the host
++// account — with no signal on the wire. Verbs are therefore designed to parse identically under both
// the old and the new loop: give every flag a value, and the two loops agree.
/** The shim's generic transport-failure sentence — exported so the agent-facing docs can quote it
* verbatim and the parity test holds the two ends together (issue #367). */
diff --cc src/shared/settings-verb.ts
index 48c37473e,48c37473e..b06cc5c73
--- a/src/shared/settings-verb.ts
+++ b/src/shared/settings-verb.ts
@@@ -23,9 -23,9 +23,9 @@@
*
* THE CLI SHAPE uses flags only — `settings`, `settings --get <key>`, `settings --set <key> --value
* <v> [--project <id>]` — never a positional sub-action. The sh shim maps a bare positional only for
-- * the verbs it names, and an SSH host keeps the shim it was given at connect
-- * (`RemoteHooks.setup()`), so `settings get` would reach an already-connected host's server with
-- * the `get` silently dropped. Every flag carries a value, which both the old and the new shim loop
++ * the verbs it names, and an SSH host can still be running an older shim (it is brought up to
++ * date on connect, but not through a dead tunnel, and not over another desktop's older copy), so
++ * `settings get` could reach the server with the `get` silently dropped. Every flag carries a value, which both the old and the new shim loop
* read identically.
*
* In `src/shared` because both edges need it: the desktop renderer (dispatch + dialog) and the