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 remote-tracking branch 'origin/main' into fix/triage-711-20260923

review9cf183f2d552
diff --cc CONTRIBUTING.md
index 92a26f913,ac203f4e4..0a513fe33
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@@ -611,13 -622,65 +622,70 @@@ examples). If the same effect also WRIT
mid-session applies stored state to whatever the user is doing right then, which is a different
feature from the one they asked for.
+Maximize placement and refocusing must use the same measured usable rectangle
+(`measureMaximizeInsets`): pinned side panels plus persistent top controls and bottom dock.
+Do not hardcode chrome heights or add the outer margin twice; transient menus must not resize
+terminals. Ordinary focus and zone snap keep their own policies.
+
+ **Usage readouts distinguish failed reads from empty data.** For Claude, show the failure when
+ `status` is `error` and limits are empty, including beside other providers; preserve last-known
+ bars when limits remain. Keep both single-account and multi-account views covered.
+
+ **A context capacity needs session provenance.** Claude's effective `CLAUDE_CODE_MAX_CONTEXT_TOKENS`
+ is reported by its managed hook, accepted only with verified node identity, and validated as a
+ positive decimal safe integer. Never read the app's global env for another session or let a
+ model-family guess enlarge an observed limit. Unobserved Claude windows are labelled estimates.
+ The renderer rehydrates through `context.ensure`; it does not restore Claude denominators from
+ storage. Other agents retain transcript-window persistence.
+ Only an explicit ensure replays an unchanged live snapshot; repeated hook observations must not
+ broadcast it again. Remote path, ControlMaster or connection changes replace the tracked generation.
+
+ **Command-bearing terminal opens (issue #653):** the shared hook-server route requires verified
+ node identity whenever `open-terminal` carries `cmd`, including an empty value or a dry run.
+ The strict-policy override and foreign-instance fallback cannot release this gate. Desktop plain
+ terminal opens keep their existing identity policy; Server Edition still requires verification
+ for every control verb. Legacy mobile/SSH callers must present this instance’s node token for
+ command-bearing opens; this does not add a human-confirm dialog or change mobile transport APIs.
+
+ ## User-owned agent settings
+
+ Claude/Gemini settings must go through the guarded transactions in
+ `src/core/agents/hooks/{settings-file,remote-settings-file}.ts`. Confirmed absence or a successfully read empty/whitespace file may start from `{}`;
+ malformed, non-object and unreadable files must survive unchanged.
+ Keep unrelated settings and foreign hook handlers. Stage writes, serialize nodeterm writers,
+ and compare the original bytes again before publishing; never use `cat … || echo '{}'` or a
+ catch-all read fallback. Local and SSH symlinked profiles update and lock the resolved target without replacing
+ the link; recheck resolution before publishing. SSH uses plain readlink and cd -P (no GNU -f),
+ and refuses dangling/cyclic links and newline paths. A conflicting/stale lock skips installation
+ with a diagnostic naming the lock and safe manual recovery; do not steal it from another process. These locks
+ coordinate nodeterm, not external editors, so do not claim a filesystem-wide compare-and-swap.
+ **Creating an agent node is not proof it started.** Control opens retain their launch command
+ until delivery is acknowledged, and report `queued` while it is held. A successful terminal send
+ proves delivery only; never describe it as a healthy/running agent without agent evidence.
+ Desktop launches (automatic and Run now) use the echo-verified command writer, not `sendText`.
+ Keep unsubmitted UI intent durable through shell settle/unmount. New intent carries `attempted:false`;
+ Desktop and Server save `attempted:true` before input. Never-attempted warm `--after` launches may
+ proceed after shell verification; attempted/legacy-unknown intent requires Run now. Only confirmed
+ submission clears intent. Desktop open replies use `createControlOpenBatch` for queued accounting;
+ protect that contract and concurrent submission with behavior tests, never source-text pins.
+ Relay queued/restored launches and Run now are refused until a scoped durable claim API exists.
+ A new relay UI initialCommand may run once on a fresh PTY through the verified writer, without
+ workspace writes or pendingLaunch creation. Consume its transient attempt before shell settle;
+ never retry it on remount or serialize it as durable intent.
+ Never round-trip a relay workspace load into save: the load can contain only one shared project,
+ while save replaces the entire host index. A pre-input parked-project deferral keeps intent
+ never-attempted; it must not poison the writer or trigger a retry timer.
+ Held Desktop launches retain their attached transport even offscreen with tmux (large fan-outs cost
+ memory). Server deferred delivery is one-shot: a failed probe/send needs explicit recovery.
+
## Testing
+ **Screenshot paste has one route per gesture.** On macOS, Cmd+V saves/uploads a file and
+ pastes its path; Ctrl+V belongs to the foreground program. A node's configured agent is not
+ proof of foreground clipboard-image support. Keep shell/SSH/Server file routing and capture
+ suppression of accompanying text; do not synthesize Ctrl+V or try both routes without a
+ capability and receipt protocol. The shortcuts panel documents this distinction (#712).
+
`npm test` must pass, and `npm run typecheck` is the fastest gate.
Beyond that, one habit is worth more than any other here: