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.

Merge origin/main into feat/arrange-by-lineage

Fabricio Casali983e7612bb94
diff --cc CLAUDE.md
index ba99ee516,56cf5b72d..50e7e7fea
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -4081,33 -4185,10 +4185,33 @@@ command-bearing opens; this does not ad
frames, which `group` won't do; a cycle (a frame into itself or its own descendant) is refused.
`arrange`/`align` now run in ONE coordinate space: all top-level, OR all children of one frame
(`commonParentId` decides; a mixed set is refused, not silently subset-arranged — the old
- behavior). When the ids are a frame's children, the frame is shrunk to hug the tidied layout
- (`fitGroupToChildren`) — the fix for "grouping keeps scattered positions so the frame is too
- wide". `move` also re-fits the source + destination frames. All pure + tested in
- `state/workspace.test.ts` + `workspace.layout.test.ts`.
+ behavior). When the ids are a frame's children, that frame AND every ancestor frame are re-fitted
+ to hug the tidied layout (`fitAncestorChain` — fitting only the one frame left a nested frame
+ wider than its parent) — the fix for "grouping keeps scattered positions so the frame is too
+ wide". `arrange` fills its slots in the order the ids are LISTED (`arrangeNodes` used to place in
+ array order, which discarded every caller's sort). `move` also re-fits the source + destination
+ frames. All pure + tested in `state/workspace.test.ts` + `workspace.layout.test.ts`.
+ **`arrange --group <frameId> [--layout grid|row|column|lineage] [--cols N]`** names the FRAME
+ instead of listing its children: the frame's direct children are laid out and the frame chain is
+ re-fitted — `arrangeGroupChildren`, the SAME transform the frame's menu rows run (see
+ **Arrange inside a group** under Canvas interaction). The flag gate is the pure
+ `arrangeArgsRefusal` (`@shared/arrange-verb`), called in THREE places: `parseControlRequest`
+ (Server Edition), desktop main's control handler (which never runs `parseControlRequest` — the
+ `--issue` trap; with the gate only in the parser, all three refusals were missing on the desktop
+ and the request ran as a grid), and Canvas's `case 'arrange'` as the belt: `--nodes` and
+ `--group` together are refused rather than resolved silently, an unknown `--layout` on the
+ `--group` form is refused by name, and `--layout lineage` on the `--nodes` form is refused
+ instead of being delivered as a grid (any OTHER unknown word there still falls back to `grid`,
+ as it always has). What only the canvas knows — no such frame, an empty frame, no lineage among
+ the children — is `groupArrangeRefusal`, replied as `arrange: <reason>`; a frame already in
+ place answers `ok` with `changed: false` and writes nothing. The agent-facing text for the form
+ is `arrangeGroupGuidanceLines`, rendered into BOTH generated bodies from the same layout list the
+ gate checks. **Server Edition: refused by name** — `arrange` is not in `SERVER_V1_VERBS` in either
+ form (headless control keeps no measured node sizes), so `--group` gets the same permanent
+ `control-unsupported-on-this-edition` reply and is never dropped on the way to an `ok`
- (`control-unsupported.test.ts` pins it). Off screen it is refused like the `--nodes` form
- (`OFF_SCREEN_REFUSALS`); the dispatch branch is deliberately thin so moving `arrange` off-screen
- touches only where the node array comes from.
++ (`control-unsupported.test.ts` pins it). Off screen it works like the `--nodes` form: the
++ stored nodes are laid out and written back through `commitCtlNodes`, and the lineage ropes are
++ the OWNING project's (`offCanvas.project.ropes`), never the live canvas's.
**Fan-in (`link`, 2026-07):** a spawned fan-out was previously write-only — nodes an agent
opened were joined to it by a **rope** (`project.ropes`, explicitly *"Display-only — never
context links"*), so an orchestrator could not read back what its own team produced and the
diff --cc src/renderer/canvas/Canvas.tsx
index 620f6e422,8c92443c0..9c129e9cc
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@@ -14035,55 -14624,8 +14729,53 @@@ export function Canvas()
}
case 'arrange':
case 'align': {
- const live = nodesRef.current as CanvasNode[]
- const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+ const live = ctlNodes()
+ // The flag shape was refused in main (`arrangeArgsRefusal`); this is the belt. With it,
+ // `--layout` on the `--group` form is absent or a known word by the time it is read
+ // below — an unknown one is refused by name, never delivered as a grid.
+ const shapeRefusal = verb === 'arrange' ? arrangeArgsRefusal(args) : null
+ if (shapeRefusal) {
+ reply({ ok: false, error: shapeRefusal })
+ return
+ }
+ // `arrange --group <frameId>`: name the FRAME instead of listing its children. The
+ // whole rule set is `arrangeGroupChildren` — the same transform the frame's menu rows
+ // and the palette run — so this branch only parses, refuses by name and replies.
+ if (verb === 'arrange' && args.group) {
+ const gid = args.group.trim()
+ const groupLayout = GROUP_ARRANGE_LAYOUTS.find((l) => l === args.layout) ?? 'grid'
- const edges = controlEdgesRef.current.map((e) => ({ source: e.source, target: e.target }))
++ // Off canvas the lineage ropes are the OWNING project's, not the live canvas's.
++ const edges = (offCanvas ? offCanvas.project.ropes ?? [] : controlEdgesRef.current).map((e) => ({ source: e.source, target: e.target }))
+ const refusal = groupArrangeRefusal(live, gid, groupLayout, edges)
+ if (refusal) {
+ reply({ ok: false, error: `arrange: ${refusal}` })
+ return
+ }
+ const cols = args.cols ? parseInt(args.cols, 10) || undefined : undefined
+ const next = arrangeGroupChildren(live, gid, { layout: groupLayout, cols, edges, grid: snapGridNow() })
+ const count = live.filter((nd) => nd.parentId === gid).length
+ // The SAME array means every item already sat where the layout puts it: an answer,
+ // not a failure — and nothing to write.
- if (next !== live) {
- setNodes(next)
- markDirty()
- }
++ if (next !== live) commitCtlNodes(next)
+ const frame = next.find((nd) => nd.id === gid)
+ reply({
+ ok: true,
+ message:
+ next === live
+ ? `group ${gid} is already arranged as ${groupLayout} — nothing moved`
+ : `arranged ${count} item(s) in group ${gid} as ${groupLayout} and resized the frame to fit`,
+ result: {
+ count,
+ group: gid,
+ layout: groupLayout,
+ changed: next !== live,
+ width: frame?.width,
+ height: frame?.height
+ }
+ })
+ return
+ }
+ const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)
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' })
@@@ -14108,13 -14650,10 +14800,12 @@@
let next = verb === 'arrange'
? arrangeNodes(live, ids, { layout, cols })
: alignNodes(live, ids, edge!)
- // 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())
+ // Tidying a frame's children usually leaves the frame the wrong size (it was sized to
+ // their old scattered spots) — hug the new layout, and re-fit every ANCESTOR frame too:
+ // a nested frame that grew past its parent would be clamped by `extent:'parent'` into
+ // an inverted range. Top-level sets have no frame.
+ if (container) next = fitAncestorChain(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 } })
return
@@@ -17419,52 -18171,17 +18323,62 @@@
} as Command
]
: []),
+ // Omitted rather than disabled when there is no lineage: the palette has no disabled
+ // state, so an entry that does nothing would surface as a search hit that goes nowhere.
+ ...(hasArrangeableNodes() && hasLineageLayers()
+ ? [
+ {
+ id: 'arrange-lineage',
+ label: 'Arrange by lineage',
+ hint: 'layers levels who opened whom tree hierarchy organize',
+ icon: <IconLineage />,
+ run: arrangeByLineageAction
+ } as Command
+ ]
+ : []),
+ // The group tidies need a frame to act on, and the palette has no right-click target: they
+ // are offered for the ONE selected group frame, and each is omitted (never disabled — see
+ // above) when `groupArrangeRefusal` says it has nothing to do there.
+ ...(() => {
+ const selectedGroups = nodesRef.current.filter((n) => n.selected && n.type === 'group')
+ if (selectedGroups.length !== 1) return []
+ const groupId = selectedGroups[0].id
+ return [
+ ...(groupArrangeHint(groupId, 'grid')
+ ? []
+ : [
+ {
+ id: 'arrange-group',
+ label: 'Tidy selected group',
+ hint: 'arrange grid layout organize frame resize fit clean up',
+ icon: <IconGrid />,
+ run: () => arrangeGroupAction(groupId, 'grid')
+ } as Command
+ ]),
+ ...(groupArrangeHint(groupId, 'lineage')
+ ? []
+ : [
+ {
+ id: 'arrange-group-lineage',
+ label: 'Arrange selected group by lineage',
+ hint: 'layers levels who opened whom tree hierarchy organize frame resize',
+ icon: <IconLineage />,
+ run: () => arrangeGroupAction(groupId, 'lineage')
+ } as Command
+ ])
+ ]
+ })(),
{ id: 'zoom-100', label: 'Zoom to 100%', icon: <IconFit />, run: zoomTo100 },
+ ...(prepareUpdateAvailable
+ ? [
+ {
+ id: 'prepare-update',
+ label: 'Prepare for update…',
+ hint: 'install update installer stop session host windows quit',
+ run: () => setPrepareUpdateOpen(true)
+ } as Command
+ ]
+ : []),
// Layouts mirror the Dock's menu, and both are withheld on a relay tab for the same reason:
// it is a live connection to another machine, never a workspace on this disk. The Dock says
// so on a disabled button; the palette has no disabled row, so the entries are omitted.
diff --cc src/renderer/canvas/arrange-group.source.test.ts
index eda490b95,000000000..324bc6df7
mode 100644,000000..100644
--- a/src/renderer/canvas/arrange-group.source.test.ts
+++ b/src/renderer/canvas/arrange-group.source.test.ts
@@@ -1,113 -1,0 +1,115 @@@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+/**
+ * STRUCTURAL pins for "arrange inside a group". The rules themselves are pure and tested where
+ * they live (`state/workspace.layout.test.ts`); what cannot be tested there is that Canvas.tsx —
+ * a React component with no unit seam — reaches them from all three surfaces through ONE
+ * transform. A frame menu that packs with `arrangeGroupChildren` while the `arrange --group` verb
+ * packs with its own copy is two answers to "what does organizing a frame do", and the second one
+ * is the one that forgets to re-fit the ancestors.
+ */
+const src = readFileSync(new URL('./Canvas.tsx', import.meta.url), 'utf8').replace(/\r\n/g, '\n')
+
+/** Line comments say what a block must NOT do, so a pin has to judge the code. */
+const code = (body: string): string =>
+ body
+ .split('\n')
+ .filter((l) => !l.trim().startsWith('//') && !l.trim().startsWith('*'))
+ .join('\n')
+
+function between(start: string, end: string): string {
+ const at = src.indexOf(start)
+ expect(at, start).toBeGreaterThan(-1)
+ const stop = src.indexOf(end, at + start.length)
+ expect(stop, end).toBeGreaterThan(at)
+ return code(src.slice(at, stop))
+}
+
+describe('arrange inside a group (source pins)', () => {
+ const action = between('const arrangeGroupAction = useCallback(', '\n /** Report a refusal')
+ const verb = between(" case 'arrange':\n", "\n case 'link': {")
+ const groupBranch = verb.slice(verb.indexOf("if (verb === 'arrange' && args.group)"), verb.indexOf('const ids ='))
+
+ it('the menu/palette action is arrangeGroupChildren, decided BEFORE the write', () => {
+ // The same-array verdict is read off nodesRef first: a flag set inside the setNodes updater is
+ // still false on the next line, which would cost every run its markDirty.
+ const guard = action.indexOf('=== nodesRef.current) return')
+ const write = action.indexOf('setNodes(')
+ expect(guard).toBeGreaterThan(-1)
+ expect(write).toBeGreaterThan(guard)
+ expect(action.match(/arrangeGroupChildren\(/g)?.length).toBe(2)
+ expect(action).toContain('markDirty()')
+ // The frame's top-left stays put, so the camera has no reason to move.
+ expect(action).not.toContain('fitAll(')
+ // Canvas-only, like the two canvas tidies.
+ expect(action).toContain('isKanbanOpen(')
+ })
+
+ it('the frame menu offers both styles, disabled WITH the reason from the shared refusal', () => {
+ const hint = between('const groupArrangeHint = useCallback(', 'const arrangeGroupAction')
+ expect(hint).toContain('groupArrangeRefusal(')
+ const menu = between('const groupItems = useCallback(', '/** Right-click menu for an ephemeral card.')
+ expect(menu).toContain("label: 'Tidy group'")
+ expect(menu).toContain("label: 'Arrange group by lineage'")
+ expect(menu).toContain("groupArrangeHint(groupId, 'grid')")
+ expect(menu).toContain("groupArrangeHint(groupId, 'lineage')")
+ expect(menu).toContain('disabled: !!tidyRefusal')
+ expect(menu).toContain('disabled: !!lineageRefusal')
+ expect(menu).toContain("arrangeGroupAction(groupId, 'grid')")
+ expect(menu).toContain("arrangeGroupAction(groupId, 'lineage')")
+ })
+
+ it('the palette OMITS a refused entry instead of listing a dead one', () => {
+ const palette = between("id: 'arrange-group',", "{ id: 'zoom-100'")
+ const before = between('const selectedGroups = nodesRef.current', "id: 'arrange-group',")
+ expect(before).toContain('if (selectedGroups.length !== 1) return []')
+ expect(before).toContain("groupArrangeHint(groupId, 'grid')")
+ expect(palette).toContain("groupArrangeHint(groupId, 'lineage')")
+ expect(palette).not.toContain('disabled')
+ })
+
+ it('arrange --group runs the SAME transform and refusal, and writes only on a change', () => {
+ expect(groupBranch).toContain('groupArrangeRefusal(live, gid, groupLayout, edges)')
+ expect(groupBranch).toContain('arrangeGroupChildren(live, gid,')
+ expect(groupBranch).toContain('GROUP_ARRANGE_LAYOUTS.find(')
+ // No second packing or fitting implementation in the branch.
+ expect(groupBranch).not.toMatch(/\barrangeNodes\(|fitGroupToChildren\(|fitAncestorChain\(/)
+ const write = groupBranch.slice(groupBranch.indexOf('if (next !== live)'))
- expect(write.indexOf('setNodes(next)')).toBeGreaterThan(-1)
- expect(write.indexOf('markDirty()')).toBeGreaterThan(write.indexOf('setNodes(next)'))
++ // `commitCtlNodes` is the one write for on- and off-screen projects (it marks dirty itself).
++ expect(write).toMatch(/^if \(next !== live\) commitCtlNodes\(next\)/)
++ // Off screen the lineage ropes are the owning project's, never the live canvas's.
++ expect(groupBranch).toContain('offCanvas ? offCanvas.project.ropes')
+ // A refusal names the verb and never reports ok.
+ expect(groupBranch).toContain('reply({ ok: false, error: `arrange: ${refusal}` })')
+ })
+
+ // Desktop main never runs `parseControlRequest` (the Server Edition's parser), so the shape gate
+ // has to be called in its control handler too — without it `--group` with `--nodes`, an unknown
+ // `--layout` and `--nodes --layout lineage` all reached the renderer and ran as a grid.
+ it('desktop main refuses a malformed arrange before the forward to the renderer', () => {
+ const mainSrc = readFileSync(new URL('../../main/index.ts', import.meta.url), 'utf8').replace(/\r\n/g, '\n')
+ const handler = code(mainSrc.slice(mainSrc.indexOf('hookServer.setControlHandler(')))
+ const gate = handler.indexOf("verb === 'arrange' ? arrangeArgsRefusal(args) : null")
+ expect(gate).toBeGreaterThan(-1)
+ expect(handler.slice(gate, gate + 300)).toContain(
+ 'if (arrangeRefusal) return { ok: false, error: arrangeRefusal, message: arrangeRefusal }'
+ )
+ expect(gate).toBeLessThan(handler.indexOf("'window unavailable'"))
+ })
+
+ it('the renderer belt runs the same gate before either form reads its flags', () => {
+ const gate = verb.indexOf("verb === 'arrange' ? arrangeArgsRefusal(args) : null")
+ expect(gate).toBeGreaterThan(-1)
+ expect(verb.slice(gate, gate + 200)).toContain('reply({ ok: false, error: shapeRefusal })')
+ // Before the --group branch: its `?? 'grid'` then only ever answers an ABSENT --layout.
+ expect(gate).toBeLessThan(verb.indexOf("if (verb === 'arrange' && args.group)"))
+ expect(gate).toBeLessThan(verb.indexOf('GROUP_ARRANGE_LAYOUTS.find('))
+ })
+
+ it('the --nodes form re-fits the ancestor chain too, not just the one frame', () => {
+ const nodesForm = verb.slice(verb.indexOf('const ids ='))
+ expect(nodesForm).toContain('fitAncestorChain(next, container, snapGridNow())')
+ expect(nodesForm).not.toContain('fitGroupToChildren(')
+ })
+})