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(control): run-now text states its SSH, closed-tab and Server edges (#925)
reviewfb5321bb5339
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.tsindex 9688c026e..bcd08bd4e 100644--- a/src/core/canvas-control-core.ts+++ b/src/core/canvas-control-core.ts@@ -427,8 +427,8 @@ export function buildCanvasControlInstructions(shimPath: string): string {'a caller may mutate or message only nodes it opened during the current server run.','Restarting the server clears that creator proof; persisted nodes and queued launches are never','auto-adopted, relaunched, or controlled at boot. An unowned target receives a named refusal.',- 'On the Server Edition `--run-now` changes nothing (opens start at once) and `run` reaches only',- 'nodes you opened during this server run.',+ 'On the Server Edition `--run-now` changes nothing else (opens start at once; the `--after`',+ 'refusal still applies) and `run` reaches only nodes you opened during this server run.','','Verbs:','- `list` — current nodes (id, kind, title). Start here when you need a node id.',@@ -455,8 +455,9 @@ export function buildCanvasControlInstructions(shimPath: string): string {' Add `--run-now` (put it LAST on the line, or write `--run-now=1`) to start a cold-opened',' session immediately instead: it starts headless while the user stays where they are, the',' reply reports `started: true` with `startedIds`, and a closed project gets its tab restored',- ' (not switched to). `--run-now` cannot be combined with `--after`. A start that could not be',- ' delivered still reports `queued` with a `reason`, and the node keeps its Run now button.',+ ' (not switched to), except for an SSH project or when no project is open.',+ ' `--run-now` cannot be combined with `--after`. A start that could not be delivered still',+ ' reports `queued` with a `reason`, and the node keeps its Run now button.',' `--project <id>` opens the node(s) in another',' project instead of yours. It accepts exactly two things — any other id is refused: your OWN',' project id, which behaves exactly as if the flag were omitted; or an id `open-project`',@@ -557,8 +558,10 @@ export function buildCanvasControlInstructions(shimPath: string): string {' failed to launch is refused with `run-not-mounted`: the user must bring it into view and press',' Run now. A node in another project needs `--project <id>` (your own project, or an id',' `open-project` returned to you). The reply says `started: true`, or `queued: true` with a',- ' `reason` — `remote-unsupported` for an SSH project\'s node, which starts when the user views',- ' it. A node with nothing queued is refused.',+ ' `reason`. `remote-unsupported` is an SSH project\'s node while that project is not on screen:',+ ' its launch is left exactly as it was, so a plain queued launch starts when the user views the',+ ' project, and an armed or failed one still needs its wait or Run now.',+ ' A node with nothing queued is refused.',`- \`color --node <id,id> --color C\` — recolor nodes, frames, or stickies. C is a palette NAME`,` or its hex: ${nodeColorChoices()}. The agent names paint a node its CLI's own brand color.`,'- `write --node <id> --text "..."` / `close --node <id,id>` — type into / close nodes.',@@ -900,8 +903,8 @@ Server Edition ownership is fail-closed: every request requires verified node idcaller may mutate or message only nodes it opened during the current server run. Restartingthe server clears that creator proof; persisted nodes and queued launches are never auto-adopted,relaunched, or controlled at boot. An unowned target receives a named refusal. On the Server-Edition \`--run-now\` changes nothing (opens start at once) and \`run\` reaches only-nodes you opened during this server run.+Edition \`--run-now\` changes nothing else (opens start at once; the \`--after\` refusal still+applies) and \`run\` reaches only nodes you opened during this server run.Verbs:- \`list\` — list current nodes (id, kind, title). Start here when you need a node id.@@ -947,8 +950,9 @@ Verbs:Add \`--run-now\` (put it LAST on the line, or write \`--run-now=1\`) to start a cold-openedsession immediately instead: it starts headless while the user stays where they are, the replyreports \`started: true\` with \`startedIds\`, and a closed project gets its tab restored (not- switched to). \`--run-now\` cannot be combined with \`--after\`. A start that could not be- delivered still reports \`queued\` with a \`reason\`, and the node keeps its Run now button.+ switched to), except for an SSH project or when no project is open. \`--run-now\` cannot be+ combined with \`--after\`. A start that could not be delivered still reports \`queued\` with a+ \`reason\`, and the node keeps its Run now button.**The reply reports launch delivery, not agent health.** \`queued\` is true — and\`queuedIds\` names which of the returned ids — while launch delivery is pending: waiting for its PTY, or on\`--after\`, on a worktree's setup script, or on a project the user has not viewed yet (a@@ -1085,9 +1089,10 @@ Verbs:is not mounted (released while out of view) and that waits on \`--after\` or already failed tolaunch is refused with \`run-not-mounted\`: the user must bring it into view and press Run now.A node in another project needs \`--project <id>\` (your own project, or an id \`open-project\`- returned to you). The reply says \`started: true\`, or \`queued: true\` with a \`reason\` —- \`remote-unsupported\` for an SSH project's node, which starts when the user views it. A node- with nothing queued is refused.+ returned to you). The reply says \`started: true\`, or \`queued: true\` with a \`reason\`.+ \`remote-unsupported\` is an SSH project's node while that project is not on screen: its launch+ is left exactly as it was, so a plain queued launch starts when the user views the project, and+ an armed or failed one still needs its wait or Run now. A node with nothing queued is refused.- \`color --node <id,id> --color C\` — recolor nodes, frames, or stickies. C is a palette NAME orits hex (either is accepted, and the hex is case-insensitive): ${nodeColorChoices()}.The agent names are that CLI's own brand color — \`--color claude\` paints a node the color adiff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.tsindex fa529a40b..14071d91e 100644--- a/src/main/canvas-control-core.test.ts+++ b/src/main/canvas-control-core.test.ts@@ -121,13 +121,26 @@ describe('parseControlRequest', () => {// terminal is not mounted, armed or failed, is refused — the mount will not fire it.expect(body, name).toContain('`run-not-mounted`')expect(body, name).not.toMatch(/and it skips an `--after` wait/)- // An SSH project's node cannot start headless: it stays queued with that reason.+ // An SSH project's node cannot start headless: it stays queued with that reason, and only+ // while its project is off screen. `startHeadless` refuses before any claim, so the launch+ // is untouched — a plain one starts on view, an armed or failed one still waits (review+ // fix 1: "which starts when the user views it" over-promised for those two).expect(body, name).toContain('`remote-unsupported`')+ expect(body, name).toMatch(/while that project is not on\s+screen/)+ expect(body, name).toMatch(/left exactly as it\s+was/)+ expect(body, name).toMatch(/armed or failed one still\s+needs its wait or Run now/)+ expect(body, name).not.toMatch(/which starts when the user views it/)+ // The closed-tab restore has two exceptions in the code (Canvas.tsx startNodesHeadlessRef): an SSH+ // project, and no project open (the welcome screen). The claim must not read as universal.+ expect(body, name).toMatch(/tab restored\s+\(not\s+switched\s+to\), except for an SSH\s+project or when\s+no\s+project is open/)// `list` prints STARTING while a headless start is in flight, and says not to run it again.expect(body, name).toMatch(/`list` names QUEUED, STARTING,/)expect(body, name).toMatch(/STARTING means a background start is in flight/)- // The Server Edition: --run-now is a no-op there, and `run` is creator-owned.- expect(body, name).toMatch(/On the Server\s+Edition `--run-now` changes\s+nothing \(opens start at once\)/)+ // The Server Edition: --run-now changes nothing ELSE there (the --after refusal still+ // applies — review ruling 3), and `run` is creator-owned.+ expect(body, name).toMatch(+ /On the Server\s+Edition `--run-now` changes\s+nothing else \(opens start at once; the\s+`--after`\s+refusal still\s+applies\)/+ )expect(body, name).toMatch(/`run` reaches only\s+nodes you opened during this server run/)}})