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.

docs: task 11 fix round 1, the clamp changes no verdict, and wording fixes

review4e15635a206b
diff --git a/CLAUDE.md b/CLAUDE.md
index 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; they
ride `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 Server
Edition headless canvas control (`server/canvas-control.ts`) — and the renderer three-way merges
it 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 the
cards of nodes that are not live locally, and a client whose node op has not arrived yet would
otherwise 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 still
diff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.md
index 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 this
On the server that owns the team, the **canvas authority** (`src/core/canvas-authority.ts`) is the
one 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 client
uses (`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 retries
after 1 s, 2 s, 4 s and so on, capped at 30 s. Both server shutdown paths write what is pending
before 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-workspace
stale copy of every canvas it holds. No desktop flow sends one: the desktop's canvas saves go to its
own 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 listed
below.
**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 a
local 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's
board log, not the host's, because the modal renders outside the tab's session. This predates the
authority; it is a follow-up.
diff --git a/docs/team-presence.md b/docs/team-presence.md
index 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 full
settle; an upsert on add / remove / color / title / collapse), and the server reflects it to
every 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 the
backstop. On a Server Edition hosting a team, a shared project's content does not come from these
saves 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 ack
instead of being left on the losing value; and an **oversized** node the reflector would refuse
neither 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 your
selection, keeps relay-remote nodes, keeps local-only node data, keeps every untouched node's
object identity, drops the stale `measured` size so a peer's resize is not fought back, and keeps
diff --git a/src/core/canvas-sync.test.ts b/src/core/canvas-sync.test.ts
index 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 40
me.reset() // …and restarted at 0
diff --git a/src/shared/canvas-order.ts b/src/shared/canvas-order.ts
index 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.
}
}
}