@north-light/crouter 0.3.302 → 0.3.304

package/dist/daemon/api/handlers/reports.js

@@ -15,7 +15,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode } from '../../../core/canvas/canvas.js';
 import { push, FinalizationError } from '../../../core/feed/feed.js';
-import { autoDropCleanManagedWorktree, branchIsPushedAtCurrentTip, hasOpenManagedWorktree, missingWorktreeRecoveryHint } from '../../../core/worktree.js';
+import { branchIsPushedAtCurrentTip, hasOpenManagedWorktree, missingWorktreeRecoveryHint } from '../../../core/worktree.js';
+import { autoDropCleanManagedWorktreeAsync } from '../../../core/worktree-mutation-async.js';
 import { reportsDir } from '../../../core/canvas/paths.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { InputError } from '../../../core/io.js';
@@ -89,7 +90,7 @@ async function handlePush(ctx) {
 async function guardFinalWorktree(id) {
     if (!hasOpenManagedWorktree(getNode(id)))
         return undefined;
-    const dropped = autoDropCleanManagedWorktree(id);
+    const dropped = await autoDropCleanManagedWorktreeAsync(id);
     if (dropped !== null)
         return dropped.worktree_path;
     if (await branchIsPushedAtCurrentTip(getNode(id).managed_worktree))

package/dist/daemon/api/handlers/worktree.js

@@ -12,21 +12,22 @@
 // all of that onto `CrtrError` for every route that can raise it — so the CLI
 // leaf can reconstruct the original agent-facing contract instead of collapsing
 // to a generic status code.
-import { abandonManagedWorktree, closeManagedWorktree } from '../../../core/worktree.js';
+import { closeManagedWorktreeAsync } from '../../../core/worktree-close.js';
+import { abandonManagedWorktreeAsync } from '../../../core/worktree-mutation-async.js';
 import { listQuarantinedManagedWorktrees } from '../../../core/worktree-quarantine.js';
 import { usage } from '../../../core/errors.js';
-function handleWorktreeClose(ctx) {
+async function handleWorktreeClose(ctx) {
     const id = ctx.params['id'];
-    // No requireMeta: closeManagedWorktree already throws the precise
+    // No requireMeta: closeManagedWorktreeAsync already throws the precise
     // `unknown_node` / `no_managed_worktree` WorktreeError for a bad id.
-    return { status: 200, body: closeManagedWorktree(id) };
+    return { status: 200, body: await closeManagedWorktreeAsync(id) };
 }
-function handleWorktreeAbandon(ctx) {
+async function handleWorktreeAbandon(ctx) {
     const rawBy = ctx.body?.['by'];
     const by = typeof rawBy === 'string' ? rawBy.trim() : '';
     if (by === '')
         throw usage('abandon requires a non-empty invoking identity', { received: ctx.body, next: 'Pass the invoking node id or human identity.' });
-    return { status: 200, body: abandonManagedWorktree(ctx.params['id'], by) };
+    return { status: 200, body: await abandonManagedWorktreeAsync(ctx.params['id'], by) };
 }
 async function handleQuarantinedWorktrees() {
     return { status: 200, body: await listQuarantinedManagedWorktrees() };

package/dist/daemon/fleet.d.ts

@@ -2,7 +2,7 @@ import { type NodeMeta } from '../core/canvas/index.js';
 import { type FleetEntry, type FleetExitStatus, type FleetRegistry } from '../core/runtime/fleet.js';
 import type { NodeOutcomeDetailV1, TerminalReason } from '../core/canvas/types.js';
 import type { HostHandle } from '../core/runtime/host.js';
-export declare function surfaceBootFailure(meta: NodeMeta): Promise<void>;
+export declare function surfaceBootFailure(meta: NodeMeta, exitStatus?: FleetExitStatus): Promise<void>;
 /** Whether a dead relaunch should resume the saved session strictly, or retry
  *  as a fresh cycle instead. A cycling attempt (cycle_pending) that dies before
  *  session_start must retry AS a cycle: the fresh branch it was opening is not

package/dist/daemon/fleet.js

@@ -34,16 +34,18 @@ import { brokerThresholdsForDaemon } from '../core/runtime/fleet.js';
  *  When the daemon observes that death it errors LOUDLY up the spine: an
  *  urgent push so the parent learns the child failed to launch instead of just
  *  seeing a silent `dead`. */
-function bootFailureBody(meta) {
+function bootFailureBody(meta, exitStatus) {
+    const status = exitStatus === undefined
+        ? 'The daemon did not observe an exit status.'
+        : `The observed exit status was code ${exitStatus.code ?? 'null'}, signal ${exitStatus.signal ?? 'null'}.`;
     return (`⚠ Spawn failed — \`${meta.name}\` (${meta.kind}) never started.\n\n` +
         `Its pi vehicle exited before the session came up (no pi_session_id was ever ` +
-        `recorded), so the node produced no output. This is almost always a transient ` +
-        `launch failure — e.g. resource pressure when several nodes boot at once — not ` +
-        `a fault in the task itself.\n\n` +
-        `If the work still needs doing, re-spawn it; if spawns keep dying, spawn fewer at a time.`);
+        `recorded), so the node produced no output. ${status}\n\n` +
+        `Inspect canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`.\n\n` +
+        `If the work still needs doing, re-spawn it.`);
 }
-export async function surfaceBootFailure(meta) {
-    await pushUrgent(meta.node_id, bootFailureBody(meta), { from: meta.node_id });
+export async function surfaceBootFailure(meta, exitStatus) {
+    await pushUrgent(meta.node_id, bootFailureBody(meta, exitStatus), { from: meta.node_id });
 }
 async function surfaceCrashLoop(meta) {
     const transportPoison = readTransportPoisonVerdict(meta.node_id);
@@ -137,6 +139,8 @@ export class DaemonFleet {
     /** Brokers deliberately interrupted by profile pause. This belongs to the
      * exact child, so a resume cannot turn its later SIGTERM exit into a crash. */
     #profilePauseInterruptions = new Set();
+    /** Exit status held only until dead-row policy surfaces this broker's boot failure. */
+    #exitStatuses = new Map();
     #lastCapacityLogAt = Number.NEGATIVE_INFINITY;
     constructor(opts) {
         this.#epoch = opts.epoch;
@@ -155,6 +159,7 @@ export class DaemonFleet {
             throw new Error(`fleet: refusing to register ${nodeId} with no pid`);
         }
         this.#reservations.delete(nodeId);
+        this.#exitStatuses.delete(nodeId);
         this.#map.set(nodeId, { pid: handle.pid, handle });
     }
     has(nodeId) {
@@ -215,6 +220,7 @@ export class DaemonFleet {
     forget(nodeId) {
         this.#map.delete(nodeId);
         this.#reservations.delete(nodeId);
+        this.#exitStatuses.delete(nodeId);
     }
     onChildExit(nodeId, status) {
         // The real child exit is the liveness boundary. Its queued observation only
@@ -225,6 +231,10 @@ export class DaemonFleet {
         const uptimeMs = Number.isFinite(launchedMs) ? Math.max(0, this.#now() - launchedMs) : null;
         const consecutiveFailures = meta?.respawn_failures ?? 0;
         this.#map.delete(nodeId);
+        if (meta?.status === 'done' || meta?.status === 'canceled' || meta?.status === 'dead')
+            this.#exitStatuses.delete(nodeId);
+        else
+            this.#exitStatuses.set(nodeId, status);
         this.#enqueue(() => this.#emitExitObserved(nodeId, status, uptimeMs, consecutiveFailures));
     }
     deliverExit(nodeId, status) {
@@ -232,7 +242,14 @@ export class DaemonFleet {
     }
     /** The node-lifecycle tick's enactment entry. */
     async applyDeadRowPolicy(nodeId) {
-        await this.#applyPolicy(nodeId);
+        const exitStatus = this.#exitStatuses.get(nodeId);
+        try {
+            await this.#applyPolicy(nodeId, exitStatus);
+        }
+        finally {
+            if (this.#exitStatuses.get(nodeId) === exitStatus)
+                this.#exitStatuses.delete(nodeId);
+        }
     }
     /** A revive refusal before its launch try/catch leaves the row active but
      *  with no fleet entry. Convert that otherwise-silent strand into the same
@@ -267,10 +284,10 @@ export class DaemonFleet {
             },
         });
     }
-    async #applyPolicy(nodeId) {
-        return this.#decideAndEnact(nodeId);
+    async #applyPolicy(nodeId, exitStatus) {
+        return this.#decideAndEnact(nodeId, exitStatus);
     }
-    async #decideAndEnact(nodeId) {
+    async #decideAndEnact(nodeId, exitStatus) {
         const meta = getNode(nodeId);
         if (meta !== null && isProfilePaused(meta.profile_id)) {
             clearRespawnPolicy(nodeId);
@@ -319,9 +336,10 @@ export class DaemonFleet {
                 await this.#terminalize(nodeId, meta, {
                     event: 'broker.boot.failed',
                     reason: 'boot_failed',
-                    detail: { schema: 'crtr.node-outcome-detail/v1', message: bootFailureBody(meta) },
+                    detail: { schema: 'crtr.node-outcome-detail/v1', message: bootFailureBody(meta, exitStatus) },
                     wake: `Child crashed — ${fullName(meta)} (${nodeId}) exited before its session ever came up and is now dead. ` +
                         `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`,
+                    surface: () => surfaceBootFailure(meta, exitStatus),
                 });
                 break;
             case 'respawn-fresh':

package/dist/daemon/manage.d.ts

@@ -50,12 +50,14 @@ export interface SpawnDaemonResult {
     running?: true;
     /** Present with `running:true` when the Unix API socket is not serving. */
     serving?: false;
-    /** Recovery instruction for a live but non-serving daemon. */
-    next?: string;
+    /** The final `/healthz` probe failure when a live owner misses readiness. */
+    probe_error?: string;
 }
-/** True only when the mandatory Unix API socket answers `/healthz`. This is
- * deliberately separate from `isDaemonRunning()`: a pidfile remains useful for
- * identifying the process an operator must stop, but it is not readiness. */
+/** Make one `/healthz` observation without client-side recovery. The caller
+ * owns the availability window, so this probe cannot extend it. */
+export declare function probeDaemonServing(timeoutMs?: number): Promise<void>;
+/** True only when one mandatory Unix API socket probe answers `/healthz`.
+ * A pidfile identifies an owner; it is never readiness. */
 export declare function isDaemonServing(): Promise<boolean>;
 export interface DaemonWaitDeps {
     readPidfile?: () => number | null;
@@ -69,6 +71,7 @@ export interface DaemonStartupDeps extends DaemonWaitDeps {
         signal: NodeJS.Signals | null;
     } | null;
     isDaemonServing?: () => Promise<boolean>;
+    probeDaemonServing?: (timeoutMs: number) => Promise<void>;
 }
 /** Thrown when the spawned daemon exited on `DAEMON_EXIT_STARTUP_BLOCKED` — a
  *  standing condition (a blocked on-disk migration) that the very next spawn

package/dist/daemon/manage.js

@@ -19,7 +19,7 @@ import { clearDaemonStartupBlocked, daemonStartupBlocked } from './startup-block
 import { exclusiveLockOwnerPid } from '../core/exclusive-lock.js';
 import { onDiskMigrationLockPath } from '../core/canvas/paths.js';
 import { envNoDaemonAutostart } from '../shared/env.js';
-import { CrtrClient } from '../api/index.js';
+import { CrtrClient, waitForDaemonAvailability } from '../api/index.js';
 // Daemon env sanitization
 /** Env keys that must NEVER reach the daemon process. Restarting crtrd is
  *  overwhelmingly done from inside an agent node's own bash tool (`crtr sys
@@ -208,16 +208,20 @@ const DAEMON_VERIFY_POLL_MS = 10;
 /** A status/start readiness probe must not hang behind a daemon that accepts a
  * Unix connection but never answers it. */
 const DAEMON_HEALTH_PROBE_TIMEOUT_MS = 1_000;
-/** True only when the mandatory Unix API socket answers `/healthz`. This is
- * deliberately separate from `isDaemonRunning()`: a pidfile remains useful for
- * identifying the process an operator must stop, but it is not readiness. */
+/** Make one `/healthz` observation without client-side recovery. The caller
+ * owns the availability window, so this probe cannot extend it. */
+export async function probeDaemonServing(timeoutMs = DAEMON_HEALTH_PROBE_TIMEOUT_MS) {
+    const probeTimeoutMs = Math.min(timeoutMs, DAEMON_HEALTH_PROBE_TIMEOUT_MS);
+    const health = await CrtrClient.forLocalSocket({ autostart: false, timeoutMs: probeTimeoutMs }).probeHealthz(probeTimeoutMs);
+    if (!health.ok)
+        throw new Error('crtrd health check reported not ready');
+}
+/** True only when one mandatory Unix API socket probe answers `/healthz`.
+ * A pidfile identifies an owner; it is never readiness. */
 export async function isDaemonServing() {
     try {
-        const health = await CrtrClient.forLocalSocket({
-            autostart: false,
-            timeoutMs: DAEMON_HEALTH_PROBE_TIMEOUT_MS,
-        }).healthz();
-        return health.ok;
+        await probeDaemonServing();
+        return true;
     }
     catch {
         return false;
@@ -255,32 +259,47 @@ export async function verifyDaemonStartup(pid, timeoutMs = DAEMON_STARTUP_WINDOW
     const read = deps.readPidfile ?? readPidfile;
     const alive = deps.isPidAlive ?? isPidAlive;
     const exited = deps.childExited;
-    const serving = deps.isDaemonServing ?? isDaemonServing;
+    const serving = deps.isDaemonServing;
+    const probeServing = deps.probeDaemonServing ?? (async (remainingMs) => {
+        if (serving !== undefined) {
+            if (await serving())
+                return;
+            throw new Error('crtrd health check reported not ready');
+        }
+        await probeDaemonServing(remainingMs);
+    });
     const sleep = deps.sleepMs ?? sleepMs;
     const now = deps.now ?? Date.now;
-    const deadline = now() + timeoutMs;
-    while (now() <= deadline) {
-        const owner = read();
-        if (owner !== null && alive(owner) && await serving())
-            return owner === pid ? null : owner;
-        const exitState = exited?.();
-        if (exitState !== null && exitState !== undefined) {
-            if (exitState.signal !== null) {
-                throw new Error(`daemon ${pid} exited before becoming ready (by ${exitState.signal})`);
-            }
-            if (exitState.code === DAEMON_EXIT_STARTUP_BLOCKED) {
-                throw new DaemonStartupBlockedError(pid);
-            }
-            if (exitState.code !== 0) {
-                throw new Error(`daemon ${pid} exited before becoming ready (with exit code ${exitState.code ?? '?'})`);
+    let owner = null;
+    let terminalError = null;
+    await waitForDaemonAvailability({
+        windowMs: timeoutMs,
+        pollIntervalMs: DAEMON_VERIFY_POLL_MS,
+        now,
+        sleep,
+        retry: (error) => error !== terminalError,
+        probe: async (remainingMs) => {
+            const candidate = read();
+            if (candidate === null || !alive(candidate)) {
+                const exitState = exited?.();
+                if (exitState !== null && exitState !== undefined) {
+                    if (exitState.signal !== null)
+                        terminalError = new Error(`daemon ${pid} exited before becoming ready (by ${exitState.signal})`);
+                    else if (exitState.code === DAEMON_EXIT_STARTUP_BLOCKED)
+                        terminalError = new DaemonStartupBlockedError(pid);
+                    else if (exitState.code !== 0)
+                        terminalError = new Error(`daemon ${pid} exited before becoming ready (with exit code ${exitState.code ?? '?'})`);
+                    // A clean exit can have lost the ownership claim, so keep observing.
+                    if (terminalError !== null)
+                        throw terminalError;
+                }
+                throw new Error(`daemon ${pid} has no live pidfile owner`);
             }
-            // Clean code-0 exit: a possible ownership-claim loser, not readiness.
-            // Keep polling the same deadline for a different live pidfile owner; the
-            // loop's timeout throw below fires if none appears.
-        }
-        await sleep(DAEMON_VERIFY_POLL_MS);
-    }
-    throw new Error(`daemon ${pid} did not become ready within ${timeoutMs}ms`);
+            await probeServing(remainingMs);
+            owner = candidate;
+        },
+    });
+    return owner === pid ? null : owner;
 }
 /** Wait until a signaled daemon has exited and relinquished its pidfile. This
  *  makes a following start safe to claim the singleton rather than racing its
@@ -355,15 +374,19 @@ export async function stopDaemonProcess(pid, timeoutMs = DAEMON_SHUTDOWN_WINDOW_
 export async function spawnDaemon() {
     const recordedPid = readPidfile();
     if (recordedPid !== null && isPidAlive(recordedPid)) {
-        if (await isDaemonServing())
+        try {
+            await probeDaemonServing();
             return { started: false, existing_pid: recordedPid };
-        return {
-            started: false,
-            existing_pid: recordedPid,
-            running: true,
-            serving: false,
-            next: 'Run `crtr sys daemon stop` to release the non-serving daemon before starting it again.',
-        };
+        }
+        catch (error) {
+            return {
+                started: false,
+                existing_pid: recordedPid,
+                running: true,
+                serving: false,
+                probe_error: error.message,
+            };
+        }
     }
     // Ensure the canvas home directory exists so the daemon can write its pidfile.
     mkdirSync(crtrHome(), { recursive: true });

package/dist/daemon/reconcilers/managed-worktree-sweep.js

@@ -30,6 +30,12 @@ const TERMINAL_STATUSES = ['done', 'dead', 'canceled'];
 function isTerminal(row) {
     return TERMINAL_STATUSES.includes(row.status);
 }
+/** A closed record already has an explicit close disposition. An open record
+ *  reaches the sweep only when its owner published a final result; a crash or
+ *  cancellation leaves its managed checkout available for explicit recovery. */
+function hasSweepDisposition(row, wt) {
+    return wt?.state === 'closed' || (wt?.state === 'open' && row.status === 'done' && row.final_report !== null);
+}
 /** Is this node's engine definitively gone?
  *
  *  Terminal status alone is not enough: `push final` marks a node `done` while
@@ -49,6 +55,8 @@ function engineIsGone(row, fleet, snapshot) {
         return false;
     if (!isTerminal(row))
         return false;
+    if (!hasSweepDisposition(row, getNode(row.node_id)?.managed_worktree))
+        return false;
     return recordedPidLiveness(row.pi_pid, row.pi_pid_identity, snapshot) === 'dead';
 }
 /** The eligibility recheck the reconciliation runs immediately before EVERY Git
@@ -70,6 +78,8 @@ function eligibilityGuard(row, fleet) {
             const current = getRow(nodeId);
             if (current === null || !isTerminal(current) || current.frozen_at !== null)
                 return false;
+            if (!hasSweepDisposition(current, getNode(nodeId)?.managed_worktree))
+                return false;
             return current.pi_pid === pid && current.pi_pid_identity === identity;
         },
     };
@@ -120,6 +130,8 @@ export class ManagedWorktreeSweepReconciler {
             }
             if (!isReconcilable(wt) || wt == null)
                 continue;
+            if (!hasSweepDisposition(row, wt))
+                continue;
             if (!isDueForSweep(wt, now))
                 continue;
             due.push(row.node_id);

package/dist/daemon/reconcilers/node-lifecycle/tick.d.ts

@@ -7,12 +7,6 @@ export interface NodeLifecycleContext {
     rows: readonly NodeRow[];
     fleet: FleetRegistry;
 }
-/** Whether this row should have a live engine right now. An active row always
- *  should — that status IS the claim that it is executing. An idle row was
- *  deliberately released and holds no engine on purpose: only mail it has not
- *  seen brings one back, because a live obligation keeps a node WAKEABLE rather
- *  than awake, and relaunching on one would re-release it every tick. */
-export declare function wantsExecution(row: NodeRow): boolean;
 export declare class NodeLifecycleReconciler {
     private readonly freezeLane;
     run(now: number, ctx: NodeLifecycleContext): Promise<FrozenCounts>;

package/dist/daemon/reconcilers/node-lifecycle/tick.js

@@ -12,7 +12,6 @@ import { isSafeNodeId } from '../../../core/canvas/paths.js';
 import { recordedPidLiveness } from '../../../core/canvas/pid.js';
 import { emitEvent } from '../../../core/events/emit.js';
 import { operationIdContext } from '../../../core/events/operation-id.js';
-import { hasUnseenWakeMail } from '../../../core/feed/inbox.js';
 import { hasCleanAbort, isBusy } from '../../../core/runtime/busy.js';
 import { isProfilePaused } from '../../../core/profiles/manifest.js';
 import { classifyDeadNode } from '../../fleet.js';
@@ -20,21 +19,10 @@ import { applyParkEvent, hasPendingWake, parkEvent } from '../live-obligation.js
 import { FreezeLaneReconciler } from './freeze-lane.js';
 import { isInBackoff } from './respawn-policy.js';
 import { handleTerminatingRow } from './terminating.js';
+import { wantsExecution } from './wants-execution.js';
 function isTerminal(row) {
     return row.status === 'done' || row.status === 'canceled' || row.status === 'dead';
 }
-/** Whether this row should have a live engine right now. An active row always
- *  should — that status IS the claim that it is executing. An idle row was
- *  deliberately released and holds no engine on purpose: only mail it has not
- *  seen brings one back, because a live obligation keeps a node WAKEABLE rather
- *  than awake, and relaunching on one would re-release it every tick. */
-export function wantsExecution(row) {
-    if (row.status === 'active')
-        return true;
-    if (row.status !== 'idle')
-        return false;
-    return hasUnseenWakeMail(row.node_id);
-}
 export class NodeLifecycleReconciler {
     freezeLane = new FreezeLaneReconciler();
     async run(now, ctx) {

package/dist/daemon/reconcilers/node-lifecycle/wants-execution.d.ts

@@ -0,0 +1,5 @@
+import type { NodeRow } from '../../../core/canvas/index.js';
+/** Whether the lifecycle tick must ensure this row has an engine. The durable
+ * message handler calls this after appending its entry: that append makes the
+ * idle branch's unseen-wake-mail check true for a wake-capable entry. */
+export declare function wantsExecution(row: Pick<NodeRow, 'node_id' | 'status'>): boolean;

package/dist/daemon/reconcilers/node-lifecycle/wants-execution.js

@@ -0,0 +1,11 @@
+import { hasUnseenWakeMail } from '../../../core/feed/inbox.js';
+/** Whether the lifecycle tick must ensure this row has an engine. The durable
+ * message handler calls this after appending its entry: that append makes the
+ * idle branch's unseen-wake-mail check true for a wake-capable entry. */
+export function wantsExecution(row) {
+    if (row.status === 'active')
+        return true;
+    if (row.status !== 'idle')
+        return false;
+    return hasUnseenWakeMail(row.node_id);
+}

package/dist/pi-extensions/__tests__/canvas-context-intro.test.js

@@ -5,12 +5,16 @@
 import { test, before, after, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { existsSync, mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { registerCanvasContextIntro, CONTEXT_INTRO_CUSTOM_TYPE, } from '../canvas-context-intro.js';
 import { registerCanvasDocSubstrate } from '../canvas-doc-substrate.js';
 import { buildContextBearings as buildContextIntro } from '../../core/runtime/bearings.js';
 import { installPersonaTransitionGate } from '../../core/runtime/broker-persona-guidance.js';
+import { FaultRetry } from '../../core/runtime/broker/fault-retry.js';
+import { readFault } from '../../core/runtime/fault.js';
+import { ApiError } from '../../api/errors.js';
 import { createNode, deleteNode, getNode, updateNode } from '../../core/canvas/canvas.js';
 import { apiSocketPath } from '../../core/canvas/paths.js';
 import { createApiServer } from '../../daemon/api/server.js';
@@ -32,6 +36,23 @@ async function waitForSocket(path) {
     }
     throw new Error(`api socket never bound at ${path}`);
 }
+async function listenUnavailableApi(path) {
+    const unavailable = createServer((_request, response) => {
+        response.writeHead(503, { 'content-type': 'application/json' });
+        response.end(JSON.stringify({ error: { code: 'daemon_unavailable', message: 'local daemon connection refused' } }));
+    });
+    await new Promise((resolve, reject) => {
+        unavailable.once('error', reject);
+        unavailable.listen(path, () => {
+            unavailable.off('error', reject);
+            resolve();
+        });
+    });
+    return unavailable;
+}
+function closeHttpServer(server) {
+    return new Promise((resolve, reject) => server.close((error) => error === undefined ? resolve() : reject(error)));
+}
 function node(id, over = {}) {
     return {
         node_id: id,
@@ -322,6 +343,68 @@ test('child /new commits its baseline before ack and the provider gate delivers
             process.env['CRTR_PROFILE_ID'] = previousProfile;
     }
 });
+test('a typed local API error remains a retryable broker-to-daemon fault after settlement', async () => {
+    createNode(node('persona-transport', {
+        persona_ack: { kind: 'review', mode: 'base', lifecycle: 'terminal' },
+    }));
+    await server.close();
+    let unavailable;
+    try {
+        unavailable = await listenUnavailableApi(apiSocketPath());
+        const messages = [];
+        const agent = {
+            state: { messages },
+            transformContext: async (context) => context,
+        };
+        installPersonaTransitionGate('persona-transport', {
+            agent,
+            sessionManager: {
+                appendCustomMessageEntry: () => undefined,
+            },
+        });
+        await assert.rejects(() => agent.transformContext([{ role: 'user', content: 'continue' }]), (error) => error instanceof ApiError && error.status === 503 && error.code === 'daemon_unavailable');
+        assert.deepEqual(readFault('persona-transport'), {
+            link: 'broker↔crtrd',
+            op: 'persona transition',
+            kind: 'connection',
+            retry: { disposition: 'manual' },
+            message: 'local daemon connection refused',
+            since: readFault('persona-transport')?.since,
+            operation_id: readFault('persona-transport')?.operation_id,
+        }, 'the typed daemon transport error is recorded before Pi turns it into a generic agent error');
+        const session = {
+            sessionManager: { getLeafId: () => 'persona-transport-leaf' },
+            model: undefined,
+        };
+        const generation = {
+            id: 1,
+            session,
+            fallback: { blocked: false },
+            stagedProviderAgentEnd: {
+                messages: [{ role: 'assistant', stopReason: 'error', errorMessage: 'local daemon connection refused' }],
+            },
+            stagedWatchdogAbort: false,
+            stagedRefreshAbort: false,
+            stagedOverflowFailure: null,
+            executingTools: new Set(),
+        };
+        new FaultRetry({
+            nodeId: 'persona-transport',
+            currentSession: () => session,
+            installedGeneration: () => generation,
+        }).publishSettledProviderFault(generation);
+        const fault = readFault('persona-transport');
+        assert.equal(fault?.link, 'broker↔crtrd');
+        assert.equal(fault?.kind, 'connection');
+        assert.equal(fault?.retry.disposition, 'manual');
+    }
+    finally {
+        if (unavailable !== undefined)
+            await closeHttpServer(unavailable);
+        server = createApiServer();
+        await waitForSocket(apiSocketPath());
+    }
+});
 test('resume idempotency uses the exact details stamp independent of block text', async () => {
     createNode(node('stampD'));
     // The exact node-id stamp is authoritative even when prose carries no id.

package/dist/pi-extensions/__tests__/integration/canvas-bash-valve.test.d.ts

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