@north-light/crouter 0.3.154

package/dist/core/__tests__/stream-watchdog.test.js

@@ -0,0 +1,154 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/stream-watchdog.test.ts
+//
+// Unit-level contract test for StreamWatchdog (see stream-watchdog.ts): a
+// single-timer dead-man's switch the broker pokes while a turn awaits the
+// provider (disarmed during tool execution) and clears at agent_end. This
+// locks the class's arm/clear/single-fire/token contract directly — no broker
+// or fake-engine harness needed (that integration surface is deliberately out
+// of scope; see
+// the roadmap's Fix 3 test-scope note).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { StreamWatchdog, KNOWN_STREAM_WAIT_UI, releaseKnownStreamWait, withKnownStreamWait } from '../runtime/stream-watchdog.js';
+const MS = 30;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+test('poke() arms the watchdog, firing once after ms with no further poke', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    assert.equal(calls, 0, 'must not fire before ms elapses');
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'must fire exactly once after ms with no further poke');
+});
+test('repeated pokes rearm the deadline from the LAST poke, not the first', async () => {
+    // A cancel-without-reschedule bug (clear the old timer but never arm a new
+    // one) would also "never fire while poked", so proving no-fire mid-stream is
+    // not enough. Prove the deadline actually REARMS: no fire around the original
+    // deadline, then exactly one fire measured from the FINAL poke.
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    // Re-poke well inside the window, several times, always resetting the clock.
+    // The last poke lands at ~t=2.5*MS, so the original t=MS deadline must pass
+    // with no fire.
+    for (let i = 0; i < 5; i++) {
+        await sleep(MS / 2);
+        wd.poke(0);
+    }
+    assert.equal(calls, 0, 'no fire around the original deadline — each poke rearmed it');
+    // From the final poke the timer must still be armed and fire exactly once.
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'exactly one fire, measured from the final poke — proves rearming');
+});
+test('clear() after poke prevents firing', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    wd.clear();
+    await sleep(MS * 2);
+    assert.equal(calls, 0, 'a cleared watchdog must never fire');
+});
+test('fires exactly once even if left armed well past ms', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    await sleep(MS * 5);
+    assert.equal(calls, 1, 'must fire only once, not repeatedly, past the deadline');
+});
+test('pause() disarms the timer AND makes poke() inert until resume()', async () => {
+    // A deliberate known-stream wait (a provider cooldown) relays no engine
+    // events, and any poke that IS relayed during it must not rearm the disarmed
+    // watchdog — otherwise the intentional silence would still trip a stall.
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.poke(0);
+    wd.pause();
+    await sleep(MS * 3);
+    assert.equal(calls, 0, 'pause() must cancel the pending fire');
+    wd.poke(0); // relayed mid-wait — must be inert while paused
+    await sleep(MS * 2);
+    assert.equal(calls, 0, 'poke() while paused must not rearm the watchdog');
+});
+test('resume() rearms after a pause and fires once on continued silence', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.pause();
+    await sleep(MS * 2);
+    assert.equal(calls, 0, 'paused watchdog stays silent');
+    wd.resume(0);
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'resume() rearms; a still-silent stream fires exactly once');
+});
+test('reset() fully disarms AND unpauses so a later session is not stranded paused', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.pause();
+    wd.reset();
+    // After reset the watchdog must behave like a fresh one: poke arms and fires.
+    wd.poke(0);
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'reset() clears the paused flag; poke arms normally afterward');
+});
+test('withKnownStreamWait holds the watchdog paused across the op, then rearms', async () => {
+    // The real broker seam: the provider extension reaches a broker-owned control
+    // (keyed by KNOWN_STREAM_WAIT_UI on the UI context) that pauses for the wait's
+    // duration and resumes after. During the wait the watchdog must not fire; once
+    // the wait releases and the stream is still silent, it fires exactly once.
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    const ui = {
+        [KNOWN_STREAM_WAIT_UI]: (_deadlineMs) => {
+            wd.pause();
+            return () => wd.resume(0);
+        },
+    };
+    wd.poke(0);
+    await withKnownStreamWait(ui, Date.now() + MS * 10, () => sleep(MS * 3));
+    assert.equal(calls, 0, 'no stall fires during the deliberate wait');
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'after release, the rearmed silent stream fires exactly once');
+});
+test('broker known-wait release resumes only a live provider stream and resets a finished or tool-bound turn', async () => {
+    let calls = 0;
+    const wd = new StreamWatchdog(() => calls++, MS);
+    wd.pause();
+    releaseKnownStreamWait(wd, 7, true, false);
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'a still-streaming tool-free turn resumes the watchdog');
+    wd.pause();
+    releaseKnownStreamWait(wd, 8, false, false);
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'a finished/rebound turn resets rather than arming a stale watchdog');
+    wd.pause();
+    releaseKnownStreamWait(wd, 9, true, true);
+    await sleep(MS * 2);
+    assert.equal(calls, 1, 'an active tool resets rather than watching legitimate tool silence');
+});
+test('withKnownStreamWait releases in finally when the waited operation throws', async () => {
+    let releases = 0;
+    const ui = {
+        [KNOWN_STREAM_WAIT_UI]: (_deadlineMs) => () => { releases++; },
+    };
+    await assert.rejects(withKnownStreamWait(ui, Date.now() + 1_000, async () => { throw new Error('wait failed'); }), /wait failed/);
+    assert.equal(releases, 1, 'the broker control releases exactly once on a rejected wait');
+});
+test('withKnownStreamWait runs op with a plain fallback when no broker control is present', async () => {
+    let ran = false;
+    await withKnownStreamWait(undefined, Date.now() + 1000, async () => {
+        ran = true;
+    });
+    assert.equal(ran, true, 'op must run even without a KNOWN_STREAM_WAIT_UI control');
+});
+test('onStall receives the token of the arm that fired (generation binding)', async () => {
+    // The broker stamps each poke with the current session generation and no-ops
+    // a stall whose token is stale. This pins that the token travels with the
+    // arm: a re-poke supersedes the prior token, so a fire after a rebind carries
+    // the NEW generation — and an old timer that somehow survived would deliver
+    // the OLD one, which the broker guard rejects.
+    const tokens = [];
+    const wd = new StreamWatchdog((token) => tokens.push(token), MS);
+    wd.poke(1);
+    wd.poke(2); // supersedes generation 1 before it can fire
+    await sleep(MS * 2);
+    assert.deepEqual(tokens, [2], 'exactly one fire, carrying the most-recent arm\'s token');
+});

package/dist/core/__tests__/subcommand-tier.test.d.ts

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

package/dist/core/__tests__/subcommand-tier.test.js

@@ -0,0 +1,99 @@
+// Tests for the subcommand visibility tier (hidden | normal | common | important)
+// and the parent-level listing affordance.
+// Run with: node --import tsx/esm --test src/core/__tests__/subcommand-tier.test.ts
+//
+// Contract:
+//  - Each child def (defineLeaf/defineBranch) owns its own description /
+//    whenToUse / tier; defineBranch assembles `help.listing` from those defs —
+//    the parent never copies a child's self-description (principle 16).
+//  - renderRoot promotes a subtree's `important` children (name + shortform
+//    desc) and `common` children (bare qualified path) into that command's
+//    block, then names how many other non-hidden subcommands stay behind
+//    `crtr <name> -h`.
+//  - `hidden` children never appear (not even in the subtree's own -h) and are
+//    not counted in any "[+N]" remainder.
+//  - renderBranch renders one self-closing <subcommand> per non-hidden child
+//    and adds a `subcommands="N"` attribute when a branch child owns children.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { defineRoot, defineBranch, defineLeaf } from '../command.js';
+import { renderRoot, renderBranch } from '../help.js';
+const leaf = (name, opts = {}) => defineLeaf({
+    name,
+    description: opts.description,
+    whenToUse: opts.whenToUse,
+    tier: opts.tier,
+    help: { name, summary: name, output: [], outputKind: 'object', effects: ['None. Read-only.'] },
+    run: async () => ({}),
+});
+// A nested branch so we can assert the `subcommands="N"` depth flag. Its own
+// parent-level self-description (description/whenToUse) lives on the def, as a
+// sibling of `name`.
+const inspect = defineBranch({
+    name: 'inspect',
+    description: 'inspect things',
+    whenToUse: 'x',
+    help: { name: 'thing inspect', summary: 'inspect' },
+    children: [
+        leaf('list', { description: 'list', whenToUse: 'x' }),
+        leaf('show', { description: 'show', whenToUse: 'x' }),
+    ],
+});
+const thing = defineBranch({
+    name: 'thing',
+    rootEntry: { concept: 'a thing', desc: 'things', useWhen: 'doing things' },
+    help: { name: 'thing', summary: 'do things' },
+    children: [
+        leaf('make', { description: 'make a thing', whenToUse: 'x', tier: 'important' }),
+        leaf('promote', { description: 'promote a thing', whenToUse: 'x', tier: 'common' }),
+        inspect,
+        leaf('secret', { description: 'secret op', whenToUse: 'x', tier: 'hidden' }),
+        leaf('plain', { description: 'plain op', whenToUse: 'x' }),
+    ],
+});
+const root = defineRoot({ tagline: 'test runtime', globals: [], subtrees: [thing] });
+describe('renderRoot: subcommand promotion', () => {
+    const out = renderRoot(root.help);
+    test('important child surfaces with its shortform desc', () => {
+        assert.match(out, /\n {2}thing make {2,}make a thing\n/);
+    });
+    test('common child surfaces as a bare qualified path (no desc)', () => {
+        assert.match(out, /\n {2}thing promote\n/);
+        assert.doesNotMatch(out, /thing promote {2,}promote a thing/);
+    });
+    test('hidden child is never promoted and not counted', () => {
+        assert.doesNotMatch(out, /secret/);
+        // 5 children, 1 hidden => 4 listable, 2 promoted => 2 remaining.
+        assert.match(out, /\[\+2 other subcommands — `crtr thing -h`\]/);
+    });
+});
+describe('renderRoot: commands with no promotions', () => {
+    test('still advertise their subcommand count', () => {
+        const bare = defineBranch({
+            name: 'bare',
+            rootEntry: { concept: 'bare', desc: 'bare', useWhen: 'x' },
+            help: { name: 'bare', summary: 'bare' },
+            children: [leaf('one', { description: 'one', whenToUse: 'x' })],
+        });
+        const r = defineRoot({ tagline: 't', globals: [], subtrees: [bare] });
+        const out = renderRoot(r.help);
+        assert.match(out, /\[\+1 subcommand — `crtr bare -h`\]/); // singular, no "other"
+    });
+});
+describe('renderBranch: hidden filter + depth flag (XML)', () => {
+    const out = renderBranch(thing.help);
+    test('hidden child is dropped from the branch listing', () => {
+        assert.doesNotMatch(out, /secret/);
+    });
+    test('all non-hidden children are listed as <subcommand> rows', () => {
+        for (const n of ['make', 'promote', 'inspect', 'plain']) {
+            assert.match(out, new RegExp(`name="${n}"`));
+        }
+    });
+    test('a branch child flags how many subcommands it owns', () => {
+        assert.match(out, /name="inspect"[^>]*subcommands="2"/);
+    });
+    test('leaf children carry no subcommand flag', () => {
+        assert.doesNotMatch(out, /name="make"[^>]*subcommands=/);
+    });
+});

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

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

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

@@ -0,0 +1,211 @@
+// 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. The whole split is pure canvas/feed/daemon model logic,
+// so this is driven by FABRICATING the topology + dormant states directly
+// (foundation-spec §E.2) and exercising the real model layer (feed.push,
+// evaluateStop, superviseTick) — NO real tmux session, NO pane chrome, and NO
+// real broker boot (which would cost ~5s each). Every assertion reads the canvas
+// data layer and is checked against the state-model ORACLE (§3b, §5, §6).
+//
+// HEADLESS / FABRICATED RETARGET (foundation-spec §C.15 + §E). All nodes are
+// broker-hosted (paneless). Dormancy, which a tmux node shows as a closed pane,
+// a broker shows as an EXITED process (status=idle, intent=idle-release, pi_pid
+// dead) — fabricated directly. A daemon revive is observed via getNode().cycles
+// (reviveNode bumps cycles + transition('revive') BEFORE it spawns — revive.ts:
+// 114,145 — so the model effect is instant, no awaitBoot), never a real boot.
+//
+// (1) BUG LOCKED — the DELIVERY-vs-WAKE split (Invariant D + stop-guard): an
+//     ACTIVE subscriber's pointer lands in inbox.jsonl and the daemon's 2nd pass
+//     REVIVES it on that unseen entry; a PASSIVE subscriber's pointer lands in
+//     passive.jsonl and NEVER wakes; a PASSIVE-only tie does NOT legitimize an
+//     idle-release (hasActiveLiveSubscription filters active=1).
+// (2) WHY MODEL-LEVEL, NOT TMUX CHROME — routing (feed.ts), the active/passive
+//     edge filter (canvas.ts), the 2nd-pass inbox gate (crtrd.ts), and one-hop
+//     fan-out are all pure data-layer; the only thing a pane ever provided was a
+//     visible "dormant" signal, which a broker expresses as a dead pid — and
+//     which fabrication sets directly.
+// (3) HOW THE FABRICATED DRIVE STILL FAILS IF THE BUG REGRESSES — after T's
+//     pushFinal, one h.tick() must revive the ACTIVE subscriber B (cycles bumps,
+//     status→active) while the PASSIVE subscriber P stays idle with cycles==0. If
+//     inbox-vs-passive routing breaks, either B's entry never reaches its inbox
+//     (the 2nd-pass gate finds nothing → B not revived → cycles stays 0) or P
+//     gets an inbox entry and IS woken (its cycles/status asserts go RED).
+//     Verified by routing passive deliveries into the inbox (see bug-injection
+//     report).
+//
+// 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 subscribe(P,T,false))
+//                  P→K active   (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 } from './helpers/harness.js';
+import { closeDb } from '../canvas/db.js';
+import { subscribe } from '../canvas/canvas.js';
+import { pushFinal, pushUpdate } from '../feed/feed.js';
+import { readPassive } from '../feed/passive.js';
+import { evaluateStop, STALL_REPROMPT } from '../runtime/stop-guard.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;
+}
+// LOCAL helper: read a node's PASSIVE accumulator (passive.jsonl) straight off
+// the data layer, mirroring the harness's own `inbox()` reader. 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', { timeout: 30_000 }, async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-subdeliv' });
+    try {
+        // ===================================================================
+        // S1 — Build the graph by FABRICATION (no boots). A is a resident root
+        //      (inline, daemon-untouched); B/T/K/P/X are broker nodes whose
+        //      liveness fields are set directly. Each parent→child spine edge is
+        //      wired ACTIVE.
+        // ===================================================================
+        const A = h.spawnRoot('front door'); // resident root, active, no placement
+        // T (the target) and K (keepalive) are LIVE-active workers; B and P start
+        // already DORMANT (idle-released, broker exited = dead pid) — exactly the
+        // post-stop state the delivery split is judged against.
+        const T = h.fabricateBrokerNode({ status: 'active', pi_pid: deadPid(), pi_session_id: 'sess-T' });
+        const K = h.fabricateBrokerNode({ status: 'active', pi_pid: deadPid(), pi_session_id: 'sess-K' });
+        const B = h.fabricateBrokerNode({ status: 'idle', intent: 'idle-release', pi_pid: deadPid(), pi_session_id: 'sess-B' });
+        const P = h.fabricateBrokerNode({ status: 'idle', intent: 'idle-release', pi_pid: deadPid(), pi_session_id: 'sess-P' });
+        // Spine seeds: A→B, B→T, B→K, B→P all ACTIVE (subscriber, publisher).
+        subscribe(A, B, true);
+        subscribe(B, T, true);
+        subscribe(B, K, true);
+        subscribe(B, P, true);
+        // PASSIVE axis under test: P passively subscribes to T; P actively to K
+        // (the only tie that legitimizes P's own idle-release).
+        subscribe(P, T, false);
+        subscribe(P, K, true);
+        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.subscribers(B)), new Set([`${A}:active`]), 'A→B active seed');
+        assert.deepEqual(edgeSet(h.subscriptions(P)), new Set([`${T}:passive`, `${K}:active`]), 'P subscribes_to T(passive) + K(active)');
+        // ===================================================================
+        // S2 — PASSIVE-EXCLUSION via the PURE stop-guard (the active/passive split
+        //      half). evaluateStop is pure given the canvas; X holds a PASSIVE-only
+        //      tie to the same live K that P holds ACTIVELY. hasActiveLiveSubscription
+        //      filters active=1 (canvas.ts), so X's passive K-tie is invisible →
+        //      'stalled' (STALL_REPROMPT); P's active K-tie → 'awaiting'. Same
+        //      publisher K, opposite outcome purely by edge mode (oracle §3b, §5).
+        // ===================================================================
+        const X = h.fabricateBrokerNode({ status: 'active' });
+        subscribe(X, K, false); // X→K 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 xStop = evaluateStop(X, { pushedFinal: false, askedHuman: false });
+            assert.equal(xStop.action, 'reprompt', 'X (passive-only) → reprompt, NOT awaiting');
+            assert.equal(xStop.reason, 'stalled', 'X classified stalled — passive tie does not hold it');
+            assert.equal(xStop.message, STALL_REPROMPT, 'X gets the stall re-prompt');
+            const pStop = evaluateStop(P, { pushedFinal: false, askedHuman: false });
+            assert.equal(pStop.action, 'allow', 'P (active K-tie) → allow');
+            assert.equal(pStop.reason, 'awaiting', 'P classified awaiting on its ACTIVE K-sub — the discriminating positive');
+        }
+        // Pre-push baseline: keepalive up, grandparent untouched, nothing delivered.
+        assert.equal(h.status(K), 'active', 'K 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');
+        assert.equal(passive(P).length, 0, 'P passive accumulator empty before the push');
+        assert.equal(h.node(B).cycles ?? 0, 0, 'B not yet revived');
+        assert.equal(h.node(P).cycles ?? 0, 0, 'P not yet revived');
+        // ===================================================================
+        // S3 — T FINISHES via the model layer (pushFinal). 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.
+        // ===================================================================
+        const TARGET_FINAL = 'TARGET-FINAL-BODY: the worker completed';
+        await pushFinal(T, TARGET_FINAL);
+        closeDb();
+        {
+            assert.equal(h.status(T), 'done', 'T done after pushFinal (transition finalize)');
+            assert.equal(h.node(T).intent, 'done', 'T intent=done');
+            // ACTIVE delivery → B's INBOX (the wake channel).
+            const bFinal = h.inbox(B).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');
+        }
+        // ===================================================================
+        // S4 — The DAEMON decision pass. Its 2nd pass revives an idle-released node
+        //      ONLY on an unseen INBOX entry. B has one (active) → REVIVED. P has
+        //      none (its entry went to passive.jsonl) → stays idle. The WAKE half
+        //      of delivery-vs-wake, decided in ONE tick — observed via cycles.
+        // ===================================================================
+        await h.tick();
+        // ACTIVE subscriber: WOKEN — reviveNode bumped cycles + transition(revive).
+        {
+            const b = h.node(B);
+            assert.equal(b.cycles ?? 0, 1, 'ACTIVE subscriber B: daemon pass-2 REVIVED (cycles bumped to 1)');
+            assert.equal(b.status, 'active', 'B revive → active');
+            assert.equal(b.intent ?? null, null, 'B intent cleared by revive');
+        }
+        // PASSIVE subscriber: NOT WOKEN — the same tick did NOT revive P.
+        {
+            const p = h.node(P);
+            assert.equal(p.cycles ?? 0, 0, 'PASSIVE subscriber P: NOT revived (cycles still 0)');
+            assert.equal(p.status, 'idle', 'P STILL idle — daemon did NOT wake it');
+            assert.equal(p.intent, 'idle-release', 'P still intent=idle-release (untouched)');
+        }
+        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');
+        // ===================================================================
+        // S5 — 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.
+        // ===================================================================
+        await pushUpdate(B, 'B re-pushing the rolled-up result');
+        closeDb();
+        {
+            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 {
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/subscription-pool-credential-guard.test.d.ts

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

package/dist/core/__tests__/subscription-pool-credential-guard.test.js

@@ -0,0 +1,94 @@
+// Run with: npm test -- src/core/__tests__/subscription-pool-credential-guard.test.ts
+//
+// A stored credential may only leave the pool with its row (removal); a write that empties a
+// live account in place is refused. These pin the two ways such a write is attempted: a
+// token-less upsert under a recased label (labels resolve case-insensitively everywhere), and
+// an async writer whose provider returned an incomplete token set.
+import { before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const agentDir = mkdtempSync(join(tmpdir(), 'crtr-pool-guard-'));
+process.env['PI_CODING_AGENT_DIR'] = agentDir;
+// Imported dynamically so `PI_CODING_AGENT_DIR` is already set: the pool path is resolved per
+// access, but the import must not race the env write in any future refactor.
+let state;
+before(async () => {
+    state = await import('../subscription-state.js');
+});
+const POOL = join(agentDir, 'openai-codex-subscriptions.json');
+async function seed() {
+    await state.writeSubscriptionPool('openai-codex', [
+        {
+            label: 'work',
+            refresh: 'refresh-live',
+            access: 'access-live',
+            expires: Date.now() + 60_000,
+            accountId: 'acct-1',
+            rateLimitedUntil: 0,
+            lastAttemptAt: 100,
+            lastRateLimitedAt: 50,
+        },
+    ]);
+}
+function stored() {
+    const pool = JSON.parse(readFileSync(POOL, 'utf8'));
+    assert.equal(pool.length, 1, 'the row itself must survive every refused write');
+    return pool[0];
+}
+test('a token-less upsert cannot empty a live row by recasing its label', async () => {
+    await seed();
+    await assert.rejects(() => state.upsertSubscription('openai-codex', {
+        label: 'Work',
+        rateLimitedUntil: 0,
+        lastAttemptAt: 200,
+        lastRateLimitedAt: 60,
+    }), /Refusing to persist incomplete OpenAI Codex subscription "Work"/);
+    assert.equal(stored().refresh, 'refresh-live');
+    assert.equal(stored().access, 'access-live');
+});
+test('a refresh that returns an incomplete token set leaves the stored credential intact', async () => {
+    await seed();
+    // Expired, so the exchange actually runs.
+    await state.writeSubscriptionPool('openai-codex', [{ ...stored(), expires: Date.now() - 1_000 }]);
+    await assert.rejects(() => state.refreshSubscriptionCredential('openai-codex', 'work', async () => ({
+        refresh: '',
+        access: 'access-rotated',
+        expires: Date.now() + 60_000,
+    })), /incomplete credential/);
+    assert.equal(stored().refresh, 'refresh-live', 'the previous credential must survive a refused refresh');
+    assert.equal(stored().access, 'access-live');
+});
+test('a managed login with an incomplete token pair is rejected without changing the pool', async () => {
+    await seed();
+    await assert.rejects(() => state.commitManagedLogin('openai-codex', 'fixture', {
+        refresh: '',
+        access: 'access-fixture',
+        expires: Date.now() + 60_000,
+        lastRateLimitedAt: 0,
+    }), /Refusing to persist incomplete OpenAI Codex subscription "fixture"/);
+    assert.equal(stored().refresh, 'refresh-live');
+    assert.equal(stored().access, 'access-live');
+});
+test('pi credential refresh marks an invalid account and continues with the next pool account', async () => {
+    const expired = Date.now() - 1_000;
+    await state.writeSubscriptionPool('anthropic', [
+        { label: 'personal', refresh: 'dead-refresh', access: 'dead-access', expires: expired, rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0 },
+        { label: 'work', refresh: 'live-refresh', access: 'live-access', expires: expired, rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0 },
+    ]);
+    const attempted = [];
+    const refreshed = await state.modifyElectedSubscription('anthropic', (pool) => pool.find((entry) => !entry.authFailure && entry.rateLimitedUntil <= Date.now()) ?? pool[0], async (entry) => {
+        attempted.push(entry.label);
+        if (entry.label === 'personal') {
+            throw new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}');
+        }
+        return { refresh: 'rotated-refresh', access: 'rotated-access', expires: Date.now() + 60_000 };
+    });
+    assert.deepEqual(attempted, ['personal', 'work']);
+    assert.equal(refreshed?.label, 'work');
+    const pool = state.readSubscriptionPool('anthropic');
+    assert.equal(pool[0].authFailure, 'invalid_grant');
+    assert.ok(pool[0].rateLimitedUntil > Date.now());
+    assert.equal(pool[1].refresh, 'rotated-refresh');
+});

package/dist/core/__tests__/test-runner-cheap-sharding.test.d.ts

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