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
fix(canvas-control): a display verb no longer moves the user's view either
Bas Milius8044a37f7cc9
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex ca4761b7d..dc72d35c8 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -247,6 +247,7 @@ import {routeControlSource,needsLiveCanvas,canColdOpen,+ answersOffCanvas,sourceIsControlCapable,storedNodeListing,answerBrowserResolve,@@ -257,6 +258,8 @@ import {coldGroupChildCount,coldOpenMessage,coldPlaceBelow,+ offCanvasNoticeText,+ offCanvasReplyClause,coldResolveAfter,coldResolveGroup,groupSizeFor,@@ -939,9 +942,19 @@ export function Canvas() {// Result of a worktree operation (merge / remove). These used to be `window.alert`s — a modal// that blocks the whole app to say "Merged feat into main." Shown as a strip in the existing// top-banner column instead; an 'info' one fades itself out, an 'error' stays until dismissed.- const [notice, setNotice] = useState<{ kind: 'info' | 'error'; text: string } | null>(null)+ // `sticky` opts an info strip out of the fade. The dwell exists because a worktree result+ // reports something the user just did and is watching; an off-canvas notice reports work that+ // landed in ANOTHER project while they were busy elsewhere, and once it fades nothing anywhere+ // says it happened. `action` is an ordinary next step, not an install or a reload, so it wears+ // the app's default button rather than `.announce-banner__btn`'s accent treatment.+ const [notice, setNotice] = useState<{+ kind: 'info' | 'error'+ text: string+ sticky?: boolean+ action?: { label: string; run: () => void }+ } | null>(null)useEffect(() => {- if (notice?.kind !== 'info') return+ if (notice?.kind !== 'info' || notice.sticky) returnconst t = setTimeout(() => setNotice(null), noticeDwellMs(notice.text))return () => clearTimeout(t)}, [notice])@@ -5808,6 +5821,9 @@ export function Canvas() {// Same reason as worktreeControlRef below: the agent-control handler needs the CURRENT// travelToProject (defined far below, after the project actions it composes).const travelToProjectRef = useRef<(projectId: string) => void>(() => {})+ /** Latest `travelToNode`, for the agent-control handler's off-canvas notice — same reason as+ * travelToProjectRef: that effect mounts ONCE, so it cannot close over the callback. */+ const travelToNodeRef = useRef<(nodeId: string) => void>(() => {})// Latest worktree callbacks for the agent-control handler. That effect mounts ONCE (empty// deps) and these callbacks' identities change with the active project (activeProjectId /@@ -8856,8 +8872,35 @@ export function Canvas() {// main never hangs to its 120s timeout.useEffect(() => {return api.onAgentControl(async ({ requestId, sourceNodeId, verb, args }) => {- const reply = (r: { ok: boolean; message?: string; result?: unknown; error?: string }) =>+ // Set by the OFF-CANVAS branch below (`answersOffCanvas`): the verb runs against the owning+ // project's SERIALIZED nodes because that project is not on screen. It stays undefined on+ // every other path, which is what makes the on-screen behaviour byte-identical.+ let offCanvas: { project: Project; closed: boolean; created: string[] } | undefined+ const reply = (r: { ok: boolean; message?: string; result?: unknown; error?: string }) => {+ // Say WHERE it went, once, in both voices. The verb bodies already say WHAT they made, so+ // none of them has to know about routing: the clause is appended here and the human strip+ // is raised here. A refusal decorates nothing — it created no node and moved no view.+ if (offCanvas && r.ok && offCanvas.created.length) {+ const { project, closed, created } = offCanvas+ r = {+ ...r,+ message: (r.message ?? '') + offCanvasReplyClause(project.name, { closed }),+ result: { ...(r.result as object), projectId: project.id, offCanvas: true }+ }+ const first = created[0]+ setNotice({+ kind: 'info',+ sticky: true,+ text: offCanvasNoticeText(project.name, created.length),+ // The notice is about one thing that appeared, so the button goes to that thing —+ // `travelToNode` reopens a closed project first and resolves off the SERIALIZED nodes,+ // which the write above has already made. Landing on the project's saved camera+ // instead would leave the user hunting for it.+ action: { label: 'Go there', run: () => travelToNodeRef.current(first) }+ })+ }api.sendAgentControlResult({ requestId, ...r })+ }// `--dry-run` (issue #532): validate + report, mutate nothing. Only DRY_RUN_VERBS reach// this process with the flag set — main's setControlHandler refuses it for every other// verb before forwarding — so the per-case branches below are the whole renderer story:@@ -9574,13 +9617,45 @@ export function Canvas() {})return}- travelToProjectRef.current(route.projectId)+ // ── OFF CANVAS ──────────────────────────────────────────────────────────────────+ // A DISPLAY verb (`show-image` / `show-video` / `show-web` / `open-browser`) whose own+ // project is not on screen. Same objection as the cold open above and the same answer,+ // one set wider: an agent that renders its output as a node is the commonest reason a+ // background session touches the canvas at all, and every one of those calls used to+ // yank the human out of the project they were typing in.+ //+ // The difference from the cold open is that there is nothing to defer. These four make+ // an INERT node — a page, a video, an image, a browser — which is complete the moment it+ // is written, so the verb body runs unchanged and only the three things it touches on+ // the canvas are staged: the node counter, the placement source, and the append.+ // See `answersOffCanvas` in lib/controlRouting for why `browser` is not in the set.+ if (answersOffCanvas(verb)) {+ const ocStore = useProjects.getState()+ const owner = ocStore.getProject(route.projectId)+ const ocSrc = owner?.nodes.find((n) => n.id === sourceNodeId)+ // Same authorization boundary and the same sentence as every other path — a stored+ // node carries the agent id the live one would (`data.agentId` is serialized).+ if (!owner || !ocSrc || !sourceIsControlCapable(ocSrc.agentId)) {+ reply({ ok: false, error: 'source node is not a control-capable agent' })+ return+ }+ offCanvas = { project: owner, closed: route.kind === 'reopen', created: [] }+ // The body below reads the source for its title, cwd and placement geometry. Hydrate+ // the ONE stored node rather than hand-rolling a partial: `nodeStatesToFlow` is what+ // the project load itself uses, so the shape cannot drift from a live node's. It has+ // no `measured` (nothing rendered it), which `placeBelow` already falls back for.+ src = nodeStatesToFlow([ocSrc])[0] as CanvasNode+ } else {+ travelToProjectRef.current(route.projectId)+ }}// Wait for the node to show up on the canvas: after a travel, because the active-project// effect hydrates React Flow a tick later; on `active`, because a control call can land// while the BOOT load of the owning project is still in flight — the very moment a// re-adopted agent starts talking again. `unknown`/`blocked` have no canvas to wait for.- if (route.kind !== 'unknown' && route.kind !== 'blocked') {+ // An off-canvas answer has its source already and is deliberately NOT waiting for a+ // canvas: waiting for one is what travelling was for.+ if (!offCanvas && route.kind !== 'unknown' && route.kind !== 'blocked') {src = await waitForCanvasNode(() => nodesRef.current.find((n) => n.id === sourceNodeId))}}@@ -9606,10 +9681,16 @@ export function Canvas() {// got it right; every control verb passed `undefined` and got it wrong.) The factory reads// the node's cwd out of `remoteCwd`, so the effective cwd is threaded through there —// otherwise `--cwd` would be silently replaced by the project root.- const ctlProject = (() => {- const st = useProjects.getState()- return st.getProject(st.activeProjectId ?? '')- })()+ // Off canvas the two are different projects, and this one decides the ssh flag, the browser+ // session key and the media allowlist route. Reading `activeProjectId` there would answer a+ // background agent's call with whatever the human happens to be looking at; on every other+ // path the travel has already made the two the same project, so nothing changes.+ const ctlProject =+ offCanvas?.project ??+ (() => {+ const st = useProjects.getState()+ return st.getProject(st.activeProjectId ?? '')+ })()const ctlSsh = ctlProject?.sshconst sshFor = (cwd?: string) => nodeSshFor(ctlSsh, cwd)// Place opened nodes BELOW the source and rope them to it (source flow-out → target@@ -9678,11 +9759,33 @@ export function Canvas() {// relative coords) must pass through untouched — re-running parentInto would read its// relative position as absolute and land it off-frame.const placed = node.parentId ? node : src.parentId ? parentInto(node, src.parentId) : node+ if (offCanvas) {+ // The staged twin of the three lines below, and the whole of the off-canvas write. The+ // live setters all address the ACTIVE canvas, which is some other project's here — they+ // would put the node in front of the wrong person and dirty the wrong file.+ // `applyNodeMutation` + `appendCanvasLinks` are the store paths a peer mutation and the+ // cold open already take, and `writeDisk` is what persists them.+ const ocStore = useProjects.getState()+ ocStore.applyNodeMutation(offCanvas.project.id, {+ op: 'upsert',+ node: flowToNodeStates([placed])[0]+ })+ ocStore.appendCanvasLinks(offCanvas.project.id, {+ ropes: [ropeEdge(`ctrl-${sourceNodeId}-${placed.id}`, sourceNodeId, placed.id)]+ })+ void writeDisk()+ offCanvas.created.push(placed.id)+ return placed.id+ }setNodes((ns) => [...ns, placed])connect(placed.id)markDirty()return placed.id}+ // The colour index every factory takes. Off canvas the live array holds another project's+ // nodes, so counting it would colour by a number that has nothing to do with where the node+ // lands. One name for the two sources, so no verb body has to ask which it is on.+ const nodeCount = () => (offCanvas ? offCanvas.project.nodes.length : nodesRef.current.length)// Grid slots INSIDE a group frame (open-agent --group): 2 columns of terminal-sized// cells under the header. Pure geometry — the frame is grown to fit before children land.// `groupSlot`/`groupSizeFor` live in lib/coldOpen so the COLD path (an open answered out of a@@ -10087,7 +10190,7 @@ export function Canvas() {// (`sshFs` routes fs.readBinary over the ControlMaster) — reading it locally would// either miss or, worse, open a same-named local file.const id = addAndConnect(- createEditorNode(nodesRef.current.length, args.path, placeBelow(), !!ctlSsh)+ createEditorNode(nodeCount(), args.path, placeBelow(), !!ctlSsh))reply({ ok: true, message: `showing image ${id}`, result: { id } })return@@ -10103,7 +10206,7 @@ export function Canvas() {// same-named local file. Local projects allowlist the local path as before.if (!ctlSsh) await window.nodeTerminal.media.allow(args.path)const id = addAndConnect(- createVideoNode(nodesRef.current.length, args.path, placeBelow(), !!ctlSsh)+ createVideoNode(nodeCount(), args.path, placeBelow(), !!ctlSsh))reply({ ok: true, message: `showing video ${id}`, result: { id } })return@@ -10130,7 +10233,7 @@ export function Canvas() {}// For an agent-provided --file (not html we just wrote), allowlist it first.if (webSrc.filePath && args.file) await window.nodeTerminal.media.allow(webSrc.filePath)- const id = addAndConnect(createWebNode(nodesRef.current.length, webSrc, placeBelow()))+ const id = addAndConnect(createWebNode(nodeCount(), webSrc, placeBelow()))reply({ ok: true, message: `showing web ${id}`, result: { id } })return}@@ -10154,7 +10257,7 @@ export function Canvas() {reply({ ok: false, error: "open-browser: this project's id cannot be used as a browser session key" })return}- const id = addAndConnect(createBrowserNode(nodesRef.current.length, browserUrl, placeBelow(), partition))+ const id = addAndConnect(createBrowserNode(nodeCount(), browserUrl, placeBelow(), partition))// Return the project id + partition so main can record ownership in its in-memory// ledger (browser-control-ledger.ts). Main gates the claim on its OWN `verified` verdict// and keys it to the verified caller — these fields are descriptive (release-by-project,@@ -12582,6 +12685,12 @@ export function Canvas() {[focusNodeById, reopenProject])+ // Published BELOW the callback it mirrors, not above it: an effect placed earlier would read a+ // const that is only initialized later in the body. That works today and breaks on a reorder.+ useEffect(() => {+ travelToNodeRef.current = travelToNode+ })+// OS-notification click → focus the originating node (see the note beside focusNodeById:// travelToNode, not focusNodeById, so a closed project's tab is reopened first).useEffect(() => window.nodeTerminal.onFocusNode(travelToNode), [travelToNode])@@ -13055,6 +13164,18 @@ export function Canvas() {<div className="announce-banner__content"><span className="announce-banner__body">{notice.text}</span></div>+ {notice.action && (+ <button+ className="announce-banner__action"+ onClick={() => {+ const run = notice.action?.run+ setNotice(null)+ run?.()+ }}+ >+ {notice.action.label}+ </button>+ )}<buttonclassName="announce-banner__close"title="Dismiss"diff --git a/src/renderer/canvas/control-cold-open.source.test.ts b/src/renderer/canvas/control-cold-open.source.test.tsindex 4342b85d3..d348aebd3 100644--- a/src/renderer/canvas/control-cold-open.source.test.ts+++ b/src/renderer/canvas/control-cold-open.source.test.ts@@ -18,13 +18,15 @@ import { readFileSync } from 'node:fs'*/const src = readFileSync(new URL('./Canvas.tsx', import.meta.url), 'utf8').replace(/\r\n/g, '\n')-/** The cold-open block: from its `if (canColdOpen(verb))` guard to the travel call it stands in- * front of. */+/** The cold-open block: from its `if (canColdOpen(verb))` guard to the off-canvas guard that+ * follows it. Bounded by that guard rather than by the travel call further down, so the pins+ * below judge THIS block and never inherit a passing verdict from the one after it — the two are+ * separate branches with separate contracts (`control-off-canvas.source.test.ts`). */function coldOpenBody(): string {const start = src.indexOf('if (canColdOpen(verb)) {')expect(start, 'the cold-open guard').toBeGreaterThan(-1)- const end = src.indexOf('travelToProjectRef.current(route.projectId)', start)- expect(end, 'the travel call after the block').toBeGreaterThan(start)+ const end = src.indexOf('if (answersOffCanvas(verb)) {', start)+ expect(end, 'the off-canvas guard after the block').toBeGreaterThan(start)return src.slice(start, end)}diff --git a/src/renderer/canvas/control-off-canvas.source.test.ts b/src/renderer/canvas/control-off-canvas.source.test.tsnew file mode 100644index 000000000..8fac0d784--- /dev/null+++ b/src/renderer/canvas/control-off-canvas.source.test.ts@@ -0,0 +1,181 @@+import { describe, it, expect } from 'vitest'+import { readFileSync } from 'node:fs'++/**+ * STRUCTURAL pins for the OFF-CANVAS branch of the canvas-control dispatch — the sibling of+ * `control-cold-open.source.test.ts`, and for the same reason: the branch lives inside a+ * 12,000-line React component's IPC listener with no unit seam, and what it must be pinned on are+ * properties of the SOURCE.+ *+ * Every behavioural half is proven separately against real primitives: the verb set and its+ * disjointness from the other two in `lib/controlRouting.test.ts`, the reply clause and the notice+ * copy in `lib/coldOpen.test.ts`, the edge append in `state/projects.links.test.ts`.+ *+ * THE BUG this closes, which the cold-open fix left open: the user is looking at project B; an+ * agent in project A renders its output as a node — a report as `show-web`, a screenshot as+ * `show-image` — and the app switched to A. Those are the commonest reason a background session+ * touches the canvas at all, so the fix that covered `open-claude` covered the rarer half.+ */+const src = readFileSync(new URL('./Canvas.tsx', import.meta.url), 'utf8').replace(/\r\n/g, '\n')++/** The off-canvas block: from its `if (answersOffCanvas(verb))` guard to the travel call it stands+ * in front of. */+function offCanvasBody(): string {+ const start = src.indexOf('if (answersOffCanvas(verb)) {')+ expect(start, 'the off-canvas guard').toBeGreaterThan(-1)+ const end = src.indexOf('travelToProjectRef.current(route.projectId)', start)+ expect(end, 'the travel call after the block').toBeGreaterThan(start)+ return src.slice(start, end)+}++/** Line comments explain what a block must NOT do, so a negative pin has to judge the code. */+function code(body: string): string {+ return body+ .split('\n')+ .filter((l) => !l.trim().startsWith('//'))+ .join('\n')+}++/** The `addAndConnect` helper, whose off-canvas half is the whole write. */+function addAndConnectBody(): string {+ const start = src.indexOf('const addAndConnect = (node: CanvasNode) => {')+ expect(start, 'addAndConnect').toBeGreaterThan(-1)+ const end = src.indexOf('const nodeCount = ()', start)+ expect(end, 'nodeCount after it').toBeGreaterThan(start)+ return src.slice(start, end)+}++describe('the off-canvas dispatch block (source pins)', () => {+ it('stands IN FRONT of the travel call — a display verb never reaches it', () => {+ // The travel call is what moved the user's screen. Scoped to the dispatch's source-routing+ // block (Canvas has one other, unrelated travel for the browser-verb guest lookup), the+ // off-canvas guard must precede the single travel in it, or the block is dead code sitting+ // behind the very thing it replaces.+ const from = src.indexOf('routeControlSource(projects, activeId, sourceNodeId)')+ expect(from, 'the source-routing lookup').toBeGreaterThan(-1)+ const to = src.indexOf('waitForCanvasNode(', from)+ expect(to, 'the post-routing canvas wait').toBeGreaterThan(from)+ const routing = src.slice(from, to)+ expect(routing.match(/travelToProjectRef\.current\(route\.projectId\)/g)?.length).toBe(1)+ const guard = routing.indexOf('if (answersOffCanvas(verb)) {')+ const travel = routing.indexOf('travelToProjectRef.current(route.projectId)')+ expect(guard, 'the off-canvas guard inside the routing block').toBeGreaterThan(-1)+ expect(guard).toBeLessThan(travel)+ // …and the travel is its ELSE, so the two are exclusive by construction rather than by a+ // `return` someone can move.+ expect(routing).toMatch(/\} else \{\s*travelToProjectRef\.current\(route\.projectId\)/)+ })++ it('the guard polarity is not inverted', () => {+ expect(src).toContain('if (answersOffCanvas(verb)) {')+ expect(src).not.toContain('if (!answersOffCanvas(verb))')+ })++ it('never travels, activates, reopens or moves the camera', () => {+ // The whole point. A "Go there" button exists and is the user's to press; nothing here presses+ // it for them.+ const body = code(offCanvasBody())+ expect(body).not.toContain('travelToProject')+ expect(body).not.toContain('travelToNodeRef')+ expect(body).not.toContain('setActive')+ expect(body).not.toContain('reopenProject')+ expect(body).not.toContain('goToNode')+ expect(body).not.toContain('focusNodeById')+ })++ it('does NOT wait for a canvas — waiting for one is what travelling was for', () => {+ // `waitForCanvasNode` polls the LIVE nodes for the source. Off canvas that node is never+ // going to appear there, so an ungated wait would burn the whole timeout and then answer+ // "source node is not on an open canvas" — a refusal for being off-screen, which is exactly+ // what cecb4dfe removed.+ expect(src).toContain('if (!offCanvas && route.kind !== \'unknown\' && route.kind !== \'blocked\') {')+ })++ it('keeps cecb4dfe’s fix: the only source refusal is the capability sentence', () => {+ const body = code(offCanvasBody())+ expect(body).toContain("error: 'source node is not a control-capable agent'")+ expect(body).not.toContain('is not on an open canvas')+ expect(body).not.toContain('not the active project')+ })++ it('resolves the source from the OWNING project’s serialized nodes', () => {+ const body = offCanvasBody()+ expect(body).toContain('ocStore.getProject(route.projectId)')+ expect(body).toMatch(/owner\?\.nodes\.find\(\(n\) => n\.id === sourceNodeId\)/)+ // Hydrated with the same transform the project load uses, so the shape cannot drift from a+ // live node's — the verb bodies read `src.data.title`, `src.data.cwd` and its geometry.+ expect(body).toContain('nodeStatesToFlow([ocSrc])[0]')+ })++ it('the acting project is the SOURCE’s, not whatever is on screen', () => {+ // `ctlProject` decides the ssh flag, the browser session key and the media allowlist route.+ // Reading `activeProjectId` off canvas answers a background agent with the human's project.+ expect(src).toMatch(/const ctlProject =\s*\n\s*offCanvas\?\.project \?\?/)+ })++ it('writes through the store, never into the live canvas', () => {+ // React Flow holds the ACTIVE project's nodes. `setNodes` / `setControlEdges` / `markDirty`+ // would put the node in front of the wrong person and dirty the wrong file.+ const body = addAndConnectBody()+ const off = code(body.slice(body.indexOf('if (offCanvas) {'), body.indexOf('setNodes((ns) =>')))+ expect(off.length).toBeGreaterThan(0)+ expect(off).toContain('applyNodeMutation(offCanvas.project.id, {')+ expect(off).toContain('appendCanvasLinks(offCanvas.project.id, {')+ expect(off).toContain('writeDisk()')+ expect(off).not.toContain('setNodes(')+ expect(off).not.toContain('setControlEdges')+ expect(off).not.toContain('markDirty()')+ })++ it('the opener’s rope is written too — a display node still hangs off its agent', () => {+ // Same edge the live path's `connect` draws, under the same id, so the node reads as+ // "produced by that conversation" when the project is next shown.+ const body = addAndConnectBody()+ expect(body).toContain('ropeEdge(`ctrl-${sourceNodeId}-${placed.id}`, sourceNodeId, placed.id)')+ })++ it('the colour index comes from the owning project, not the live array', () => {+ expect(src).toContain(+ 'const nodeCount = () => (offCanvas ? offCanvas.project.nodes.length : nodesRef.current.length)'+ )+ // …and every display verb asks through it. A bare `nodesRef.current.length` in one of these+ // four cases compiles, passes every other test, and colours by a count from another project.+ // Scoped to the case bodies: these factories have unrelated callers (the user's own "open+ // file"), which legitimately count the live array because they land on the live canvas.+ for (const verb of ['show-image', 'show-video', 'show-web', 'open-browser']) {+ const at = src.indexOf(`case '${verb}': {`)+ expect(at, verb).toBeGreaterThan(-1)+ const body = src.slice(at, src.indexOf("\n case '", at + 1))+ expect(body.length, verb).toBeGreaterThan(0)+ expect(body, verb).toContain('nodeCount()')+ expect(body, verb).not.toContain('nodesRef.current')+ }+ })++ it('says WHERE it went in both voices, once, and only after a node was made', () => {+ // The reply the agent reads and the strip the human reads are raised in the same place, so+ // neither can be forgotten for a verb. `created.length` is the gate: a refusal and a+ // `--dry-run` decorate nothing, because they made nothing.+ const start = src.indexOf('const reply = (r: {')+ expect(start).toBeGreaterThan(-1)+ const decor = src.slice(start, src.indexOf('api.sendAgentControlResult({ requestId, ...r })', start))+ expect(decor).toContain('if (offCanvas && r.ok && offCanvas.created.length) {')+ expect(decor).toContain('offCanvasReplyClause(project.name, { closed })')+ expect(decor).toContain('offCanvasNoticeText(project.name, created.length)')+ expect(decor).toContain('sticky: true')+ expect(decor).toContain("label: 'Go there'")+ })++ it('a CLOSED project is written into, and both voices say so', () => {+ // The same choice route `reopen` gets on the cold path: restoring a tab AND activating it is+ // the loudest version of the hijack this fixes.+ expect(offCanvasBody()).toMatch(/closed: route\.kind === 'reopen'/)+ })++ it('the notice does not fade — it reports work the user was not watching', () => {+ // An info strip that reports something the user just did may fade; this one reports a node+ // that landed in another project while they were busy elsewhere, and once it fades nothing+ // anywhere says it happened.+ expect(src).toContain("if (notice?.kind !== 'info' || notice.sticky) return")+ })+})diff --git a/src/renderer/lib/coldOpen.test.ts b/src/renderer/lib/coldOpen.test.tsindex 52c728f01..b5f9a0736 100644--- a/src/renderer/lib/coldOpen.test.ts+++ b/src/renderer/lib/coldOpen.test.ts@@ -8,6 +8,8 @@ import {coldResolveGroup,groupSizeFor,groupSlot,+ offCanvasNoticeText,+ offCanvasReplyClause,storedAgentIdOf,type ColdNode} from './coldOpen'@@ -218,3 +220,42 @@ describe('coldOpenMessage — ONE sentence for both cold-open sites', () => {expect(closed).toContain('that project is closed')})})++describe('offCanvasReplyClause — the display verbs\' half of the same event', () => {+ it('is a CLAUSE, so the verb keeps saying what it made', () => {+ // Appended to `showing web nt-3f2a`, not instead of it: only the WHERE is new, which is what+ // lets the four case bodies stay ignorant of routing.+ expect(offCanvasReplyClause('api')).toBe(+ ' — placed in "api"; that project is not on screen'+ )+ })++ it('adds — and only adds — a clause when the project is CLOSED', () => {+ const open = offCanvasReplyClause('api')+ const closed = offCanvasReplyClause('api', { closed: true })+ expect(closed.startsWith(open)).toBe(true)+ expect(closed).toContain('reopen it from the welcome screen')+ })++ it('never claims the node is queued — it is complete when written', () => {+ // The distinction this builder exists for. A cold-opened SESSION has not started; a page, a+ // video or an image has. Telling a caller its screenshot is "queued" invites it to wait for+ // something that already happened.+ expect(offCanvasReplyClause('api')).not.toContain('queued')+ expect(offCanvasReplyClause('api')).not.toContain('starts when')+ })+})++describe('offCanvasNoticeText — the HUMAN half', () => {+ it('is an active-voice sentence naming the actor and the project', () => {+ expect(offCanvasNoticeText('api', 1)).toBe(+ 'An agent opened a node in "api". That project is not on screen.'+ )+ })++ it('counts, rather than saying "a node" for five', () => {+ expect(offCanvasNoticeText('api', 3)).toBe(+ 'An agent opened 3 nodes in "api". That project is not on screen.'+ )+ })+})diff --git a/src/renderer/lib/coldOpen.ts b/src/renderer/lib/coldOpen.tsindex 2d1da9872..5e17aa843 100644--- a/src/renderer/lib/coldOpen.ts+++ b/src/renderer/lib/coldOpen.ts@@ -218,3 +218,37 @@ export function coldOpenMessage((opts.closed ? ' (that project is closed — reopen it from the welcome screen)' : ''))}++/**+ * The clause appended to a display verb's own reply when the node landed in a project the user is+ * not looking at.+ *+ * A CLAUSE rather than a whole sentence, because the verb already said what it made ("showing web+ * nt-3f2a") and only the WHERE is new — so the four case bodies need to know nothing about+ * routing. Deliberately not `coldOpenMessage`: that one reports a session which has not started,+ * while a web page, a video or an image is COMPLETE the moment it is written, and telling a caller+ * its screenshot is "queued; starts when that project is next viewed" invites it to wait for+ * something that already happened. The `closed` clause is additive for the same reason it is+ * there: a caller told nothing would report the node as visible.+ */+export function offCanvasReplyClause(projectName: string, opts: { closed?: boolean } = {}): string {+ return (+ ` — placed in "${projectName}"; that project is not on screen` ++ (opts.closed ? ' and is closed (reopen it from the welcome screen)' : '')+ )+}++/**+ * The HUMAN half of the same event: a strip naming the project a background agent just wrote to.+ *+ * The reply above goes to the agent. Without this 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.+ *+ * Active voice and a full sentence. "A node opened by an agent in X." is a noun phrase, and the+ * passive repair ("was opened by") buries the actor the reader needs.+ */+export function offCanvasNoticeText(projectName: string, count: number): string {+ const what = count === 1 ? 'a node' : `${count} nodes`+ return `An agent opened ${what} in "${projectName}". That project is not on screen.`+}diff --git a/src/renderer/lib/controlRouting.test.ts b/src/renderer/lib/controlRouting.test.tsindex ba93786e7..cc2320140 100644--- a/src/renderer/lib/controlRouting.test.ts+++ b/src/renderer/lib/controlRouting.test.ts@@ -3,6 +3,7 @@ import {routeControlSource,needsLiveCanvas,canColdOpen,+ answersOffCanvas,controlVerbSetsForTests,sourceIsControlCapable,storedNodeListing,@@ -141,6 +142,58 @@ describe('canColdOpen — an OPEN is answered out of the store, not by moving th}})+ it('answers the four DISPLAY verbs off canvas, and nothing else', () => {+ for (const verb of ['show-image', 'show-video', 'show-web', 'open-browser']) {+ expect(answersOffCanvas(verb), verb).toBe(true)+ }+ for (const verb of [+ 'open-terminal',+ 'open-claude',+ 'open-agent',+ 'list',+ 'send',+ 'reply',+ 'sticky',+ 'open-project',+ 'write',+ 'close',+ 'group',+ 'ungroup',+ 'move',+ 'arrange',+ 'align',+ 'link',+ 'rename',+ 'color',+ 'verify',+ 'spawn-team',+ 'open-worktree',+ 'board',+ 'assign'+ ]) {+ expect(answersOffCanvas(verb), verb).toBe(false)+ }+ })++ it('keeps `browser` on the travelling path — it NAVIGATES a mounted guest', () => {+ // The one pair worth stating side by side. `open-browser` places a node, which a serialized+ // canvas can hold; `browser` drives an Electron <webview> guest that exists only while its+ // project is on screen. Adding it here would answer "navigated" about a guest that is not+ // there.+ expect(answersOffCanvas('open-browser')).toBe(true)+ expect(answersOffCanvas('browser')).toBe(false)+ expect(needsLiveCanvas('browser')).toBe(true)+ })++ it('the display verbs still NEED a canvas — off-canvas is the narrower claim again', () => {+ // Same relationship the cold-open set has to store-answered: these do need somewhere to put a+ // node, they just do not need the LIVE one. Collapsing them into STORE_ANSWERED_VERBS would+ // send `show-web` down the `list` branch and answer it with a node listing.+ for (const verb of ['show-image', 'show-video', 'show-web', 'open-browser']) {+ expect(needsLiveCanvas(verb), verb).toBe(true)+ }+ })+it('still NEEDS a canvas — cold-openable is a narrower claim than store-answered', () => {// The whole reason this is a second set: `needsLiveCanvas` stays TRUE for an open (it does// need somewhere to put the node), it just does not need the LIVE one. Collapsing the two@@ -151,12 +204,15 @@ describe('canColdOpen — an OPEN is answered out of the store, not by moving th}})- it('the two sets are DISJOINT', () => {- const { storeAnswered, coldOpenable } = controlVerbSetsForTests()+ it('the three sets are DISJOINT', () => {+ const { storeAnswered, coldOpenable, offCanvas } = controlVerbSetsForTests()expect(storeAnswered.filter((v) => coldOpenable.includes(v))).toEqual([])- // …and neither is empty, so the assertion above cannot pass vacuously.+ expect(storeAnswered.filter((v) => offCanvas.includes(v))).toEqual([])+ expect(coldOpenable.filter((v) => offCanvas.includes(v))).toEqual([])+ // …and none is empty, so the assertions above cannot pass vacuously.expect(storeAnswered.length).toBeGreaterThan(0)expect(coldOpenable.length).toBeGreaterThan(0)+ expect(offCanvas.length).toBeGreaterThan(0)})it('does NOT change which project answers — routing is still by source (cecb4dfe stands)', () => {diff --git a/src/renderer/lib/controlRouting.ts b/src/renderer/lib/controlRouting.tsindex 1281e7380..c804f27a7 100644--- a/src/renderer/lib/controlRouting.ts+++ b/src/renderer/lib/controlRouting.ts@@ -152,9 +152,10 @@ export function needsLiveCanvas(verb: string): boolean {* open needs somewhere to put the node, and a project's serialized nodes are somewhere.** Deliberately NOT here: every verb that acts on nodes that already exist (`write`, `close`,- * `group`, `move`, `arrange`, `align`, `verify`, `spawn-team`, `open-worktree`, `open-browser`,- * `show-*`). They read live canvas state — measured node sizes, worktree staleness, the React Flow- * edge arrays — that the serialized copy does not carry, so they keep travelling.+ * `group`, `move`, `arrange`, `align`, `verify`, `spawn-team`, `open-worktree`). They read live+ * canvas state — measured node sizes, worktree staleness, the React Flow edge arrays — that the+ * serialized copy does not carry, so they keep travelling. The verbs that create a node with no+ * session behind it are the third set below.*/const COLD_OPENABLE_VERBS: ReadonlySet<string> = new Set(['open-terminal',@@ -166,9 +167,52 @@ export function canColdOpen(verb: string): boolean {return COLD_OPENABLE_VERBS.has(verb)}-/** Test-only view of the two sets, so their disjointness can be asserted rather than eyeballed. */-export function controlVerbSetsForTests(): { storeAnswered: string[]; coldOpenable: string[] } {- return { storeAnswered: [...STORE_ANSWERED_VERBS], coldOpenable: [...COLD_OPENABLE_VERBS] }+/**+ * Verbs that create a DISPLAY node — one with no session behind it — and can therefore run against+ * the owning project's serialized nodes without that canvas being on screen.+ *+ * The third set, and the reason it is not folded into `COLD_OPENABLE_VERBS`: a cold open has a+ * launch to defer, so it moves the composed command into `pendingLaunch` and tells the caller the+ * session is QUEUED. These four have nothing to defer. A web page, a video, an image and a browser+ * node are inert wherever they sit; writing one into a project's serialized nodes is the whole+ * effect, and it is complete the moment `writeDisk` returns. One set with two contracts inside it+ * is how a caller ends up told a picture is queued.+ *+ * WHY they were still travelling after the cold-open fix: an agent that renders its output as a+ * node — a report as `show-web`, a screenshot as `show-image` — is the commonest reason a+ * background session touches the canvas at all, and every one of those calls yanked the human out+ * of the project they were typing in. Same G5 objection, same answer as the two sets above.+ *+ * Deliberately NOT here: `browser`, which NAVIGATES an existing node and needs a mounted+ * `<webview>` guest to do it. `open-browser` merely places the node; the guest is created when+ * that project is next shown, exactly as a cold-opened terminal's PTY is.+ *+ * None of the four takes `--group`, which is why this set owes no worktree question. A verb+ * joining it that does would: `cwdForNewNodeIn` subtracts the worktree store's `staleGroupIds`,+ * which is epoch-scoped to the ACTIVE project, so off canvas that subtraction cannot be made.+ */+const OFF_CANVAS_VERBS: ReadonlySet<string> = new Set([+ 'show-image',+ 'show-video',+ 'show-web',+ 'open-browser'+])++export function answersOffCanvas(verb: string): boolean {+ return OFF_CANVAS_VERBS.has(verb)+}++/** Test-only view of the three sets, so their disjointness can be asserted rather than eyeballed. */+export function controlVerbSetsForTests(): {+ storeAnswered: string[]+ coldOpenable: string[]+ offCanvas: string[]+} {+ return {+ storeAnswered: [...STORE_ANSWERED_VERBS],+ coldOpenable: [...COLD_OPENABLE_VERBS],+ offCanvas: [...OFF_CANVAS_VERBS]+ }}/**diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex fd76e58ea..b6fa15d43 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -5241,7 +5241,11 @@ body,gap: 8px;}-.confirm__btn {+/* The app's default button. `.announce-banner__action` shares the recipe rather than restating it:+ a banner offering an ordinary next step ("Go there") is not asking for the accent treatment+ `.announce-banner__btn` gives an install or a reload, and two copies of a default button drift. */+.confirm__btn,+.announce-banner__action {background: var(--panel-header);border: 1px solid var(--border);border-radius: 8px;@@ -5251,10 +5255,15 @@ body,cursor: pointer;}-.confirm__btn:hover {+.confirm__btn:hover,+.announce-banner__action:hover {background: rgba(var(--tint-rgb), 0.1);}+.announce-banner__action {+ flex: none;+}+.confirm__btn.danger {background: var(--danger);border-color: transparent;