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.

fix(team): an adopt keeps a refused node and its held edges owed

reviewabc5898a871d
diff --git a/docs/team-presence.md b/docs/team-presence.md
index 898efe9fe..84ff78cd6 100644
--- a/docs/team-presence.md
+++ b/docs/team-presence.md
@@ -462,11 +462,19 @@ They are in the vocabulary now, and everything around them is the node machinery
- **An edge whose endpoint the peer does not have is held, not cast.** A node the size guard refuses
(an oversized sticky) never reaches the peer; an edge to it that did would be pruned there, and the
peer's `edge-remove` would delete the link on our canvas too. The publisher holds such an
- `edge-upsert` inside the emit that refused the node (and on every later one while the node's last
- cast stays refused, across adopts — `refusedNodeIds()`), keeps it owed, and casts it in the same
- batch as the node once the node goes through. The hold is in the publisher, not a filter on the
- scene: dropping an edge the baseline already holds would diff as an `edge-remove` — the same delete,
- cast by us. It is conservative: an edge to a node whose EARLIER version the peer has also waits.
+ `edge-upsert` inside the emit that refused the node (and on every later emit while the node's last
+ cast stays refused — `refusedNodeIds()`), keeps it owed, and casts it in the same batch as the node,
+ after it, on the first emit in which the node goes through. That holds across adopts too: an adopt
+ (every peer op, every project load) takes the scene on screen, which already contains the refused
+ node and the held edge, so the adopted baseline keeps the PREVIOUS baseline's entry for the owed
+ node and every edge touching it (`adoptBaseline`) — otherwise the node would re-diff only when it
+ next changed, and the edge would never differ from the baseline again and never be cast. The hold
+ is in the publisher, not a filter on the scene: dropping an edge the baseline already holds would
+ diff as an `edge-remove` — the same delete, cast by us. It is conservative: an edge to a node whose
+ EARLIER version the peer has also waits. What it does not cover: a baseline taken while the solo
+ gate is closed (`shouldPublish` false) is not rebased, so an owed item swallowed there syncs only
+ when it next changes; the gate closes on an open publisher only when a hosted role drops to
+ read-only.
- **"This note is too large" is said only for a node upsert.** An edge op is refused only for a
malformed or over-long id, so the sentence would name a cause nobody measured; the refusal is
logged instead.
diff --git a/src/shared/canvas-publish.test.ts b/src/shared/canvas-publish.test.ts
index 9e5e87604..406547961 100644
--- a/src/shared/canvas-publish.test.ts
+++ b/src/shared/canvas-publish.test.ts
@@ -481,3 +481,94 @@ describe('an edge to a refused node', () => {
expect(p.refusedNodeIds().size).toBe(0)
})
})
+
+// An adopt (every peer op, every project load) replaces the baseline with the scene on screen —
+// which already holds a refused node and the edges held for it. Taken as-is, that baseline claims
+// the peer has them: once the node finally casts, the held edge no longer differs from the baseline,
+// so it is never cast, and the peer's next save drops it. An adopt therefore keeps owed items owed.
+describe('an adopt does not swallow what is still owed', () => {
+ const link = (id: string, source: string, target: string): BridgeLink => ({ id, source, target })
+ const scene = (nodes: CanvasNodeState[], bridges: BridgeLink[] = [], ropes: BridgeLink[] = []) => ({
+ nodes,
+ bridges,
+ ropes
+ })
+ const label = (m: CanvasMutation): string =>
+ `${m.op}:${mutationNodeId(m) ?? (m.op === 'edge-remove' ? m.id : m.op === 'edge-upsert' ? m.edge.id : '')}`
+ /** Refuses node UPSERTS for the ids in `bad` — what the size guard does to an oversized sticky
+ * (a remove is never too large). */
+ function refusing(bad: Set<string>) {
+ const sent: CanvasMutation[] = []
+ const send = (m: CanvasMutation): boolean => {
+ if (m.op === 'upsert' && bad.has(m.node.id)) return false
+ sent.push(m)
+ return true
+ }
+ return { sent, send }
+ }
+
+ it('a held edge is cast after its endpoint once the endpoint fits, even with an adopt in between', () => {
+ const bad = new Set(['big'])
+ const c = refusing(bad)
+ const p = createCanvasPublisher(c.send)
+ p.publish(scene([node('big'), node('t')], [link('b1', 'big', 't')])) // big refused, b1 held
+ p.adopt(scene([node('big'), node('t', 5)], [link('b1', 'big', 't')])) // a peer op landed
+ bad.clear() // the user trims the sticky
+ p.publish(scene([node('big', 1), node('t', 5)], [link('b1', 'big', 't')]))
+ expect(c.sent.map(label)).toEqual(['upsert:t', 'upsert:big', 'edge-upsert:b1'])
+ expect(p.refusedNodeIds().size).toBe(0)
+ })
+
+ it('after the trim the edge is cast exactly once, and a later publish casts nothing', () => {
+ const bad = new Set(['big'])
+ const c = refusing(bad)
+ const p = createCanvasPublisher(c.send)
+ const now = () => scene([node('big', 1), node('t', 5)], [link('b1', 'big', 't')])
+ p.publish(scene([node('big'), node('t')], [link('b1', 'big', 't')]))
+ p.adopt(scene([node('big'), node('t', 5)], [link('b1', 'big', 't')]))
+ bad.clear()
+ p.publish(now())
+ const cast = c.sent.length
+ p.publish(now())
+ p.publish(now())
+ expect(c.sent.filter((m) => m.op === 'edge-upsert')).toHaveLength(1)
+ expect(c.sent.slice(cast)).toEqual([])
+ })
+
+ it('holds for a lazy adopt thunk too (what Canvas actually passes)', () => {
+ const bad = new Set(['big'])
+ const c = refusing(bad)
+ const p = createCanvasPublisher(c.send)
+ p.publish(() => scene([node('big'), node('t')], [link('b1', 'big', 't')]))
+ p.adopt(() => scene([node('big'), node('t', 5)], [link('b1', 'big', 't')]))
+ bad.clear()
+ p.publish(() => scene([node('big', 1), node('t', 5)], [link('b1', 'big', 't')]))
+ expect(c.sent.map(label)).toEqual(['upsert:t', 'upsert:big', 'edge-upsert:b1'])
+ })
+
+ // Why the adopted baseline keeps the owed items' PREVIOUS entries instead of dropping them: the
+ // peer may hold an older version of the refused node (and its edge). Dropped from the baseline, a
+ // later local delete would diff to nothing — and the peer would keep both forever.
+ it('a node the peer holds an older version of is still deleted on the peer after an adopt', () => {
+ const bad = new Set<string>()
+ const c = refusing(bad)
+ const p = createCanvasPublisher(c.send)
+ p.publish(scene([node('n'), node('t')], [link('b1', 'n', 't')])) // all cast
+ bad.add('n')
+ p.publish(scene([node('n', 9), node('t')], [link('b1', 'n', 't')])) // n's edit refused
+ p.adopt(scene([node('n', 9), node('t', 5)], [link('b1', 'n', 't')]))
+ const cast = c.sent.length
+ p.publish(scene([node('t', 5)])) // the user deletes n (its link goes with it)
+ expect(c.sent.slice(cast).map(label)).toEqual(['edge-remove:b1', 'remove:n'])
+ })
+
+ it('an adopt with nothing owed stays lazy', () => {
+ const c = collect()
+ const p = createCanvasPublisher(c.send)
+ p.publish([node('a')])
+ const snapshot = vi.fn(() => [node('a', 1)])
+ p.adopt(snapshot)
+ p.adopt(() => [node('a', 2)])
+ expect(snapshot).not.toHaveBeenCalled()
+ })
+})
diff --git a/src/shared/canvas-publish.ts b/src/shared/canvas-publish.ts
index 52060b132..4ad06f2e2 100644
--- a/src/shared/canvas-publish.ts
+++ b/src/shared/canvas-publish.ts
@@ -54,7 +54,8 @@ export interface CanvasPublisher {
* the baseline and nothing is diffed or sent — a solo user pays nothing for team sync. */
publish(next: CanvasSnapshot, opts?: { throttle?: boolean }): void
/** Take `next` as the new baseline WITHOUT sending — the loop guard (a peer's mutation, or a
- * programmatic project load). The next diff against it is empty. */
+ * programmatic project load). The next diff against it is empty, except for what is still owed
+ * (a refused node and the edges held for it), which stays owed — see `adoptBaseline`. */
adopt(next: CanvasSnapshot): void
/** Send any coalesced drag frame immediately (drag settle / unmount). */
flush(): void
@@ -146,8 +147,8 @@ export function createCanvasPublisher(
let pending: CanvasSnapshot | null = null
let timer: ReturnType<typeof setTimeout> | null = null
/** Node ids whose latest cast was refused and not yet made good (`refusedNodeIds`). Kept ACROSS
- * emits and adopts: an adopt takes the refused node into the baseline (so it is no longer
- * re-diffed) but the peer still does not have it — which is exactly when an edge to it must wait. */
+ * emits and adopts: the peer still does not have the node, so an edge to it must keep waiting,
+ * and an adopt keeps both owed in the baseline (`adoptBaseline`). */
const owedNodes = new Set<string>()
const resolve = (s: CanvasSnapshot): CanvasScene =>
@@ -173,6 +174,45 @@ export function createCanvasPublisher(
}
}
+ /**
+ * Take an ADOPTED snapshot as the baseline without letting it swallow what is still owed.
+ *
+ * An adopt (a peer's op applied locally, a project load) takes the scene on screen, and that scene
+ * already holds every refused node and every edge held for one. Taken as-is, the baseline would
+ * claim the peer has them: the node re-diffs only if it changes again, and once it finally casts,
+ * a held edge no longer differs from the baseline, so it is never cast at all — the peer's next save
+ * then drops it. So for the owed nodes, and every edge touching one, the adopted baseline keeps the
+ * PREVIOUS baseline's entry (the refusal rebase, reused): absent where the peer never had it, the
+ * older version where it did. Dropping them outright instead would lose that older version, and a
+ * later local delete of the node would diff to nothing.
+ *
+ * Only while something is owed — and then the previous baseline is resolved now, one serialize per
+ * adopt, because the adopted thunk must be rebased against the baseline AS OF this adopt. With
+ * nothing owed an adopt is exactly what it was: a thunk stored unresolved.
+ */
+ const adoptBaseline = (s: CanvasSnapshot): void => {
+ if (!owedNodes.size) {
+ setBaseline(s)
+ return
+ }
+ const owed = new Set(owedNodes)
+ const prev = baseline()
+ const keepOwed = (next: CanvasScene): CanvasScene => {
+ const keys = new Set<string>()
+ for (const id of owed) keys.add('n:' + id)
+ for (const e of [...prev.bridges, ...prev.ropes, ...next.bridges, ...next.ropes]) {
+ if (owed.has(e.source) || owed.has(e.target)) keys.add('e:' + e.id)
+ }
+ return rebaseRefused(prev, next, keys)
+ }
+ if (typeof s === 'function') {
+ lastLazy = () => keepOwed(asScene(s()))
+ } else {
+ last = keepOwed(asScene(s))
+ lastLazy = null
+ }
+ }
+
const emit = (snapshot: CanvasSnapshot): void => {
if (!shouldPublish()) {
setBaseline(snapshot) // solo: adopt as baseline, diff nothing, send nothing
@@ -249,7 +289,7 @@ export function createCanvasPublisher(
emit(next)
},
adopt(next) {
- setBaseline(next)
+ adoptBaseline(next)
pending = null
},
flush() {