@north-light/crouter 0.3.302 → 0.3.304

package/dist/core/__tests__/integration/worktree-land.test.js

@@ -10,6 +10,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { gitSync } from '../../git.js';
 import { createManagedWorktree, closeManagedWorktree, managedWorktreePath, rollbackManagedWorktree } from '../../worktree.js';
+import { closeManagedWorktreeAsync } from '../../worktree-close.js';
 import { reconcileManagedWorktree } from '../../worktree-sweep.js';
 import { createNode, getNode } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
@@ -223,6 +224,55 @@ test('closeManagedWorktree fast-forwards local main to the worktree tip without
     const originMainAfter = gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim();
     assert.equal(originMainAfter, originMainBefore, 'origin/main must not move — landing is local-only');
 });
+test('async close leaves an upstream-contained tip and a diverged local base byte-for-byte unchanged (#958)', async () => {
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-contained-close-'));
+    const remote = mkdtempSync(join(tmpdir(), 'crtr-worktree-contained-close-remote-'));
+    try {
+        run(['init', '-b', 'main'], repo);
+        run(['config', 'user.email', 'test@example.com'], repo);
+        run(['config', 'user.name', 'Test'], repo);
+        writeFileSync(join(repo, 'README.md'), 'initial\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'initial'], repo);
+        run(['init', '--bare'], remote);
+        run(['remote', 'add', 'origin', remote], repo);
+        run(['push', '-u', 'origin', 'main'], repo);
+        const nodeId = 'wt-contained-diverged-base';
+        const wt = createManagedWorktree(repo, nodeId);
+        createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+        writeFileSync(join(wt.path, 'delivered.txt'), 'already delivered\n');
+        run(['add', '.'], wt.path);
+        run(['commit', '-m', 'delivered work'], wt.path);
+        const deliveredHead = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+        run(['push', 'origin', `${wt.branch}:main`], wt.path);
+        run(['fetch', 'origin'], repo);
+        writeFileSync(join(repo, 'local-only.txt'), 'must not receive a replay\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'independent local base work'], repo);
+        const before = {
+            childHead: gitSync(['rev-parse', 'HEAD'], wt.path).stdout,
+            baseRef: gitSync(['rev-parse', 'refs/heads/main'], repo).stdout,
+            baseHead: gitSync(['rev-parse', 'HEAD'], repo).stdout,
+            status: gitSync(['status', '--porcelain=v1'], repo).stdout,
+            worktree: gitSync(['worktree', 'list', '--porcelain'], repo).stdout,
+            index: readFileSync(join(repo, '.git', 'index')),
+        };
+        const result = await closeManagedWorktreeAsync(nodeId);
+        assert.equal(result.landed_sha, deliveredHead);
+        assert.deepEqual({
+            childHead: gitSync(['rev-parse', 'HEAD'], wt.path).stdout,
+            baseRef: gitSync(['rev-parse', 'refs/heads/main'], repo).stdout,
+            baseHead: gitSync(['rev-parse', 'HEAD'], repo).stdout,
+            status: gitSync(['status', '--porcelain=v1'], repo).stdout,
+            worktree: gitSync(['worktree', 'list', '--porcelain'], repo).stdout,
+            index: readFileSync(join(repo, '.git', 'index')),
+        }, before, 'a delivered child must not rebase or move the divergent local base');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(remote, { recursive: true, force: true });
+    }
+});
 test('custom local base is recorded and fast-forwarded without touching main or origin', () => {
     const nodeId = 'wt-custom-base';
     run(['branch', 'feature/custom-base'], sourceDir);

package/dist/core/__tests__/integration/worktree-reap.test.js

@@ -4,20 +4,28 @@
 // (worktree-land.test.ts) only so the two run as two parallel files.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, existsSync, writeFileSync, chmodSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { mkdtempSync, mkdirSync, renameSync, rmSync, existsSync, writeFileSync, chmodSync, realpathSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { gitSync } from '../../git.js';
-import { createManagedWorktree, closeManagedWorktree } from '../../worktree.js';
+import { withExclusiveDirectoryLockAsync } from '../../exclusive-lock.js';
+import { createManagedWorktree, closeManagedWorktree, worktreeLockPathForCommonDir } from '../../worktree.js';
 import { reconcileManagedWorktree } from '../../worktree-sweep.js';
 import { createApiServer } from '../../../daemon/api/server.js';
+import { ManagedWorktreeSweepReconciler } from '../../../daemon/reconcilers/managed-worktree-sweep.js';
 import { apiSocketPath } from '../../canvas/paths.js';
-import { CrtrClient } from '../../../api/index.js';
+import { ApiError, CrtrClient } from '../../../api/index.js';
 import { createNode, getNode } from '../../canvas/canvas.js';
+import { headlessBrokerHost } from '../../runtime/host.js';
+import { reviveNode } from '../../runtime/revive.js';
+import { bindTestFleet } from '../helpers/fleet.js';
+import { resetFleetForTests } from '../../runtime/fleet.js';
 import { closeDb } from '../../canvas/db.js';
 let home;
 let remoteDir;
 let sourceDir;
+const scratchRoot = join(homedir(), '.crouter', 'canvas', 'scratch');
 function run(args, cwd) {
     const res = gitSync(args, cwd);
     if (res.status !== 0) {
@@ -42,7 +50,8 @@ before(() => {
     // `/var` → `/private/var` symlink, so the recorded managed-worktree path and
     // git's canonical `worktree list` output differ as strings while naming one
     // directory. Every path-ownership check must judge identity, not spelling.
-    home = mkdtempSync(join(tmpdir(), 'crtr-worktree-home-'));
+    mkdirSync(scratchRoot, { recursive: true });
+    home = mkdtempSync(join(scratchRoot, 'crtr-worktree-home-'));
     process.env['CRTR_HOME'] = home;
     // Bare "remote" wired up as origin so the test can prove landing NEVER pushes
     // to it (managed worktrees are based on and land onto local `main` only).
@@ -97,6 +106,104 @@ test('autoDropCleanManagedWorktree drops a clean, zero-commit worktree', async (
     const swept = getNode(nodeId)?.managed_worktree;
     assert.deepEqual({ state: swept?.state, cleanup: swept?.cleanup }, { state: 'closed', cleanup: 'complete' });
 });
+test('a dead managed child keeps its open checkout through the sweep and revives there (#962)', async () => {
+    const repo = mkdtempSync(join(scratchRoot, 'crtr-worktree-962-'));
+    const nodeId = 'wt-sweep-dead-open';
+    const originalLaunch = headlessBrokerHost.launch;
+    try {
+        run(['init', '-b', 'main'], repo);
+        run(['config', 'user.email', 'test@example.com'], repo);
+        run(['config', 'user.name', 'Test'], repo);
+        writeFileSync(join(repo, 'README.md'), 'hello\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'init'], repo);
+        const wt = createManagedWorktree(repo, nodeId);
+        createNode(node(nodeId, { cwd: wt.path, status: 'dead', managed_worktree: wt }));
+        const reconciler = new ManagedWorktreeSweepReconciler();
+        let pass;
+        reconciler.run(Date.now(), {
+            lifecycle: {
+                acceptsDetachedWork: () => true,
+                registerDetached: (work) => { pass = work; },
+            },
+            fleet: { isClaimed: () => false },
+        });
+        await pass;
+        const afterSweep = getNode(nodeId);
+        assert.equal(afterSweep.managed_worktree?.state, 'open', 'a failed launch does not authorize disposal');
+        assert.equal(afterSweep.cwd, wt.path, 'the sweep leaves the durable launch cwd unchanged');
+        assert.ok(existsSync(wt.path), 'the isolated checkout remains available for recovery');
+        const testFleet = bindTestFleet();
+        const launchCwds = [];
+        headlessBrokerHost.launch = (id, _inv, options) => {
+            launchCwds.push(options.cwd);
+            const handle = { pid: process.pid, exited: new Promise(() => { }) };
+            testFleet.fleet.register(id, handle);
+            return handle;
+        };
+        const revived = await reviveNode(nodeId, { resume: false, capacity: 'freeze' });
+        assert.equal(revived.outcome, 'launched');
+        assert.deepEqual(launchCwds, [wt.path], 'a fresh revive launches in the retained managed checkout');
+        const closedId = 'wt-sweep-closed';
+        const closedWt = createManagedWorktree(repo, closedId);
+        createNode(node(closedId, { cwd: closedWt.path, status: 'done', managed_worktree: closedWt }));
+        closeManagedWorktree(closedId);
+        const cleanup = await reconcileManagedWorktree(closedId, { stillEligible: () => true });
+        assert.equal(cleanup.status, 'complete', 'a successful close is still physically cleaned after its engine exits');
+        assert.equal(getNode(closedId)?.cwd, repo, 'a successful close deliberately repoints future launch cwd to the repository root');
+        launchCwds.length = 0;
+        const closedRevive = await reviveNode(closedId, { resume: false, capacity: 'freeze' });
+        assert.equal(closedRevive.outcome, 'launched');
+        assert.deepEqual(launchCwds, [repo], 'a closed node still revives against the repository root');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        resetFleetForTests();
+        rmSync(repo, { recursive: true, force: true });
+    }
+});
+test('the sweep does not conclude a missing record while its branch survives in a moved repository', async () => {
+    const repo = mkdtempSync(join(scratchRoot, 'crtr-worktree-moved-root-'));
+    const movedRepo = join(scratchRoot, `crtr-worktree-moved-root-destination-${Date.now()}`);
+    const nodeId = 'wt-sweep-moved-root';
+    try {
+        run(['init', '-b', 'main'], repo);
+        run(['config', 'user.email', 'test@example.com'], repo);
+        run(['config', 'user.name', 'Test'], repo);
+        writeFileSync(join(repo, 'README.md'), 'hello\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'init'], repo);
+        const wt = createManagedWorktree(repo, nodeId);
+        createNode(node(nodeId, { cwd: wt.path, status: 'done', managed_worktree: wt }));
+        run(['worktree', 'remove', wt.path], repo);
+        renameSync(repo, movedRepo);
+        const outcome = await reconcileManagedWorktree(nodeId, { stillEligible: () => true });
+        assert.deepEqual(outcome.status === 'refused' ? outcome.reason : undefined, 'repo_unavailable');
+        assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'a missing recorded path cannot prove the worktree branch is gone');
+        assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/${wt.branch}`], movedRepo).status, 0, 'the moved repository still holds the managed branch');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(movedRepo, { recursive: true, force: true });
+    }
+});
+test('the sweep retries containment when the base upstream advances', async () => {
+    const nodeId = 'wt-sweep-upstream-advance';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, status: 'done', managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'delivered.txt'), 'delivered remotely\n');
+    run(['add', 'delivered.txt'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'delivered work'], wt.path);
+    const refused = await reconcileManagedWorktree(nodeId, { stillEligible: () => true });
+    assert.equal(refused.status, 'refused');
+    const before = getNode(nodeId)?.managed_worktree?.sweep?.observed;
+    assert.ok(before, 'the initial refusal records the observation that caused backoff');
+    run(['push', 'origin', `${wt.branch}:main`], wt.path);
+    run(['fetch', 'origin'], sourceDir);
+    const completed = await reconcileManagedWorktree(nodeId, { stillEligible: () => true });
+    assert.equal(completed.status, 'complete', 'a newly contained branch is re-proved instead of remaining in backoff');
+    assert.equal(existsSync(wt.path), false, 'the newly contained checkout is removed');
+});
 test('the sweep refuses a managed checkout with uncommitted changes', async () => {
     const nodeId = 'wt-sweep-dirty';
     const wt = createManagedWorktree(sourceDir, nodeId);
@@ -297,6 +404,78 @@ test('autoDropCleanManagedWorktree refuses a worktree with real uncommitted chan
     assert.equal(result, null, 'real uncommitted changes must never be silently dropped');
     assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open');
 });
+test('async close returns the typed lock refusal before the client socket timeout (#1024)', async () => {
+    const nodeId = 'wt-async-close-busy';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    const commonDir = realpathSync(join(sourceDir, gitSync(['rev-parse', '--git-common-dir'], sourceDir).stdout.trim()));
+    const lockModule = new URL('../../exclusive-lock.ts', import.meta.url).href;
+    const child = spawn(process.execPath, ['--import', 'tsx/esm', '--input-type=module', '--eval', `
+    const { withExclusiveDirectoryLockAsync } = await import(${JSON.stringify(lockModule)});
+    await withExclusiveDirectoryLockAsync(${JSON.stringify(worktreeLockPathForCommonDir(commonDir))}, async () => {
+      console.log('locked');
+      await new Promise((resolve) => setTimeout(resolve, 40_000));
+    });
+  `], { env: { ...process.env, CRTR_HOME: home }, stdio: ['ignore', 'pipe', 'pipe'] });
+    try {
+        await new Promise((resolve, reject) => {
+            let output = '';
+            child.stdout.on('data', (chunk) => { output += chunk; if (output.includes('locked'))
+                resolve(); });
+            child.once('error', reject);
+            child.once('exit', (code) => reject(new Error(`lock holder exited before acquiring the lock (${code})`)));
+        });
+        const server = createApiServer();
+        try {
+            await new Promise((resolve) => setTimeout(resolve, 25));
+            const client = new CrtrClient({ socketPath: apiSocketPath(), autostart: false });
+            const started = Date.now();
+            await assert.rejects(client.closeWorktree(nodeId), (error) => error instanceof ApiError && error.code === 'worktree_lock_timeout');
+            assert.ok(Date.now() - started < 30_000, 'the daemon must serialize the typed busy refusal before the 30s client timeout');
+        }
+        finally {
+            await server.close();
+        }
+    }
+    finally {
+        child.kill('SIGTERM');
+    }
+});
+test('async close yields while an async repository holder runs, keeping API requests responsive (#1024)', async () => {
+    const zeroId = 'wt-async-close-zero';
+    const committedId = 'wt-async-close-committed';
+    const zero = createManagedWorktree(sourceDir, zeroId);
+    const committed = createManagedWorktree(sourceDir, committedId);
+    createNode(node(zeroId, { cwd: zero.path, managed_worktree: zero }));
+    createNode(node(committedId, { cwd: committed.path, managed_worktree: committed }));
+    writeFileSync(join(committed.path, 'committed.txt'), 'work\n');
+    run(['add', 'committed.txt'], committed.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'work'], committed.path);
+    const commonDir = realpathSync(join(sourceDir, gitSync(['rev-parse', '--git-common-dir'], sourceDir).stdout.trim()));
+    let release;
+    const held = new Promise((resolve) => { release = resolve; });
+    const holder = withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), async () => { await held; });
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    const server = createApiServer();
+    try {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+        const client = new CrtrClient({ socketPath: apiSocketPath(), autostart: false });
+        const zeroClose = client.closeWorktree(zeroId);
+        const committedClose = client.closeWorktree(committedId);
+        const responsive = await Promise.race([client.listNodes().then(() => true), new Promise((resolve) => setTimeout(() => resolve(false), 250))]);
+        assert.equal(responsive, true, 'a waiting close must not block another daemon request');
+        release();
+        await holder;
+        const [zeroResult, committedResult] = await Promise.all([zeroClose, committedClose]);
+        assert.equal(zeroResult.landed_sha, zero.base_sha, 'the zero-commit close returns its actual result after the holder releases');
+        assert.equal(committedResult.landed_sha, gitSync(['rev-parse', 'HEAD'], committed.path).stdout.trim(), 'the committed close returns its actual landed result after the holder releases');
+    }
+    finally {
+        release();
+        await holder;
+        await server.close();
+    }
+});
 test('abandon preserves committed and dirty work, records its retained tip, and releases finalization', async () => {
     const nodeId = 'wt-abandon';
     const wt = createManagedWorktree(sourceDir, nodeId);

package/dist/core/__tests__/parse-argv-stdin-secret.test.js

@@ -23,6 +23,9 @@ const PROFILE_SET_SHAPED_PARAMS = [
     { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'var name' },
     { kind: 'stdin', name: 'value', required: true, constraint: 'value piped on stdin' },
 ];
+const STRING_FLAG_PARAMS = [
+    { kind: 'flag', name: 'arg', type: 'string', required: true, constraint: 'argument' },
+];
 test('a lone positional supplies the stdin body on a leaf declaring no positional param', async () => {
     const result = await parseArgv(YIELD_SHAPED_PARAMS, ['refresh against the original goal']);
     assert.equal(result['message'], 'refresh against the original goal');
@@ -42,6 +45,17 @@ test('allowPositional:false keeps a stdin-only leaf rejecting positionals by ari
         return true;
     });
 });
+test('a value bound with = may start with --', async () => {
+    const result = await parseArgv(STRING_FLAG_PARAMS, ['--arg=--help']);
+    assert.equal(result['arg'], '--help');
+});
+test('a separate flag value starting with -- is rejected as missing', async () => {
+    await assert.rejects(() => parseArgv(STRING_FLAG_PARAMS, ['--arg', '--help']), (err) => {
+        assert.equal(err.code, 'missing_parameter');
+        assert.equal(err.message, '--arg requires a value');
+        return true;
+    });
+});
 test('an extra positional on a stdin-bearing leaf is rejected without echoing it', async () => {
     const secret = 'SUPERSECRET_ARGV';
     await assert.rejects(() => parseArgv(PROFILE_SET_SHAPED_PARAMS, ['some-profile', secret, '--name', 'REVIEW_TOKEN']), (err) => {

package/dist/core/__tests__/seam/broker-attach-stream.test.js

@@ -161,3 +161,16 @@ test('G3 — a deliver whose prompt rejects acks ok:false and records deliver_fa
     assert.equal(okAck.type === 'ack' && okAck.ok, true, 'G3: an accepted prompt acks delivered:true');
     assert.equal(okAck.type === 'ack' ? okAck.detail : undefined, 'prompt');
 });
+// A message_end is only a broker/viewer relay. It must not depend on a daemon
+// read: a daemon outage after boot leaves tool results and the run settlement intact.
+test('G4 — a daemon read failure after boot does not interrupt a tool result or its settlement', async () => {
+    const c = await ctrl('g4-ctrl');
+    const pid = brokerPid();
+    await h.stopApiServer();
+    const token = tok('G4-TOOL-RESULT');
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 0 });
+    await c.waitFrame((f) => f.type === 'tool_execution_end', 'G4 tool result relayed after the daemon server exits');
+    await c.waitFrame((f) => f.type === 'agent_settled', 'G4 run settles after the daemon server exits');
+    await delay(200);
+    assert.equal(isPidAlive(pid), true, 'G4: broker remains alive after relaying and settling the tool result');
+});

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.

package/dist/core/__tests__/seam/broker-startup-diagnostics.test.d.ts

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

package/dist/core/__tests__/seam/broker-startup-diagnostics.test.js

@@ -0,0 +1,82 @@
+// Run with: npm run build && node --test --test-timeout=180000 dist/core/__tests__/seam/broker-startup-diagnostics.test.js
+//
+// A refused broker launch, a broker fatal emitted before session_start, and a
+// SIGKILL all surface through canonical diagnostics. broker.log remains raw
+// stdout/stderr residue, so a canonical fatal need not write anything there.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { subscribe } from '../../canvas/canvas.js';
+import { resolveRef } from '../../canvas/history.js';
+import { readLogSnapshot } from '../../events/read.js';
+import { spawnChild } from '../../runtime/spawn.js';
+import { FAIL_BEFORE_SESSION_START } from '../fixtures/fake-engine.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+let h;
+let root;
+function eventsFor(nodeId) {
+    return readLogSnapshot({ nodeId }, false).items.flatMap((item) => item.kind === 'event' ? [item.envelope] : []);
+}
+function reportBody(entry) {
+    assert.ok(entry.ref, 'the boot-failure notification has a report reference');
+    const report = resolveRef(entry.ref);
+    assert.ok(report, 'the boot-failure notification report resolves');
+    return report.body;
+}
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-broker-startup-diagnostics' });
+    root = h.spawnRoot('broker startup diagnostics seam root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+test('broker startup failures name canonical diagnostics, preserve launch errors, and report the observed exit status', { timeout: 60_000 }, async () => {
+    const refusedId = 'launch-refused';
+    const missingCwd = join(h.home, 'missing-cwd');
+    await assert.rejects(spawnChild({
+        kind: 'general',
+        cwd: missingCwd,
+        prompt: 'this launch must be refused by the operating system',
+        parent: root,
+        nodeId: refusedId,
+    }), (error) => {
+        const details = error.details;
+        assert.match(String(details?.next), new RegExp(`crtr sys logs --node ${refusedId}`));
+        return true;
+    });
+    const launchFailure = await h.waitFor(() => eventsFor(refusedId).find((event) => event.event === 'broker.launch.failed') ?? null, { label: 'canonical launch refusal' });
+    assert.match(launchFailure.error?.message ?? '', /ENOENT/, 'the canonical event preserves the operating-system launch error');
+    const refusedLog = join(h.home, 'nodes', refusedId, 'job', 'broker.log');
+    assert.equal(existsSync(refusedLog), true, 'the raw broker log exists for the refused launch');
+    assert.equal(readFileSync(refusedLog, 'utf8'), '', 'a launch refusal writes its diagnostic canonically, not as raw broker output');
+    const fatal = await spawnChild({
+        kind: 'general',
+        cwd: h.node(root).cwd,
+        prompt: `canonical fatal ${FAIL_BEFORE_SESSION_START}`,
+        parent: root,
+    });
+    const fatalId = fatal.node.node_id;
+    await h.awaitFleetExit(fatalId);
+    await h.tick();
+    const fatalEvent = eventsFor(fatalId).find((event) => event.event === 'broker.runtime.fatal');
+    assert.ok(fatalEvent, 'a pre-session broker fatal is available in canonical node diagnostics');
+    assert.match(fatalEvent.error?.message ?? '', /simulated pre-session_start boot failure/);
+    const fatalLog = join(h.home, 'nodes', fatalId, 'job', 'broker.log');
+    assert.equal(readFileSync(fatalLog, 'utf8'), '', 'a successfully emitted canonical fatal leaves raw broker.log empty');
+    const fatalNotice = h.inbox(root).find((entry) => entry.from === fatalId && entry.tier === 'urgent');
+    assert.ok(fatalNotice, 'the parent receives the fatal broker boot-failure notification');
+    assert.match(reportBody(fatalNotice), /code 1, signal null/);
+    assert.match(reportBody(fatalNotice), new RegExp(`crtr sys logs --node ${fatalId}`));
+    const exited = spawnSync(process.execPath, ['-e', ''], { stdio: 'ignore' });
+    assert.ok(exited.pid !== undefined, 'the fabricated boot failure has a recorded, dead pid');
+    const killedId = h.fabricateBrokerNode({ id: 'killed-before-session', parent: root, pi_pid: exited.pid });
+    subscribe(root, killedId, true);
+    await h.deliverExit(killedId, { code: null, signal: 'SIGKILL' });
+    await h.tick();
+    const killNotice = h.inbox(root).find((entry) => entry.from === killedId && entry.tier === 'urgent');
+    assert.ok(killNotice, 'the parent receives the SIGKILL boot-failure notification');
+    assert.match(reportBody(killNotice), /code null, signal SIGKILL/);
+});

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

@@ -0,0 +1,6 @@
+/** Seconds a leading `sleep ...` will block for, or null when the command does
+ *  not open with a sleep (or its duration isn't statically knowable). */
+export declare function leadingSleepSeconds(command: string): number | null;
+/** The refusal this command earns before it runs, or null when it may run.
+ *  `cwd` is the directory the command will execute in. */
+export declare function bashCommandRefusal(command: string, cwd: string, home?: string): string | null;