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 remote-tracking branch 'origin/main' into fix/triage-711-20260923
review9cf183f2d552
diff --cc CONTRIBUTING.mdindex 92a26f913,ac203f4e4..0a513fe33--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@@ -611,13 -622,65 +622,70 @@@ examples). If the same effect also WRITmid-session applies stored state to whatever the user is doing right then, which is a differentfeature 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: