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
feat(canvas-control): group, move, arrange and align a project that is not on screen
Fabricio Casali4adcb9f9af41
diff --git a/CLAUDE.md b/CLAUDE.mdindex ef1965189..f32faf702 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -3780,9 +3780,19 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile`STORE_ANSWERED_VERBS` (no canvas at either end), `COLD_OPENABLE_VERBS` (a session node, armedand inert until shown), `OFF_CANVAS_VERBS` (a display node, complete when written),`STORED_NODE_VERBS` (`write`/`close`/`rename`/`color`/`link`/`board`/`assign` — each reaches a- pane, a store writer or the board file), and `OFF_SCREEN_REFUSALS` (the eleven that genuinely+ pane, a store writer or the board file — plus the five layout verbs+ `group`/`ungroup`/`move`/`arrange`/`align`), and `OFF_SCREEN_REFUSALS` (the six that genuinelyneed live React Flow, each with its own reason in the refusal the agent reads). A refusal an- agent can act on is strictly better than hijacking someone's screen. Load-bearing details:+ agent can act on is strictly better than hijacking someone's screen. **The layout verbs off+ screen lay out from PERSISTED sizes** (nothing there was measured; a node is born at a persisted+ default size and a user resize is persisted too, so the gap is at most the overlap a live canvas+ can already show) and write back through `commitCtlNodes` → `geometryMutations`+ (`renderer/lib/storedGeometry.ts`): only the geometry that changed (`position`/`size`/`parentId`/+ `group`) is patched onto the STORED node, a created frame is added whole, only a frame is ever+ removed, and the batch lands in one `applyOwnNodeMutations` re-sorted parents-first. Never write+ the hydrated array back whole: that round-trips every node through the serializers. They were+ refusals until 2026-09-30; an orchestrator that could open a team off screen but never frame it+ was the report that moved them. Load-bearing details:(1) **`ctlNodes()` is the one name for "the node array this call acts on"** — on screen it is`nodesRef.current` verbatim, off canvas it is the owning project's serialized nodes hydrated by`nodeStatesToFlow`. A verb body that resolves `--node` against the live array while answeringdiff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.tsindex 0116f7743..e4ab9605c 100644--- a/src/main/canvas-control-core.test.ts+++ b/src/main/canvas-control-core.test.ts@@ -1218,7 +1218,7 @@ describe('the --project clause tells the truth about travel (review #363 I-1 + M}// Every refused verb is named AND carries its own reason — a bare list would tell an agent// that `branch` and `arrange` fail for the same cause, and they do not.- for (const v of ['group', 'ungroup', 'move', 'arrange', 'align', 'verify', 'spawn-team', 'branch', 'open-worktree', 'close-worktree', 'browser']) {+ for (const v of ['verify', 'spawn-team', 'branch', 'open-worktree', 'close-worktree', 'browser']) {const d = offScreenDisposition(v)expect(d.kind, v).toBe('refuse')if (d.kind !== 'refuse') continuediff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 72a50b0d8..3cbdd8e20 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -319,6 +319,7 @@ import {storedAgentIdOf,type ColdNode} from '../lib/coldOpen'+import { geometryMutations } from '../lib/storedGeometry'import { stampOpenedBy, withOpenedBy } from '../lib/stationOpener'import { installStationNoticeWiring } from '../lib/stationNoticeWiring'import { installBoardDispatchReportWiring } from '../lib/boardDispatchReportWiring'@@ -13195,6 +13196,24 @@ export function Canvas() {// against a stranger's project.const ctlNodes = (): CanvasNode[] =>offCanvas ? offCanvas.nodes : (nodesRef.current as CanvasNode[])+ // The write twin of `ctlNodes`, for the structural verbs (group/ungroup/move/arrange/align)+ // that compute a whole new node array. On screen it is the live write it always was. Off+ // canvas it writes only what changed into the owning project's stored nodes — geometry of+ // the nodes that moved, plus a frame created or dissolved (lib/storedGeometry.ts) — through+ // our own store writer, and persists it. The layout was computed from the persisted sizes,+ // which is what an unmeasured canvas has.+ const commitCtlNodes = (next: CanvasNode[]): void => {+ if (!offCanvas) {+ setNodes(next)+ markDirty()+ return+ }+ const st = useProjects.getState()+ const stored = st.getProject(offCanvas.project.id)?.nodes ?? []+ st.applyOwnNodeMutations(offCanvas.project.id, geometryMutations(stored, next))+ offCanvas.nodes = next+ void writeDisk()+ }// `linkEndpointOf` off canvas. Same answer, read out of the hydrated array: the live one// holds another project's nodes, so every id would resolve to null (or, worse, to a// same-named node over there).@@ -13829,7 +13848,7 @@ export function Canvas() {}}const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)- const live = nodesRef.current as CanvasNode[]+ const live = ctlNodes()const resolvable = ids.filter((id) => live.some((node) => node.id === id))if (resolvable.length === 0) {reply({ ok: false, error: 'group: none of the given node ids exist' })@@ -13859,8 +13878,7 @@ export function Canvas() {: nd)}- setNodes(grouped)- markDirty()+ commitCtlNodes(grouped)const skippedGrouped = ids.length - resolvable.lengthconst groupNote = skippedGrouped > 0 ? ` (${skippedGrouped} unknown id(s) skipped)` : ''reply({@@ -13872,15 +13890,14 @@ export function Canvas() {}case 'ungroup': {const gid = (args.group ?? '').trim()- const live = nodesRef.current as CanvasNode[]+ const live = ctlNodes()const frame = live.find((nd) => nd.id === gid && nd.type === 'group')if (!frame) {reply({ ok: false, error: `ungroup: --group names no group frame (${gid || 'missing'})` })return}const freed = live.filter((nd) => nd.parentId === gid).map((nd) => nd.id)- setNodes(ungroupNodes(live, gid))- markDirty()+ commitCtlNodes(ungroupNodes(live, gid))reply({ ok: true, message: `ungrouped ${gid}, freed ${freed.length} node(s)`, result: { freed } })return}@@ -13890,7 +13907,7 @@ export function Canvas() {// deliberately won't do. `reparentNode` keeps each node's ROOT-space position fixed// and refuses a cycle (a frame into itself or its own descendant).const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)- const live = nodesRef.current as CanvasNode[]+ const live = ctlNodes()const rawTarget = (args.group ?? '').trim().toLowerCase()const toTop = !rawTarget || rawTarget === 'top' || rawTarget === 'none' || rawTarget === 'ungrouped'const targetGroup = toTop ? null : args.group!.trim()@@ -13922,8 +13939,7 @@ export function Canvas() {for (const g of affected) {if (next.some((n) => n.parentId === g)) next = fitGroupToChildren(next, g, snapGridNow())}- setNodes(next)- markDirty()+ commitCtlNodes(next)const where = targetGroup ? `into ${targetGroup}` : 'to the top level'reply({ ok: true, message: `moved ${moved.length} node(s) ${where}`, result: { moved, group: targetGroup } })return@@ -13931,7 +13947,7 @@ export function Canvas() {case 'arrange':case 'align': {const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)- const live = nodesRef.current as CanvasNode[]+ const live = ctlNodes()const edge = (['left', 'right', 'top', 'bottom', 'hcenter', 'vcenter'] as const).find((e2) => e2 === args.edge)if (verb === 'align' && !edge) {reply({ ok: false, error: 'align requires --edge left|right|top|bottom|hcenter|vcenter' })@@ -13959,8 +13975,7 @@ export function Canvas() {// Tidying a frame's children usually leaves the frame oversized (it was sized to their// old scattered spots) — shrink it to hug the new layout. Top-level sets have no frame.if (container) next = fitGroupToChildren(next, container, snapGridNow())- setNodes(next)- markDirty()+ commitCtlNodes(next)const how = verb === 'arrange' ? `as ${layout}` : `to ${edge}`reply({ ok: true, message: `${verb === 'arrange' ? 'arranged' : 'aligned'} ${ids.length} node(s) ${how}`, result: { count: ids.length, container } })returndiff --git a/src/renderer/lib/controlRouting.test.ts b/src/renderer/lib/controlRouting.test.tsindex a0c91e186..2c36da997 100644--- a/src/renderer/lib/controlRouting.test.ts+++ b/src/renderer/lib/controlRouting.test.ts@@ -393,24 +393,26 @@ describe('the off-screen disposition table (the verbs that used to travel)', ()}})- it('the structural verbs refuse, and each says WHY in its own words', () => {+ it('the structural layout verbs are answered from the stored nodes (persisted sizes)', () => {+ for (const v of ['group', 'ungroup', 'move', 'arrange', 'align']) {+ expect(offScreenDisposition(v), v).toEqual({ kind: 'stored-node' })+ }+ })++ it('the verbs that still refuse each say WHY in their own words', () => {// A refusal an agent can act on beats hijacking the human's screen. The reasons are per verb- // because the caller's next move differs: an `arrange` can wait for the human, a `branch`+ // because the caller's next move differs: a `verify` can wait for the human, a `branch`// cannot happen at all until that terminal is mounted.const why = (v: string) => {const d = offScreenDisposition(v)expect(d.kind, v).toBe('refuse')return d.kind === 'refuse' ? d.why : ''}- expect(why('arrange')).toMatch(/measured/)- expect(why('group')).toMatch(/measured/)expect(why('branch')).toMatch(/parks the original/)expect(why('verify')).toMatch(/live canvas/)+ expect(why('spawn-team')).toMatch(/live canvas/)expect(why('open-worktree')).toMatch(/worktree store/)expect(why('browser')).toMatch(/webview/)- // …and no two structural verbs share a copy-pasted sentence that names the wrong mechanism.- expect(why('move')).toContain('reparenting')- expect(why('align')).toContain('aligning')})it('an unknown verb refuses — the fail-closed direction', () => {@@ -435,9 +437,9 @@ describe('the off-screen disposition table (the verbs that used to travel)', ()})it('the refusal sentence names the project, the reason and the fact that nothing happened', () => {- const msg = offScreenRefusal('group', 'web-app')- expect(msg.startsWith('group: project "web-app" is not on screen')).toBe(true)- expect(msg).toContain('measured node sizes')+ const msg = offScreenRefusal('branch', 'web-app')+ expect(msg.startsWith('branch: project "web-app" is not on screen')).toBe(true)+ expect(msg).toContain('parks the original session')expect(msg).toContain('Open that project and run this again')expect(msg).toContain('nothing was changed')})diff --git a/src/renderer/lib/storedGeometry.test.ts b/src/renderer/lib/storedGeometry.test.tsnew file mode 100644index 000000000..701f078b5--- /dev/null+++ b/src/renderer/lib/storedGeometry.test.ts@@ -0,0 +1,63 @@+import { describe, it, expect } from 'vitest'+import type { CanvasNodeState } from '@shared/types'+import { applyOwnCanvasMutation, groupSelectedNodes, nodeStatesToFlow, ungroupNodes } from '../state/workspace'+import { groupsFirst } from '@shared/node-order'+import { geometryMutations } from './storedGeometry'++const term = (id: string, x: number, extra: Partial<CanvasNodeState> = {}): CanvasNodeState =>+ ({+ id,+ kind: 'terminal',+ position: { x, y: 0 },+ size: { width: 600, height: 400 },+ title: id,+ color: '#0a84ff',+ group: null,+ tags: [],+ collapsed: false,+ ...extra+ }) as CanvasNodeState++// The stored project, as the store holds it: one node carries a held launch the serializers must+// never be trusted to round-trip.+const stored: CanvasNodeState[] = [+ term('a', 0, { pendingLaunch: { after: [], command: 'claude' } } as Partial<CanvasNodeState>),+ term('b', 700),+ term('c', 1400)+]++const apply = (nodes: CanvasNodeState[], ms: ReturnType<typeof geometryMutations>) =>+ groupsFirst(ms.reduce(applyOwnCanvasMutation, nodes))++describe('geometryMutations — a structural verb run off screen', () => {+ it('groups from persisted sizes: a new frame, children re-parented, nothing else rewritten', () => {+ const next = groupSelectedNodes(nodeStatesToFlow(stored), ['a', 'b'], 0, false)+ const ms = geometryMutations(stored, next)+ const after = apply(stored, ms)+ const frame = after.find((n) => n.kind === 'group')!+ expect(frame).toBeTruthy()+ expect(after[0].id).toBe(frame.id) // parents first+ expect(after.find((n) => n.id === 'a')!.parentId).toBe(frame.id)+ expect(after.find((n) => n.id === 'b')!.parentId).toBe(frame.id)+ // The frame wraps both 600-wide nodes laid out from their persisted size.+ expect(frame.size.width).toBeGreaterThanOrEqual(1300)+ // The untouched node is not rewritten, and the held launch survives on the moved one.+ expect(ms.some((m) => m.op === 'upsert' && m.node.id === 'c')).toBe(false)+ expect(after.find((n) => n.id === 'a')!.pendingLaunch).toEqual({ after: [], command: 'claude' })+ })++ it('ungroup removes only the frame and frees its children', () => {+ const grouped = apply(stored, geometryMutations(stored, groupSelectedNodes(nodeStatesToFlow(stored), ['a', 'b'], 0, false)))+ const frameId = grouped.find((n) => n.kind === 'group')!.id+ const ms = geometryMutations(grouped, ungroupNodes(nodeStatesToFlow(grouped), frameId))+ const after = apply(grouped, ms)+ expect(after.map((n) => n.id).sort()).toEqual(['a', 'b', 'c'])+ expect(after.every((n) => n.parentId === undefined)).toBe(true)+ expect(ms.filter((m) => m.op === 'remove')).toEqual([{ op: 'remove', id: frameId }])+ })++ it('never removes a non-frame the hydration did not return', () => {+ const ms = geometryMutations(stored, nodeStatesToFlow(stored.slice(0, 2)))+ expect(ms).toEqual([])+ })+})diff --git a/src/renderer/lib/storedGeometry.ts b/src/renderer/lib/storedGeometry.tsnew file mode 100644index 000000000..4c7f2fbd2--- /dev/null+++ b/src/renderer/lib/storedGeometry.ts@@ -0,0 +1,53 @@+// The write half of a structural control verb (`group`, `ungroup`, `move`, `arrange`, `align`) run+// against a project that is NOT on screen.+//+// Those verbs compute a whole new node array through the same pure transforms the live canvas uses+// (`groupSelectedNodes`, `reparentNode`, `arrangeNodes`, …), over the owning project's serialized+// nodes hydrated by `nodeStatesToFlow`. Off screen nothing was ever measured, so the sizes they lay+// out with are the persisted ones — which is what a node is born with and what it keeps until the+// user resizes it, so the layout matches what the user will see closely enough (a node the user+// resized is persisted at that size too).+//+// Writing that array back whole would round-trip every node through the serializers. This turns it+// into the smallest set of ops instead: an existing node keeps EVERY stored field (exec overlay,+// launch, account, …) and only takes the geometry the verb changed; a frame the verb created is+// added whole; a frame the verb dissolved is removed. Nothing else is ever removed.++import type { CanvasMutation, CanvasNodeState } from '@shared/types'+import { flowToNodeStates, type CanvasNode } from '../state/workspace'++/** The fields a structural verb may change on a node that already exists. */+const GEOMETRY = ['position', 'size', 'parentId', 'group'] as const++// null and absent are the same fact here (`group: null` vs no `group`), or an untouched node would+// be rewritten just for its spelling.+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a ?? null) === JSON.stringify(b ?? null)++export function geometryMutations(+ stored: readonly CanvasNodeState[],+ next: readonly CanvasNode[]+): CanvasMutation[] {+ const byId = new Map(stored.map((n) => [n.id, n]))+ const out: CanvasMutation[] = []+ const kept = new Set<string>()+ for (const n of flowToNodeStates(next as CanvasNode[])) {+ kept.add(n.id)+ const s = byId.get(n.id)+ if (!s) {+ out.push({ op: 'upsert', node: n })+ continue+ }+ const changed = GEOMETRY.filter((k) => !same(s[k], n[k]))+ if (changed.length === 0) continue+ const patched: CanvasNodeState = { ...s }+ for (const k of changed) {+ if (n[k] === undefined) delete (patched as Partial<CanvasNodeState>)[k]+ else (patched as unknown as Record<string, unknown>)[k] = n[k]+ }+ out.push({ op: 'upsert', node: patched })+ }+ // Only a FRAME can be dissolved by these verbs (`ungroup`). A non-frame missing from `next` is one+ // the hydration skipped, and it is not this write's to delete.+ for (const s of stored) if (!kept.has(s.id) && s.kind === 'group') out.push({ op: 'remove', id: s.id })+ return out+}diff --git a/src/renderer/state/projects.ts b/src/renderer/state/projects.tsindex f88170583..c7ee33b92 100644--- a/src/renderer/state/projects.ts+++ b/src/renderer/state/projects.ts@@ -25,6 +25,7 @@ import {} from '@shared/canvas-layout'import { applyCanvasOp as applyCanvasOpTo, contentOf } from '@shared/canvas-content'import { diffToMutations, type CanvasScene } from '@shared/canvas-mutations'+import { groupsFirst } from '@shared/node-order'import { applyOwnCanvasMutation, createProject, reorderGroupWithinParent } from './workspace'import { registerCodexRelayProjectCheck } from './codexCli'import { markWorkspaceDirty } from './workspaceDirty'@@ -191,6 +192,9 @@ interface ProjectsState {* Never route a peer's mutation through this.*/applyOwnNodeMutation(projectId: string, mutation: CanvasMutation): boolean+ /** Several of our own node writes as ONE store write, re-sorted parents-first (`groupsFirst`) —+ * a structural control verb run off screen adds a frame after the children it now holds. */+ applyOwnNodeMutations(projectId: string, mutations: readonly CanvasMutation[]): boolean/** Renames a node within a project (source of truth for inactive projects). */renameNode(projectId: string, nodeId: string, title: string): void/** Recolors a node within a project. */@@ -740,6 +744,19 @@ export const useProjects = create<ProjectsState>((set, get) => ({return true},+ applyOwnNodeMutations(projectId, mutations) {+ if (!get().projects.some((p) => p.id === projectId)) return false+ if (mutations.length === 0) return true+ ownWrite(get, projectId, () =>+ set((s) => ({+ projects: mapProjectNodes(s.projects, projectId, (nodes) =>+ groupsFirst(mutations.reduce(applyOwnCanvasMutation, nodes))+ )+ }))+ )+ return true+ },+renameNode(projectId, nodeId, title) {ownWrite(get, projectId, () =>set((s) => ({diff --git a/src/shared/control-off-screen.ts b/src/shared/control-off-screen.tsindex 7626fca3e..06465d11f 100644--- a/src/shared/control-off-screen.ts+++ b/src/shared/control-off-screen.ts@@ -212,12 +212,24 @@ export function answersOffCanvas(verb: string): boolean {* to read `activeProjectId`, which off canvas was a second bug hiding behind the first: after* the travel the two projects were the same, so the wrong read was never wrong in practice.*+ * - `group` / `ungroup` / `move` / `arrange` / `align` lay out from persisted sizes (below).+ ** Deliberately NOT here — and these REFUSE rather than travel, see `offScreenDisposition`: the- * structural verbs. A refusal an agent can act on is strictly better than hijacking the human's+ * verbs that arm a graph, park a live terminal, read the worktree store or drive a webview. A refusal an agent can act on is strictly better than hijacking the human's* screen, and every one of these would have to guess at something the serialized copy does not* carry.*/const STORED_NODE_VERBS: ReadonlySet<string> = new Set([+ // The five structural verbs run their pure transforms over the stored nodes, laid out from the+ // PERSISTED sizes (nothing off screen was measured — but a node is born at a persisted default+ // size and keeps it until the user resizes it, which is persisted too), and write back only the+ // geometry that changed (renderer/lib/storedGeometry.ts). They were refused here once; a team an+ // orchestrator could open off screen but never frame was the worse outcome.+ 'group',+ 'ungroup',+ 'move',+ 'arrange',+ 'align','write','close','run',@@ -242,16 +254,6 @@ export function answersFromStoredNodes(verb: string): boolean {* verb unable to act, it says so.*/const OFF_SCREEN_REFUSALS: Readonly<Record<string, string>> = {- // The five structural verbs rewrite the WHOLE node array through React Flow's parent/extent- // model and re-fit frames from MEASURED sizes (`nodeW`/`nodeH` prefer `measured` over the- // persisted `size`), which the serialized copy does not carry — nothing rendered it. Laying a- // canvas out to geometry the user would not get on screen, and round-tripping every node- // through the serializers to persist it, is drift no reply could report.- group: 'grouping re-fits frames from measured node sizes, which only a rendered canvas has',- ungroup: 'ungrouping re-fits frames from measured node sizes, which only a rendered canvas has',- move: 'reparenting re-fits both frames from measured node sizes, which only a rendered canvas has',- arrange: 'arranging lays nodes out from measured node sizes, which only a rendered canvas has',- align: 'aligning lays nodes out from measured node sizes, which only a rendered canvas has',// Both compose `--after` arming and context bridges over nodes created in the SAME tick, and// check each dep against the live canvas before arming it. A cold open defers ONE node's launch;// these defer a graph, and an armed station is fired by the live canvas effect.