@crouton-kit/crouter 0.3.16 → 0.3.17

package/dist/core/__tests__/spike-harness.test.js

@@ -0,0 +1,241 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/spike-harness.test.ts
+//
+// SPIKE — a throwaway-grade proof that a faithful integration harness for the
+// node/canvas runtime is feasible. It drives the REAL `crtr` CLI into an
+// isolated REAL tmux session, substitutes a FAKE-PI vehicle (the fake-pi-host
+// fixture) via the CRTR_PI_BINARY seam, and proves the spawned window actually
+// exec's the fake pi with the right argv+env, that the fake loads the REAL
+// extensions, and that one real lifecycle hook drives a real canvas transition.
+//
+// Milestones (de-risk order):
+//   1. SEAM      — piCommand substitutes CRTR_PI_BINARY only when set (unit).
+//   2. ROUND-TRIP— real `node new` → isolated tmux window → fake pi boots with
+//                  CRTR_NODE_ID + the -e env intact (GO/NO-GO).
+//   3. REAL HOOKS— the fake pi loads the real stophook and a clean /quit drives
+//                  status=done via the real session_shutdown handler.
+//   4. TEARDOWN  — the isolated session + fake-pi procs are killed; no strays.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, readFileSync, readdirSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { createNode, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { piCommand } from '../runtime/placement.js';
+import { CANVAS_EXTENSIONS } from '../runtime/launch.js';
+// --- locations --------------------------------------------------------------
+const HERE = dirname(fileURLToPath(import.meta.url)); // src/core/__tests__
+const CROUTER = join(HERE, '..', '..', '..'); // package root
+const CLI_SRC = join(CROUTER, 'src', 'cli.ts');
+const FAKE_PI_HOST = join(HERE, 'fixtures', 'fake-pi-host.ts');
+const TSX_ESM = createRequire(import.meta.url).resolve('tsx/esm');
+// A multi-word launcher baked verbatim ahead of the (shell-quoted) argv.
+const FAKE_PI_BINARY = `${process.execPath} --import ${TSX_ESM} ${FAKE_PI_HOST}`;
+function hasTmux() {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+}
+function tmuxSessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+// --- env isolation: scrub every canvas var the harness itself runs under, so
+// the spawned CLI cannot leak into the real canvas. -------------------------
+const CANVAS_ENV_KEYS = [
+    'CRTR_NODE_ID',
+    'CRTR_HOME',
+    'CRTR_ROOT_SESSION',
+    'CRTR_NODE_SESSION',
+    'CRTR_PARENT_NODE_ID',
+    'CRTR_FRONT_DOOR',
+    'CRTR_KIND',
+    'CRTR_MODE',
+    'CRTR_LIFECYCLE',
+    'CRTR_NODE_CWD',
+    'CRTR_PI_BINARY',
+    'TMUX',
+    'TMUX_PANE',
+];
+function cleanBaseEnv() {
+    const e = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (v !== undefined)
+            e[k] = v;
+    for (const k of CANVAS_ENV_KEYS)
+        delete e[k];
+    // Contain per-invocation bootstrap + auto-update side effects.
+    e['CRTR_NO_BOOTSTRAP'] = '1';
+    e['CRTR_NO_AUTO_UPDATE'] = '1';
+    e['CRTR_NO_BOOT_SKILL'] = '1';
+    e['CRTR_NO_MODE_CMDS'] = '1';
+    e['CRTR_NO_AUTO_INIT'] = '1';
+    return e;
+}
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: CROUTER,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        status: 'active',
+        parent: null,
+        ...over,
+    };
+}
+async function waitFor(probe, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 20_000;
+    const intervalMs = opts.intervalMs ?? 150;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const v = probe();
+        if (v)
+            return v;
+        if (Date.now() > deadline)
+            throw new Error(`waitFor timed out: ${opts.label ?? 'condition'}`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+// --- harness state ----------------------------------------------------------
+let home;
+let tmpHome;
+let origHome;
+const sessionsToKill = new Set();
+const pidsToKill = new Set();
+before(() => {
+    origHome = process.env['CRTR_HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-spike-home-'));
+    tmpHome = mkdtempSync(join(tmpdir(), 'crtr-spike-HOME-'));
+    // The harness reads/writes the isolated canvas in-process.
+    process.env['CRTR_HOME'] = home;
+    closeDb();
+});
+after(() => {
+    for (const s of sessionsToKill)
+        spawnSync('tmux', ['kill-session', '-t', s], { stdio: 'ignore' });
+    for (const p of pidsToKill) {
+        try {
+            process.kill(p, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    if (tmpHome)
+        rmSync(tmpHome, { recursive: true, force: true });
+    if (origHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = origHome;
+});
+// ===========================================================================
+// MILESTONE 1 — the CRTR_PI_BINARY seam (always runs; no tmux needed).
+// ===========================================================================
+test('M1 seam: piCommand exec\'s `pi` when CRTR_PI_BINARY is unset, substitutes when set', () => {
+    const saved = process.env['CRTR_PI_BINARY'];
+    try {
+        delete process.env['CRTR_PI_BINARY'];
+        const unset = piCommand(['-e', '/abs/ext.ts', '-n', 'label']);
+        assert.equal(unset, "pi '-e' '/abs/ext.ts' '-n' 'label'", 'unset → identical to exec pi');
+        assert.ok(unset.startsWith('pi '), 'unset → leads with the literal pi binary');
+        process.env['CRTR_PI_BINARY'] = '/tmp/fake-pi';
+        const set = piCommand(['-e', '/abs/ext.ts']);
+        assert.ok(set.startsWith('/tmp/fake-pi '), 'set → leads with the substituted binary');
+        assert.ok(!set.startsWith('pi '), 'set → no longer the literal pi');
+        assert.equal(set, "/tmp/fake-pi '-e' '/abs/ext.ts'", 'argv still shell-quoted after the substitution');
+        // A multi-word launcher is spliced verbatim (argv stays quoted).
+        process.env['CRTR_PI_BINARY'] = 'node --import tsx/esm host.ts';
+        assert.equal(piCommand(['-n', 'x']), "node --import tsx/esm host.ts '-n' 'x'", 'multi-word binary spliced ahead of the quoted argv');
+        // An explicit binary arg still overrides the env.
+        assert.ok(piCommand(['-n', 'x'], 'pi').startsWith('pi '), 'explicit binary arg wins over the env seam');
+    }
+    finally {
+        if (saved === undefined)
+            delete process.env['CRTR_PI_BINARY'];
+        else
+            process.env['CRTR_PI_BINARY'] = saved;
+    }
+});
+// ===========================================================================
+// MILESTONES 2 + 3 — real CLI → isolated tmux → fake pi → real hooks.
+// THE GO/NO-GO. Shares one spawned child across both milestones.
+// ===========================================================================
+test('M2+M3 round-trip: real `node new` reaches the fake pi via the seam, and a real hook drives status=done', { skip: !hasTmux() }, async () => {
+    const session = `crtr-spike-${process.pid}-rt`;
+    sessionsToKill.add(session);
+    // Pre-create the isolated session (default tmux server — the runtime shells
+    // `tmux` with no -L, so an -L server would be invisible to the real CLI).
+    spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', CROUTER, 'sleep 600'], {
+        stdio: 'ignore',
+    });
+    assert.ok(tmuxSessionExists(session), 'isolated tmux session created');
+    // Bootstrap the acting node in the isolated canvas (the parent `node new`
+    // spawns under). createNode shares the harness CRTR_HOME.
+    createNode(node('A', { name: 'acting-root' }));
+    // Drive the REAL CLI: `crtr node new` AS node A, into the isolated session,
+    // with the fake-pi seam. Body passed as a positional (dodges the stdin hang).
+    const env = cleanBaseEnv();
+    env['CRTR_HOME'] = home;
+    env['HOME'] = tmpHome;
+    env['CRTR_NODE_ID'] = 'A';
+    env['CRTR_NODE_SESSION'] = session;
+    env['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
+    const res = spawnSync(process.execPath, ['--import', TSX_ESM, CLI_SRC, 'node', 'new', 'spike task', '--parent', 'A', '--cwd', CROUTER], { cwd: CROUTER, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 });
+    assert.equal(res.status, 0, `node new should exit 0\n--- stdout ---\n${res.stdout}\n--- stderr ---\n${res.stderr}`);
+    // Find the spawned child: the only node dir that isn't the acting root.
+    closeDb();
+    const nodesDir = join(home, 'nodes');
+    const childId = readdirSync(nodesDir).find((d) => d !== 'A');
+    assert.ok(childId, 'a child node dir was created by node new');
+    // ---- MILESTONE 2 assertions: the round-trip reached the fake pi --------
+    const bootPath = join(nodesDir, childId, 'fake-pi.boot.json');
+    const errPath = join(nodesDir, childId, 'fake-pi.error');
+    await waitFor(() => existsSync(bootPath), {
+        timeoutMs: 30_000,
+        label: `fake-pi boot proof at ${bootPath}${existsSync(errPath) ? ` (error file: ${readFileSync(errPath, 'utf8')})` : ''}`,
+    });
+    const boot = JSON.parse(readFileSync(bootPath, 'utf8'));
+    if (typeof boot.pid === 'number')
+        pidsToKill.add(boot.pid);
+    // env delivered via tmux -e arrived in the fake pi's process.env.
+    assert.equal(boot.env.CRTR_NODE_ID, childId, 'CRTR_NODE_ID is the CHILD id, intact');
+    assert.equal(boot.env.CRTR_HOME, home, 'CRTR_HOME isolated value intact');
+    assert.ok(boot.env.CRTR_KIND, 'CRTR_KIND present');
+    assert.ok(boot.env.CRTR_MODE, 'CRTR_MODE present');
+    assert.ok(boot.env.CRTR_LIFECYCLE, 'CRTR_LIFECYCLE present');
+    assert.equal(boot.env.CRTR_FRONT_DOOR, '1', 'CRTR_FRONT_DOOR overlay present');
+    // argv from buildPiArgv arrived: every canvas -e extension + the kickoff.
+    // Assert against the live CANVAS_EXTENSIONS count (8 at current HEAD — the
+    // placement-v3 refactor added canvas-resume) so this never drifts again.
+    assert.equal(boot.extPaths.length, CANVAS_EXTENSIONS.length, `all ${CANVAS_EXTENSIONS.length} canvas -e extension paths in argv`);
+    assert.ok(boot.loaded.some((p) => p.includes('canvas-stophook')), 'real stophook module loaded by the fake pi');
+    assert.ok(boot.loaded.some((p) => p.includes('canvas-inbox-watcher')), 'real inbox-watcher module loaded by the fake pi');
+    assert.equal(boot.failedExt.length, 0, `no extension failed to load: ${JSON.stringify(boot.failedExt)}`);
+    assert.equal(boot.resuming, false, 'fresh start (no --session)');
+    assert.equal(boot.prompt, 'spike task', 'kickoff prompt is the last positional');
+    // The REAL stophook session_start handler ran inside the fake pi and wrote
+    // shared canvas state (proves the hook chain, not just the boot).
+    closeDb();
+    const afterBoot = getNode(childId);
+    assert.ok(afterBoot, 'child node readable from the shared canvas');
+    assert.equal(afterBoot.pi_session_id, boot.sessionId, 'stophook captured pi_session_id');
+    assert.equal(afterBoot.status, 'active', 'child active after boot');
+    // ---- MILESTONE 3: a clean /quit drives a real transition to done -------
+    writeFileSync(join(nodesDir, childId, 'fake-pi.cmd'), JSON.stringify({ cmd: 'shutdown' }));
+    const done = await waitFor(() => {
+        closeDb();
+        return getNode(childId)?.status === 'done' ? true : false;
+    }, { timeoutMs: 20_000, label: 'child status=done after clean /quit' });
+    assert.ok(done, 'real session_shutdown hook resolved the node to done');
+    assert.equal(getNode(childId)?.status, 'done', 'status=done via the real stophook');
+    // ---- MILESTONE 4: teardown leaves no stray session ---------------------
+    spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+    sessionsToKill.delete(session);
+    assert.ok(!tmuxSessionExists(session), 'isolated session killed, no stray left');
+});

package/dist/core/__tests__/subscription-delivery.test.d.ts

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

package/dist/core/__tests__/subscription-delivery.test.js

@@ -0,0 +1,233 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/subscription-delivery.test.ts
+//
+// MULTI-LEVEL SUBSCRIPTION DELIVERY — the DELIVERY-vs-WAKE distinction across a
+// graph >=2 levels deep, driven through the FAITHFUL integration harness (real
+// CLI, real isolated tmux, real extension hooks in the fake-pi vehicle, real
+// daemon decision pass via superviseTick). Every assertion reads the canvas
+// data layer and is checked against the state-model ORACLE (§3b, §5, §6).
+//
+// This is the multi-level companion to the UNIT-level passive-subscription.test.ts
+// (which pins push→inbox vs push→passive.jsonl routing in-process). What that test
+// CANNOT show — and what is added here — is the runtime WAKE consequence of the
+// split when BOTH an active and a passive subscriber sit on the SAME target and
+// BOTH are DORMANT (terminal idle-released): the active one is daemon-REVIVED on
+// its unseen inbox entry; the passive one is NOT (its pointer lands in the passive
+// accumulator the daemon never reads), so it stays idle.
+//
+// THE ORACLE CONTRACT under test:
+//   • feed.push fans to subscribersOf(target): active → inbox.jsonl (wakes),
+//     passive → passive.jsonl (accumulates, NEVER wakes). (state-model §5; feed.ts)
+//   • The daemon's 2nd pass revives an idle-released node ONLY on an unseen INBOX
+//     entry (crtrd.ts) — so a passive subscriber's idle-released node never wakes.
+//   • hasActiveLiveSubscription excludes passive edges (canvas.ts active=1) — a
+//     passive tie does NOT legitimize idle-release (stop-guard §3b).
+//   • Wake is ONE HOP per push: a push fans to DIRECT subscribers only; an indirect
+//     ancestor hears nothing until a middle node explicitly re-pushes. (state-model §5)
+//
+// Graph (>=2 levels; T is two hops under A):
+//        A  (resident root — the user's virtual front door)
+//        └── B  (terminal)         A→B active seed  ── ACTIVE subscriber of T
+//            ├── T  (terminal)     B→T active seed  ── THE TARGET (level 2)
+//            ├── K  (terminal)     B→K active seed  ── keepalive (stays active)
+//            └── P  (terminal)     B→P active seed  ── PASSIVE subscriber of T
+//                  P→T passive  (wired via `crtr node subscribe --passive`)
+//                  P→K active   (wired — the ONLY tie that legitimizes P's release;
+//                                P→T passive is excluded from the stop-guard)
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { closeDb } from '../canvas/db.js';
+import { readPassive } from '../feed/passive.js';
+import { STALL_REPROMPT } from '../runtime/stop-guard.js';
+function sessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+// LOCAL helper (candidate for harness consolidation — see report): read a node's
+// PASSIVE accumulator (passive.jsonl) straight off the data layer, mirroring the
+// harness's own `inbox()` reader. closeDb() keeps it consistent with the harness's
+// cross-process WAL discipline (the push that wrote passive.jsonl ran in a `cli`
+// subprocess). The harness exposes inbox() but NOT passive() — this fills that gap.
+function passive(nodeId) {
+    closeDb();
+    return readPassive(nodeId);
+}
+// `{node_id, active}` arrays → a stable comparable set of `id:active|passive`.
+function edgeSet(arr) {
+    return new Set(arr.map((e) => `${e.node_id}:${e.active ? 'active' : 'passive'}`));
+}
+test('multi-level subscription delivery: active subscriber WOKEN vs passive subscriber DELIVERED-not-woken, on the same dormant target', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 180_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-subdeliv' });
+    try {
+        // ===================================================================
+        // S1 — Build the graph. A (resident root, virtual) ► B ► {T,K,P}.
+        //      Each spawn seeds an ACTIVE parent→child subscription (the spine).
+        // ===================================================================
+        const A = h.spawnRoot('front door');
+        const B = await h.spawnChild(A, 'mid manager', { kind: 'developer' });
+        const T = await h.spawnChild(B, 'the target worker');
+        const K = await h.spawnChild(B, 'a keepalive worker');
+        const P = await h.spawnChild(B, 'the passive observer');
+        // Spine seeds: A→B, B→T, B→K, B→P all ACTIVE. T's sole subscriber so far is B.
+        assert.deepEqual(edgeSet(h.subscribers(T)), new Set([`${B}:active`]), "T's only subscriber at birth is B (active spawn seed)");
+        assert.deepEqual(edgeSet(h.subscribers(B)), new Set([`${A}:active`]), 'A→B active seed');
+        // ===================================================================
+        // S2 — Wire the PASSIVE subscriber. P passively subscribes to T (the axis
+        //      under test), and ACTIVELY subscribes to K (the only tie that will
+        //      legitimize P's own idle-release — its passive tie to T does NOT count).
+        // ===================================================================
+        {
+            const passiveRes = h.cli(P, ['node', 'subscribe', T, '--passive']);
+            assert.equal(passiveRes.code, 0, `P→T passive subscribe exit 0\n${passiveRes.stderr}`);
+            assert.match(passiveRes.stdout, /mode="passive"/, 'P→T wired PASSIVE');
+            const activeRes = h.cli(P, ['node', 'subscribe', K]);
+            assert.equal(activeRes.code, 0, `P→K active subscribe exit 0\n${activeRes.stderr}`);
+            assert.match(activeRes.stdout, /mode="active"/, 'P→K wired ACTIVE');
+        }
+        // T now has BOTH an active (B) and a passive (P) subscriber — the crux.
+        assert.deepEqual(edgeSet(h.subscribers(T)), new Set([`${B}:active`, `${P}:passive`]), 'T has B(active) + P(passive) as subscribers — the same-target split');
+        assert.deepEqual(edgeSet(h.subscriptions(P)), new Set([`${T}:passive`, `${K}:active`]), 'P subscribes_to T(passive) + K(active)');
+        // ===================================================================
+        // S2b — PASSIVE-EXCLUSION, demonstrated directly (the stop-guard half of
+        //       the active/passive split). X subscribes PASSIVE-ONLY to the very
+        //       same live K that P subscribes to ACTIVELY. On stop, X holds NO
+        //       active live subscription — hasActiveLiveSubscription filters
+        //       active=1 (canvas.ts), so the passive K-tie is invisible to it →
+        //       the stop-guard returns 'stalled', NOT 'awaiting': X is re-prompted
+        //       (STALL_REPROMPT) and stays ACTIVE; it does NOT idle-release. Same
+        //       publisher K, opposite outcome purely by edge mode — ACTIVE holds a
+        //       node alive to await, PASSIVE does not (oracle §3b, §5). This is the
+        //       discriminating negative the rest of the test relies on.
+        // ===================================================================
+        const X = await h.spawnChild(B, 'a passive-only observer');
+        {
+            const res = h.cli(X, ['node', 'subscribe', K, '--passive']);
+            assert.equal(res.code, 0, `X→K passive subscribe exit 0\n${res.stderr}`);
+            assert.match(res.stdout, /mode="passive"/, 'X→K wired PASSIVE-only (its ONLY subscription)');
+        }
+        assert.deepEqual(edgeSet(h.subscriptions(X)), new Set([`${K}:passive`]), 'X holds exactly one tie: K(passive) — no active live subscription');
+        const injBeforeStall = h.injected(X).length;
+        await h.stop(X);
+        // The PASSIVE tie does NOT legitimize a release → 'stalled' → re-prompt.
+        await h.waitFor(() => h.injected(X).slice(injBeforeStall).find((e) => e.content.includes(STALL_REPROMPT)), { timeoutMs: 15_000, label: 'X (passive-only) → STALL_REPROMPT, not awaiting' });
+        assert.equal(h.status(X), 'active', 'X stays ACTIVE — a PASSIVE-only tie does NOT hold it as awaiting');
+        assert.equal(h.node(X).intent ?? null, null, 'X intent untouched — it did NOT idle-release');
+        // ===================================================================
+        // S3 — P goes DORMANT. P stops while holding an ACTIVE live sub to K →
+        //      stop-guard 'awaiting' → idle-release. (Its PASSIVE sub to T is
+        //      EXCLUDED from hasActiveLiveSubscription — proven directly by S2b:
+        //      a passive-only tie stalls; only the ACTIVE K-tie releases P here.)
+        // ===================================================================
+        await h.stop(P);
+        await h.waitForStatus(P, 'idle');
+        {
+            const p = h.node(P);
+            assert.equal(p.status, 'idle', 'P idle (released on the strength of its ACTIVE K-sub)');
+            assert.equal(p.intent, 'idle-release', 'P intent=idle-release');
+        }
+        await h.waitForPaneGone(P);
+        assert.equal(h.paneAlive(P), false, 'P unfocused → pane closed on idle-release (dormant)');
+        // ===================================================================
+        // S4 — B (the ACTIVE subscriber of T) goes DORMANT too. B awaits T,K
+        //      (active) and P (now idle) → 'awaiting' → idle-release, pane closes.
+        //      Now BOTH subscribers of T are dormant — one active, one passive.
+        // ===================================================================
+        await h.stop(B);
+        await h.waitForStatus(B, 'idle');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'idle', 'B idle (released, awaiting its live children)');
+            assert.equal(b.intent, 'idle-release', 'B intent=idle-release');
+        }
+        await h.waitForPaneGone(B);
+        assert.equal(h.paneAlive(B), false, 'B unfocused → pane closed on idle-release');
+        // Pre-push baseline: the keepalive is up, the grandparent is untouched.
+        assert.equal(h.status(K), 'active', 'K still active (keepalive holds P legitimately dormant)');
+        assert.equal(h.status(A), 'active', 'A (resident root) untouched');
+        assert.equal(h.inbox(A).length, 0, 'A inbox empty before the push');
+        assert.equal(h.inbox(B).length, 0, 'B inbox empty before the push (nothing delivered yet)');
+        assert.equal(passive(P).length, 0, 'P passive accumulator empty before the push');
+        // ===================================================================
+        // S5 — T FINISHES (push final). feed.push fans the pointer to
+        //      subscribersOf(T) = {B(active), P(passive)} ONLY, by the delivery
+        //      split: B's lands in inbox.jsonl, P's in passive.jsonl. A (the
+        //      grandparent, NOT a subscriber of T) gets NOTHING — one-hop fan-out.
+        // ===================================================================
+        const TARGET_FINAL = 'TARGET-FINAL-BODY: the worker completed';
+        await h.finish(T, TARGET_FINAL);
+        {
+            const t = h.node(T);
+            assert.equal(t.status, 'done', 'T done after push final');
+            assert.equal(t.intent, 'done', 'T intent=done');
+            assert.equal(h.paneAlive(T), false, 'T pane closed on done');
+            // ACTIVE delivery → B's INBOX (the wake channel).
+            const bInbox = h.inbox(B);
+            const bFinal = bInbox.find((e) => e.from === T && e.kind === 'final');
+            assert.ok(bFinal, 'ACTIVE subscriber B: T-final pointer DELIVERED to inbox.jsonl');
+            // PASSIVE delivery → P's ACCUMULATOR, NOT its inbox (no wake channel).
+            const pPassive = passive(P);
+            assert.equal(pPassive.length, 1, 'PASSIVE subscriber P: exactly one passive entry');
+            assert.equal(pPassive[0].from, T, "P's passive entry is from T");
+            assert.equal(pPassive[0].kind, 'final', "P's passive entry is the final");
+            assert.equal(h.inbox(P).length, 0, 'PASSIVE subscriber P: inbox.jsonl stays EMPTY (no wake channel)');
+            // ONE-HOP: the indirect ancestor and the non-subscriber sibling hear nothing.
+            assert.equal(h.inbox(A).length, 0, 'A (grandparent, not a subscriber of T) NOT delivered — one-hop');
+            assert.equal(h.inbox(K).length, 0, 'K (sibling, not a subscriber of T) NOT delivered');
+        }
+        // ===================================================================
+        // S6 — The DAEMON decision pass. Its 2nd pass revives an idle-released
+        //      node ONLY on an unseen INBOX entry. B has one (active) → REVIVED
+        //      (resume). P has none (its entry went to passive.jsonl) → stays idle.
+        //      This is the WAKE half of delivery-vs-wake, decided in ONE tick.
+        // ===================================================================
+        const injBeforeWake = h.injected(B).length;
+        await h.tick();
+        // ACTIVE subscriber: WOKEN — status flips to active and a fresh pi resumes.
+        await h.waitForStatus(B, 'active');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'active', 'ACTIVE subscriber B: daemon-REVIVED → active');
+            assert.equal(b.intent ?? null, null, "B intent cleared by revive");
+        }
+        await h.awaitBoot(B, { minCount: 2 }); // spawn boot + resume boot
+        // awaitWake THROWS on a 15s timeout unless an injected entry matching T's
+        // body arrives — that match-or-timeout IS the load-bearing oracle here. The
+        // resume-boot injects persona/bearings, never the report body, so only the
+        // real inbox-watcher delivery of T's final can satisfy the match.
+        await h.awaitWake(B, { sinceCount: injBeforeWake, match: /TARGET-FINAL-BODY/ });
+        // PASSIVE subscriber: NOT WOKEN — the synchronous tick that revived B did
+        // NOT revive P; P remains idle-released with its pane gone. (The tick's
+        // loop completed before tick() returned, so P's non-revive is settled.)
+        assert.equal(h.status(P), 'idle', 'PASSIVE subscriber P: STILL idle — daemon did NOT wake it');
+        assert.equal(h.node(P).intent, 'idle-release', 'P still intent=idle-release (untouched)');
+        assert.equal(h.paneAlive(P), false, 'P pane STILL gone — no resume happened');
+        assert.equal(passive(P).length, 1, "P's passive entry is still pending (drained only on its next message)");
+        assert.equal(h.inbox(P).length, 0, "P's inbox still empty");
+        // The grandparent is STILL untouched even though B woke — one-hop confirmed.
+        assert.equal(h.inbox(A).length, 0, 'A inbox STILL empty after B woke — wake did not propagate up');
+        assert.equal(h.status(A), 'active', 'A unchanged');
+        // ===================================================================
+        // S7 — SECOND SITE: one-hop fan-out on a re-push. The indirect ancestor A
+        //      hears B ONLY when B explicitly re-pushes up its own spine. B (now
+        //      active) pushes an UPDATE → it fans to subscribersOf(B) = {A} only.
+        //      This corroborates the flagship one-hop finding at an independent site.
+        // ===================================================================
+        {
+            const res = h.cli(B, ['push', 'update', 'B re-pushing the rolled-up result']);
+            assert.equal(res.code, 0, `B push update exit 0\n${res.stderr}`);
+            const aInbox = h.inbox(A);
+            assert.equal(aInbox.length, 1, "A inbox now has exactly B's update (one hop, on B's explicit re-push)");
+            assert.equal(aInbox[0].from, B, "A's entry is from B");
+            assert.equal(aInbox[0].kind, 'update', "A's entry is the update");
+        }
+        // The re-push reached its DIRECT subscriber A only — siblings/observer untouched.
+        assert.equal(h.inbox(P).length, 0, "P inbox untouched by B's re-push (P does not subscribe to B)");
+        assert.equal(h.inbox(K).length, 0, "K inbox untouched by B's re-push");
+        assert.equal(passive(P).length, 1, "P's passive backlog unchanged by B's re-push");
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/canvas/browse/__tests__/model.test.d.ts

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

package/dist/core/canvas/browse/__tests__/model.test.js

@@ -0,0 +1,142 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildTree, flatten, fuzzyMatch, tabPredicate, TABS } from '../model.js';
+// ── Fixture canvas ───────────────────────────────────────────────────────────
+//   root1 (active)            ← rank 0
+//     child-a (idle)
+//       grand-x (done)
+//     child-b (active, ⚑2)
+//   root2 (done)              ← rank 2 (dormant root, but ancestor of a live node)
+//     child-c (active)
+//   lonely (idle)             ← straggler: in rows, no edge reaches it, not a root
+function row(node_id, name, status, asks = 0) {
+    return { node_id, name, status, kind: 'general', mode: 'base', ctx_tokens: 0, asks, cwd: '/tmp/proj', created: '2026-01-01T00:00:00.000Z' };
+}
+const ROWS = [
+    row('root1', 'root-one', 'active'),
+    row('child-a', 'child-a', 'idle'),
+    row('grand-x', 'grand-x', 'done'),
+    row('child-b', 'child-b', 'active', 2),
+    row('root2', 'root-two', 'done'),
+    row('child-c', 'child-c', 'active'),
+    row('lonely', 'lonely-node', 'idle'),
+];
+// rootIds intentionally unsorted to prove buildTree sorts live-first.
+const ROOT_IDS = ['root2', 'root1'];
+const CHILDREN = {
+    root1: ['child-a', 'child-b'],
+    'child-a': ['grand-x'],
+    root2: ['child-c'],
+};
+const childIdsOf = (id) => CHILDREN[id] ?? [];
+function tree() {
+    return buildTree(ROWS, ROOT_IDS, childIdsOf);
+}
+// ── fuzzyMatch ───────────────────────────────────────────────────────────────
+test('fuzzyMatch: empty query matches everything', () => {
+    assert.equal(fuzzyMatch('', 'whatever'), true);
+});
+test('fuzzyMatch: case-insensitive subsequence', () => {
+    assert.equal(fuzzyMatch('abc', 'aXbXc'), true);
+    assert.equal(fuzzyMatch('AB', 'xaYbz'), true);
+    assert.equal(fuzzyMatch('grandx', 'grand-x'), true);
+});
+test('fuzzyMatch: out-of-order is not a match', () => {
+    assert.equal(fuzzyMatch('abc', 'acb'), false);
+    assert.equal(fuzzyMatch('zz', 'z'), false);
+});
+// ── buildTree ────────────────────────────────────────────────────────────────
+test('buildTree: roots sorted live-first, stragglers appended', () => {
+    const t = tree();
+    assert.deepEqual(t.roots, ['root1', 'root2', 'lonely']);
+});
+test('buildTree: depth, parentId, childIds', () => {
+    const t = tree();
+    assert.equal(t.nodes.size, 7);
+    assert.deepEqual(t.nodes.get('root1'), {
+        row: ROWS[0], depth: 0, parentId: null, childIds: ['child-a', 'child-b'],
+    });
+    assert.equal(t.nodes.get('child-a').depth, 1);
+    assert.equal(t.nodes.get('child-a').parentId, 'root1');
+    assert.deepEqual(t.nodes.get('child-a').childIds, ['grand-x']);
+    assert.equal(t.nodes.get('grand-x').depth, 2);
+    assert.equal(t.nodes.get('grand-x').parentId, 'child-a');
+    // straggler attaches at depth 0 with no parent
+    assert.equal(t.nodes.get('lonely').depth, 0);
+    assert.equal(t.nodes.get('lonely').parentId, null);
+});
+test('buildTree: unknown child ids are dropped (missing meta safe)', () => {
+    const t = buildTree(ROWS, ['root1'], (id) => (id === 'root1' ? ['child-a', 'ghost'] : childIdsOf(id)));
+    assert.deepEqual(t.nodes.get('root1').childIds, ['child-a']);
+    assert.equal(t.nodes.has('ghost'), false);
+});
+// ── tab predicates ───────────────────────────────────────────────────────────
+test('tabPredicate: All / Live / Dormant / Flagged', () => {
+    assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Flagged']);
+    const active = ROWS[0]; // root1 active
+    const idle = ROWS[1]; // child-a idle
+    const done = ROWS[2]; // grand-x done
+    const flagged = ROWS[3]; // child-b active asks 2
+    assert.equal(tabPredicate('All', done), true);
+    assert.equal(tabPredicate('Live', active), true);
+    assert.equal(tabPredicate('Live', idle), true);
+    assert.equal(tabPredicate('Live', done), false);
+    assert.equal(tabPredicate('Dormant', done), true);
+    assert.equal(tabPredicate('Dormant', active), false);
+    assert.equal(tabPredicate('Flagged', flagged), true);
+    assert.equal(tabPredicate('Flagged', active), false);
+});
+// ── flatten: collapse / expand ───────────────────────────────────────────────
+const allCollapsed = () => new Set(['root1', 'child-a', 'root2']); // every node with children
+test('flatten: default-collapsed shows only top-level', () => {
+    const v = flatten(tree(), { collapsed: allCollapsed(), tab: 'All', query: '' });
+    assert.deepEqual(v.map((r) => r.id), ['root1', 'root2', 'lonely']);
+    // root1 has children and is collapsed → glyph state
+    assert.equal(v[0].hasChildren, true);
+    assert.equal(v[0].collapsed, true);
+    assert.equal(v[2].hasChildren, false); // lonely is a leaf
+});
+test('flatten: expanding a root reveals its (still-collapsed) children', () => {
+    const collapsed = allCollapsed();
+    collapsed.delete('root1');
+    const v = flatten(tree(), { collapsed, tab: 'All', query: '' });
+    assert.deepEqual(v.map((r) => r.id), ['root1', 'child-a', 'child-b', 'root2', 'lonely']);
+    // child-a still collapsed → grand-x hidden
+    assert.equal(v.find((r) => r.id === 'child-a').collapsed, true);
+});
+test('flatten: fully expanded shows the whole subtree', () => {
+    const collapsed = new Set(); // nothing collapsed
+    const v = flatten(tree(), { collapsed, tab: 'All', query: '' });
+    assert.deepEqual(v.map((r) => r.id), ['root1', 'child-a', 'grand-x', 'child-b', 'root2', 'child-c', 'lonely']);
+});
+// ── flatten: tab filtering + ancestor context ────────────────────────────────
+test('flatten: Live tab dims dormant ancestors, keeps live matches', () => {
+    const v = flatten(tree(), { collapsed: allCollapsed(), tab: 'Live', query: '' });
+    assert.deepEqual(v.map((r) => r.id), ['root1', 'root2', 'lonely']);
+    const byId = Object.fromEntries(v.map((r) => [r.id, r]));
+    assert.equal(byId['root1'].matched, true); // active
+    assert.equal(byId['lonely'].matched, true); // idle
+    assert.equal(byId['root2'].matched, false); // dormant, shown only as ancestor of child-c
+});
+test('flatten: Dormant tab excludes live-only branches', () => {
+    const v = flatten(tree(), { collapsed: new Set(), tab: 'Dormant', query: '' });
+    const ids = v.map((r) => r.id);
+    assert.ok(ids.includes('grand-x')); // done
+    assert.ok(ids.includes('root2')); // done
+    assert.ok(!ids.includes('child-b')); // active → excluded
+    assert.ok(!ids.includes('lonely')); // idle → excluded
+});
+// ── flatten: query auto-expands ancestors of matches ─────────────────────────
+test('flatten: query force-expands ancestors even when collapsed', () => {
+    // Everything collapsed; query targets a deep leaf. Its ancestors must appear.
+    const v = flatten(tree(), { collapsed: allCollapsed(), tab: 'All', query: 'grandx' });
+    assert.deepEqual(v.map((r) => r.id), ['root1', 'child-a', 'grand-x']);
+    const byId = Object.fromEntries(v.map((r) => [r.id, r]));
+    assert.equal(byId['grand-x'].matched, true); // the actual match
+    assert.equal(byId['child-a'].matched, false); // ancestor for context
+    assert.equal(byId['root1'].matched, false); // ancestor for context
+});
+test('flatten: query with no matches yields nothing', () => {
+    const v = flatten(tree(), { collapsed: allCollapsed(), tab: 'All', query: 'zzzznope' });
+    assert.deepEqual(v, []);
+});

package/dist/core/canvas/browse/__tests__/render.test.d.ts

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