@north-light/crouter 0.3.154

package/dist/core/__tests__/full/broker-pane-resolution.test.js

@@ -0,0 +1,155 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-pane-resolution.test.ts
+//
+// REGRESSION — broker-hosted nodes were second-class in the tmux command
+// surface (audit: findings-headless-default.md, Gaps 1 + 3). Both regressions
+// are observable only with a REAL tmux pane, so this is a FULL-tier test.
+//
+// (1) Gap 1 — `nodeInPane()` (src/commands/node.ts) resolved a pane via
+//     window→node ONLY. A broker engine runs DETACHED with window=null, and its
+//     on-screen presence is a `crtr surface attach` VIEWER pane, so the window lookup
+//     never found it: viewer navigation and node lifecycle operations all
+//     broke when the current pane was a broker viewer. The fix has attach
+//     self-tag its pane `@crtr_node=<id>` and nodeInPane resolve that tag first.
+//     LOCKED: an untagged pane over a broker resolves undefined (the bug); the
+//     SAME pane, once tagged, resolves the broker (the fix).
+//
+// (3) Gap 3 (tests-lens MAJOR-1) — the §A.4 viewer-DEDUP, the headline new
+//     behavior of the broker-universal cut, had ZERO end-to-end coverage: a
+//     SECOND `surface node focus` on a node must REUSE/move its one viewer, never
+//     STACK a second. Only the DB UNIQUE(node_id)/GC layer was tested; `focus()` itself
+//     (placement.ts) was unexercised. LOCKED here over a REAL broker viewer: two
+//     `surface node focus` calls leave EXACTLY ONE viewer pane + ONE focus row for the
+//     node, the second reused IN PLACE (in_place=true). A focus() that always
+//     opened a fresh pane would yield two tagged panes (or crash on the UNIQUE
+//     constraint) — either way this goes RED.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux, TMUX_TIMEOUT_MS } from '../helpers/harness.js';
+import { taggedViewerPanes, waitForOneTaggedViewer } from '../helpers/viewer-panes.js';
+import { closeDb } from '../../canvas/db.js';
+import { nodeInPane } from '../../../commands/node.js';
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ sessionPrefix: 'crtr-brkpane' });
+    root = h.spawnRoot('host root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+/** Split a throwaway pane in the harness session; return its %id. */
+function makePane() {
+    const r = spawnSync('tmux', ['split-window', '-d', '-t', h.session, '-P', '-F', '#{pane_id}', 'sleep 100000'], { encoding: 'utf8', timeout: TMUX_TIMEOUT_MS });
+    const pane = (r.stdout ?? '').trim();
+    assert.ok(pane.startsWith('%'), `expected a %pane_id, got "${pane}" (stderr: ${r.stderr})`);
+    return pane;
+}
+function tagPane(pane, value) {
+    spawnSync('tmux', ['set-option', '-p', '-t', pane, '@crtr_node', value], {
+        stdio: 'ignore',
+        timeout: TMUX_TIMEOUT_MS,
+    });
+}
+/** Parse `crtr`'s human-list stdout (`- key: value` lines) into a map. */
+function parseList(stdout) {
+    const out = {};
+    for (const line of stdout.split('\n')) {
+        const m = /^- ([^:]+):\s*(.*)$/.exec(line.trim());
+        if (m)
+            out[m[1].trim()] = m[2].trim();
+    }
+    return out;
+}
+// `taggedViewerPanes` / `waitForOneTaggedViewer` live in helpers/viewer-panes.ts:
+// the attach client sets `@crtr_node` asynchronously on CONNECT (not
+// synchronously by openViewerWindow), and the second focus's reuse branch keys
+// on that tag, so the test must let attach connect before reading the registry.
+test('Gap 1 — nodeInPane resolves a broker node from its tagged viewer pane (undefined when untagged)', async (t) => {
+    if (!hasTmux())
+        return t.skip('tmux unavailable');
+    const broker = await h.spawnHeadlessChild(root, 'broker worker');
+    closeDb();
+    assert.equal(h.node(broker).host_kind, 'broker', 'spawned a broker-hosted node');
+    assert.equal(h.node(broker).window ?? null, null, 'broker engine has window=null (paneless)');
+    const viewer = makePane();
+    // BUG REPRODUCTION: an untagged pane over a broker is invisible — no node owns
+    // this pane's window, and a broker has no window to find, so resolution fails.
+    closeDb();
+    assert.equal(nodeInPane(viewer), undefined, 'untagged viewer pane → broker is invisible (the bug)');
+    // FIX: the viewer self-tag (`@crtr_node`) is the broker's pane handle.
+    tagPane(viewer, broker);
+    closeDb();
+    assert.equal(nodeInPane(viewer), broker, 'tagged viewer pane → resolves the broker (the fix)');
+    // A stale tag pointing at a DONE node is ignored (must be live: active/idle).
+    spawnSync('tmux', ['kill-pane', '-t', viewer], { stdio: 'ignore', timeout: TMUX_TIMEOUT_MS });
+});
+// 30s, not the 10s default: this test's own `waitForOneTaggedViewer` budget is
+// 15s (the attach client self-tags its pane asynchronously on connect), so a
+// 10s cap kills the test BEFORE its internal wait can even expire — it passed
+// locally only because a dev box tags in ~1s. A hosted runner is slower, and
+// the run then reported `test timed out after 10000ms` with no real signal.
+test('Gap 3 — a second `surface node focus` REUSES the one viewer (in place), never stacks a second pane/row', { timeout: 30_000 }, async (t) => {
+    if (!hasTmux())
+        return t.skip('tmux unavailable');
+    const broker = await h.spawnHeadlessChild(root, 'broker to focus twice');
+    closeDb();
+    assert.equal(h.node(broker).host_kind, 'broker', 'precondition: broker-hosted node');
+    // A caller pane in the harness session to focus BESIDE (the user's pane the
+    // viewer splits next to). The viewer lands in this same session, so the SECOND
+    // focus's reuse takes the in-session NAVIGATE path (in_place), not the
+    // cross-session MOVE path.
+    const caller = makePane();
+    // FOCUS #1 — a managed child boots with NO viewer (spawn no longer auto-opens
+    // one), so this OPENS the broker's single viewer beside the caller.
+    const f1 = h.cli(broker, ['surface', 'node', 'focus', broker, '--pane', caller]);
+    assert.equal(f1.code, 0, `first focus exit 0\n${f1.stderr}`);
+    assert.equal(parseList(f1.stdout).focused, 'true', 'first focus brought the viewer on screen');
+    // The `@crtr_node` pane tag is the viewer registry (P1: `surface node focus` no longer
+    // writes the focuses DB table — the CLI can't reach canvas.db). Let the attach
+    // client connect + self-tag its one viewer pane before the second focus — the
+    // reuse branch keys on `@crtr_node`; without the tag focus() would (correctly)
+    // treat it as stale and open fresh. This wait is a test-timing concern, not a
+    // product gap (in real use the second focus is a much-later user action).
+    const pane1 = await waitForOneTaggedViewer(h.session, broker);
+    assert.deepEqual(taggedViewerPanes(h.session, broker), [pane1], 'exactly ONE tagged viewer pane on screen after focus #1');
+    // FOCUS #2 — the headline dedup: the node already has a live, tagged viewer in
+    // the caller's session, so focus NAVIGATES to it (no new pane), never stacks.
+    const f2 = h.cli(broker, ['surface', 'node', 'focus', broker, '--pane', caller]);
+    assert.equal(f2.code, 0, `second focus exit 0\n${f2.stderr}`);
+    const f2out = parseList(f2.stdout);
+    assert.equal(f2out.focused, 'true', 'second focus also on screen');
+    assert.equal(f2out.in_place, 'true', 'second focus REUSED the viewer in place (navigate, no new pane)');
+    // The invariant: STILL exactly one viewer pane, the SAME pane (never stacked).
+    assert.deepEqual(taggedViewerPanes(h.session, broker), [pane1], 'STILL exactly ONE tagged viewer pane after focus #2 — the SAME pane (reused, not stacked)');
+});
+// 30s for the same reason as Gap 3 above: a 15s internal viewer-tag wait
+// cannot live under a 10s per-test cap.
+test('surface node focus reuses a viewer in another session instead of reopening it beside the caller', { timeout: 30_000 }, async (t) => {
+    if (!hasTmux())
+        return t.skip('tmux unavailable');
+    const broker = await h.spawnHeadlessChild(root, 'cross-session viewer reuse');
+    const firstCaller = makePane();
+    const first = h.cli(broker, ['surface', 'node', 'focus', broker, '--pane', firstCaller]);
+    assert.equal(first.code, 0, `first focus exit 0\n${first.stderr}`);
+    const originalPane = await waitForOneTaggedViewer(h.session, broker);
+    const otherSession = `${h.session}-other`;
+    const created = spawnSync('tmux', 
+    // -x/-y for the same reason the harness session sets them: a detached
+    // session defaults to 80x24, and the viewer this test MOVES here needs a
+    // pane it can actually live in.
+    ['new-session', '-d', '-s', otherSession, '-x', '250', '-y', '60', '-P', '-F', '#{pane_id}', 'sleep 100000'], { encoding: 'utf8', timeout: TMUX_TIMEOUT_MS });
+    assert.equal(created.status, 0, `created caller session: ${created.stderr}`);
+    const otherCaller = (created.stdout ?? '').trim();
+    try {
+        const second = h.cli(broker, ['surface', 'node', 'focus', broker, '--pane', otherCaller]);
+        assert.equal(second.code, 0, `cross-session focus exit 0\n${second.stderr}`);
+        assert.equal(parseList(second.stdout).in_place, 'true', 'cross-session focus navigated to the existing viewer');
+        assert.deepEqual(taggedViewerPanes(h.session, broker), [originalPane], 'the existing viewer remained open and attached');
+        assert.deepEqual(taggedViewerPanes(otherSession, broker), [], 'no duplicate viewer opened beside the caller');
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', otherSession], { stdio: 'ignore', timeout: TMUX_TIMEOUT_MS });
+    }
+});

package/dist/core/__tests__/full/broker-provider-retry.test.d.ts

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

package/dist/core/__tests__/full/broker-provider-retry.test.js

@@ -0,0 +1,387 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-provider-retry.test.ts
+//
+// Broker-level regression coverage for turn-time provider rotation. The fake
+// engine emits pi's actual auto_retry_start event over session.subscribe, so this
+// exercises runBroker's live retry handler rather than its helpers in isolation.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { createAttachKit } from '../helpers/broker-clients.js';
+import { defaultModelLaddersConfig } from '../../../types.js';
+import { readFault } from '../../runtime/fault.js';
+import { normalizeModel } from '../../runtime/launch.js';
+import { setModelLive } from '../../runtime/model-swap.js';
+const MODEL_LADDERS = defaultModelLaddersConfig();
+function resolvedModel(spec) {
+    const normalized = normalizeModel(spec, MODEL_LADDERS);
+    const modelSpec = normalized.replace(/:(?:off|minimal|low|medium|high|xhigh|max)$/, '');
+    const slash = modelSpec.indexOf('/');
+    assert.notEqual(slash, -1, `${spec} must normalize to a qualified provider/model spec`);
+    const provider = modelSpec.slice(0, slash);
+    const id = modelSpec.slice(slash + 1);
+    return { spec: normalized, model: { provider, id }, pin: { providerId: provider, modelId: id } };
+}
+const ANTHROPIC_STRONG = resolvedModel('anthropic/strong');
+const OPENAI_STRONG = resolvedModel('openai/strong');
+let h;
+const kit = createAttachKit(() => h);
+function poolPath(provider) {
+    const name = provider === 'anthropic' ? 'anthropic-subscriptions.json' : 'openai-codex-subscriptions.json';
+    return join(h.agentHome, '.pi', 'agent', name);
+}
+function seedPool(provider, cooling) {
+    const path = poolPath(provider);
+    mkdirSync(join(h.agentHome, '.pi', 'agent'), { recursive: true });
+    writeFileSync(path, JSON.stringify([{
+            label: 'test-account', refresh: 'refresh', access: 'access', expires: Date.now() + 60_000,
+            rateLimitedUntil: cooling ? Date.now() + 60_000 : 0, lastAttemptAt: 0, lastRateLimitedAt: 0,
+        }]));
+}
+function rotationPath() {
+    return join(h.agentHome, '.pi', 'agent', 'provider-rotation.json');
+}
+function clearRotation() {
+    rmSync(rotationPath(), { force: true });
+}
+function preferred() {
+    try {
+        return JSON.parse(readFileSync(rotationPath(), 'utf8')).preferredModel;
+    }
+    catch {
+        return undefined;
+    }
+}
+function model(id) {
+    return JSON.parse(readFileSync(join(h.home, 'nodes', id, 'fake-pi.model.json'), 'utf8'));
+}
+// Every fired lifecycle event is appended to fake-pi.events.jsonl. A broker
+// re-drive is a fresh session.prompt → emitTurn, which fires one 'agent_start';
+// counting them is the observable proof of how many times the turn was re-driven.
+function agentStartCount(id) {
+    try {
+        return readFileSync(join(h.home, 'nodes', id, 'fake-pi.events.jsonl'), 'utf8')
+            .split('\n')
+            .filter((l) => {
+            try {
+                return JSON.parse(l).event === 'agent_start';
+            }
+            catch {
+                return false;
+            }
+        }).length;
+    }
+    catch {
+        return 0;
+    }
+}
+async function autoRetry(id, expected) {
+    h.fakeCmd(id, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
+    await h.waitFor(() => {
+        try {
+            return assert.deepEqual(model(id), expected) === undefined ? true : false;
+        }
+        catch {
+            return false;
+        }
+    }, { label: `auto-retry switch for ${id}` });
+}
+// The auto-retry receipt file's timestamp, so re-firing auto_retry a second/
+// third time in one test doesn't false-positive on a STALE receipt that
+// already existed from an earlier fire in the same test.
+function autoRetryAt(id) {
+    try {
+        return JSON.parse(readFileSync(join(h.home, 'nodes', id, 'fake-pi.auto-retry.json'), 'utf8')).at;
+    }
+    catch {
+        return 0;
+    }
+}
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-provider-retry' });
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+test('broker auto-retry preserves the launch requested pin, clears it on restoration, and never persists the temporary fallback', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('provider retry parent');
+    seedPool('anthropic', true);
+    seedPool('openai-codex', false);
+    clearRotation();
+    const child = await h.spawnHeadlessChild(parent, 'launch fallback then retry', { model: ANTHROPIC_STRONG.spec });
+    assert.deepEqual(model(child), OPENAI_STRONG.model, 'a cooling requested managed launch starts its viable equivalent');
+    assert.deepEqual(preferred(), ANTHROPIC_STRONG.pin, 'launch retains the requested managed model as its restoration pin');
+    const before = h.node(child);
+    seedPool('anthropic', false);
+    await autoRetry(child, ANTHROPIC_STRONG.model);
+    await h.waitFor(() => preferred() === undefined, { label: 'launch preferred pin cleared after restoration' });
+    assert.deepEqual(preferred(), undefined, 'reaching the launch-requested provider fulfils and clears its temporary pin');
+    const after = h.node(child);
+    assert.equal(after.model_override, before.model_override, 'turn-time fallback never overwrites the durable model override');
+    assert.equal(after.launch?.model, before.launch?.model, 'turn-time fallback never overwrites the durable launch recipe');
+});
+test('broker auto-retry records its current managed model only when no restoration pin exists', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('normal retry parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    clearRotation();
+    // Establish the exact qualified OpenAI ladder cell, then explicitly release
+    // its structural pin so this test reaches the retry resolver by construction.
+    const child = await h.spawnHeadlessChild(parent, 'normal retry', { model: OPENAI_STRONG.spec });
+    await setModelLive(child, OPENAI_STRONG.spec, false);
+    clearRotation();
+    const before = h.node(child);
+    assert.deepEqual(model(child), OPENAI_STRONG.model);
+    await autoRetry(child, ANTHROPIC_STRONG.model);
+    await h.waitFor(() => {
+        try {
+            assert.deepEqual(preferred(), OPENAI_STRONG.pin);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { label: 'normal retry preferred model recorded' });
+    assert.deepEqual(preferred(), OPENAI_STRONG.pin, 'a normal automatic switch records its failed managed model for later restoration');
+    const after = h.node(child);
+    assert.equal(after.model_override, before.model_override);
+    assert.equal(after.launch?.model, before.launch?.model);
+});
+test('a managed-cooling terminal authors a rate-limit auto fault whose deadline drives exactly one broker re-drive', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('cooling terminal parent');
+    // The terminal fault path is pool-independent — the stophook classifies purely
+    // off the errorMessage text + the cooling diagnostic, so pool state is inert.
+    // A qualified openai-codex id now pins structurally, but that has no effect
+    // here either way: this test never triggers retry/not-found policy (only the
+    // stophook fault path + launch-time pinnedToFirst, which is a no-op because
+    // the pool isn't cooling at spawn).
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    clearRotation();
+    const child = await h.spawnHeadlessChild(parent, 'cooling terminal', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial cooling fixture turn started' });
+    const baselineStarts = agentStartCount(child);
+    // A terminal managed-cooling error at agent_end: its explanatory prose avoids
+    // rate-limit words entirely; the typed diagnostic alone must classify the
+    // fault as rate-limit/auto and carry its exact deadline.
+    const deadline = Date.now() + 2000;
+    h.fakeCmd(child, {
+        cmd: 'stop',
+        reason: 'error',
+        errorMessage: 'Managed provider pools are temporarily unavailable; switch to a direct API key. (tried anthropic, openai-codex)',
+        deadline,
+    });
+    // (1) the REAL stophook authored the pi→provider fault, stamping nextAt from
+    //     the cooling diagnostic — this is the whole point of the runtime fix.
+    const fault = await h.waitFor(() => {
+        const f = readFault(child);
+        return f !== null && f.link === 'pi→provider' ? f : undefined;
+    }, { label: 'cooling fault authored by stophook' });
+    assert.equal(fault.kind, 'rate-limit', 'the typed cooling terminal classifies as rate-limit without prose matching');
+    assert.equal(fault.retry.disposition, 'auto', 'a rate-limit fault is auto-retryable');
+    assert.equal(fault.retry.by, 'daemon', 'the broker/daemon owns the re-drive');
+    assert.equal(fault.retry.nextAt, new Date(deadline).toISOString(), 'the earliest cooling deadline becomes retry.nextAt');
+    // (2) the broker's own fault-retry timer fires exactly ONE re-drive at the
+    //     deadline. A completed re-drive turn clears the pi→provider fault at
+    //     turn_end, so no second timer is ever armed.
+    await h.waitFor(() => agentStartCount(child) >= baselineStarts + 1, {
+        label: 'broker re-drove the turn at the deadline',
+        timeoutMs: 10_000,
+    });
+    // A persistent fault would re-arm immediately (nextAt is now in the past), so a
+    // spurious second re-drive would land within a poll interval. Wait past that.
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+    assert.equal(agentStartCount(child), baselineStarts + 1, 'the fault-retry timer re-drives the turn exactly once');
+});
+test('reload_auth re-drives a parked fatal provider-auth turn exactly once', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('auth reload parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'auth reload child', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial auth fixture turn started' });
+    const baselineStarts = agentStartCount(child);
+    h.fakeCmd(child, {
+        cmd: 'stop',
+        reason: 'error',
+        errorMessage: 'Provider authentication failed (invalid_grant) for anthropic/test-account',
+    });
+    const fault = await h.waitFor(() => {
+        const current = readFault(child);
+        return current?.kind === 'auth' ? current : undefined;
+    }, { label: 'fatal auth fault authored by stophook' });
+    assert.equal(fault.link, 'pi→provider');
+    assert.equal(fault.retry.disposition, 'fatal');
+    const observer = await kit.attach(child, 'observer', 'auth-reload-test');
+    observer.send({ type: 'reload_auth' });
+    observer.send({ type: 'reload_auth' });
+    await observer.waitFrame((frame) => frame.type === 'ack' && frame.for === 'reload_auth', 'reload_auth acknowledged');
+    await h.waitFor(() => agentStartCount(child) >= baselineStarts + 1, {
+        label: 'fresh auth re-drove the parked turn',
+    });
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    assert.equal(readFault(child), null, 'the auth fault is cleared before the recovery prompt');
+    assert.equal(agentStartCount(child), baselineStarts + 1, 'overlapping auth reloads produce one recovery turn');
+    observer.close();
+});
+test('reload_auth leaves a parked auth fault with its original session when navigation is overtaken by replacement', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('auth replacement parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'auth replacement child', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial replacement fixture turn started' });
+    h.fakeCmd(child, {
+        cmd: 'stop',
+        reason: 'error',
+        errorMessage: 'Provider authentication failed (invalid_grant) for anthropic/test-account',
+    });
+    const fault = await h.waitFor(() => {
+        const current = readFault(child);
+        return current?.kind === 'auth' ? current : undefined;
+    }, { label: 'replacement fixture auth fault authored by stophook' });
+    const baselineStarts = agentStartCount(child);
+    const nodeDir = join(h.home, 'nodes', child);
+    // Force the redrive's leaf/anchor comparison to diverge so it actually enters
+    // navigateTree (a matching leaf/anchor legitimately skips the rewind) — the
+    // fixture's fault otherwise anchors to the leaf already current.
+    const faultFilePath = join(nodeDir, 'job', 'fault');
+    const rawFault = JSON.parse(readFileSync(faultFilePath, 'utf8'));
+    rawFault['anchorEntryId'] = 'auth-replacement-anchor-mismatch';
+    writeFileSync(faultFilePath, JSON.stringify(rawFault));
+    writeFileSync(join(nodeDir, 'fake-pi.navigate-hold'), '');
+    const controller = await kit.attach(child, 'controller', 'auth-replacement-test');
+    controller.send({ type: 'reload_auth' });
+    await h.waitFor(() => existsSync(join(nodeDir, 'fake-pi.navigate-started')) ? true : null, { label: 'auth redrive entered held navigation' });
+    controller.send({ type: 'new_session' });
+    await controller.waitFrame((frame) => frame.type === 'ack' && frame.for === 'new_session', 'replacement session acknowledged');
+    writeFileSync(join(nodeDir, 'fake-pi.navigate-release'), '');
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    assert.equal(readFault(child)?.since, fault.since, 'the original auth fault remains for its original session');
+    assert.equal(agentStartCount(child), baselineStarts, 'the replacement session receives no stale recovery prompt');
+    controller.close();
+});
+test('successful compact-and-retry settles without a fatal fault or terminal transition', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('recovered overflow parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'recovered overflow child', { model: OPENAI_STRONG.spec });
+    h.fakeCmd(child, { cmd: 'overflow', outcome: 'recover' });
+    await h.waitFor(() => existsSync(join(h.home, 'nodes', child, 'fake-pi.overflow.json')), { label: 'recovered overflow reached agent_settled' });
+    await h.tick();
+    assert.equal(readFault(child), null, 'raw overflow is never committed before Pi recovery settles');
+    assert.notEqual(h.status(child), 'dead', 'a recovered child remains live');
+    assert.doesNotMatch(h.inbox(parent).map((entry) => entry.label).join('\n'), /context window|will not recover/i, 'recovery publishes no fatal parent notice');
+});
+test('queued continuation success supersedes an earlier definitive compaction failure', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('continued overflow parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'continued overflow child', { model: OPENAI_STRONG.spec });
+    h.fakeCmd(child, { cmd: 'overflow', outcome: 'failure-continued' });
+    await h.waitFor(() => existsSync(join(h.home, 'nodes', child, 'fake-pi.overflow.json')), { label: 'post-failure continuation reached agent_settled' });
+    await h.tick();
+    assert.equal(readFault(child), null, 'the final successful continuation owns the settled provider outcome');
+    assert.notEqual(h.status(child), 'dead', 'an earlier compaction failure cannot reap a recovered child');
+    assert.doesNotMatch(h.inbox(parent).map((entry) => entry.label).join('\n'), /context window|will not recover/i, 'the superseded compaction failure publishes no parent notice');
+});
+test('failed compact-and-retry publishes one structured overflow fault and terminal notice', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('failed overflow parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'failed overflow child', { model: OPENAI_STRONG.spec });
+    // A settled ordinary provider failure leaves an active daemon-owned retry
+    // marker in place while the next turn runs. The later terminal overflow must
+    // supersede that marker rather than lose to its priority in fault storage.
+    h.fakeCmd(child, {
+        cmd: 'stop',
+        reason: 'error',
+        errorMessage: 'Managed provider pools are temporarily unavailable.',
+        deadline: Date.now() + 60_000,
+    });
+    const autoFault = await h.waitFor(() => {
+        const f = readFault(child);
+        return f?.retry.disposition === 'auto' ? f : undefined;
+    }, { label: 'ordinary settled provider fault published' });
+    assert.equal(autoFault.kind, 'rate-limit', 'ordinary settled provider failures retain broker-owned retry behavior');
+    h.fakeCmd(child, { cmd: 'overflow', outcome: 'fail' });
+    await h.waitFor(() => existsSync(join(h.home, 'nodes', child, 'fake-pi.overflow.json')), { label: 'failed overflow reached agent_settled' });
+    const fault = readFault(child);
+    assert.equal(fault?.kind, 'context-overflow');
+    assert.equal(fault?.op, 'context overflow recovery');
+    assert.equal(fault?.retry.disposition, 'fatal');
+    assert.match(fault?.message ?? '', /failed after one compact-and-retry attempt/i);
+    await h.tick();
+    assert.equal(h.status(child), 'dead', 'the daemon applies one terminal child transition');
+    const notices = h.inbox(parent).filter((entry) => /exceeded its model context window/i.test(entry.label));
+    assert.equal(notices.length, 1, 'the parent receives exactly one structured overflow notice');
+});
+test('raw overflow settling without compaction terminates instead of hanging', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('uncompacted overflow parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'uncompacted overflow child', { model: OPENAI_STRONG.spec });
+    h.fakeCmd(child, { cmd: 'overflow', outcome: 'uncompacted' });
+    await h.waitFor(() => existsSync(join(h.home, 'nodes', child, 'fake-pi.overflow.json')), { label: 'uncompacted overflow reached agent_settled' });
+    const fault = readFault(child);
+    assert.equal(fault?.kind, 'context-overflow', 'settlement makes a raw overflow terminal when recovery never began');
+    assert.equal(fault?.retry.disposition, 'fatal');
+    await h.tick();
+    assert.equal(h.status(child), 'dead', 'settled raw overflow cannot leave the child hanging');
+});
+test("a live set_model decision updates the running broker's pin policy immediately, in both directions, without a revive", { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('live pin policy parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    clearRotation();
+    // Establish the desired qualified Anthropic ladder cell while explicitly
+    // keeping its live retry policy unpinned, independent of ambient defaults.
+    const child = await h.spawnHeadlessChild(parent, 'live pin policy', { model: ANTHROPIC_STRONG.spec });
+    await setModelLive(child, ANTHROPIC_STRONG.spec, false);
+    clearRotation();
+    assert.deepEqual(model(child), ANTHROPIC_STRONG.model, 'explicit setup selects the current Anthropic strong model');
+    // false → true, LIVE: an explicit raw qualified re-pick pins the SAME
+    // resolved model — no model value changes, only the live pin decision. The
+    // running broker's retry-fallback policy (broker.ts's cfg.modelProviderPinned
+    // read) enforces it on the VERY NEXT retry, with no revive in between: the
+    // auto_retry below is suppressed rather than allowed to rotate the model.
+    await setModelLive(child, ANTHROPIC_STRONG.spec, true);
+    assert.deepEqual(model(child), ANTHROPIC_STRONG.model, 'the explicit re-pick keeps the same resolved model');
+    const priorAt1 = autoRetryAt(child);
+    h.fakeCmd(child, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
+    await h.waitFor(() => autoRetryAt(child) > priorAt1, { label: 'pinned auto-retry processed' });
+    // Settle past the fallback's own async continuation window.
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    assert.deepEqual(model(child), ANTHROPIC_STRONG.model, 'a live pin suppresses turn-time provider rotation immediately, without revive');
+    assert.deepEqual(preferred(), undefined, 'a suppressed retry records no restoration pin');
+    // true → false, LIVE: an explicit re-pick of the same qualified model with
+    // pinned=false releases the pin. The next retry must now be free to rotate.
+    await setModelLive(child, ANTHROPIC_STRONG.spec, false);
+    await autoRetry(child, OPENAI_STRONG.model);
+    assert.deepEqual(preferred(), ANTHROPIC_STRONG.pin, 'the released pin lets the next retry rotate and record a restoration pin');
+});
+test('a picker-originated set_model frame with no pinned field derives the pin from the real registry provider namespace; an internal no-raw-token path preserves it', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('picker frame parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'picker frame child', { model: 'strong' }); // unpinned boot
+    const ctrl = await kit.attach(child, 'controller', 'picker-test');
+    ctrl.send({ type: 'set_model', model: OPENAI_STRONG.spec }); // exactly what buildModelPicker sends — no `pinned`
+    await ctrl.waitFrame((f) => f.type === 'ack' && f.for === 'set_model', 'picker set_model acked');
+    let after = h.node(child);
+    assert.equal(after.launch?.modelProviderPinned, true, 'the omitted-pinned frame derives pinned from the real openai-codex registry namespace');
+    // `cycle_ladder` — an internal no-raw-token path (no `model`/`pinned` on the
+    // frame at all) — reuses the SAME resolve+setModel machinery `set_model` does
+    // (real `nextLadderModel`/`resolveModelQuery`, the fake engine's real
+    // `session.setModel`), unlike `cycle_model` which the fake engine's session
+    // does not implement. `broadcastModelChanged()` is called here with no
+    // override, so the existing pin must survive verbatim.
+    ctrl.send({ type: 'cycle_ladder', direction: 'forward' });
+    await ctrl.waitFrame((f) => f.type === 'ack' && f.for === 'cycle_ladder', 'cycle_ladder acked');
+    after = h.node(child);
+    assert.equal(after.launch?.modelProviderPinned, true, 'an internal no-raw-token change (cycle_ladder) preserves the existing pin verbatim');
+    ctrl.close();
+});

package/dist/core/__tests__/full/cascade-close.test.d.ts

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