Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs: task 11 fix round 1, the clamp changes no verdict, and wording fixes
review4e15635a206b
diff --git a/CLAUDE.md b/CLAUDE.mdindex addc1f079..eab4bee46 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -287,7 +287,9 @@ Persistence has two layers:one-time renderer note). Outside edits (git pull/sync) are detected by`core/workspace-watcher.ts` → silent reload, or a Reload/Keep-mine conflict bar when dirty; theyride `workspace:external-change`, and so do the phone's `appendRemoteNode` and the SSH- reconcile, which really are "another device".+ reconcile, which really are "another device". The exception is a project a hosted Server Edition+ shares with its team: the canvas authority adopts that outside edit and publishes it as+ `canvas:mut` ops, with no `workspace:external-change` (see **Hosted team relay**).**A write this core made ITSELF rides `workspace:server-change` instead** — today that is ServerEdition headless canvas control (`server/canvas-control.ts`) — and the renderer three-way mergesit against the store baseline (`renderer/lib/serverChange.ts`: incoming nodes adopted silently,@@ -6736,8 +6738,9 @@ The invariants, each with its reason:- **Prune removals are never cast** (`diffKanbanOps`' `liveNodeIds`). Every board commit prunes thecards of nodes that are not live locally, and a client whose node op has not arrived yet wouldotherwise cast the removal of a fresh card for everyone. `liveNodeIds` is one project's nodes- (React Flow ∩ store while the Omni board is open). Card and meta removals are last-writer-wins- VALUES; only node, edge, column, label and view removals are rule-4 deletions.+ (for the rendered project, React Flow ∩ store while the Omni board is open). Card and meta+ removals are last-writer-wins VALUES; only node, edge, column, label and view removals are rule-4+ deletions.**Known limitations** (full list in the doc): non-editors still receive cross-project presence and`context:update` metadata (deploy one core per team); a viewer's socket backlog over 1 MB stilldiff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.mdindex 4cf81c23b..08ab4782b 100644--- a/docs/hosted-team-relay.md+++ b/docs/hosted-team-relay.md@@ -315,9 +315,11 @@ unapproved after 2.5 s, the tab says "Waiting for an owner of X to approve thisOn the server that owns the team, the **canvas authority** (`src/core/canvas-authority.ts`) is theone writer of every shared project's canvas **content**: its nodes, bridges, ropes and board items-(columns, cards, card metadata, labels, saved views). Clients send edits, never content. Every edit-travels as a `canvas:mut` op, which the core's reflector places in one total order (`seq`); the-authority hears each op right after that stamp, judges it with the same ordering rules every client+(columns, cards, card metadata, labels, saved views). A client's edits reach it as `canvas:mut`+ops; a Server Edition tab still sends whole-workspace saves too, but the content in them is+overlaid with the authority's (input 2), and only a node too large to travel as an op is taken from+them. The core's reflector places every op in one total order (`seq`); the authority hears each op+right after that stamp, judges it with the same ordering rules every clientuses (`src/shared/canvas-order.ts`: the highest `seq` wins per item, and a causal delete, see`docs/team-presence.md`), and applies it through the same reducer (`applyCanvasOp`,`src/shared/canvas-content.ts`).@@ -347,8 +349,9 @@ whole-workspace saves still write them.client gets the Reload / Keep mine bar (`src/server/workspace-external-watch.ts`).**Writing.** A governed project is written 1 s after its last op, and at most 5 s after the first op-not yet written, through the store's atomic content write (`WorkspaceStore.writeProjectContent`: the-same file a save writes, apart from `rev` and `savedAt`). A failed write keeps every op and retries+not yet written, through the store's atomic content write (`WorkspaceStore.writeProjectContent`: it+bumps `rev` like a save, and the file is byte-identical to a save's apart from `rev` and `savedAt`).+A failed write keeps every op and retriesafter 1 s, 2 s, 4 s and so on, capped at 30 s. Both server shutdown paths write what is pendingbefore they exit, so a crash loses only what was not written yet: normally at most the last 5 s.Viewers can watch a terminal an Editor opened once its node is written, because node membership is@@ -376,9 +379,10 @@ workspace over the relay; edits travel as canvas operations". A whole-workspacestale copy of every canvas it holds. No desktop flow sends one: the desktop's canvas saves go to itsown local core.-**The oversized-node exception.** A node too large to travel as an op (over `MUTATION_MAX_BYTES`,-256,000 bytes; in practice a sticky note with a pasted document in it) can only reach the core inside-a save, so a save may contribute that node. It sits outside the total order; its limits are listed+**The oversized-node exception.** A node too large to travel as an op (its upsert op, serialized, is+longer than `MUTATION_MAX_BYTES`: `JSON.stringify(op).length` over 256,000, about 250 KB; in+practice a sticky note with a pasted document in it) can only reach the core inside a save, so a+save may contribute that node. It sits outside the total order; its limits are listedbelow.**Bridges grant reads.** On the Server Edition, which agent sessions may read each other's context@@ -407,9 +411,9 @@ it is a new way to use it.is on. An edit on the Omni board to a lane of a project on another core (a hosted lane while alocal tab is active, or the reverse) is not cast, so on a hosted core it is not written either.- **The Omni board and a brand-new node.** While the Omni board is open, removing the card of a node- created moments ago is not cast (teammates keep the card). For the project on screen, only nodes- that are both on the canvas and in the stored copy count as live then, which can only ever cast- fewer removals.+ created moments ago in the project on screen is not cast (teammates keep the card). For that+ project only, the nodes that are both on the canvas and in the stored copy count as live then,+ which can only ever cast fewer removals.- **The card modal's comments on a relay tab** (`BoardLogPanel`) still read and write the local core'sboard log, not the host's, because the modal renders outside the tab's session. This predates theauthority; it is a follow-up.diff --git a/docs/team-presence.md b/docs/team-presence.mdindex dac8c9db4..250c2aab3 100644--- a/docs/team-presence.md+++ b/docs/team-presence.md@@ -347,9 +347,11 @@ publishes a mutation (position-only, throttled to 20 Hz, while dragging; a fullsettle; an upsert on add / remove / color / title / collapse), and the server reflects it toevery client except the sender.-Convergence makes persistence safe for free: because all clients converge on the same node set,-whichever client calls `workspace.save` writes the same bytes, which defuses today's-last-writer-wins save. The existing rev-based conflict bar (`workspace-watcher`) stays as the+Convergence makes persistence safe for free: because all clients that saw the whole exchange+converge on the same node set, whichever of them calls `workspace.save` writes the same canvas,+which defuses today's last-writer-wins save. The exceptions (a client that loaded after a delete,+board bytes in two cases) are in the+[does-not-converge list](#concurrent-edit-resolution-what-converges-and-what-does-not). The existing rev-based conflict bar (`workspace-watcher`) stays as thebackstop. On a Server Edition hosting a team, a shared project's content does not come from thesesaves at all: the canvas authority overlays each one with the content it applied from ops(`docs/hosted-team-relay.md`).@@ -952,7 +954,7 @@ read-only guests, per-user settings.client whose **inbox is stalled past the TTL** (a backed-up socket) is repaired by its own late ackinstead of being left on the losing value; and an **oversized** node the reflector would refuseneither deafens that node to a peer's concurrent delete nor is silently lost (it is retried, and- syncs once trimmed). → `src/core/canvas-sync.convergence.test.ts` (18 tests)+ syncs once trimmed). → `src/core/canvas-sync.convergence.test.ts`- **Applying a peer's mutation** (delivered): patches the live React Flow array — keeps yourselection, keeps relay-remote nodes, keeps local-only node data, keeps every untouched node'sobject identity, drops the stale `measured` size so a peer's resize is not fought back, and keepsdiff --git a/src/core/canvas-sync.test.ts b/src/core/canvas-sync.test.tsindex 3dc311819..9a014b3be 100644--- a/src/core/canvas-sync.test.ts+++ b/src/core/canvas-sync.test.ts@@ -124,7 +124,9 @@ describe('stampMutation', () => {expect(stampMutation({ op: 'upsert', node: node('n1'), seen: 9 }, 9).seen).toBe(8)})- it('drops a non-integer / negative `seen` — degrading to unstamped, never to outranking a delete', () => {+ // Unstamped is judged exactly as before rule 4: never stale, so an unstamped upsert ordered after a+ // remove IS applied over it (canvas-order `supersededByRemove`). Hygiene, like the clamp above.+ it('drops a non-integer / negative `seen`, degrading to unstamped (judged as before rule 4)', () => {for (const bad of [-1, 1.5, NaN, Infinity, '5', null]) {expect(stampMutation({ op: 'upsert', node: node('n1'), seen: bad as unknown as number }, 4).seen@@ -134,10 +136,11 @@ describe('stampMutation', () => {})// canvas-order's reset() keeps a client's causal position (a same-core reconnect needs it). If the- // core REALLY restarted, that kept value is above every `seq` the new core hands out, and this- // clamp is what makes it harmless: the cast can only read as "never stale" on a peer — the- // pre-rule-4 verdict. A degrade, never a split.- it('a causal position kept across a real core restart is clamped into a verdict that applies', () => {+ // core REALLY restarted, that kept value is above every `seq` the new core hands out, so the cast+ // reads as "never stale" on a peer (the pre-rule-4 verdict: a degrade, never a split) WITH OR+ // WITHOUT the clamp: unclamped, 40 is also ≥ the tombstone's 3 (canvas-order `supersededByRemove`).+ // The clamp to `seq - 1` asserted below is hygiene; it changes no verdict.+ it('a causal position kept across a real core restart reads as never stale (the clamp is hygiene)', () => {const me = createCanvasOrder('me')me.accept({ op: 'upsert', node: node('n2'), src: 'x', seq: 40 }) // the old core had reached 40me.reset() // …and restarted at 0diff --git a/src/shared/canvas-order.ts b/src/shared/canvas-order.tsindex dbe265386..b7b6e6b21 100644--- a/src/shared/canvas-order.ts+++ b/src/shared/canvas-order.ts@@ -419,9 +419,10 @@ export function createCanvasOrder(// clientId, `seq` carrying on), and zeroing it stamped our first cast after it `seen: 0` — a// ⌘Z of a node deleted before the drop was then a stale frame to every peer holding the// tombstone, and our own echo of it is no repair: a persistent split. If the core REALLY- // restarted, the kept value is above every `seq` it hands out and the reflector clamps it to- // `seq - 1` (canvas-sync `stampMutation`), so our casts read as "never stale" there — the- // pre-rule-4 verdict. A degrade, never a split.+ // restarted, the kept value is above every `seq` it hands out, so our casts read as "never+ // stale" there (`supersededByRemove`: it is ≥ every new tombstone) — the pre-rule-4 verdict. A+ // degrade, never a split. The reflector's clamp to `seq - 1` (canvas-sync `stampMutation`)+ // changes no verdict here; it is hygiene.}}}