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
docs: record the third canvas-control verb tier and what it owes
Bas Miliusb632c1e7f1bd
diff --git a/CLAUDE.md b/CLAUDE.mdindex 420fcd56d..cca7c94fe 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1783,7 +1783,7 @@ else, and its context links must keep classifying across restarts).originally did with the answer was TRAVEL there (`travelToProjectRef`), and that was a screenhijack: the user looks at project B, an agent in project A runs `open-claude`, the tab switchesand A's saved viewport is applied, so the camera appears to jump and zoom on a background agent's- say-so. Two membership lists now decide, and their difference is the whole design:+ say-so. THREE membership lists now decide, and their differences are the whole design:- `STORE_ANSWERED_VERBS` (`needsLiveCanvas` false) = **no canvas is needed at either end** —`list` reads names, `send`/`reply` deliver into a tmux PANE, `sticky` rewrites a note,`open-project` acts on the projects store.@@ -1794,10 +1794,42 @@ else, and its context links must keep classifying across restarts).node is upserted through `applyNodeMutation`, edges go through `appendCanvasLinks` (the edgecounterpart, so the opener's rope and the fan-in bridge are not lost), `writeDisk` persists, andthe reply is the ONE shared `coldOpenMessage` sentence with `queued: true`.+ - `OFF_CANVAS_VERBS` (`answersOffCanvas` — `show-image`/`show-video`/`show-web`/`open-browser`)+ = **a canvas is needed, the serialized one will do, and there is nothing to defer.** The node+ these make has no session behind it: a page, a video, an image, a browser node is inert+ wherever it sits, so writing it into the owning project's serialized nodes IS the whole effect+ and it is complete when `writeDisk` returns. That is why it is a third set and not four more+ entries in the second one — a cold open reports `queued: true`, and a caller told its+ screenshot is queued waits for something that already happened. It gets+ `offCanvasReplyClause` and `offCanvas: true` instead. **This was the half the cold-open fix+ left open, and it is the half an agent meets most often**: a skill that renders its report as+ HTML reaches for `show-web` every time it finishes, and every one of those calls used to yank+ the user out of the project they were typing in. The verb bodies are untouched; three things+ they read from the canvas are staged — the colour index (`nodeCount`), the placement source+ (the stored node, hydrated through `nodeStatesToFlow` so its shape cannot drift from a live+ one's) and the append, where `applyNodeMutation` + `appendCanvasLinks` + `writeDisk` replace+ `setNodes` + `connect` + `markDirty`. The opener's edge is a **rope** and only a rope: a+ display node has nothing to read, so a bridge there would grant a context link the live path+ never draws. **`ctlProject` resolves from the SOURCE's project**, not the active one — off+ canvas it decides the ssh flag, the browser session key and the media allowlist route; on+ every other path the travel has already made the two the same project. None of the four takes+ `--group`, which is why this set owes no worktree question; a verb joining it that does would,+ because `cwdForNewNodeIn` subtracts `staleGroupIds`, which is epoch-scoped to the ACTIVE+ project.Everything else keeps travelling **on purpose**: `write`/`close`/`group`/`move`/`arrange`/- `align`/`verify`/`spawn-team`/`open-worktree`/`open-browser`/`show-*` read live canvas state the- serialized copy does not carry (measured node sizes, worktree staleness, the React Flow edge- arrays). Route `active` is byte-identical to before. Route **`reopen` (a CLOSED project) cold-writes+ `align`/`verify`/`spawn-team`/`open-worktree` read live canvas state the serialized copy does not+ carry (measured node sizes, worktree staleness, the React Flow edge arrays). **`browser` is the+ pair worth stating beside `open-browser`**: it NAVIGATES a mounted `<webview>` guest, which+ exists only while its project is on screen, so it travels; `open-browser` merely places the node+ and its guest is created when that project is next shown, exactly as a cold-opened terminal's PTY+ is. Route `active` is byte-identical to before.+ **The human is told, once, in the other voice.** The reply goes to the agent; without a strip the+ person sees nothing at all, and the whole point of not travelling is that the choice to go and+ look stays theirs — a choice they can only make if they are told there is something to look at.+ `offCanvasNoticeText` names the project and the button is `travelToNode` (which reopens a closed+ project first and resolves off the SERIALIZED nodes the write has already made). It is **sticky**:+ every other info strip reports something the user just did and is watching, this one reports work+ that landed while they were busy elsewhere, and once it fades nothing anywhere says it happened. Route **`reopen` (a CLOSED project) cold-writestoo and does NOT reopen the tab** — closing is the user's explicit "park this, keep it running", sorestoring the tab *and* activating it is the loudest form of the hijack; the reply names the closureso a caller does not report a session as started. On the cold path `--group`/`--after` ARE resolveddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 0323b48ae..779afcc4d 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -289,15 +289,27 @@ retry anywhere, ask what the clock actually starts on and where its exhaustion bSOURCE, and React Flow holds only the ACTIVE project's nodes — so the dispatch used to travel to thecaller's project before answering. For an OPEN that was a screen hijack: the user is looking atproject B, an agent in project A runs `open-claude`, the tab switches and A's saved viewport is-applied, so the camera appears to jump and zoom. The rule now has two tiers, both membership lists in-`renderer/lib/controlRouting.ts`: `STORE_ANSWERED_VERBS` ("no canvas is needed at either end" —-`list`, `send`, `reply`, `sticky`, `open-project`) and `canColdOpen` ("a canvas IS needed, but the+applied, so the camera appears to jump and zoom. The rule now has three tiers, all membership lists+in `renderer/lib/controlRouting.ts`: `STORE_ANSWERED_VERBS` ("no canvas is needed at either end" —+`list`, `send`, `reply`, `sticky`, `open-project`), `canColdOpen` ("a canvas IS needed, but theserialized one will do" — `open-terminal`, `open-claude`, `open-agent`, which write into the owning-project's stored nodes with their launch armed and report `queued: true`). Everything that acts on-nodes which already exist still travels, because it reads live state the serialized copy does not-carry. When you add a verb, decide which tier it is in — and if you change what a verb DOES, update-`buildCanvasSkillBody` / `buildCanvasControlInstructions` in the same PR, with a test that goes red-on the stale claim (`src/main/canvas-control-core.test.ts`).+project's stored nodes with their launch armed and report `queued: true`) and `answersOffCanvas`+("…and there is nothing to defer" — `show-image`, `show-video`, `show-web`, `open-browser`, whose+node has no session behind it and is finished the moment it is written, so it reports `offCanvas:+true` and never `queued`). Everything that acts on nodes which already exist still travels, because+it reads live state the serialized copy does not carry — `browser` included, which navigates a+mounted `<webview>` guest, unlike `open-browser`, which only places the node.++Three things to carry over when you put a verb in one of the two off-screen tiers. **The acting+project is the SOURCE's**: `ctlProject` decides the ssh flag, the browser session key and the media+allowlist route, and reading `activeProjectId` there answers a background agent with whatever the+human is looking at. **Nothing may reach the live canvas**: `setNodes` / `setControlEdges` /+`markDirty` address the ACTIVE project, so the write goes through `applyNodeMutation` ++`appendCanvasLinks` + `writeDisk`. And **tell the human** — the reply goes to the agent, so without+a strip nothing anywhere reports that a node landed in another project; it is sticky, because it+describes work the user was not watching. When you add a verb, decide which tier it is in — and if+you change what a verb DOES, update `buildCanvasSkillBody` / `buildCanvasControlInstructions` in the+same PR, with a test that goes red on the stale claim (`src/main/canvas-control-core.test.ts`).**Pointing a project at a folder is a WRITE — probe before you bind.** A project's canvas iswritten to `<cwd>/.nodeterm/project.json`, so the moment a project gains a `cwd` the next autosave