@north-light/crouter 0.3.154

package/dist/core/__tests__/flagship-lifecycle.test.js

@@ -0,0 +1,303 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/flagship-lifecycle.test.ts
+//
+// HEADLESS RETARGET (foundation-spec §C.9 + §E). The flagship end-to-end
+// lifecycle scenario, driven entirely at the MODEL layer against FABRICATED
+// broker-hosted (paneless) nodes — no real tmux session, no pane chrome, and NO
+// real broker boot. The full status×intent×lifecycle×mode state machine is host-
+// independent: every hop is a CLI lifecycle verb (promote/yield) or a pure model
+// op (fabricate + subscribe + transition + pushFinal + superviseTick), so the
+// scenario never pays the ~5s SDK-boot cost.
+//
+// THREE-PART LOCK HEADER ──────────────────────────────────────────────────
+// (1) BUG LOCKED — the full lifecycle state machine (state-model §2): each hop
+//     (spawn → terminal idle-release dormancy → one-hop wake → promote → yield-
+//     refresh → finish) must land in the correct durable (status,intent,
+//     lifecycle,mode) and route completion ONE HOP up the spine (a push fans to
+//     DIRECT subscribers only; an indirect ancestor hears nothing until a middle
+//     node re-pushes).
+// (2) WHY MODEL-LEVEL, NOT PANE/WINDOW — every transition lives in canvas.db +
+//     the lifecycle table (transition()) + the daemon's second-pass wake gate +
+//     the feed fan-out. A tmux node showed dormancy as a closed pane; a broker
+//     shows it as an EXITED process (status=idle, intent=idle-release, pi_pid
+//     dead) — fabricated directly. The only thing a pane ever added was a visible
+//     dormancy signal, which a broker expresses as a dead pid. No pane is read.
+// (3) HOW THE HEADLESS DRIVE STILL FAILS IF THE FIX REGRESSES — the one-hop wake
+//     is asserted via getNode(B).cycles (reviveNode bumps cycles +
+//     transition('revive') BEFORE the detached, unawaited broker spawn — revive.
+//     ts:114,145 — so the wake is observable INSTANTLY). If the daemon's second-
+//     pass reviveNode is removed, the post-inbox tick never bumps cycles → S7's
+//     "B revived" asserts go RED. If a push wrongly fanned past its direct
+//     subscriber, the "A inbox empty" one-hop asserts go RED.
+//
+// STOPHOOK CAVEAT — split (option b). The original leaned on the REAL stophook
+// committing idle-release / the stall reprompt / the persona steer INSIDE a live
+// broker at agent_end/turn_end. Fabrication can set the post-stop row but cannot
+// run that hook. So for each such point this test fabricates the post-stop MODEL
+// state (or asserts the PURE decision the hook enacts — evaluateStop /
+// personaDrift) and asserts the downstream lifecycle/daemon CONSEQUENCE, leaving
+// the hook-commit proof to the already-pure siblings:
+//   • idle-release commit at agent_end → canvas-stophook-agentend.test.ts
+//     ('natural stop while awaiting a live worker → idle-release …').
+//   • stall reprompt at agent_end     → canvas-stophook-agentend.test.ts
+//     ('stalled leaf … is still reprompted').
+//   • persona-drift steer + ack commit at turn_end → persona.test.ts
+//     ('personaDrift detects base→orchestrator after promote, then clears on
+//     commit'). Here we assert only the PENDING drift the injector would deliver.
+//
+// 2×2 coverage (mode {base,orchestrator} × lifecycle {terminal,resident}):
+//   • base×resident         — A's fabricated row shape at S1 (a spawnRoot
+//                             fixture; the real resident-birth boot path is
+//                             structurally unreachable headlessly).
+//   • orchestrator×resident — A after promote (top-level orchestrator).
+//   • base×terminal         — B/C/D workers (fabricated managed children).
+//   • orchestrator×terminal — B after promote (sub-orchestrator).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHeadlessHarness } from './helpers/harness.js';
+import { subscribe } from '../canvas/canvas.js';
+import { transition } from '../runtime/lifecycle.js';
+import { pushFinal } from '../feed/feed.js';
+import { evaluateStop, STALL_REPROMPT } from '../runtime/stop-guard.js';
+import { personaDrift, commitPersonaAck } from '../runtime/persona.js';
+// A pid reaped (dead) by the time spawnSync returns — a released broker's exited
+// process (the headless analog of a closed pane).
+function deadPid() {
+    const r = spawnSync('true', [], { stdio: 'ignore' });
+    return r.pid ?? 0x7ffffffe;
+}
+test('flagship: full node lifecycle — spawn, dormancy, one-hop wake, promote, yield, finish (headless)', 
+// Spawns real broker children + several full-CLI subprocesses; 30s risked the
+// same slow-CI-runner timeout as the live-mutation tests. 60s = safe margin.
+{ timeout: 60_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-flagship' });
+    try {
+        // ===================================================================
+        // S1 — A's ROW SHAPE: base × RESIDENT (the user's front door). A spawnRoot
+        //   fixture pins the PERSISTED row shape the scenario builds on; the real
+        //   resident-birth boot path (bootRoot execs pi inline) is unreachable
+        //   headlessly, exactly as in the tmux flagship. The resident BEHAVIOR (no
+        //   idle-release) is exercised in live-mutation.test.ts.
+        // ===================================================================
+        const A = h.spawnRoot('top-level orchestrator');
+        {
+            const a = h.node(A);
+            assert.equal(a.mode, 'base', 'A row shape: base');
+            assert.equal(a.lifecycle, 'resident', 'A row shape: resident (fixture, not a real boot)');
+            assert.equal(a.status, 'active', 'A active');
+            assert.equal(a.intent ?? null, null, 'A no intent');
+        }
+        // ===================================================================
+        // S2 — A promotes: orchestrator × RESIDENT (top-level orchestrator). The
+        //      real `node promote` verb; mode flips, lifecycle/status/intent
+        //      untouched (no transition()).
+        // ===================================================================
+        {
+            const res = h.cli(A, ['node', 'promote']);
+            assert.equal(res.code, 0, `promote A exit 0\n${res.stderr}`);
+            const a = h.node(A);
+            assert.equal(a.mode, 'orchestrator', 'A → orchestrator');
+            assert.equal(a.lifecycle, 'resident', 'A stays resident (no --resident)');
+            assert.equal(a.status, 'active', 'A still active (promote does not transition)');
+            assert.equal(a.intent ?? null, null, 'A intent untouched by promote');
+        }
+        // ===================================================================
+        // S3 — A spawns terminal child B: base × TERMINAL. Fabricated as a broker-
+        //      hosted node (pi_pid dead + pi_session_id set, so its later dormant
+        //      wake RESUMES that session); the spine seed is wired explicitly
+        //      (fabrication does not auto-subscribe). B is born acked to its own
+        //      persona (commitPersonaAck), mirroring a real birth.
+        // ===================================================================
+        const B = h.fabricateBrokerNode({
+            parent: A, kind: 'developer', mode: 'base', lifecycle: 'terminal',
+            status: 'active', pi_pid: deadPid(), pi_session_id: 'sess-B',
+        });
+        subscribe(A, B, true); // the load-bearing spine seed: A subscribes_to B (active).
+        commitPersonaAck(B, { mode: 'base', lifecycle: 'terminal' }); // born acked to its persona
+        {
+            const b = h.node(B);
+            assert.equal(b.host_kind, 'broker', 'B broker-hosted (paneless)');
+            assert.equal(b.mode, 'base', 'B born base');
+            assert.equal(b.lifecycle, 'terminal', 'B born terminal (managed child)');
+            assert.equal(b.status, 'active', 'B active');
+            assert.equal(b.intent ?? null, null, 'B no intent');
+            assert.equal(b.parent, A, 'B spawned_by / parent = A');
+            assert.deepEqual(h.subscribers(B), [{ node_id: A, active: true }], "A is B's sole ACTIVE subscriber (spine seed)");
+            assert.equal(h.inbox(A).length, 0, 'A inbox empty (spawn pushes nothing)');
+        }
+        // ===================================================================
+        // S4 — B spawns child C (base × terminal). B now holds an active live
+        //      subscription to C → B is legitimately "awaiting" if it stops.
+        // ===================================================================
+        const C = h.fabricateBrokerNode({ parent: B, mode: 'base', lifecycle: 'terminal', status: 'active' });
+        subscribe(B, C, true);
+        {
+            const c = h.node(C);
+            assert.equal(c.mode, 'base', 'C base');
+            assert.equal(c.lifecycle, 'terminal', 'C terminal');
+            assert.equal(c.status, 'active', 'C active');
+            assert.deepEqual(h.subscribers(C), [{ node_id: B, active: true }], "B is C's sole ACTIVE subscriber");
+            assert.deepEqual(h.subscriptions(B), [{ node_id: C, active: true }], 'B subscribes_to C (active)');
+            assert.equal(h.status(B), 'active', 'B still active');
+        }
+        // ===================================================================
+        // S5 — B goes DORMANT. PURE precondition: B is TERMINAL holding an active
+        //      live sub to C, so the stop-guard classifies its stop 'awaiting'
+        //      (legitimate idle-release). We then enact the post-stop MODEL state
+        //      directly: transition('release') → idle / idle-release (a released
+        //      broker is a dead pid; pi_pid was fabricated dead at S3). The actual
+        //      agent_end idle-release COMMIT is locked by canvas-stophook-agentend
+        //      ('natural stop while awaiting a live worker → idle-release …').
+        // ===================================================================
+        {
+            const stop = evaluateStop(B, { pushedFinal: false, askedHuman: false });
+            assert.equal(stop.action, 'allow', 'awaiting terminal B → allow (legit idle-release)');
+            assert.equal(stop.reason, 'awaiting', "B classified awaiting on its ACTIVE live sub to C");
+        }
+        transition(B, 'release');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'idle', 'B idle (released)');
+            assert.equal(b.intent, 'idle-release', 'B intent=idle-release');
+        }
+        assert.equal(h.status(C), 'active', 'C still active while B sleeps');
+        assert.equal(h.status(A), 'active', 'A still active (a dormant worker does not disturb its manager)');
+        assert.equal(h.inbox(A).length, 0, 'A inbox still empty');
+        // ===================================================================
+        // S6 — C FINISHES (pushFinal). The pointer fans to subscribersOf(C) = {B}
+        //      ONLY. C → done/done. A is NOT a subscriber of C → A inbox stays
+        //      empty — the one-hop wake contract at the push site.
+        // ===================================================================
+        await pushFinal(C, 'C result body');
+        {
+            const c = h.node(C);
+            assert.equal(c.status, 'done', 'C done');
+            assert.equal(c.intent, 'done', 'C intent=done');
+            const cFinal = h.inbox(B).find((e) => e.from === C && e.kind === 'final');
+            assert.ok(cFinal, "B inbox received C's final pointer (one hop)");
+            assert.equal(h.inbox(A).length, 0, 'A inbox empty — A NOT woken by C (one-hop)');
+        }
+        // ===================================================================
+        // S7 — WAKE B. The in-process daemon second pass sees B idle/idle-release,
+        //      pi dead, an unseen inbox entry → reviveNode(resume). reviveNode
+        //      bumps cycles + transition('revive') BEFORE the (detached, unawaited)
+        //      broker spawn, so the wake is observable INSTANTLY via cycles — no
+        //      awaitBoot. (The real inbox-watcher's redelivery of C's report on the
+        //      fresh boot is an engine artifact, out of the model tier; the wake
+        //      DECISION is locked here by cycles + the S6 inbox entry.)
+        // ===================================================================
+        assert.equal(h.node(B).cycles ?? 0, 0, 'B not yet revived');
+        await h.tick();
+        {
+            const b = h.node(B);
+            assert.equal(b.cycles ?? 0, 1, 'unseen inbox + tick → daemon pass-2 REVIVED (cycles bumped to 1)');
+            assert.equal(b.status, 'active', 'B revived → active');
+            assert.equal(b.intent ?? null, null, 'B intent cleared by revive');
+        }
+        assert.equal(h.inbox(A).length, 0, 'A inbox STILL empty after B woke (one-hop confirmed)');
+        assert.equal(h.status(A), 'active', 'A unchanged');
+        // ===================================================================
+        // S8 — B PROMOTES: base → orchestrator, lifecycle TERMINAL unchanged
+        //      (no --resident). orchestrator × terminal (the sub-orchestrator).
+        // ===================================================================
+        {
+            const res = h.cli(B, ['node', 'promote', '--kind', 'developer']);
+            assert.equal(res.code, 0, `promote B exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.mode, 'orchestrator', 'B → orchestrator');
+            assert.equal(b.lifecycle, 'terminal', 'B stays TERMINAL (promote is mode-only)');
+            assert.equal(b.status, 'active', 'B still active');
+            assert.equal(b.intent ?? null, null, 'B intent untouched by promote');
+        }
+        // ===================================================================
+        // S9 — The next turn's hooks, asserted as the PURE decisions they enact:
+        //      (a) turn_end would inject the base→orchestrator persona-drift steer —
+        //          personaDrift(B) reports that PENDING drift (the guidance the
+        //          injector delivers). The actual delivery + ack commit is locked
+        //          by persona.test.ts.
+        //      (b) agent_end would stall (orchestrator, no live sub — C done, D not
+        //          yet spawned — no final) → evaluateStop → 'stalled'/STALL_REPROMPT.
+        //          The actual reprompt injection is locked by canvas-stophook-agentend.
+        // ===================================================================
+        {
+            const drift = personaDrift(B);
+            assert.ok(drift !== null, 'turn_end would inject a persona-drift steer (drift pending)');
+            assert.deepEqual(drift?.from, { mode: 'base', lifecycle: 'terminal' }, 'drift.from = the acked base×terminal');
+            assert.deepEqual(drift?.to, { mode: 'orchestrator', lifecycle: 'terminal' }, 'drift.to = the new orchestrator persona');
+            assert.match(drift?.guidance ?? '', /ORCHESTRATOR/i, 'the steer carries the base→orchestrator guidance');
+            const stop = evaluateStop(B, { pushedFinal: false, askedHuman: false });
+            assert.equal(stop.action, 'reprompt', 'orchestrator B with no live sub, no final → reprompt');
+            assert.equal(stop.reason, 'stalled', 'classified stalled');
+            assert.equal(stop.action === 'reprompt' ? stop.message : '', STALL_REPROMPT, 'the stall reprompt nudge');
+        }
+        // ===================================================================
+        // S10 — B YIELDS. The real plain `node yield` verb sets intent=refresh
+        //       while preserving mode (already orchestrator); persona survives the request. We
+        //       then model the daemon's completed refresh-revive with transition
+        //       ('revive') (the in-place fresh boot is engine; its model effect —
+        //       active, intent cleared, persona preserved — is asserted here).
+        // ===================================================================
+        {
+            const res = h.cli(B, ['node', 'yield', 'refresh against the roadmap']);
+            assert.equal(res.code, 0, `node yield exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.intent, 'refresh', 'yield set intent=refresh');
+            assert.equal(b.mode, 'orchestrator', 'B mode survives the yield request');
+            assert.equal(b.lifecycle, 'terminal', 'B lifecycle survives the yield request');
+        }
+        transition(B, 'revive'); // model the completed refresh-revive (fresh boot is engine)
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'active', 'B active after the refresh-revive');
+            assert.equal(b.intent ?? null, null, 'B intent=refresh cleared by the fresh boot');
+            assert.equal(b.mode, 'orchestrator', 'B mode survives the refresh');
+            assert.equal(b.lifecycle, 'terminal', 'B lifecycle survives the refresh');
+        }
+        // ===================================================================
+        // S11 — B spawns child D (base × terminal). New spine seed B→D active.
+        // ===================================================================
+        const D = h.fabricateBrokerNode({ parent: B, mode: 'base', lifecycle: 'terminal', status: 'active' });
+        subscribe(B, D, true);
+        {
+            const d = h.node(D);
+            assert.equal(d.mode, 'base', 'D base');
+            assert.equal(d.lifecycle, 'terminal', 'D terminal');
+            assert.equal(d.status, 'active', 'D active');
+            assert.ok(h.subscriptions(B).some((s) => s.node_id === D && s.active), 'B subscribes_to D (active)');
+        }
+        // ===================================================================
+        // S12 — D FINISHES → pointer to B (its only subscriber).
+        // ===================================================================
+        await pushFinal(D, 'D result body');
+        {
+            assert.equal(h.node(D).status, 'done', 'D done');
+            const dFinal = h.inbox(B).find((e) => e.from === D && e.kind === 'final');
+            assert.ok(dFinal, "B inbox received D's final pointer");
+        }
+        // ===================================================================
+        // S13 — B pushes its FINAL up the spine → done/done; the pointer fans to
+        //       subscribersOf(B) = {A}. NOW A finally hears B (its own explicit
+        //       push — the only way the chain propagates a hop).
+        // ===================================================================
+        await pushFinal(B, 'all work complete');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'done', 'B done after push final');
+            assert.equal(b.intent, 'done', 'B intent=done');
+            const aInbox = h.inbox(A);
+            assert.equal(aInbox.length, 1, "A inbox now has exactly B's final (one hop, on B's push)");
+            assert.equal(aInbox[0].from, B, "A's entry is from B");
+            assert.equal(aInbox[0].kind, 'final', "A's entry is a final");
+        }
+        // A — the resident top-level orchestrator — is still alive and well.
+        {
+            const a = h.node(A);
+            assert.equal(a.status, 'active', 'A still active at the end');
+            assert.equal(a.mode, 'orchestrator', 'A still orchestrator');
+            assert.equal(a.lifecycle, 'resident', 'A still resident');
+        }
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/focuses.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/focuses.test.js

@@ -0,0 +1,208 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/focuses.test.ts
+//
+// The `focuses` table (canvas.db, migration v6) + its canvas setters + the
+// placement reads that compose over them. The table is the CANONICAL focus store
+// — there is no focus.ptr file and no dual-write bridge. Covers:
+//   - migration v6 adds `focuses` to a fresh db (and a legacy v5 db migrates up);
+//     idempotent / forward-only on re-run + re-open
+//   - canvas setters/reads round-trip: open / setOccupant / setPane / close;
+//     getFocusByNode / getFocusByPane / getFocusById / listFocuses
+//   - UNIQUE(node_id): a second focus row (and an occupant UPDATE) for one node
+//     is rejected (upholds "a node occupies <=1 focus", Q5)
+//   - independent focus rows don't contend
+//   - placement focusOf / isFocused / focusByPane / focusedNodes / listFocuses
+//     GC dead-pane viewer rows on read (liveOrPrune), and pass null-pane rows
+//     through (broker-host cut: placement reads self-heal the viewer registry)
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { openFocusRow, setFocusOccupant, setFocusPane, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses, } from '../canvas/focuses.js';
+import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
+import { canvasDbPath, ensureHome } from '../canvas/paths.js';
+import { focusOf, isFocused, focusByPane, focusedNodes, listFocuses as placementListFocuses, } from '../runtime/placement.js';
+let home;
+function userVersion(db) {
+    return db.prepare('PRAGMA user_version').get().user_version;
+}
+function tableNames(db) {
+    return db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => r.name);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-focuses-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// Migration v6 — the additive `focuses` table.
+// ---------------------------------------------------------------------------
+test('a fresh db migrates to the latest version and has the focuses table', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.ok(tableNames(db).includes('focuses'), 'focuses table exists on a fresh db');
+});
+test('the focuses table has the v6 shape (UNIQUE node_id, nullable pane/session)', () => {
+    const db = openDb();
+    const cols = db.prepare('PRAGMA table_info(focuses)').all();
+    const byName = new Map(cols.map((c) => [c.name, c]));
+    assert.equal(byName.get('focus_id')?.pk, 1, 'focus_id is the primary key');
+    assert.equal(byName.get('node_id')?.notnull, 1, 'node_id is NOT NULL');
+    assert.equal(byName.get('pane')?.notnull, 0, 'pane is nullable');
+    assert.equal(byName.get('session')?.notnull, 0, 'session is nullable');
+    // node_id carries a UNIQUE index.
+    const idx = db.prepare('PRAGMA index_list(focuses)').all();
+    assert.ok(idx.some((i) => i.unique === 1), 'a UNIQUE index exists (the node_id constraint)');
+});
+test('a v5 db migrates forward, adding focuses without disturbing existing data', () => {
+    // Hand-build a db at exactly v5: baseline + the four v2 runtime columns + the
+    // v5 pane column + edges WITH the v4 FK shape, user_version=5 — the shape just
+    // before v6.
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    raw.exec(`
+    CREATE TABLE nodes (
+      node_id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL,
+      mode TEXT NOT NULL DEFAULT 'base', lifecycle TEXT NOT NULL DEFAULT 'terminal',
+      status TEXT NOT NULL DEFAULT 'active', cwd TEXT NOT NULL, parent TEXT,
+      created TEXT NOT NULL,
+      intent TEXT, pi_pid INTEGER, window TEXT, tmux_session TEXT, pane TEXT
+    );
+    CREATE TABLE edges (
+      type TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL,
+      active INTEGER NOT NULL DEFAULT 1, created TEXT NOT NULL,
+      PRIMARY KEY (type, from_id, to_id),
+      FOREIGN KEY (from_id) REFERENCES nodes(node_id) ON DELETE CASCADE,
+      FOREIGN KEY (to_id)   REFERENCES nodes(node_id) ON DELETE CASCADE
+    );
+    PRAGMA user_version = 5;
+  `);
+    raw
+        .prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created, window, tmux_session, pane) VALUES (?,?,?,?,?,?,?,?,?)')
+        .run('legacy', 'Legacy', 'general', 'idle', '/tmp/work', '2020-01-01T00:00:00Z', '@9', 'crtr', '%3');
+    assert.equal(userVersion(raw), 5);
+    assert.ok(!tableNames(raw).includes('focuses'), 'precondition: no focuses table at v5');
+    raw.close();
+    // openDb() runs v6 forward.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.ok(tableNames(db).includes('focuses'), 'focuses table added by v6');
+    // The pre-existing node row is intact (the v6 migration only adds a table).
+    const row = db
+        .prepare('SELECT status, window, tmux_session, pane FROM nodes WHERE node_id = ?')
+        .get('legacy');
+    assert.equal(row['status'], 'idle', 'existing status untouched');
+    assert.equal(row['window'], '@9', 'existing window untouched');
+    assert.equal(row['tmux_session'], 'crtr', 'existing session untouched');
+    assert.equal(row['pane'], '%3', 'existing pane untouched');
+    // The fresh focuses table is empty.
+    const n = db.prepare('SELECT COUNT(*) AS n FROM focuses').get().n;
+    assert.equal(n, 0, 'a fresh focuses table starts empty');
+});
+test('the v6 migration is idempotent / forward-only on re-run and re-open', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-running migrate() is a no-op — the gate skips applied steps. The CREATE
+    // TABLE IF NOT EXISTS would be harmless anyway, but the gate must not re-fire.
+    assert.doesNotThrow(() => migrate(db));
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-opening from disk is likewise a no-op.
+    closeDb();
+    const db2 = openDb();
+    assert.equal(userVersion(db2), MIGRATIONS.length);
+    assert.ok(tableNames(db2).includes('focuses'));
+});
+// ---------------------------------------------------------------------------
+// Canvas setters / reads — open / setOccupant / setPane / close round-trip.
+// ---------------------------------------------------------------------------
+test('open / setOccupant / close round-trip with the reads', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    // getFocusByNode / getFocusByPane / getFocusById all resolve the same row.
+    const byNode = getFocusByNode('A');
+    assert.deepEqual(byNode, { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'A' });
+    assert.deepEqual(getFocusByPane('%a'), byNode);
+    assert.deepEqual(getFocusById('f1'), byNode);
+    assert.deepEqual(listFocuses(), [byNode]);
+    // setFocusOccupant hot-swaps the occupant in place (same focus_id/pane).
+    setFocusOccupant('f1', 'B');
+    assert.equal(getFocusByNode('A'), null, 'A no longer occupies the focus');
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'B' });
+    // setFocusPane re-points the pane + session cache after a viewer move.
+    setFocusPane('f1', '%a2', 'Sa2');
+    assert.deepEqual(getFocusById('f1'), { focus_id: 'f1', pane: '%a2', session: 'Sa2', node_id: 'B' });
+    assert.equal(getFocusByPane('%a'), null, 'the old pane no longer resolves');
+    assert.deepEqual(getFocusByPane('%a2')?.node_id, 'B');
+    // closeFocusRow deletes the viewport.
+    closeFocusRow('f1');
+    assert.equal(getFocusByNode('B'), null);
+    assert.equal(getFocusById('f1'), null);
+    assert.deepEqual(listFocuses(), []);
+});
+test('UNIQUE(node_id): a second focus row for the same node is rejected', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    // A second viewport occupied by the SAME node violates UNIQUE(node_id) — this
+    // is the constraint that upholds "a node occupies <=1 focus" (Q5).
+    assert.throws(() => openFocusRow('f2', '%b', 'Sb', 'A'), /UNIQUE|constraint/i);
+    // The first row is untouched; no stray second row was created.
+    assert.deepEqual(listFocuses().map((f) => f.focus_id), ['f1']);
+});
+test('UNIQUE(node_id): hot-swapping an occupant onto an already-focused node is rejected', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    openFocusRow('f2', '%b', 'Sb', 'B');
+    // B already occupies f2 — moving it onto f1 via setFocusOccupant must throw
+    // (the Q5 vacate-first is placement.focus()'s job, not this setter's).
+    assert.throws(() => setFocusOccupant('f1', 'B'), /UNIQUE|constraint/i);
+    assert.deepEqual(getFocusByNode('A'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'A' });
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
+});
+test('independent focus rows do not contend', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    openFocusRow('f2', '%b', 'Sb', 'B');
+    // Mutating one viewport leaves the other entirely intact.
+    setFocusOccupant('f1', 'C');
+    setFocusPane('f1', '%a2', 'Sa2');
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
+    closeFocusRow('f1');
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
+    assert.deepEqual(listFocuses().map((f) => f.focus_id), ['f2']);
+});
+// ---------------------------------------------------------------------------
+// Placement reads — focusOf / isFocused / focusByPane / focusedNodes /
+// listFocuses GC dead-pane viewer rows on read (broker-host cut: liveOrPrune).
+// A row whose viewer pane no longer exists is pruned the next time it is read,
+// so the registry self-heals without a sweeper; a row with a null pane (a
+// registered-but-not-yet-realized viewer) is passed through. A live tmux pane
+// can't be fabricated in the fast tier, so we cover the prune + null-pane paths
+// here; the live-pane read is covered in the full-tier broker lifecycle suite.
+// ---------------------------------------------------------------------------
+test('placement reads GC dead-pane viewer rows and keep null-pane rows', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A'); // %a is not a live tmux pane → pruned on read
+    openFocusRow('f2', null, 'Sb', 'B'); // null pane (not realized yet) → kept
+    // The dead-pane row is GC'd on read: placement returns null AND the row is
+    // removed from the canvas table (self-healing registry).
+    assert.equal(focusOf('A'), null, 'a viewer whose pane is gone is pruned on read');
+    assert.equal(getFocusByNode('A'), null, 'the pruned row is closed in the db');
+    assert.equal(isFocused('A'), false);
+    assert.equal(focusByPane('%a'), null, 'focusByPane prunes the dead pane too');
+    // The null-pane row survives (liveOrPrune only prunes a non-null dead pane).
+    assert.deepEqual(focusOf('B'), { focus_id: 'f2', pane: null, session: 'Sb', node_id: 'B' });
+    assert.equal(isFocused('B'), true);
+    assert.equal(focusOf('Z'), null, 'an unfocused node has no focus');
+    assert.equal(isFocused('Z'), false);
+    assert.deepEqual(focusedNodes(), new Set(['B']));
+    assert.deepEqual(placementListFocuses().map((f) => f.node_id), ['B']);
+});

package/dist/core/__tests__/fork.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/fork.test.js

@@ -0,0 +1,108 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/fork.test.ts
+//
+// Covers `crtr node new --fork-from`: the spawn-time branch where a new node is
+// born as a COPY of an existing pi conversation. Two pure layers are unit-tested
+// here — `buildPiArgv` emitting `--fork` (vs `--session`), and `resolveForkSource`
+// turning a node id / path / uuid into the `--fork <path|id>` argument. The tmux
+// spawn itself is exercised elsewhere (it needs a live pi + tmux).
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { buildPiArgv } from '../runtime/launch.js';
+import { resolveForkSource } from '../runtime/spawn.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-fork-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// buildPiArgv — `--fork` is the spawn-time branch (not `--session`)
+// ---------------------------------------------------------------------------
+test('buildPiArgv emits --fork <src> and delivers the kickoff prompt', () => {
+    const m = node('n');
+    const { argv } = buildPiArgv(m, { prompt: 'continue from here', forkFrom: '/abs/src.jsonl' });
+    const i = argv.indexOf('--fork');
+    assert.ok(i >= 0, 'argv carries --fork');
+    assert.equal(argv[i + 1], '/abs/src.jsonl', 'forks from the resolved source');
+    assert.ok(!argv.includes('--session'), 'a fork never also resumes');
+    assert.equal(argv[argv.length - 1], 'continue from here', 'the kickoff prompt is the last positional');
+});
+test('buildPiArgv prefers --fork over --session when both are somehow set', () => {
+    const m = node('n');
+    const { argv } = buildPiArgv(m, { forkFrom: '/abs/src.jsonl', resumeSessionPath: '/abs/own.jsonl' });
+    assert.ok(argv.includes('--fork'), 'fork wins');
+    assert.ok(!argv.includes('--session'), 'resume is suppressed when forking');
+});
+test('buildPiArgv without forkFrom is unchanged (fresh launch, no --fork)', () => {
+    const m = node('n');
+    const { argv } = buildPiArgv(m, { prompt: 'go' });
+    assert.ok(!argv.includes('--fork'), 'no fork on an ordinary fresh launch');
+    assert.ok(!argv.includes('--session'), 'no resume either');
+});
+// ---------------------------------------------------------------------------
+// resolveForkSource — node id / path / uuid → the `--fork` argument
+// ---------------------------------------------------------------------------
+test('resolveForkSource resolves a node id to its absolute session FILE', () => {
+    createNode(node('src', { pi_session_id: 'uuid-1', pi_session_file: '/abs/src.jsonl' }));
+    assert.equal(resolveForkSource('src'), '/abs/src.jsonl');
+});
+test('resolveForkSource THROWS when a node has a session id but no captured FILE', () => {
+    // Broker-cut contract (U6/§B.broker): the broker forks an absolute .jsonl PATH,
+    // never a bare session id. A node row carrying only pi_session_id (no
+    // pi_session_file) can no longer be forked — it fails loudly pre-launch.
+    createNode(node('src', { pi_session_id: 'uuid-1' }));
+    assert.throws(() => resolveForkSource('src'), /no pi session yet|session FILE/);
+});
+test('resolveForkSource throws when the node has no pi session to fork yet', () => {
+    createNode(node('fresh'));
+    assert.throws(() => resolveForkSource('fresh'), /no pi session yet/);
+});
+test('resolveForkSource passes an absolute path straight through', () => {
+    assert.equal(resolveForkSource('/some/where/sess.jsonl'), '/some/where/sess.jsonl');
+});
+test('resolveForkSource makes a relative path absolute', () => {
+    assert.equal(resolveForkSource('sub/sess.jsonl'), join(process.cwd(), 'sub/sess.jsonl'));
+});
+test('resolveForkSource THROWS on a bare/partial uuid that resolves to no session', () => {
+    // Broker-cut contract (U6): an unknown bare/partial uuid is scanned against
+    // pi's sessions store and fails loudly when it matches nothing — it is no
+    // longer passed through verbatim (the broker fork won't resolve a uuid).
+    const sessRoot = mkdtempSync(join(tmpdir(), 'crtr-pi-agent-'));
+    process.env['PI_CODING_AGENT_DIR'] = sessRoot;
+    try {
+        assert.throws(() => resolveForkSource('019e8ce3-322e'), /no pi session/);
+    }
+    finally {
+        delete process.env['PI_CODING_AGENT_DIR'];
+        rmSync(sessRoot, { recursive: true, force: true });
+    }
+});
+test('resolveForkSource rejects an empty reference', () => {
+    assert.throws(() => resolveForkSource('   '), /requires a node id/);
+});

package/dist/core/__tests__/full/broker-attach-limits.test.d.ts

@@ -0,0 +1 @@
+export {};