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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
Merge origin/main into fix/ssh-agent-docs-freshness
review08da81de1ca3
diff --cc CLAUDE.mdindex 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 inplay 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 otheropen 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, theServer Edition and main's `parseControlRequest`: an **allowlist** (`agentMessaging` per project;`snapToGrid`/`gridSize`/`defaultNodeWidth`/`defaultNodeHeight` machine-wide, bounds = the UI's) witha required `why` per entry, and a **forbidden set + name pattern that outranks it** (permissiondiff --cc src/core/canvas-control-core.tsindex 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.tsindex 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