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.

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.tsx
index 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) return
const 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?.ssh
const 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>
+ )}
<button
className="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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.css
index 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;