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: shared canvas authority, edge and board sync

review556e951e0850
diff --git a/CLAUDE.md b/CLAUDE.md
index e3b209a2d..addc1f079 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6708,14 +6708,42 @@ The invariants, each with its reason:
survives Electron IPC. Only `E_JOIN_NETWORK` and `E_JOIN_THROTTLED` (at least 60 s) retry
unattended. A drop the host did not explain retries 5 times (1/2/4/8/15 s), then stops and says so.
+**Shared canvas authority** (doc section of that name; ordering rules in `docs/team-presence.md`).
+`canvas:mut` carries nodes, edges (`edge-*`) and board items (`kb-*`, `shared/kanban-ops.ts`).
+
+- **On the Server Edition, only the canvas authority writes a shared project's content**
+ (`core/canvas-authority.ts`: nodes, bridges, ropes, board items; only in the process that owns the
+ team). A client's whole-workspace save is a stale copy of every canvas it holds, so saves AND
+ loads pass through the authority's overlay (`WorkspaceStore.setContentAuthority`), and an outside
+ edit (a `git pull`) is adopted and published as ops instead of `workspace:external-change`, whose
+ conflict bar would offer "Keep mine" over it. It writes 1 s after the last op, at most 5 s after
+ the first. The consequence for code: **a content change that is not cast as an op is dropped by
+ the next overlaid save.** That is why server canvas control casts a diff of the whole content
+ before every save (`castAndSave`, never a per-verb list, which drifts), and why a hosted relay
+ peer may not `workspace:save` at all (refused for every role). One exception: a node too large
+ to travel as an op is taken from saves.
+- **One reducer, `applyCanvasOp`** (`shared/canvas-content.ts`), applies an op to the authority's
+ state and to every client's STORED copy of a project (background projects, and every board op).
+ Two appliers is how an authority and its clients silently diverge. The only other applier patches
+ the active project's live React Flow array for node ops (`applyMutationToFlow`), because a trip
+ through the serializers would wipe the selection; live edge ops go through the reducer's own edge
+ applier, `applyEdgeMutationToScene`.
+- **The solo-gate trap.** The publisher casts nothing while no teammate is attached, and on a governed
+ project that loses every edit. The gate is `shouldPublishFor` = `(hasPeers || governed) && sameCore
+ && !readOnly`: a Server Edition tab publishes every project until its first `canvas:authority`
+ answer and re-asks on reconnect, and neither our own echo nor a src-less core op proves a peer
+ (`provesPeer`). The desktop answers `[]`, so it is unchanged.
+- **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.
+
**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
-pauses the shared pty through Stage 2 backpressure; canvas edits made in a hosted tab are not
-written to the host, because a relay tab never saves the host workspace and the reflector persists
-nothing (ruling R42). Workaround: keep a Server Edition browser tab open on the host's core; it
-applies each reflected mutation, marks itself dirty and saves. Edits made while no browser tab is
-attached are lost. Kanban, bridge and rope edits made in a relay tab are never propagated or saved
-at all, because `canvas:mut` carries nodes only; that predates this feature.
+pauses the shared pty through Stage 2 backpressure; the canvas authority's own limits (outside edits
+of name/colour/icon/layouts, the share-time window, oversized nodes, board edits to another core,
+the card modal's comments on a relay tab) are under "Known limits" in the doc.
**Surfaces:** Desktop is full (joiner, plus approval and invite code in an owner's hosted tab).
Server Edition is the host (the `team` CLI; its browser clients cannot approve and are not hosted
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 42699b2be..7f0727a31 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -448,6 +448,12 @@ anything else. Board-level fields survive every transform — `pullLinks` is one
test forces that: without one, the event simply never arrives. Deep version: CLAUDE.md § Hosted
team relay.
+- **A change to canvas content that does not travel as a `canvas:mut` op is lost on a hosted core —
+ route new content edits through the op vocabulary (`src/shared/canvas-content.ts`).** On a Server
+ Edition hosting a team, the canvas authority writes a shared project's nodes, edges and board
+ from the ops it hears, and overlays every save with that content, so a content change that reaches
+ the core only inside a save is dropped from disk. Deep version: CLAUDE.md § Hosted team relay.
+
- **Normalize BOTH sides of a path comparison, through one function.** A marker normalized where
it is built and matched raw where it is used is a no-op on the machine you wrote it on and a
silent defect on Windows. That is issue #558: the managed-hook marker was folded to `/` while
diff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.md
index 31b73dc4c..4cf81c23b 100644
--- a/docs/hosted-team-relay.md
+++ b/docs/hosted-team-relay.md
@@ -30,9 +30,10 @@ every message**. The desktop's UI only mirrors it.
| Role policy | `access-policy.ts` | `VIEW`, `COMMENT`, `EDITOR_ONLY`, `VIEW_EVENTS`; the guard test is `access-policy.guard.test.ts`. |
| Admin channel | `team-admin.ts` (socket) + `src/server/team-cli.ts` (CLI) | `<dataDir>/relay/admin.sock`, 0600 in a 0700 directory. |
| Server boot | `src/server/index.ts` (search "Hosted team relay") | Booted in headless AND serving mode, after every handler is registered and the workspace index is loaded. |
+| Canvas authority | `src/core/canvas-authority.ts`; store seams in `src/core/workspace-store.ts`; wired in `src/server/index.ts` | The one writer of a shared project's canvas content. See [Shared canvas authority](#shared-canvas-authority). |
| Desktop joiner | `src/main/remote/hosted-join.ts`, `relay-bookmarks.ts`; core `join-code.ts`, `join-token.ts` | Runs the core relay client with **no pin store**. |
| Renderer | `lib/hostedJoin.ts`, `lib/hostedAttempts.ts`, `lib/hostedOwner.ts`, `lib/hostedPendingQueue.ts`, `components/HostedApprovalDialog.tsx`, `bridge/hosted-gate.ts`, `bridge/relay-local-close.ts`, `@shared/hosted-access.ts` | Every hosted branch sits behind a join code, a hosted api or a hosted role, so a Team Access tab and a local tab take their old paths (`canvas/hosted-team.source.test.ts`). |
-| End-to-end test | `src/server/hosted-e2e.test.ts` | A real headless server boot, the real admin socket, access policy, `PtyManager`, git handlers (a real repository) and trust gates, with an in-process relay and a fake token API. |
+| End-to-end test | `src/server/hosted-e2e.test.ts` | A real headless server boot, the real admin socket, access policy, `PtyManager`, git handlers (a real repository) and trust gates, with an in-process relay and a fake token API. It also checks that shared canvas edits are written with no browser attached and survive a restart. |
## Setup over SSH
@@ -99,22 +100,6 @@ on the same data directory still serves the UI, but it skips hosting ("Hosted te
started — another nodeterm server is already running on this data directory …") and disables its
agent hooks.
-To keep the UI running instead (the route [Limitations](#limitations-v1) needs for saving canvas
-edits), switch the unit to serving mode with a drop-in rather than by editing the unit:
-
-```bash
-mkdir -p ~/.config/systemd/user/nodeterm-server.service.d
-printf '[Service]\nEnvironment=NODETERM_HEADLESS=\n' \
- > ~/.config/systemd/user/nodeterm-server.service.d/serving.conf
-systemctl --user daemon-reload && systemctl --user restart nodeterm-server
-```
-
-An empty `NODETERM_HEADLESS` is not headless. A drop-in is parsed after the unit and the later
-assignment wins, and the installer (re-run daily by its auto-update) rewrites only the `.service`
-file, never its `.d/` directory, so the drop-in survives updates. For a root install the directory
-is `/etc/systemd/system/nodeterm-server.service.d/`, with plain `systemctl`. If no password exists
-yet, the first boot prints a one-time setup URL to the journal.
-
A joiner's tab shows **one** project: the first shared project in the host's workspace order
(`openRelayTab` adopts `projects[0]` of the narrowed workspace). With nothing shared, even an owner
gets an empty tab, because `workspace:load` is narrowed to `sharedProjects` for every hosted peer,
@@ -326,6 +311,109 @@ unapproved after 2.5 s, the tab says "Waiting for an owner of X to approve this
from an owner's desktop. The only way the CLI admits a device is `team add-owner`, which makes it
an owner.
+## Shared canvas authority
+
+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
+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`).
+
+**What is governed.** Every project in `team.json`'s `sharedProjects`, and nothing else. A project
+that is not shared, a server with no team, and a server that found another one on its data directory
+(it creates no authority) are saved as before; so is every desktop's canvas. A shared project's other
+fields (name, colour, icon, layouts, the board's `github` mapping and `pullLinks`) are not governed:
+whole-workspace saves still write them.
+
+**Its four inputs:**
+
+1. **Ops**: from Editors' hosted tabs, from the server's own browser tabs, and from server canvas
+ control, which diffs everything a verb changed and casts each op before it saves (`castAndSave`,
+ `src/server/headless-node-factory.ts`).
+2. **Saves.** Before a whole-workspace save is written, a governed project's content is replaced by
+ the authority's (`overlaySave`). The board is overlaid field by field: its items (columns, cards,
+ metadata, labels, views) come from the authority, `github` and `pullLinks` from the save. This
+ machine's exec fields (`shell`, `ssh.extraArgs`) are carried over from the save's copy of each
+ node, since the authority's own state holds none. A stale copy cannot write content back, with
+ one exception, the oversized node below.
+3. **Loads**, overlaid the same way (`overlayLoad`), so a client that loads sees every op the
+ authority applied, written to disk or not.
+4. **Outside edits.** A `git pull` or hand edit of a governed `.nodeterm/project.json`, seen by the
+ server's file watcher, is adopted: the authority re-applies the ops it has not written yet on top,
+ publishes the difference as `canvas:mut` ops, and broadcasts no `workspace:external-change`, so no
+ 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
+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
+read from the saved canvas.
+
+**When it adopts.** At boot, once `team.json` is loaded, every shared project is read, so an outside
+edit that lands before any op still has a baseline to compare with. `team share` adopts the project;
+`team unshare` writes what is pending, then lets it go (it is saved the old way again). The server's
+browser tabs are told the new governed set (`canvas:authority-changed`). A shared project whose file
+cannot be read stays governed, so its clients keep publishing, but the authority writes nothing for
+it and saves of it pass through unchanged until it can be read. The journal says so once:
+"[canvas-authority] project <id> is shared, but its content could not be read …". `team share` does
+not check the id, so a shared id that is not a project on this core logs the same line.
+
+**Publishing when alone.** A client normally casts nothing while no teammate is attached. On a
+governed project that would lose every edit, so a client publishes whenever the project is governed:
+a Server Edition browser tab asks its core (`canvas:authority`), publishes for every project until
+the first answer arrives, and asks again on reconnect; a hosted relay tab treats every project it
+holds as governed. The desktop answers that it governs nothing, so a desktop publishes exactly as
+before.
+
+**Relay peers cannot save the host's workspace.** A `workspace:save` from a hosted relay peer is
+refused for every role, owners included, with `E_ROLE`: "A hosted team cannot save the host's
+workspace over the relay; edits travel as canvas operations". A whole-workspace save from a peer is a
+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
+below.
+
+**Bridges grant reads.** On the Server Edition, which agent sessions may read each other's context
+(Context Link) is derived from the saved `bridges` of every canvas (`src/server/context-link.ts`). A
+link an Editor draws in a hosted tab is now saved, so it lets the two agents it joins read each
+other's conversation on the host. An Editor already has a shell there, so this is no new power, but
+it is a new way to use it.
+
+### Known limits
+
+- **An outside edit's other fields are not delivered live.** A pulled change to a governed project's
+ name, colour, icon or layouts reaches no client until that client loads again. A Server Edition
+ browser tab that saves before it reloads writes its own copies back over the pulled ones: those
+ fields are still whole-file, last writer wins.
+- **The share-time window.** An edit a client made just before `team share` (not yet cast because it
+ was alone, or cast but not yet saved) is not in what the authority reads from disk, and that
+ client's next save is overlaid, so the edit can be lost from disk. It stays on that client's screen
+ until it reloads. The window is short: a client saves 800 ms after its last change.
+- **Oversized nodes.** A node too large to travel as an op is taken from saves, with three
+ consequences. A client's save issued before that client applied a `remove` of such a node still
+ carries it, so the node is written back and stays until someone removes it again (the other
+ clients see it only after they reload). An outside edit of such a node reaches no client (the op
+ is refused as too large), and the next client save can put the client's older copy back. Two
+ clients holding different copies of one such node replace each other's on every save.
+- **Board edits reach only the active tab's core.** A client casts only to the core its active tab
+ 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.
+- **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.
+
## Status and troubleshooting
`team status --json` returns:
@@ -476,23 +564,7 @@ The human `team status` reads `state`, `idle` and `lastError` together:
pauses the shared pty for every subscriber until that backlog drains below 256 KB or the peer
leaves. Past 8 MB its output is dropped (redrawn later) and the pause is handed back
(`ui-sink-registry.ts`).
-- **Canvas edits in a hosted tab are not saved on the host.** A relay tab never writes the host's
- workspace (it would replace the whole host index with one project), and the core's canvas
- reflector persists nothing. So nodes a teammate adds, moves or deletes are live for everyone
- connected, but are not in the host's project file: a teammate who connects later, or everyone
- after a host restart, sees the saved canvas. A terminal an Editor starts that way keeps running
- on the host, but Viewers cannot watch it, because node membership is read from the saved canvas.
- **Workaround (verified in code, not yet run; device checklist item 12):** run the service in
- serving mode with the drop-in from setup step 1, and keep a Server Edition browser tab open on it
- through an SSH tunnel. The one-off serving run in step 1 is not enough: it ends by restarting the
- headless unit. The reflector sends every mutation to every attached client, and a browser's canvas
- applies it and marks itself dirty (to its store for a background project, to the live canvas for
- the active one), so its own autosave writes the edit. Edits made while no browser tab is attached,
- including across a service restart, are lost. This is a v1 limitation (ruling R42); a server-side
- persister belongs to sub-project 2.
-- **Kanban, bridge and rope edits made in a relay tab are never propagated or saved.** `canvas:mut`
- carries nodes only (an upsert or a remove), so project-level state (`kanban`, `bridges`, `ropes`)
- never leaves the tab. This predates the hosted relay; it holds for Team Access relay tabs too.
+- **Shared canvas edits:** see [Known limits](#known-limits) under Shared canvas authority.
- **No git for Viewers in a subfolder of a larger repository.** Viewers and Commenters get the git
panel only for a project that is the top folder of its own repository (or a worktree's). A
monorepo subfolder shows its files but refuses every git read (see [Roles](#roles)).
@@ -583,8 +655,15 @@ on a Mac and a second desktop as a teammate. Record `team status --json` at each
is `~/Library/Application Support/node-terminal/remote-peer-key.json` (the setup step 2 command
prints the key), and `ls ~/Library/Application\ Support/*/remote-peer-key.json` finds no other
copy.
-12. **Canvas edits survive with a browser tab attached (R42 workaround).** With the service in
- serving mode (the setup step 1 drop-in) and a Server Edition browser tab open on it, a teammate
- adds and moves a node in their hosted tab. After `systemctl --user restart nodeterm-server`, a
- reconnected teammate (and the browser tab) still sees the node where it was moved. Repeat with no
- browser tab attached: the edit is lost, as documented.
+12. **Edits persist with no browser attached.** With the service headless and no Server Edition tab
+ open, an Editor adds a node, moves another, draws a link and moves a card in a shared project.
+ Wait 5 s, then `systemctl --user restart nodeterm-server`: after the reconnect every edit is
+ still there, and in the project's `.nodeterm/project.json`.
+13. **A `git pull` during a drag.** While a teammate drags a node of a shared project, pull (or hand
+ edit) that project's `.nodeterm/project.json` on the host with a change to another node. No
+ client shows the Reload / Keep mine bar, the pulled change appears on every client, and the
+ teammate's node stays where they dropped it.
+14. **Two cards at once.** Two teammates move two different cards of one shared board at the same
+ moment. Both moves stay, on both screens and after a service restart.
+15. **A Windows joiner.** A teammate on a Windows desktop joins, moves a card and adds a column; both
+ are still there after a service restart.
diff --git a/docs/team-presence.md b/docs/team-presence.md
index 47927ad97..dac8c9db4 100644
--- a/docs/team-presence.md
+++ b/docs/team-presence.md
@@ -14,8 +14,11 @@ that stamps one total order (`seq`) and fans each mutation to every client, a di
with an `adopt()` loop guard and a solo gate, per-node last-write-wins in that order
(`canvas-order.ts`) so concurrent edits **converge** instead of splitting the canvas in two, an
in-place apply into the live React Flow array, a real `window.nodeTerminal.canvas` on both surfaces,
-and per-project apply (including into a loaded-but-inactive project's serialized nodes). What it
-resolves and what it does not:
+and per-project apply (including into a loaded-but-inactive project's serialized nodes). Edges and
+board items now travel on the same channel, ordered by the same rules
+([Edge sync](#edge-sync-bridges--ropes), [Board sync](#board-sync-kanban)); on a Server Edition
+hosting a team, a shared project's content is written from these ops by the canvas authority
+(`docs/hosted-team-relay.md`). What it resolves and what it does not:
[Concurrent-edit resolution](#concurrent-edit-resolution-what-converges-and-what-does-not).
Deltas between this document and what actually shipped are recorded in
[What Stage 1 changed](#what-stage-1-changed-relative-to-this-spec),
@@ -347,7 +350,9 @@ 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
-backstop.
+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`).
Two things are deliberately **not** synced: ephemeral nodes (subagent / loop cards) are derived
independently on each client from the already-broadcast `agent:status` stream; and undo stays
@@ -365,7 +370,13 @@ independently on each client from the already-broadcast `agent:status` stream; a
re-render Canvas). With nobody else attached, `publish()` degrades to `adopt()`: it takes the
snapshot as the baseline and does **no** diff, no `stableStringify` of every node, no IPC cast. A
solo user pays nothing for team sync, and because the baseline still tracks the canvas, the first
- edit after a peer joins diffs correctly — no resync step, no missed mutation.
+ edit after a peer joins diffs correctly — no resync step, no missed mutation. **The exception is a
+ governed project** (`shouldPublishCanvas`: peers OR governed). A canvas authority writes a project
+ only from the ops it hears, so an edit the solo gate swallowed there would be erased by the next
+ overlaid save. A Server Edition tab asks its core which projects are governed (`canvas:authority`),
+ publishes for every project until the first answer, and asks again on reconnect; the desktop
+ answers none, so its gate is unchanged. Only a cast from ANOTHER client proves a peer
+ (`provesPeer`): our own echo and a core-published op (no `src`) do not.
- **Reflector** (`src/core/canvas-sync.ts`) — holds no canvas state and persists nothing, but it is
**not** stateless: it stamps every mutation with a monotone **`seq`** and sends it to **every**
attached client, the sender included (`CorePlatform.clientIds()` + `onWithSender`). `seq` is
@@ -391,8 +402,9 @@ independently on each client from the already-broadcast `agent:status` stream; a
ws-bridge's `location.reload()`. The reset keeps one thing: our own causal position (`lastSeq`,
what rule 4's `seen` stamps). A reconnect to the SAME core also resets, and a first cast stamped
`seen: 0` there — ⌘Z of a node deleted before the drop — was a stale frame to every peer holding
- the tombstone. After a real restart the kept value is above every new `seq`, and the reflector
- clamps it to `seq - 1`, so our casts read as "never stale": the pre-rule-4 verdict, not a split.
+ the tombstone. After a real restart the kept value is above every new `seq`, so our casts read as
+ "never stale": the pre-rule-4 verdict, not a split. (The reflector clamps it to `seq - 1`, which
+ changes no verdict here; see the note on the clamp under rule 4.)
- **A cast the reflector would refuse is never made** — the publisher validates with the **same**
predicate the reflector's ingest uses (`isCanvasMutation`, moved to `src/shared/canvas-mutations.ts`
so both ends share one verdict) *before* recording a pending entry and *before* casting. A refusal
@@ -422,7 +434,7 @@ Stage 3 addressed **nodes**. Edges — `bridges` (context links, which an agent
through) and `ropes` (display-only "spawned by" lineage) — were left out, and that was the worst
gap the stage shipped with, because they are **persisted in the same whole-file `workspace.save`**.
An edge you drew never reached your teammate, and their next save — of a canvas that never had it —
-**deleted it**. Same in reverse. The advice was "draw links when you are alone on the canvas".
+**deleted it**. Same in reverse.
They are in the vocabulary now, and everything around them is the node machinery unchanged:
@@ -497,9 +509,75 @@ open: a peer edge op applied in the same task as a local functional edge update
update (the node path no longer does: its receive `setNodes` is functional, `rebaseOnLatest`); a
local node delete publishes its `remove` first and the
pruned edges' `edge-remove`s one render later, and every peer prunes the same dangling edge itself
-(converges, with redundant casts); canvas-control writes into a project that is not on screen, and
-the Server Edition's headless edge writes, are not cast as edge ops (the latter reach browsers
-through `workspace:server-change`, which every tab with peers then re-casts).
+(converges, with redundant casts); canvas-control writes into a project that is not on screen are
+not cast as edge ops. The Server Edition's headless canvas control is cast now: it diffs every
+project's whole content (nodes, edges, board) against what it last loaded or saved, and casts every
+op before it saves (`castAndSave`, `src/server/headless-node-factory.ts`).
+
+## Board sync (kanban)
+
+The board (`project.kanban`) had the edges' problem: `canvas:mut` carried no board item, and the
+board rode every whole-file save, so a teammate's card move never reached you and your next save
+wrote your board over theirs. Board items are in the vocabulary now, one op per item
+(`src/shared/kanban-ops.ts`), under a third key prefix:
+
+| Item | Ops | Order key |
+|---|---|---|
+| Column | `kb-column` / `kb-column-remove` | `k:col:<id>` |
+| Column order | `kb-column-order` | `k:colorder:<projectId>` |
+| Card placement | `kb-card` / `kb-card-remove` | `k:card:<nodeId>` |
+| Card metadata | `kb-meta` / `kb-meta-remove` | `k:meta:<nodeId>` |
+| Label | `kb-label` / `kb-label-remove` | `k:label:<id>` |
+| Label order | `kb-label-order` | `k:labelorder:<projectId>` |
+| Saved view | `kb-view` / `kb-view-remove` | `k:view:<id>` |
+
+- **Last writer wins per ITEM, not per board.** The node rules are unchanged: per key, the highest
+ `seq` wins. Two people moving two different cards at once both land; two moves of the same card
+ end on the later-ordered one. A card's placement and metadata key by its node id under their own
+ sub-prefix, so a card move is not a node edit, and deleting a node does not tombstone its card.
+- **The two order keys carry the project.** Each is a per-project singleton, and one `CanvasOrder`
+ orders every loaded project: unscoped, our unacked reorder in one project held off (rule 2) a
+ teammate's reorder in another.
+- **Rule 4 is for deletions only.** `kb-column-remove`, `kb-label-remove` and `kb-view-remove` mean
+ "this item is gone" and tombstone their key, exactly like `remove` and `edge-remove`.
+ `kb-card-remove` ("back to Ungrouped") and `kb-meta-remove` ("no metadata") are VALUES and order
+ like any other write (`isKanbanDeletion`): a card taken off the board and filed again is not a
+ resurrection, and a tombstone would drop a teammate's concurrent move as a stale frame.
+- **Order ops are cast on additions too.** An item op only says the item exists, and a peer that
+ applies it alone appends it. So the publisher also casts the list's order op whenever the list
+ gained an id or the relative order of the ids both sides share changed (`orderChanged`), and every
+ replica lands on the later order op's list. Residual: an order op lists only the ids its sender
+ knew, so two ids added in the same window by two different clients can sit in different relative
+ orders until the next order op.
+- **Names are repaired, not refused.** A column title, label name or assignee name is trimmed,
+ stripped of control and bidi-override characters and cut to its bound (`displayText`); only an
+ empty result is refused. The UI puts no length cap on them, so a refusal would be a rename that
+ silently never syncs. Ids are refused, never repaired. The sender casts the repaired form and keeps
+ it locally too, because its own echo is only an ack (`renderer/canvas/kanban-sync.ts`).
+- **Default columns are deterministic.** A project with no `kanban` block renders a lazy default
+ board that is not written until the first edit, and with live sync two people can make that edit
+ at once. Its column ids are a hash of the project id and the column's index (`seededColumnId`,
+ `defaultKanbanFor` in `src/shared/kanban-default-board.ts`): the same on every client, so the two
+ first edits land on the same three columns instead of six. A board created explicitly (the core's
+ `ensureProjectBoard`, the phone's first board) keeps random ids.
+- **The publisher hangs off the one store funnel.** Every board write goes through
+ `useProjects.setProjectKanban`, whose hook diffs the board item by item and casts through the same
+ send and the same publish gate as nodes: the board, the card modal, the Omni board, node labels and
+ the `assign` verb all publish without a call site of their own. A peer's board op is applied
+ through the store reducer (`applyCanvasOp`), never through `setProjectKanban`, so nothing received
+ is published again, and it writes no board-log entry: only the client that made a change records
+ it. The entries a board change writes go through the project's own session (a relay tab's to its
+ host).
+- **Prune removals are never cast.** Every board commit prunes the cards of nodes that are not live
+ locally. A teammate whose node op has not arrived yet would otherwise cast the removal of a fresh
+ card for everyone, so `diffKanbanOps` casts a card or metadata removal only for a node live in that
+ project: React Flow's nodes for the project it holds, the stored nodes for any other. While the Omni
+ board is open, React Flow ∩ the stored copy (`boardLiveNodeIds`): its lanes prune against the stored
+ copy, which lags React Flow for the rendered project, and a smaller live set can only cast fewer
+ removals. The cost: removing, on the Omni board, the card of a node created moments ago is not cast.
+- **A board edit is cast only to the active tab's core** (`castFor`), as a node edit is: the order
+ hears one core's echoes. A board edit to a lane on another core (the Omni board editing a relay
+ lane while a local tab is active, or the reverse) is not cast.
## UI
@@ -691,8 +769,9 @@ here so the delta is legible.
two live paths still reach `create` for a deleted node, and both would spawn a fresh `nt-<id>`
(the terminal its owner deliberately killed, as an empty shell) if the tombstone were deleted:
- **Project-level operations are not in the mutation vocabulary.** `CanvasMutation` addresses
- *nodes*. `deleteProject` (`src/renderer/canvas/Canvas.tsx`, the `×` on a "Recently closed"
- entry) ends every terminal's tmux session via `transport.destroy(nodeId)` and publishes
+ nodes, edges and board items, never a project. `deleteProject`
+ (`src/renderer/canvas/Canvas.tsx`, the `×` on a "Recently closed" entry) ends every
+ terminal's tmux session via `transport.destroy(nodeId)` and publishes
**nothing** — the project itself, with all of its nodes, is still in every peer's `projects`
store. A peer that reopens it from *its* "Recently closed" list mounts those nodes and creates
their ptys. Only the tombstone refuses that.
@@ -723,18 +802,20 @@ here so the delta is legible.
would kill the owner's live session for real.
- **Project lifecycle** (create / rename / close / delete / folder change) is **not** synced.
- **Viewport, selection and undo** are not synced. Undo is local per user, by design.
- - **No conflict resolution beyond per-node last-write-wins.** See
+ - **No conflict resolution beyond per-item last-write-wins** (per node, edge or board item). See
[Concurrent-edit resolution](#concurrent-edit-resolution-what-converges-and-what-does-not).
No CRDT.
## Concurrent-edit resolution: what converges, and what does not
-**Converges — guaranteed, on any interleaving.** Every client ends with the same **node set** and
-the same **value** for every node, because every mutation is ordered by the reflector's `seq` and the
-highest `seq` per node wins everywhere (`src/shared/canvas-order.ts`). This is the property
-persistence depends on: whichever client's whole-file `workspace.save` runs, it writes a canvas the
-others agree with. Proven end-to-end against an **asynchronous** bus (queued casts + FIFO deliveries,
-edits genuinely in flight) in `src/core/canvas-sync.convergence.test.ts`.
+**Converges, on any interleaving, among the clients that saw the whole exchange.** Every such client
+ends with the same **set** and the same **value** for every node and edge, and shows the same board,
+because every mutation is ordered by the reflector's `seq` and the highest `seq` per item wins
+everywhere (`src/shared/canvas-order.ts`). A client that loaded after a delete did not see it all; it
+is the first entry in the list below, and the board's exceptions are listed there too. This is the
+property persistence depends on: whichever client's whole-file `workspace.save` runs, it writes a
+canvas the others agree with. Proven end-to-end against an **asynchronous** bus (queued casts + FIFO
+deliveries, edits genuinely in flight) in `src/core/canvas-sync.convergence.test.ts`.
That guarantee does **not** rest on any timeout. The pending TTL is a bound on how long we *suppress*
peers, never on correctness: an ack that arrives after it **repairs** the node (rule 3 above), and a
@@ -745,6 +826,13 @@ concurrently with a peer's delete.
**Does NOT converge — named, not hidden:**
+- **A stale frame reaching a client that holds no tombstone.** Rule 4 (below) judges an upsert only
+ against the removes a client has itself applied. A client that loaded the canvas after a delete, or
+ reset its order on a reconnect (`reset()` clears the tombstones), has none for that node, so a stale
+ frame for it arriving later (from a peer whose socket was stalled) is applied there and dropped by
+ every other client. That client holds a node the others do not until its next load, and its next
+ whole-file save can write it back. (A canvas authority that heard the delete drops the frame too,
+ and overlays that save.)
- **Array order after a resurrection.** If a node is deleted and then legitimately re-created, the
client that issued the delete removed it and re-appended it, so it can sit in a different **slot**
in the array than on a client that never removed it. Node set, positions, sizes and data all agree;
@@ -755,7 +843,13 @@ concurrently with a peer's delete.
- **Edge array ORDER**, for the same reason and with even less consequence: two clients that draw
an edge at the same time each append the peer's to their own, so the two arrays hold the same
edges in different slots. Nothing lists edges in order; they are rendered as a set.
-- **Anything outside the node/edge vocabulary** — project lifecycle (see item 5 above).
+- **Board column and label order, for ids two clients added in the same window**, until the next
+ order op (see [Board sync](#board-sync-kanban)).
+- **A card's stored placement when its column is deleted as it is filed there.** Depending on the
+ order, one client can keep a placement naming the deleted column while another has none. Both show
+ the card in Ungrouped, which holds every card with no placement or one naming no column
+ (convergence case 5 in `src/core/canvas-sync.convergence.test.ts`).
+- **Anything outside the node/edge/board vocabulary** — project lifecycle (see item 5 above).
### A delete beats a concurrent edit — CAUSALLY, not by a tiebreak (rule 4)
@@ -789,10 +883,14 @@ op is usually what arrives during that round trip). Nothing else would ever cast
ack and changes no React state — so the echo that clears the gate re-publishes, after the handler and
only when the publisher `hasOwed()`.
-`seen` is client-supplied and it *decides* something, so the reflector **bounds** it
-(`stampMutation`): it can never legitimately reach the order the mutation is being given, so it is
-clamped there, and a non-integer/negative one is dropped. A mutation with **no** `seen` (an older
-peer, the relay mirror) is judged exactly as before rule 4 existed — degrade, never break.
+`seen` is client-supplied. The reflector tidies it (`stampMutation`): a value at or past the order the
+mutation is being given is clamped to just below it, and a non-integer or negative one is dropped.
+**The clamp is hygiene, not a guard: it changes no verdict.** A remove ordered before this mutation
+has a `seq` at most `seq - 1`, so a clamped `seen` still counts as having seen it, and a remove ordered
+after it supersedes it by `seq` alone. A forged `seen` therefore resurrects a deleted node, clamp or no
+clamp. What bounds that is who may cast at all: on a hosted team `canvas:mut` is Editor-only, and an
+Editor has a shell on the host anyway. A mutation with **no** `seen` (an older peer, the relay mirror)
+is judged exactly as before rule 4 existed — degrade, never break.
What this does **not** do: un-kill the process. If the delete wins, the terminal is gone, which is
what the human asked for. If the node is deliberately re-created later, it is still a fresh session
@@ -859,6 +957,15 @@ read-only guests, per-user settings.
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
group parents before their children. → `src/renderer/state/workspace.mutation.test.ts` (10 tests)
+- **Board sync** (delivered): the reducer and sanitizers per op; two different cards moved at once
+ both land; one card moved twice ends on the later op; two first-ever board edits make three
+ columns, not six; a card whose node has not arrived survives a peer that prunes it; a column
+ deleted while a card moves into it leaves the card in Ungrouped; concurrent column and label adds
+ converge. → `src/shared/kanban-ops.test.ts`, `src/shared/kanban-ops.convergence.test.ts`,
+ `src/shared/canvas-content.test.ts`, `src/renderer/canvas/kanban-sync.test.ts`, and the board cases
+ in `src/core/canvas-sync.convergence.test.ts`. The Server Edition's canvas authority has its own
+ suite (`src/core/canvas-authority.test.ts`) and an end-to-end run with no browser attached
+ (`src/server/hosted-e2e.test.ts`).
### Manual smoke test (Stage 1)
@@ -1035,8 +1142,9 @@ logged in, named, and on the **same project**.
- **Weak identity** — anyone can claim any name.
- **Concurrent typing garbles input** — accepted; the badge is the warning.
- **Cross-user undo** — last-write-wins, no CRDT.
-- **Per-node last-write-wins is a resolution, not an arbitration.** Clients always converge, but two
- people dragging one node fight over it and the last-ordered frame decides. (A delete no longer
+- **Per-item last-write-wins is a resolution, not an arbitration.** Clients that saw the whole
+ exchange converge (a client that loaded after a delete may not: see the does-not-converge list), but
+ two people dragging one node fight over it and the last-ordered frame decides. (A delete no longer
loses that race — see rule 4 under
[Concurrent-edit resolution](#concurrent-edit-resolution-what-converges-and-what-does-not).)
- ~~**A peer's edge (context link / note link) is deleted by your next save.**~~ Closed — edges are
@@ -1045,7 +1153,8 @@ logged in, named, and on the **same project**.
completes, that client sees no peers and therefore publishes nothing (it still *applies* what it
receives, and the first mutation from a peer flips the gate on for good). Presence and canvas sync
ride the same transport, so a client that cannot say hello generally cannot cast either — but the
- coupling is real and is the price of a solo user paying zero.
+ coupling is real and is the price of a solo user paying zero. A project a canvas authority governs
+ does not depend on it: its clients publish whether or not they see a peer.
- **Cursor traffic** is 20 Hz × peers: comfortable for a 5–10 person team, not for a public room.
- **Plain-shell (no tmux) co-attach shows a joiner a blank-but-live terminal** until the next output
arrives (pressing Enter paints it). A joiner gets `fresh:false`, so it skips the cold-restore