@north-light/crouter 0.3.301 → 0.3.303

package/dist/commands/memory/__tests__/command-selector-and-mutation-guards.test.js

@@ -14,7 +14,7 @@
 // Run: node --conditions=crtr-src --import tsx/esm --test --test-concurrency=4 --test-timeout=10000 src/commands/memory/__tests__/command-selector-and-mutation-guards.test.ts
 import { test, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { resetScopeCache } from '../../../core/scope.js';
@@ -23,6 +23,7 @@ import { createProfile, profileMemoryDir } from '../../../core/profiles/manifest
 import { openProjectMemoryStore } from '../../../core/memory-resolver.js';
 import { appendHistoryRecord, buildHistoryRecord, readHistoryRecords } from '../../../core/memory/history.js';
 import { CrtrError } from '../../../core/errors.js';
+import { gitSync } from '../../../core/git.js';
 import { deleteLeaf } from '../delete.js';
 import { editLeaf } from '../edit.js';
 import { historyLeaf } from '../history.js';
@@ -319,6 +320,34 @@ test('a targeted read suppresses malformed descendant-store warnings', async ()
     }
     assert.equal(writes.some((line) => line.includes('memory store not mounted')), false, writes.join(''));
 });
+test('a truncated nested-store read reports that its corpus was incomplete', async () => {
+    assert.equal(gitSync(['init', '-q'], root).status, 0, 'fixture repository initializes');
+    const fakeBin = join(base, 'slow-git');
+    mkdirSync(fakeBin);
+    const originalPath = process.env['PATH'] ?? '';
+    const fakeGit = join(fakeBin, 'git');
+    writeFileSync(fakeGit, `#!/bin/sh\nfor arg in "$@"; do\n  if [ "$arg" = "ls-files" ]; then sleep 1; exit 0; fi\ndone\nPATH=${JSON.stringify(originalPath)}\nexport PATH\nexec git "$@"\n`, 'utf8');
+    chmodSync(fakeGit, 0o755);
+    process.chdir(root);
+    resetScopeCache();
+    const stderr = process.stderr;
+    const originalWrite = stderr.write;
+    const writes = [];
+    stderr.write = ((chunk) => {
+        writes.push(String(chunk));
+        return true;
+    });
+    process.env['PATH'] = `${fakeBin}:${originalPath}`;
+    try {
+        const error = await thrownByAsync(() => readLeaf.run({ name: 'acme/child/foo', kind: undefined, frontmatter: false, scope: undefined, dir: undefined }));
+        assert.equal(error.code, 'not_found');
+    }
+    finally {
+        process.env['PATH'] = originalPath;
+        stderr.write = originalWrite;
+    }
+    assert.match(writes.join(''), /nested-store discovery.*result may omit nested stores.*--dir <owner>/s, `a timed-out scan must tell a failed read how to bypass discovery; got:\n${writes.join('')}`);
+});
 test('deleted history points at the revision holding the retained text, never a read that cannot answer', async () => {
     await deleteLeaf.run({ name: 'acme/disposable', dir: root });
     const result = (await historyLeaf.run({ name: 'acme/disposable', dir: root }));

package/dist/commands/memory/read.js

@@ -1,10 +1,9 @@
 import { envNodeId } from '../../shared/env.js';
 import { CrtrClient } from '../../api/index.js';
 import { defineLeaf } from '../../core/command.js';
-import { CrtrError } from '../../core/errors.js';
 import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
-import { ambientMemoryTarget, createMemoryDocSnapshot, listAllMemoryDocs, loadMemoryStoreView, readMemoryDocContent, resolveMemoryCandidates, resolveMemoryDocs, } from '../../core/memory-resolver.js';
+import { ambientMemoryTarget, createMemoryDocSnapshot, listAllMemoryDocs, loadMemoryStoreView, loadMemoryTargetView, readMemoryDocContent, resolveMemoryDocs, } from '../../core/memory-resolver.js';
 import { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../core/runtime/shell-expansion.js';
 import { emptyContextExposureState, exposureTarget, loadContextExposureState, registerDocumentExposure, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
 import { dirDedupKey, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
@@ -121,18 +120,17 @@ export const readLeaf = defineLeaf({
                 ...(selector.scope === undefined ? {} : { scope: selector.scope }),
                 includeDescendants: true,
             };
-            // A named read must not turn malformed stores elsewhere in the corpus
-            // into warnings about the requested document. `memory lint` owns that
-            // corpus health report; resolution still includes every candidate.
-            listingByName = linkByName = docsByName(listAllMemoryDocs(selector.scope, true, true));
-            try {
-                set = resolveMemoryCandidates(nameRaw, resolveOpts);
-            }
-            catch (e) {
-                if (!(e instanceof CrtrError && e.code === 'not_found'))
-                    throw e;
-            }
-            fail = () => resolveMemoryCandidates(nameRaw, resolveOpts);
+            // A named read keeps unrelated malformed documents quiet, but a timed
+            // discovery leaves its corpus incomplete and must remain visible before
+            // this branch can report not_found.
+            const view = loadMemoryTargetView(ambientMemoryTarget(), {
+                ...resolveOpts,
+                quiet: true,
+                reportDiscovery: true,
+            });
+            listingByName = linkByName = docsByName(view.docs);
+            set = view.candidates(nameRaw, kindOpts);
+            fail = () => view.resolve(nameRaw, kindOpts);
         }
         const nodeId = envNodeId() || undefined;
         if (set === null) {

package/dist/commands/node/lifecycle.js

@@ -71,11 +71,11 @@ const nodeRecycle = defineLeaf({
 // node lifecycle close — close a node + cascade-cancel its exclusive subtree (Alt+C → x)
 const nodeClose = defineLeaf({
     name: 'close',
-    description: 'close a node + cascade-cancel its exclusive subtree (revivable)',
-    whenToUse: 'you want to tear a node down WITHOUT finishing it, cascade-cancelling every descendant it exclusively owns: abandoning a line of work, killing a stuck or wrong-turn subtree, clearing a branch you no longer need. Windows die but nothing is deleted — each closed node keeps its pi session and can be revived later (`node lifecycle revive`). Use `node lifecycle recycle` instead to FINISH the agent in your pane with a final report, and `push final` when a worker should end its own work normally (Alt+C → x)',
+    description: 'close a node + cascade-cancel its exclusive subtree',
+    whenToUse: 'you want to tear a node down WITHOUT finishing it, cascade-cancelling every descendant it exclusively owns: abandoning a line of work, killing a stuck or wrong-turn subtree, clearing a branch you no longer need. A node that never produced substantive assistant output is deleted and cannot be revived; streaming nodes and nodes with an open managed worktree are retained. Other closed nodes keep their pi session and can be revived later (`node lifecycle revive`). Use `node lifecycle recycle` instead to FINISH the agent in your pane with a final report, and `push final` when a worker should end its own work normally (Alt+C → x)',
     help: {
         name: 'node lifecycle close',
-        summary: 'close a node and cascade-cancel its subtree — kill its tmux window plus those of every descendant it EXCLUSIVELY owns (down the subscribes_to spine), mark them all canceled, and leave each a notice it reads on resume. A descendant still subscribed to by a manager outside the subtree is left running. Nothing is deleted: every closed node keeps its pi session and can be revived later (`crtr node lifecycle revive`)',
+        summary: 'close a node and cascade-cancel its subtree — kill its tmux window plus those of every descendant it EXCLUSIVELY owns (down the subscribes_to spine), mark retained nodes canceled, and leave them a notice they read on resume. A descendant still subscribed to by a manager outside the subtree is left running. A node that never produced substantive assistant output is deleted and cannot be revived; streaming nodes and nodes with an open managed worktree are retained. Other closed nodes keep their pi session and can be revived later (`crtr node lifecycle revive`)',
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to close. Defaults to the node occupying --pane (or your current pane).' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to close. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
@@ -88,9 +88,10 @@ const nodeClose = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Marks the node and its exclusive descendants `canceled` and clears intent (the daemon never revives a canceled node).',
-            'Kills each closed node\'s tmux window; their pi sessions and canvas edges persist for a later revive.',
-            'Appends a cancellation notice to each closed node\'s inbox, surfaced on its next resume.',
+            'Marks retained nodes and their exclusive descendants `canceled` and clears intent (the daemon never revives a canceled node).',
+            'Deletes a non-streaming node with no substantive assistant output unless it has an open managed worktree; a deleted node cannot be revived.',
+            'Kills each closed node\'s tmux window; retained nodes keep their pi sessions and canvas edges for a later revive.',
+            'Appends a cancellation notice to each retained node\'s inbox, surfaced on its next resume.',
         ],
     },
     run: async (input) => {

package/dist/commands/push.js

@@ -160,8 +160,8 @@ function makePushLeaf(kind) {
                 ...(kind === 'final'
                     ? [
                         { name: 'transitioned', type: 'object', required: false, constraint: 'Present only for a final that flipped the node — { from, to } lifecycle-status transition applied server-side.' },
-                        { name: 'worktree_auto_dropped', type: 'boolean', required: false, constraint: 'Present only when this node owned a managed worktree with zero commits ahead of its base and no uncommitted changes — the server auto-dropped it instead of requiring `node worktree close` first (see worktree_auto_dropped_path).' },
-                        { name: 'worktree_auto_dropped_path', type: 'string', required: false, constraint: 'Present only alongside worktree_auto_dropped: the checkout path that was dropped.' },
+                        { name: 'worktree_auto_dropped', type: 'boolean', required: false, constraint: 'Present only when the server closed this node’s managed-worktree record without requiring `node worktree close`; cleanup of an existing checkout remains pending (see worktree_auto_dropped_path).' },
+                        { name: 'worktree_auto_dropped_path', type: 'string', required: false, constraint: 'Present only alongside worktree_auto_dropped: the closed worktree path; an existing checkout remains until pending cleanup.' },
                     ]
                     : []),
             ],
@@ -172,7 +172,7 @@ function makePushLeaf(kind) {
                 ...(kind === 'final'
                     ? [
                         'Marks the node done (status + intent) server-side; its engine shuts down on next stop.',
-                        'When this node owns a clean managed worktree already contained in its local base, the server auto-drops it instead of blocking on `node worktree close`. A clean worktree whose exact tip exists on any branch on origin may also finalize while retaining its branch and checkout; uncommitted changes or a tip absent from origin still block with open_managed_worktree.',
+                        'When this node owns a clean managed worktree already contained in its local base, the server closes its record with cleanup pending instead of blocking on `node worktree close`. A clean worktree whose exact tip exists on any branch on origin may also finalize while retaining its branch and checkout; uncommitted changes or a tip absent from origin still block with open_managed_worktree.',
                     ]
                     : []),
             ],
@@ -242,7 +242,7 @@ function makePushLeaf(kind) {
             const line = kind === 'final'
                 ? 'Result recorded — node finished; its engine shuts down on next stop. Nothing more to do here: STOP your turn immediately. Reply with just "Done." and nothing else.'
                 : `Progress report fanned to ${n} subscriber(s).`;
-            const dropNote = r['worktree_auto_dropped'] === true ? `\n\nAuto-dropped a clean, zero-commit managed worktree at ${String(r['worktree_auto_dropped_path'])} — nothing to land.` : '';
+            const dropNote = r['worktree_auto_dropped'] === true ? `\n\nClosed a clean managed-worktree record at ${String(r['worktree_auto_dropped_path'])} — nothing to land; cleanup remains pending if the checkout still exists.` : '';
             return `${line}\n\n- report: ${r['report_path']}${dropNote}`;
         },
     });

package/dist/core/__tests__/bash-guard.test.d.ts

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

package/dist/core/__tests__/bash-guard.test.js

@@ -0,0 +1,190 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/bash-guard.test.ts
+//
+// BUG REGRESSION: a node ran
+//   cd star-theory-2 && HOME="$(mktemp -d …)" godot …; rm -rf "$HOME" …
+// The `HOME=` prefix applied only to `godot`, so the trailing `rm -rf "$HOME"`
+// expanded to the real home directory and deleted for ~108s before another node
+// killed it. The guard refuses that command text before bash ever sees it.
+import assert from 'node:assert/strict';
+import { homedir, userInfo } from 'node:os';
+import { test } from 'node:test';
+import { bashCommandRefusal } from '../bash-guard.js';
+const HOME = homedir();
+const CWD = `${HOME}/Code/cli/crouter`;
+function refusal(command, cwd = CWD) {
+    return bashCommandRefusal(command, cwd);
+}
+function assertRefused(command, expectedTarget, cwd = CWD) {
+    const message = refusal(command, cwd);
+    assert.notEqual(message, null, `expected refusal for: ${command}`);
+    assert.ok(message.includes(expectedTarget), `refusal for ${command} should name ${expectedTarget}, got: ${message}`);
+}
+function assertAllowed(command, cwd = CWD) {
+    assert.equal(refusal(command, cwd), null, `expected to allow: ${command}`);
+}
+// The incident
+test('the incident command is refused and names the segment and resolved target', () => {
+    const command = 'cd star-theory-2 && HOME="$(mktemp -d /tmp/st2-legend-proof.XXXXXX)" godot --headless --path . ' +
+        '--script "$CRTR_CONTEXT_DIR/legend_proof.gd"; status=$?; rm -rf "$HOME" 2>/dev/null || true; exit $status';
+    const message = refusal(command);
+    assert.notEqual(message, null);
+    assert.ok(message.includes('rm -rf "$HOME"'), `should quote the offending segment: ${message}`);
+    assert.ok(message.includes(HOME), `should name the resolved target: ${message}`);
+});
+// Home, however it is spelled
+test('every textual spelling of the home directory is refused', () => {
+    for (const target of ['~', '~/', '"$HOME"', '$HOME', '${HOME}', '"${HOME}/"', HOME, `${HOME}/`, '~/*', '"$HOME"/*']) {
+        assertRefused(`rm -rf ${target}`, HOME);
+    }
+});
+// System roots
+test('system roots are refused', () => {
+    for (const target of ['/', '/Users', '/home', '/private', '/var', '/etc', '/tmp', '/usr', '/opt', '/System', '/Library', '/Applications', '/private/var']) {
+        assertRefused(`rm -rf ${target}`, target);
+    }
+});
+test('the canvas home is refused', () => {
+    assertRefused('rm -rf ~/.crouter', `${HOME}/.crouter`);
+});
+// Ancestors of the working directory
+test('a strict ancestor of the working directory is refused', () => {
+    assertRefused(`rm -rf ${HOME}/Code/cli`, `${HOME}/Code/cli`);
+    assertRefused('rm -rf ..', `${HOME}/Code/cli`);
+});
+test('a relative target is read against every directory the line could be in', () => {
+    assertRefused('cd packages && rm -rf ../..', `${HOME}/Code/cli`);
+    // The guard cannot know a `cd` succeeded: after a failed one bash stays put,
+    // so `..` really is the ancestor and the refusal must still fire.
+    assertRefused('cd definitely-does-not-exist; rm -rf ..', `${HOME}/Code/cli`);
+    // Nowhere knowable to resolve from, so nothing relative is refused.
+    assertAllowed('cd "$SOMEWHERE" && rm -rf ..');
+    assertRefused('cd "$SOMEWHERE" && rm -rf ~', HOME);
+});
+test('the working directory itself still removes — a node may delete its own merged worktree', () => {
+    const worktree = `${HOME}/.crouter/canvas/worktrees/node-1`;
+    assertAllowed('rm -rf .', worktree);
+    assertAllowed(`rm -rf ${worktree}`, worktree);
+});
+// Recursive flag spellings
+test('every recursive flag spelling is refused', () => {
+    for (const flags of ['-rf', '-fr', '-r', '-R', '-Rf', '-rvf', '--recursive -f', '-f --recursive', '-f -r', '-r --', '-rf --']) {
+        assertRefused(`rm ${flags} ~`, HOME);
+    }
+});
+test('a non-recursive rm is not this guard\u2019s business', () => {
+    assertAllowed('rm ~');
+    assertAllowed('rm -f ~/.zshrc');
+});
+// Prefixes that hide the verb
+test('a command prefix does not hide the rm', () => {
+    for (const prefix of ['sudo', 'sudo -E', 'command', 'nice -n 10', 'nohup', 'time', 'env', 'doas']) {
+        assertRefused(`${prefix} rm -rf ~`, HOME);
+    }
+});
+test('a leading VAR=value assignment does not hide the rm', () => {
+    assertRefused('FOO=bar rm -rf ~', HOME);
+});
+// The distinction the incident turned on: an `export` changes $HOME for the
+// rest of the line, a `HOME=… cmd` PREFIX changes it for that one command.
+test('a reassigned HOME is honoured for the rest of the line', () => {
+    assertAllowed('export HOME=/tmp/st2home_5e && rm -rf "$HOME"');
+    assertAllowed('export HOME=/tmp/st2home_5e\nfind "$HOME" -name settings.cfg -delete');
+    assertAllowed('cd star-theory-2 && export HOME=/tmp/x && rm -rf "$HOME" && mkdir -p "$HOME"');
+    assertAllowed('HOME=/tmp/x\nrm -rf ~');
+    // Reassigned to something the guard cannot read: unknowable, so allowed.
+    assertAllowed('export HOME="$(mktemp -d)"; rm -rf "$HOME"');
+});
+test('a HOME= prefix on one command does not carry to the next', () => {
+    assertRefused('HOME=/tmp/x godot --headless; rm -rf "$HOME"', HOME);
+});
+test('a HOME= prefix does apply to its own command', () => {
+    assertAllowed('HOME=/tmp/x rm -rf "$HOME"');
+});
+test('a backgrounded assignment runs in a subshell and does not carry', () => {
+    assertRefused('HOME=/tmp/x & rm -rf "$HOME"', HOME);
+    assertRefused('export HOME=/tmp/x & rm -rf "$HOME"', HOME);
+    assertAllowed('export HOME=/tmp/x && rm -rf "$HOME"');
+});
+test('an assignment to a builtin that exports it persists', () => {
+    assertAllowed('HOME=/tmp/x export HOME; rm -rf "$HOME"');
+});
+test('$USER and $LOGNAME expand — a per-user path spelled that way still resolves', () => {
+    // Anchored on the working directory rather than the home path, whose per-user
+    // segment is not the username on every platform this runs on.
+    const user = userInfo().username;
+    const parent = `/srv/people/${user}`;
+    assertRefused('rm -rf /srv/people/$USER', parent, `${parent}/project`);
+    assertRefused('rm -rf "/srv/people/${LOGNAME}"', parent, `${parent}/project`);
+});
+test('a redirection is not a target', () => {
+    assertAllowed('rm -rf ./dist 2>/dev/null');
+    assertAllowed('rm -rf ./dist > /dev/null 2>&1');
+    assertRefused('rm -rf ~ 2>/dev/null', HOME);
+});
+// Segment separators
+test('the rm is found in any shell segment', () => {
+    for (const command of ['ls && rm -rf ~', 'ls; rm -rf ~', 'ls || rm -rf ~', 'ls | rm -rf ~', 'ls &\nrm -rf ~']) {
+        assertRefused(command, HOME);
+    }
+});
+// Must still run
+test('ordinary removals still run', () => {
+    assertAllowed('rm -rf "$d"');
+    assertAllowed('rm -rf node_modules');
+    assertAllowed('rm -rf /tmp/foo.XXXX');
+    assertAllowed('rm -rf "$CRTR_CONTEXT_DIR/jobs/x"');
+    assertAllowed('rm -rf ~/Code/cli/crouter/dist');
+    assertAllowed('rm -rf ./dist .dist-build-*');
+    assertAllowed('rm -rf "$HOME/.cache/crouter/termrender"');
+    assertAllowed('rm -rf ~/.crouter/canvas/scratch/old');
+    assertAllowed('rm -rf /tmp/crtr-build.1234');
+});
+test('a quoted mention of a dangerous command is data, not a command', () => {
+    assertAllowed('echo "rm -rf ~"');
+    assertAllowed("git commit -m 'never rm -rf $HOME'");
+});
+test('a heredoc body is data, not a command', () => {
+    assertAllowed('cat > note.md <<\'EOF\'\nrm -rf ~\nEOF');
+});
+// Other operations that can destroy a home or system tree
+test('moving a protected path away is refused', () => {
+    assertRefused('mv ~ /tmp/old-home', HOME);
+    assertRefused('mv /etc /tmp/etc', '/etc');
+});
+test('a recursive permission or ownership change on a protected path is refused', () => {
+    assertRefused('chmod -R 777 /', '/');
+    assertRefused('sudo chown -R root ~', HOME);
+    assertRefused('chgrp -R staff /usr', '/usr');
+    assertAllowed('chmod -R 755 ./scripts');
+    assertAllowed('chmod 600 ~/.ssh/config');
+});
+test('a find that deletes or executes over a protected path is refused', () => {
+    assertRefused('find ~ -name "*.log" -delete', HOME);
+    assertRefused('find / -name core -exec rm -f {} \\;', '/');
+    assertAllowed('find ~ -name "*.log"');
+    assertAllowed('find . -name "*.log" -delete');
+});
+test('find’s leading global options do not hide its start path', () => {
+    assertRefused('find -H ~ -delete', HOME);
+    assertRefused('find -- ~ -delete', HOME);
+    assertRefused('find -L -x /etc -delete', '/etc');
+    assertRefused('find -f ~ -delete', HOME);
+    assertAllowed('find -H ./logs -delete');
+});
+test('writing a raw disk or reformatting one is refused', () => {
+    assertRefused('dd if=/dev/zero of=/dev/disk0 bs=1m', '/dev/disk0');
+    assertRefused('dd if=/dev/zero of=/dev/rdisk3 bs=1m', '/dev/rdisk3');
+    assertRefused('sudo mkfs.ext4 /dev/sda1', 'mkfs.ext4');
+    assertRefused('diskutil eraseDisk JHFS+ Blank /dev/disk2', 'diskutil eraseDisk');
+    assertAllowed('dd if=/dev/zero of=./blob bs=1m count=1');
+    // A character device is ordinary output, not a disk.
+    assertAllowed('dd if=/dev/zero of=/dev/null bs=1m count=1');
+    assertAllowed('dd if=./blob of=/dev/stdout');
+});
+// The long-sleep refusal moved here with the rest of the bash refusals.
+test('a long leading sleep is still refused, a short one still runs', () => {
+    assert.notEqual(refusal('sleep 300'), null);
+    assert.notEqual(refusal('sleep 5m'), null);
+    assert.equal(refusal('sleep 5'), null);
+    assert.equal(refusal('sleep "$n"'), null);
+});

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -148,6 +148,7 @@ declare class FakeSession {
     /** Compiled-seam graceful-teardown vehicle: a real active turn that only settles
      * after abort(), so the broker's bounded abort wait is observable. */
     private heldTurn;
+    private retryAbort;
     private readonly listeners;
     /** Idle watcher sends received while bindExtensions is still running. They
      * start naturally as soon as broker.ts subscribes, without a retry loop that
@@ -195,6 +196,9 @@ declare class FakeSession {
     };
     get isStreaming(): boolean;
     getSessionStats(): Record<string, unknown>;
+    getContextUsage(): {
+        tokens: number;
+    } | undefined;
     private syncTreeSnapshot;
     /** Reads the crashed process's last `fake-pi.tree.json` (if any) and rebuilds
      *  this process's tree from it. Best-effort: a first boot (no snapshot yet)
@@ -238,6 +242,7 @@ declare class FakeSession {
         deliverAs?: string;
     }): Promise<void>;
     abort(): Promise<void>;
+    abortRetry(): void;
     /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
      *  contract: the session file is unchanged, the live history is truncated,
      *  and the navigated-to user message's text comes back as `editorText`. The
@@ -274,6 +279,7 @@ interface FakeModel {
     provider: string;
     id: string;
     api?: string;
+    contextWindow?: number;
 }
 /** The fake `ModelRuntime` — the runtime-method subset broker.ts's
  *  `registryOf` facade (and its model-less construction mask) actually reads. */

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -298,6 +298,7 @@ class FakeSession {
     /** Compiled-seam graceful-teardown vehicle: a real active turn that only settles
      * after abort(), so the broker's bounded abort wait is observable. */
     heldTurn;
+    retryAbort;
     // The broker's fan-out subscribers (broker.ts `session.subscribe(...)`) and the
     // accumulating message history the catch-up snapshot serializes (G3).
     listeners = new Set();
@@ -458,6 +459,15 @@ class FakeSession {
     getSessionStats() {
         return { messages: 0, tokens: 0 };
     }
+    getContextUsage() {
+        try {
+            const tokens = Number(readFileSync(join(this.dir, 'fake-pi.context-tokens'), 'utf8'));
+            return Number.isFinite(tokens) ? { tokens } : undefined;
+        }
+        catch {
+            return { tokens: 1000 };
+        }
+    }
     syncTreeSnapshot() {
         try {
             writeFileSync(join(this.dir, 'fake-pi.tree.json'), JSON.stringify({
@@ -571,6 +581,9 @@ class FakeSession {
         this.bashAbort?.abort();
         return this.bashRun ?? Promise.resolve();
     }
+    abortRetry() {
+        this.retryAbort?.();
+    }
     /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
      *  contract: the session file is unchanged, the live history is truncated,
      *  and the navigated-to user message's text comes back as `editorText`. The
@@ -938,7 +951,7 @@ class FakeSession {
                 getBranch: () => this.tree.getBranch(),
                 getEntries: () => this.tree.getEntries(),
             },
-            getContextUsage: () => ({ tokens: 1000 }),
+            getContextUsage: () => this.getContextUsage(),
             // Wired to the broker's shutdownHandler: the stophook calls ctx.shutdown()
             // in exactly its done / idle-release / refresh branches → disposeAndExit.
             shutdown: () => {
@@ -1068,8 +1081,9 @@ class FakeSession {
                 this.emit({ type: 'agent_settled' });
                 break;
             case 'stop': {
-                // Match pi's lifecycle: the stophook sees agent_end while the run is
-                // active, then the subscriber receives agent_settled after it clears.
+                // Match pi's lifecycle: message_end reaches broker fallback policy
+                // before the stophook sees agent_end while the run is active; the
+                // subscriber receives agent_settled after it clears.
                 this.streaming = true;
                 const stopMessages = [
                     {
@@ -1097,6 +1111,7 @@ class FakeSession {
                         content: [{ type: 'text', text: cmd.text ?? '' }],
                     },
                 ];
+                this.emit({ type: 'message_end', message: stopMessages[0] });
                 await this.fire('agent_end', { messages: stopMessages }, ctx);
                 // Every attempt reaches the broker subscriber while streaming; only the
                 // following settled event may publish its fault or arm a retry timer.
@@ -1174,16 +1189,29 @@ class FakeSession {
                 writeFileSync(join(this.dir, 'fake-pi.overflow.json'), JSON.stringify({ outcome: cmd.outcome ?? 'uncompacted' }));
                 break;
             }
-            case 'auto_retry':
-                // Drive the exact broker subscription event that pi emits before its
-                // retry timer, so provider fallback policy runs in the live broker.
+            case 'auto_retry': {
+                // Pi emits agent_end for the failed attempt, then auto_retry_start, and
+                // only then creates the AbortController for its delay. The capacity
+                // fallback must defer abortRetry one microtask to cancel this retry.
+                const retryMessages = [{
+                        role: 'assistant', stopReason: 'error', errorMessage: cmd.errorMessage ?? 'rate limit exceeded', content: [],
+                    }];
+                this.streaming = true;
+                await this.fire('agent_end', { messages: retryMessages }, ctx);
+                this.emit({ type: 'agent_end', messages: retryMessages, willRetry: true });
                 this.emit({ type: 'auto_retry_start', errorMessage: cmd.errorMessage ?? 'rate limit exceeded' });
-                // The broker begins its fallback async; the next check phase follows
-                // its resolved registry/setModel microtasks and is a deterministic
-                // receipt for a rejected target (which intentionally never changes model).
+                let aborted = false;
+                this.retryAbort = () => { aborted = true; };
                 await new Promise((resolve) => setImmediate(resolve));
-                writeFileSync(join(this.dir, 'fake-pi.auto-retry.json'), JSON.stringify({ at: Date.now() }));
+                this.retryAbort = undefined;
+                if (aborted)
+                    this.emit({ type: 'auto_retry_end', success: false, finalError: 'Retry cancelled' });
+                this.streaming = false;
+                await this.fire('agent_settled', { type: 'agent_settled' }, ctx);
+                this.emit({ type: 'agent_settled' });
+                writeFileSync(join(this.dir, 'fake-pi.auto-retry.json'), JSON.stringify({ at: Date.now(), aborted }));
                 break;
+            }
             case 'display':
                 // Paint through the broker's REAL uiContext exactly as an extension does.
                 // These are LEVELS with no pi getter, so the broker is their only holder
@@ -1221,6 +1249,18 @@ class FakeSession {
         }
     }
 }
+function fakeModel(provider, id) {
+    try {
+        const capacities = JSON.parse(readFileSync(join(nodeDirFromEnv(), 'fake-pi.model-capacities.json'), 'utf8'));
+        const contextWindow = capacities[`${provider}/${id}`];
+        return typeof contextWindow === 'number' && Number.isFinite(contextWindow)
+            ? { provider, id, contextWindow }
+            : { provider, id };
+    }
+    catch {
+        return { provider, id };
+    }
+}
 /** The real pi SDK's model-less sentinel (Agent.DEFAULT_MODEL). The fake mirrors
  *  it so `session.model` is NEVER literally `undefined` after a model-less boot,
  *  matching prod — see the FakeSession constructor. */
@@ -1292,7 +1332,7 @@ export async function createAgentSessionServices(options) {
             // A minimal model stub for any spec — the set_model regression test drives
             // the broker's findModelSpec → session.setModel path through it. Nothing is
             // findable during a zero-auth window.
-            getModel: (provider, id) => (zeroAuth() ? undefined : { provider, id }),
+            getModel: (provider, id) => (zeroAuth() ? undefined : fakeModel(provider, id)),
             // Always-authenticated single fake model — the M-9 no-boot-model branch
             // (broker.ts) picks `available[0]` and must never see an empty list here —
             // EXCEPT during a zero-auth window, when nothing is available/registered.

package/dist/core/__tests__/integration/revive.test.js

@@ -33,7 +33,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { createNode, deleteNode, getNode, subscribe, updateNode } from '../../canvas/canvas.js';
-import { armCron, hasPendingCancelOnWakeCron } from '../../canvas/crons.js';
+import { armCron, getCron } from '../../canvas/crons.js';
 import { readInboxSince } from '../../feed/inbox.js';
 import { closeDb } from '../../canvas/db.js';
 import { apiSocketPath } from '../../canvas/paths.js';
@@ -304,11 +304,11 @@ test('a recovery relaunch keeps the armed deadline; a wake revive consumes it',
         const recovered = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-1' });
         armDeadline(recovered, 'cron-recovery');
         await reviveNode(recovered, { resume: true, recovery: true, capacity: 'freeze' });
-        assert.equal(hasPendingCancelOnWakeCron(recovered), true, 'the daemon replacing a dead broker is not a wake — the deadline survives so the wait can still settle');
+        assert.equal(getCron('cron-recovery') !== null, true, 'the daemon replacing a dead broker is not a wake — the deadline survives so the wait can still settle');
         const woken = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-2' });
         armDeadline(woken, 'cron-wake');
         await reviveNode(woken, { resume: true, capacity: 'freeze' });
-        assert.equal(hasPendingCancelOnWakeCron(woken), false, 'a wake revive won the race and cancels the deadline');
+        assert.equal(getCron('cron-wake'), null, 'a wake revive won the race and cancels the deadline');
     }
     finally {
         await h.dispose();

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

@@ -43,6 +43,33 @@ function seedPool(provider, cooling) {
             rateLimitedUntil: cooling ? Date.now() + 60_000 : 0, lastAttemptAt: 0, lastRateLimitedAt: 0,
         }]));
 }
+function modelRoute(spec) {
+    return { ultra: spec, strong: spec, medium: spec, light: spec };
+}
+function seedCapacityFallbackRoutes() {
+    const userConfigDir = join(h.agentHome, '.crouter');
+    const userConfigPath = join(userConfigDir, 'config.json');
+    mkdirSync(userConfigDir, { recursive: true });
+    writeFileSync(userConfigPath, JSON.stringify({
+        kinds: { 'test/capacity-fallback': { whenToUse: 'Capacity fallback regression.', model: 'anthropic/medium' } },
+        modelRoutes: {
+            primary: { family: 'anthropic', credentialSource: 'user', providerId: 'fake-primary', models: modelRoute('fake-primary/primary') },
+            fallback: { family: 'anthropic', credentialSource: 'northlight', providerId: 'fake-small', models: modelRoute('fake-small/small') },
+            largerFallback: { family: 'anthropic', credentialSource: 'third', providerId: 'fake-large', models: modelRoute('fake-large/large') },
+        },
+        modelRouting: { credentialSourceOrder: ['user', 'northlight', 'third'], familyOrder: ['anthropic'], strengthFallback: ['medium'] },
+    }));
+    return userConfigPath;
+}
+function seedCapacityFixture(id, largeContextWindow = 999) {
+    const dir = join(h.home, 'nodes', id);
+    writeFileSync(join(dir, 'fake-pi.context-tokens'), '1000');
+    writeFileSync(join(dir, 'fake-pi.model-capacities.json'), JSON.stringify({
+        'fake-primary/primary': 2000,
+        'fake-small/small': 999,
+        'fake-large/large': largeContextWindow,
+    }));
+}
 // The node's recorded model (fake-pi.model.json, written by the fake's
 // recordModel) — `null` for a model-less boot. A disk read, so it survives the
 // broker exiting after its kickoff turn idle-releases.
@@ -395,6 +422,36 @@ test('a recovered compact-and-retry commits nothing, while a definitive failure
     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('provider-retry and model-not-found fallback both terminate when every available target has a smaller known context window', { timeout: 30_000 }, async () => {
+    const userConfigPath = seedCapacityFallbackRoutes();
+    try {
+        const parent = h.spawnRoot('capacity fallback parent');
+        const providerRetry = await h.spawnHeadlessChild(parent, 'provider retry capacity fallback', { kind: 'test/capacity-fallback' });
+        await h.waitFor(() => agentStartCount(providerRetry) >= 1, { label: 'provider retry capacity fixture started' });
+        seedCapacityFixture(providerRetry, 2000);
+        h.fakeCmd(providerRetry, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
+        await h.waitFor(() => model(providerRetry)?.provider === 'fake-large' ? true : null, { label: 'provider retry skips the too-small target for the large enough target' });
+        assert.equal(model(providerRetry).provider, 'fake-large', 'a large enough fallback remains eligible after the smaller route is rejected');
+        const exhaustedProviderRetry = await h.spawnHeadlessChild(parent, 'exhausted provider retry capacity fallback', { kind: 'test/capacity-fallback' });
+        await h.waitFor(() => agentStartCount(exhaustedProviderRetry) >= 1, { label: 'exhausted provider retry capacity fixture started' });
+        seedCapacityFixture(exhaustedProviderRetry);
+        h.fakeCmd(exhaustedProviderRetry, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
+        const providerRetryFault = await h.waitFor(() => readFault(exhaustedProviderRetry)?.kind === 'context-overflow' ? readFault(exhaustedProviderRetry) : null, { label: 'provider retry rejects every too-small fallback target' });
+        assert.equal(providerRetryFault.retry.disposition, 'fatal', 'all known-too-small provider retry targets produce a fatal context-overflow fault');
+        assert.match(providerRetryFault.message, /1000 tokens/, 'the terminal fault identifies the current conversation size');
+        assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', exhaustedProviderRetry, 'fake-pi.auto-retry.json'), 'utf8')).aborted, true, 'the retry delay is cancelled after Pi creates its retry controller');
+        const modelNotFound = await h.spawnHeadlessChild(parent, 'model-not-found capacity fallback', { kind: 'test/capacity-fallback' });
+        await h.waitFor(() => agentStartCount(modelNotFound) >= 1, { label: 'model-not-found capacity fixture started' });
+        seedCapacityFixture(modelNotFound);
+        h.fakeCmd(modelNotFound, { cmd: 'stop', reason: 'error', errorMessage: 'Model not found' });
+        const modelNotFoundFault = await h.waitFor(() => readFault(modelNotFound)?.kind === 'context-overflow' ? readFault(modelNotFound) : null, { label: 'model-not-found rejects the too-small fallback target' });
+        assert.equal(modelNotFoundFault.retry.disposition, 'fatal', 'all known-too-small model-not-found targets produce a fatal context-overflow fault');
+        assert.match(modelNotFoundFault.message, /1000 tokens/, 'the terminal fault survives ordinary settlement staging');
+    }
+    finally {
+        rmSync(userConfigPath, { force: true });
+    }
+});
 // Two real logical launches keep both user paths non-vacuous: the picker first
 // proves an explicit concrete choice pins and clears routing, while Alt+M runs
 // directly against still-present logical intent before Shift+Tab and replay.