@north-light/crouter 0.3.304 → 0.3.305

package/dist/commands/node/create.js

@@ -82,8 +82,9 @@ function nodeNewParams() {
         { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name.' },
         { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
         { kind: 'flag', name: 'node-id', type: 'string', required: false, constraint: 'Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present.' },
-        { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent resident root with no parent or subscription. Mutually exclusive with --worktree.' },
+        { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent root with no parent or subscription. Mutually exclusive with --worktree.' },
         { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'Birth the node as resident: it parks and stays wakeable without being forced to submit a final. Pass it ONLY when the user will open this node’s viewer pane and work with it back and forth; a child that only other nodes message stays terminal. Applies to managed children and roots; roots default to resident.' },
+        { kind: 'flag', name: 'terminal', type: 'bool', required: false, constraint: 'Birth the node as terminal: it finalizes when its work is done and leaves nothing wakeable behind. Only meaningful with --root, whose default is resident; managed children are already terminal. Pass it for bounded programmatic work no one will open a viewer on. Mutually exclusive with --resident.' },
         { kind: 'flag', name: 'worktree', type: 'string', required: false, constraint: 'Local base branch for a crouter-managed worktree for this child. Mutually exclusive with --root.' },
         { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'Fork the new node from an existing node id, absolute session path, or partial pi session uuid.' },
         {
@@ -190,6 +191,10 @@ async function runNodeCreation(input) {
     const parent = input['parent'];
     const root = input['root'] === true;
     const resident = input['resident'] === true;
+    const terminal = input['terminal'] === true;
+    if (resident && terminal) {
+        throw new InputError({ error: 'lifecycle_conflict', message: '--resident and --terminal cannot both be passed', field: 'terminal', next: 'Pass the one birth lifecycle you want, or neither to take the default (resident for --root, terminal for a managed child).' });
+    }
     const worktreeBaseRaw = input['worktree'];
     if (worktreeBaseRaw !== undefined && worktreeBaseRaw.trim() === '') {
         throw new InputError({ error: 'worktree_base_required', message: '--worktree requires a base branch', field: 'worktree', next: 'Pass an existing local branch that landing can fast-forward.' });
@@ -257,6 +262,7 @@ async function runNodeCreation(input) {
         ...(root ? { root: true } : { parent: parentId ?? null }),
         ...(creator !== undefined ? { creator } : {}),
         ...(resident ? { root_lifecycle: 'resident' } : {}),
+        ...(terminal ? { root_lifecycle: 'terminal' } : {}),
         ...(worktreeBase !== undefined ? { worktree: worktreeBase } : {}),
         ...(forkFrom !== undefined ? { fork_from: forkFrom } : {}),
         ...(modelSpec !== undefined ? { model: modelSpec } : {}),

package/dist/commands/node/wait.js

@@ -46,7 +46,7 @@ function deadlineHeredoc(body, nodeId) {
     const lines = new Set(body.split('\n'));
     while (lines.has(delimiter))
         delimiter = `CRTR_DEADLINE_${++suffix}`;
-    return `crtr cron cancel "$CRTR_CRON_ID" && crtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
+    return `crtr cron cancel "$CRTR_CRON_ID"\ncrtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
 }
 const nodeWaitDeadline = defineLeaf({
     name: 'deadline',

package/dist/commands/node-worktree.js

@@ -85,7 +85,8 @@ const worktreeClose = defineLeaf({
             { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'Always false for an active caller: its checkout remains intact rather than being removed beneath the node.' },
             { name: 'worktree_remove_error', type: 'string', required: true, constraint: 'The named deferred-cleanup state and safe manual follow-up after the caller exits.' },
             { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'False while the deferred-cleanup checkout still has this branch checked out.' },
-            { name: 'branch_delete_error', type: 'string', required: true, constraint: 'The safe branch-cleanup follow-up after the checkout is removed.' }
+            { name: 'branch_delete_error', type: 'string', required: true, constraint: 'The safe branch-cleanup follow-up after the checkout is removed.' },
+            { name: 'base_checkout_stash', type: 'string', required: false, constraint: 'Present when conflicting base-checkout changes were retained in a stash; names the exact stash SHA and command required to recover them.' }
         ],
         outputKind: 'object',
         effects: [
@@ -116,6 +117,9 @@ const worktreeClose = defineLeaf({
         if (r['branch_deleted'] === false) {
             notes.push(String(r['branch_delete_error'] ?? `local branch ${branch} could not be deleted automatically.`));
         }
+        if (typeof r['base_checkout_stash'] === 'string') {
+            notes.push(`Warning: ${r['base_checkout_stash']}`);
+        }
         if (notes.length > 0)
             return `${base} Note: ${notes.join(' ')}`;
         return base;

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

@@ -35,6 +35,7 @@ import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { DefaultResourceLoader, getAgentDir } from '@earendil-works/pi-coding-agent';
 import { MANAGED_PROVIDER_COOLING_DIAGNOSTIC } from '../../runtime/managed-provider-cooling.js';
+import { PROVIDER_FAILURE_DIAGNOSTIC } from '../../provider-failure.js';
 import registerCanvasBashValve, { createValveOperations } from '../../../pi-extensions/canvas-bash-valve.js';
 /** Test seams for prompt-scoped failures before session_start. The one-shot
  *  variant records its first failure per node so the next cycling retry can
@@ -1085,6 +1086,18 @@ class FakeSession {
                 // before the stophook sees agent_end while the run is active; the
                 // subscriber receives agent_settled after it clears.
                 this.streaming = true;
+                const diagnostics = [
+                    ...(cmd.deadline === undefined ? [] : [{
+                            type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
+                            timestamp: Date.now(),
+                            details: { rateLimitedUntil: cmd.deadline },
+                        }]),
+                    ...(cmd.providerFailure === undefined ? [] : [{
+                            type: PROVIDER_FAILURE_DIAGNOSTIC,
+                            timestamp: Date.now(),
+                            details: cmd.providerFailure,
+                        }]),
+                ];
                 const stopMessages = [
                     {
                         role: 'assistant',
@@ -1093,21 +1106,7 @@ class FakeSession {
                         // turn; the stophook classifies it for the active-fault marker.
                         // Forward it so a test can drive a CONNECTION stall faithfully.
                         ...(cmd.errorMessage === undefined ? {} : { errorMessage: cmd.errorMessage }),
-                        // A managed-provider cooling terminal carries the earliest pool
-                        // deadline as a typed diagnostic that survives verbatim into
-                        // agent_end.messages; the stophook reads it (extractCoolingDeadline)
-                        // to stamp retry.nextAt. Attached only when a test drives `deadline`.
-                        ...(cmd.deadline === undefined
-                            ? {}
-                            : {
-                                diagnostics: [
-                                    {
-                                        type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
-                                        timestamp: Date.now(),
-                                        details: { rateLimitedUntil: cmd.deadline },
-                                    },
-                                ],
-                            }),
+                        ...(diagnostics.length === 0 ? {} : { diagnostics }),
                         content: [{ type: 'text', text: cmd.text ?? '' }],
                     },
                 ];

package/dist/core/__tests__/integration/tmux-surface.test.js

@@ -275,3 +275,56 @@ test('tmux installer reads pair-array manifests and replaces owned pairs', (t) =
         isolatedTmux(socket, ['kill-server']);
     }
 });
+// Regression: a passthrough wrapper survives the user re-sourcing their own tmux
+// config over it. Crouter wraps an occupied root key and fingerprints the result;
+// every `source-file` (and every fresh tmux server) re-installs the user's own
+// bind-key line over that wrapper. Reading the mismatch as a deliberate rebind
+// relinquished the key permanently, so the attach viewer silently stopped
+// receiving its own scroll keys and no reconciliation ever restored them.
+test('tmux passthrough re-wraps a re-sourced config but yields to a real rebind', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-passthrough-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, '-f', '/dev/null', 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socket = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' }).stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    process.env['TMUX'] = `${socket},1,0`;
+    const userBinding = ['bind-key', '-T', 'root', 'C-k', 'copy-mode', '-e'];
+    const bindings = resolveKeybindings({ 'crtr.attach.scroll.up': ['ctrl+k'] });
+    const passthrough = ['crtr.attach.scroll.up'];
+    try {
+        isolatedTmux(socket, userBinding);
+        const original = tmuxBinding(socket, 'root', 'C-k');
+        assert.match(original ?? '', /copy-mode/);
+        const wrapped = installTmuxBindings(bindings, passthrough);
+        assert.equal(wrapped.ok, true, JSON.stringify(wrapped.diagnostics));
+        assert.match(tmuxBinding(socket, 'root', 'C-k') ?? '', /@crtr_attach/, 'occupied key should be wrapped');
+        // The user reloads their tmux config: their own line lands over the wrapper.
+        isolatedTmux(socket, userBinding);
+        assert.equal(tmuxBinding(socket, 'root', 'C-k'), original);
+        const resourced = installTmuxBindings(bindings, passthrough);
+        assert.equal(resourced.ok, true, JSON.stringify(resourced.diagnostics));
+        assert.match(tmuxBinding(socket, 'root', 'C-k') ?? '', /@crtr_attach/, 're-sourced config should be re-wrapped, not relinquished');
+        // A line matching neither the wrapper nor the recorded original is a real
+        // rebind and stays the user's, here and on every later reconciliation.
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'C-k', 'display-message', 'user-owned']);
+        for (const pass of ['first', 'second']) {
+            const rebound = installTmuxBindings(bindings, passthrough);
+            assert.equal(rebound.ok, true, JSON.stringify(rebound.diagnostics));
+            const live = tmuxBinding(socket, 'root', 'C-k') ?? '';
+            assert.match(live, /user-owned/, `${pass} reconciliation should leave a real rebind alone`);
+            assert.doesNotMatch(live, /@crtr_attach/);
+        }
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});

package/dist/core/__tests__/kickoff.test.js

@@ -62,6 +62,46 @@ test('drainBearings preserves the yield note until explicit boot confirmation',
     assert.equal(readYieldMessage(id), null, 'confirmation clear is idempotent');
     assert.equal(existsSync(yieldMessagePath(id)), false, 'confirmed handoff removes the note');
 });
+test('fresh kickoff keeps each inbox card directly before its own message', () => {
+    const id = 'ordered-cards';
+    const meta = createNode(node(id));
+    appendInbox(id, {
+        from: 'sender',
+        tier: 'normal',
+        kind: 'message',
+        label: 'FIRST-BODY',
+        data: { body: 'FIRST-BODY', cards: ['<runtime kind="test-card">FIRST-CARD</runtime>'] },
+    });
+    appendInbox(id, {
+        from: 'sender',
+        tier: 'normal',
+        kind: 'message',
+        label: 'SECOND-BODY',
+        data: { body: 'SECOND-BODY', cards: ['<runtime kind="test-card">SECOND-CARD</runtime>'] },
+    });
+    for (const body of ['GROUPED-BODY-1', 'GROUPED-BODY-2', 'GROUPED-BODY-3']) {
+        appendInbox(id, {
+            from: 'card-free-sender',
+            tier: 'normal',
+            kind: 'message',
+            label: body,
+            data: { body },
+        });
+    }
+    const kickoff = buildReviveKickoff(meta, drainBearings(meta));
+    const firstCard = kickoff.indexOf('FIRST-CARD');
+    const firstBody = kickoff.indexOf('FIRST-BODY');
+    const secondCard = kickoff.indexOf('SECOND-CARD');
+    const secondBody = kickoff.indexOf('SECOND-BODY');
+    assert.ok(firstCard >= 0 && firstCard < firstBody, 'the first card stays ahead of its own message');
+    assert.ok(firstBody < secondCard, 'the second card cannot leap ahead of the first message');
+    assert.ok(secondCard < secondBody, 'the second card stays ahead of its own message');
+    const groupedSections = kickoff.match(/<from id="card-free-sender">([\s\S]*?)<\/from>/g) ?? [];
+    assert.equal(groupedSections.length, 1, 'card-free entries from one sender remain one delivery');
+    for (const body of ['GROUPED-BODY-1', 'GROUPED-BODY-2', 'GROUPED-BODY-3']) {
+        assert.ok(groupedSections[0].includes(body), `${body} remains in the sender's single delivery`);
+    }
+});
 test('drainBearings leaves persona drift pending until the replacement context exists', () => {
     const oldPersona = { kind: 'developer', mode: 'base', lifecycle: 'terminal' };
     const meta = createNode(node('pending-persona', {

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

@@ -117,6 +117,31 @@ after(async () => {
 afterEach(() => {
     kit.closeAll();
 });
+test('a normalized 503 survives into a durable provider fault and re-drives the turn', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('structured provider failure parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const child = await h.spawnHeadlessChild(parent, 'structured provider failure', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial structured-failure fixture turn started' });
+    const baselineStarts = agentStartCount(child);
+    h.fakeCmd(child, {
+        cmd: 'stop',
+        reason: 'error',
+        errorMessage: 'Request failed',
+        providerFailure: { status: 503 },
+    });
+    const fault = await h.waitFor(() => {
+        const current = readFault(child);
+        return current?.kind === 'overloaded' && current.retry.disposition === 'auto' ? current : undefined;
+    }, { label: 'structured 503 published as an automatic provider fault' });
+    assert.equal(fault.providerError?.provider, OPENAI_STRONG.model.provider);
+    assert.equal(fault.providerError?.model, OPENAI_STRONG.model.id);
+    assert.equal(fault.providerError?.status, 503);
+    await h.waitFor(() => agentStartCount(child) >= baselineStarts + 1, {
+        label: 'structured 503 automatic recovery turn started',
+    });
+    await h.waitFor(() => readFault(child) === null, { label: 'successful recovery clears the structured provider fault' });
+});
 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

package/dist/core/__tests__/seam/deadline-wake-delivery.test.d.ts

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

package/dist/core/__tests__/seam/deadline-wake-delivery.test.js

@@ -0,0 +1,138 @@
+// Run with: npm run build && node --test --test-timeout=180000 dist/core/__tests__/seam/deadline-wake-delivery.test.js
+//
+// Pins the compiled deadline command: self-cancel cleanup runs before its urgent
+// inbox wake, but a nonzero cleanup result cannot suppress that durable wake.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getCron } from '../../canvas/crons.js';
+import { ensureRootProfile } from '../../profiles/manifest.js';
+import { executeCron } from '../../../daemon/cron-run.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+let h;
+let root;
+let fakeBin;
+let journal;
+let argsPath;
+let bodyPath;
+let cancelCodePath;
+let sendCodePath;
+let savedPath;
+let savedProfileId;
+let profileId;
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function writeFakeFrontDoor() {
+    writeFileSync(join(fakeBin, 'crtr'), `#!/bin/sh
+journal=${shellQuote(journal)}
+args=${shellQuote(argsPath)}
+body=${shellQuote(bodyPath)}
+cancel_code=${shellQuote(cancelCodePath)}
+send_code=${shellQuote(sendCodePath)}
+
+if [ "$1" = cron ] && [ "$2" = cancel ]; then
+  printf '%s\\n' cancel >> "$journal"
+  ${shellQuote(process.execPath)} --input-type=module -e ${shellQuote(`import { cancelCron } from ${JSON.stringify(join(process.cwd(), 'dist', 'core', 'canvas', 'crons.js'))}; cancelCron(process.argv[1], { preserveRunningProcess: true });`)} "$3" || exit $?
+  code=$(cat "$cancel_code")
+  if [ "$code" -ne 0 ]; then
+    printf '%s\\n' 'cancel failed' >&2
+  fi
+  exit "$code"
+fi
+
+if [ "$1" = node ] && [ "$2" = message ]; then
+  printf '%s\\n' message >> "$journal"
+  printf '%s\\n' "$@" > "$args"
+  cat > "$body"
+  code=$(cat "$send_code")
+  if [ "$code" -ne 0 ]; then
+    printf '%s\\n' 'send failed' >&2
+    exit "$code"
+  fi
+  exec ${shellQuote(process.execPath)} ${shellQuote(join(process.cwd(), 'dist', 'cli.js'))} "$@" < "$body"
+fi
+
+printf '%s\\n' unexpected >> "$journal"
+exit 99
+`, { mode: 0o755 });
+    chmodSync(join(fakeBin, 'crtr'), 0o755);
+}
+async function armDeadline(body) {
+    const target = await h.spawnHeadlessChild(root, 'deadline target', { profile: profileId });
+    const armed = h.cli(target, ['--json', 'node', 'wait', 'deadline', body, '--until', '1m']);
+    assert.equal(armed.code, 0, `node wait deadline: ${armed.stderr}`);
+    const id = armed.json?.id;
+    assert.equal(typeof id, 'string', 'the compiled deadline CLI returns its cron id');
+    const cron = getCron(id);
+    assert.notEqual(cron, null, 'the compiled deadline CLI persisted its cron command');
+    return { target, cron: cron };
+}
+async function runDeadline(cancelCode, sendCode, body) {
+    writeFileSync(journal, '');
+    writeFileSync(argsPath, '');
+    writeFileSync(bodyPath, '');
+    writeFileSync(cancelCodePath, String(cancelCode));
+    writeFileSync(sendCodePath, String(sendCode));
+    const { target, cron } = await armDeadline(body);
+    process.env['PATH'] = `${fakeBin}:${savedPath ?? ''}`;
+    try {
+        const record = await executeCron(cron, { outOfBand: false });
+        return { target, record: record ?? null };
+    }
+    finally {
+        if (savedPath === undefined)
+            delete process.env['PATH'];
+        else
+            process.env['PATH'] = savedPath;
+    }
+}
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-deadline-wake' });
+    profileId = ensureRootProfile().profileId;
+    savedProfileId = process.env['CRTR_PROFILE_ID'];
+    process.env['CRTR_PROFILE_ID'] = profileId;
+    root = h.spawnRoot('deadline wake seam root');
+    fakeBin = mkdtempSync(join(tmpdir(), 'crtr-deadline-front-door-'));
+    journal = join(fakeBin, 'journal');
+    argsPath = join(fakeBin, 'args');
+    bodyPath = join(fakeBin, 'body');
+    cancelCodePath = join(fakeBin, 'cancel-code');
+    sendCodePath = join(fakeBin, 'send-code');
+    writeFakeFrontDoor();
+    savedPath = process.env['PATH'];
+});
+after(async () => {
+    if (savedPath === undefined)
+        delete process.env['PATH'];
+    else
+        process.env['PATH'] = savedPath;
+    if (savedProfileId === undefined)
+        delete process.env['CRTR_PROFILE_ID'];
+    else
+        process.env['CRTR_PROFILE_ID'] = savedProfileId;
+    rmSync(fakeBin, { recursive: true, force: true });
+    if (h !== undefined)
+        await h.dispose();
+});
+test('compiled deadline wakes once after cancel failure, retains cancel-first ordering, and propagates send failure', { timeout: 60_000 }, async () => {
+    const failedCancelBody = 'deadline wake after failed cancel\nbody remains intact';
+    const failedCancel = await runDeadline(2, 0, failedCancelBody);
+    assert.equal(failedCancel.record?.exit_code, 0, 'a successful send is the cron command result after failed cleanup');
+    assert.match(failedCancel.record?.stderr_head ?? '', /cancel failed/, 'cancel diagnostics remain on stderr');
+    assert.deepEqual(readFileSync(journal, 'utf8').trim().split('\n'), ['cancel', 'message'], 'cancel runs before exactly one message send');
+    assert.deepEqual(readFileSync(argsPath, 'utf8').trim().split('\n'), ['node', 'message', 'send', '--to', failedCancel.target, '--tier', 'urgent'], 'the generated urgent send receives its target and tier');
+    assert.equal(readFileSync(bodyPath, 'utf8'), `${failedCancelBody}\n`, 'the generated heredoc body reaches the front door byte-for-byte');
+    await h.awaitWake(failedCancel.target, { match: /deadline wake after failed cancel/ });
+    assert.ok(h.inbox(failedCancel.target).some((entry) => entry.tier === 'urgent' && entry.data?.['body'] === failedCancelBody), 'the successful send durably appends the urgent deadline message to the target inbox');
+    const successfulCancel = await runDeadline(0, 0, 'deadline wake after successful cancel');
+    assert.equal(successfulCancel.record?.exit_code, 0, 'the ordinary successful-cancel path still succeeds');
+    assert.deepEqual(readFileSync(journal, 'utf8').trim().split('\n'), ['cancel', 'message'], 'successful cleanup also precedes one message send');
+    await h.awaitWake(successfulCancel.target, { match: /deadline wake after successful cancel/ });
+    const failedSend = await runDeadline(2, 23, 'deadline send failure');
+    assert.equal(failedSend.record?.exit_code, 23, 'the final message-send status remains the cron failure status');
+    assert.match(failedSend.record?.stderr_head ?? '', /cancel failed[\s\S]*send failed/, 'both cleanup and send diagnostics remain visible');
+    assert.deepEqual(readFileSync(journal, 'utf8').trim().split('\n'), ['cancel', 'message'], 'a failed send is still attempted once after failed cleanup');
+});

package/dist/core/__tests__/seam/reopen-invalidated-worktree.test.d.ts

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

package/dist/core/__tests__/seam/reopen-invalidated-worktree.test.js

@@ -0,0 +1,60 @@
+// Run with: npm run build && node --test --test-timeout=180000 dist/core/__tests__/seam/reopen-invalidated-worktree.test.js
+//
+// Regression for #1070 and #1064: a completed managed-worktree node loses its
+// session when the worktree closes. Atomic message reopen must start from the
+// retained final report and the new instruction, never replay its birth goal.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { pushFinal } from '../../feed/feed.js';
+import { persistClosedWorktreeState } from '../../worktree.js';
+import { readGoal } from '../../runtime/kickoff.js';
+let h;
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-reopen-invalidated-worktree' });
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+test('atomic message reopen of a closed worktree starts fresh from the prior final and follow-up, not the birth goal', { timeout: 30_000 }, async () => {
+    const root = h.spawnRoot('reopen invalidated-worktree manager');
+    const originalGoal = 'ORIGINAL-MANDATE: do not replay this completed implementation task';
+    const followUp = 'FOLLOW-UP-MANDATE: inspect the completed work without changing it';
+    const child = await h.spawnHeadlessChild(root, originalGoal);
+    await pushFinal(child, 'COMPLETED-FINAL: the original implementation is complete');
+    const finalReport = h.node(child)?.final_report;
+    assert.ok(finalReport, 'the completed worker has a canonical final report');
+    const finalPath = join(h.home, 'nodes', child, 'reports', finalReport);
+    assert.equal(existsSync(finalPath), true, 'the canonical final exists before reopening');
+    persistClosedWorktreeState(child, {
+        state: 'open',
+        path: join(h.home, 'removed-worktree'),
+        branch: 'crtr/reopen-invalidated-worktree',
+        repo_root: process.cwd(),
+        base_ref: 'main',
+        base_sha: 'test',
+        created: new Date().toISOString(),
+    });
+    assert.equal(h.node(child)?.pi_session_file ?? null, null, 'closed worktree invalidates the old session coordinate');
+    const oldPid = h.node(child)?.pi_pid;
+    assert.ok(oldPid != null, 'the original broker is still live until its completed turn exits');
+    process.kill(oldPid, 'SIGKILL');
+    await h.awaitFleetExit(child);
+    const result = h.cli(root, ['node', 'message', 'send', '--to', child, '--reopen', followUp]);
+    assert.equal(result.code, 0, `atomic reopen message should succeed\n--stderr--\n${result.stderr}`);
+    const boot = await h.awaitBoot(child, { minCount: 2 });
+    assert.equal(boot.resuming, false, 'the cleared session forces a fresh broker boot');
+    assert.equal(boot.prompt?.includes(originalGoal), false, 'a completed node never replays its birth mandate');
+    const priorFinalIndex = boot.prompt?.indexOf('reopen-final-report') ?? -1;
+    const followUpIndex = boot.prompt?.indexOf(followUp) ?? -1;
+    assert.ok(priorFinalIndex >= 0 && boot.prompt?.includes(finalPath), 'the prior final report path is delivered as context');
+    assert.ok(followUpIndex >= 0, 'the new instruction is delivered in the fresh kickoff');
+    assert.ok(priorFinalIndex < followUpIndex, 'the prior final report context arrives before the new instruction');
+    assert.equal(readGoal(child)?.trim(), originalGoal, 'the birth goal remains on disk as historical data');
+    assert.equal(existsSync(finalPath), true, 'reopen does not delete the prior final report');
+    assert.equal(h.node(child)?.lifecycle, 'resident', 'atomic reopen restores resident lifecycle before the fresh broker starts');
+    assert.equal(h.node(child)?.final_report ?? null, null, 'atomic reopen clears only the live finalization latch');
+});

package/dist/core/fault-classifier.d.ts

@@ -1,4 +1,5 @@
 import type { ErrorClass, OperationId } from './events/types.js';
+import { type ProviderFailureDetails } from './provider-failure.js';
 export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'broker↔crtrd' | 'daemon→node' | 'crtr→pi';
 export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
 export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
@@ -10,6 +11,10 @@ export interface FaultRetry {
     max?: number;
     nextAt?: string;
 }
+export interface FaultProviderError extends ProviderFailureDetails {
+    provider: string;
+    model: string;
+}
 export interface Fault {
     link: FaultLink;
     op: string;
@@ -19,6 +24,7 @@ export interface Fault {
     since: string;
     operation_id: OperationId;
     anchorEntryId?: string;
+    providerError?: FaultProviderError;
 }
 export interface FaultClassification {
     kind: FaultKind;

package/dist/core/fault-classifier.js

@@ -1,5 +1,6 @@
 import { hasManagedProviderCoolingDiagnostic } from './runtime/managed-provider-cooling.js';
 import { recognizeProviderError } from './provider-error-recognition.js';
+import { extractProviderFailureDetails } from './provider-failure.js';
 import { isRecord } from '../shared/predicates.js';
 const errorClassByFaultKind = {
     'rate-limit': 'rate_limit',
@@ -78,13 +79,17 @@ export function classify(link, raw) {
         return { kind: 'rate-limit', disposition: 'auto' };
     }
     const value = isRecord(raw) ? raw : {};
+    const failure = extractProviderFailureDetails(raw);
+    const nested = failure?.causes ?? [];
     const signal = recognizeProviderError({
-        code: value['code'],
-        errno: value['errno'],
-        status: value['status'],
+        code: value['code'] ?? failure?.code ?? nested.find((cause) => cause.code !== undefined)?.code,
+        errno: value['errno'] ?? failure?.errno ?? nested.find((cause) => cause.errno !== undefined)?.errno,
+        status: value['status'] ?? failure?.status,
         wsCloseCode: value['code'],
         wsCloseReason: value['reason'],
-        message: rawText(raw),
+        message: [rawText(raw), failure?.body, ...nested.flatMap((cause) => [cause.message, cause.body])]
+            .filter((part) => typeof part === 'string' && part !== '')
+            .join(' '),
     });
     const kind = faultKindFromProviderSignal(signal);
     return { kind, disposition: classifyDisposition(link, kind) };

package/dist/core/provider-failure.d.ts

@@ -0,0 +1,30 @@
+export declare const PROVIDER_FAILURE_DIAGNOSTIC = "crtr:provider-failure";
+export interface ProviderFailureCause {
+    message?: string;
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+}
+export interface ProviderFailureDetails {
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+    causes?: ProviderFailureCause[];
+}
+export interface NormalizedProviderFailure extends ProviderFailureDetails {
+    message: string;
+}
+/** Converts an arbitrary provider failure into serializable facts before an SDK stream flattens it to `errorMessage`. */
+export declare function normalizeProviderFailure(error: unknown, observed?: {
+    status?: number;
+}): NormalizedProviderFailure;
+/** The stable diagnostic carrier for normalized provider error facts on an assistant error message. */
+export declare function providerFailureDiagnostic(details: ProviderFailureDetails): {
+    type: string;
+    timestamp: number;
+    details: Record<string, unknown>;
+};
+/** Reads provider facts from the assistant-message diagnostic without trusting arbitrary nested error objects. */
+export declare function extractProviderFailureDetails(message: unknown): ProviderFailureDetails | undefined;

package/dist/core/provider-failure.js

@@ -0,0 +1,86 @@
+import { isRecord } from '../shared/predicates.js';
+export const PROVIDER_FAILURE_DIAGNOSTIC = 'crtr:provider-failure';
+const CAUSE_LIMIT = 8;
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function status(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function code(value) {
+    return typeof value === 'string' || typeof value === 'number' ? value : undefined;
+}
+function record(value) {
+    return isRecord(value) ? value : undefined;
+}
+function failureCause(value) {
+    const message = text(value['errorMessage']) ?? text(value['message']) ?? text(value['reason']) ?? text(value['statusText']);
+    const cause = {
+        ...(message === undefined ? {} : { message }),
+        ...(status(value['status']) === undefined ? {} : { status: status(value['status']) }),
+        ...(code(value['code']) === undefined ? {} : { code: code(value['code']) }),
+        ...(text(value['errno']) === undefined ? {} : { errno: text(value['errno']) }),
+        ...(text(value['body']) === undefined ? {} : { body: text(value['body']) }),
+    };
+    return Object.keys(cause).length === 0 ? undefined : cause;
+}
+/** Converts an arbitrary provider failure into serializable facts before an SDK stream flattens it to `errorMessage`. */
+export function normalizeProviderFailure(error, observed = {}) {
+    const root = record(error);
+    const rootCause = root === undefined ? undefined : failureCause(root);
+    const causes = [];
+    const seen = new Set([error]);
+    let current = root === undefined ? undefined : record(root['cause']);
+    while (current !== undefined && !seen.has(current) && causes.length < CAUSE_LIMIT) {
+        seen.add(current);
+        const cause = failureCause(current);
+        if (cause !== undefined)
+            causes.push(cause);
+        current = record(current['cause']);
+    }
+    const message = rootCause?.message ?? (error instanceof Error ? error.message : undefined) ?? String(error ?? 'Provider request failed');
+    return {
+        message,
+        ...((observed.status ?? rootCause?.status) === undefined ? {} : { status: observed.status ?? rootCause?.status }),
+        ...(rootCause?.code === undefined ? {} : { code: rootCause.code }),
+        ...(rootCause?.errno === undefined ? {} : { errno: rootCause.errno }),
+        ...(rootCause?.body === undefined ? {} : { body: rootCause.body }),
+        ...(causes.length === 0 ? {} : { causes }),
+    };
+}
+/** The stable diagnostic carrier for normalized provider error facts on an assistant error message. */
+export function providerFailureDiagnostic(details) {
+    return { type: PROVIDER_FAILURE_DIAGNOSTIC, timestamp: Date.now(), details: { ...details } };
+}
+function providerFailureDetails(value) {
+    const diagnostics = record(value)?.['diagnostics'];
+    if (!Array.isArray(diagnostics))
+        return undefined;
+    for (const diagnostic of diagnostics) {
+        const diagnosticRecord = record(diagnostic);
+        if (diagnosticRecord?.['type'] !== PROVIDER_FAILURE_DIAGNOSTIC)
+            continue;
+        const details = record(diagnosticRecord['details']);
+        if (details === undefined)
+            continue;
+        const causes = Array.isArray(details['causes'])
+            ? details['causes'].flatMap((item) => {
+                const cause = record(item);
+                const normalized = cause === undefined ? undefined : failureCause(cause);
+                return normalized === undefined ? [] : [normalized];
+            })
+            : undefined;
+        return {
+            ...(status(details['status']) === undefined ? {} : { status: status(details['status']) }),
+            ...(code(details['code']) === undefined ? {} : { code: code(details['code']) }),
+            ...(text(details['errno']) === undefined ? {} : { errno: text(details['errno']) }),
+            ...(text(details['body']) === undefined ? {} : { body: text(details['body']) }),
+            ...(causes === undefined || causes.length === 0 ? {} : { causes }),
+        };
+    }
+    return undefined;
+}
+/** Reads provider facts from the assistant-message diagnostic without trusting arbitrary nested error objects. */
+export function extractProviderFailureDetails(message) {
+    return providerFailureDetails(message);
+}