@north-light/crouter 0.3.154

package/dist/core/runtime/connectivity.js

@@ -0,0 +1,73 @@
+// connectivity.ts — "is the network reachable right now" for the daemon.
+//
+// Used by the daemon's connectivity-recovery pass to decide whether a node
+// parked on a CONNECTION error should be nudged to continue. The signal the
+// user thinks in terms of is "my wifi is back" — so this is a coarse internet-
+// reachability probe, NOT a per-provider health check.
+//
+// Implementation: a fast TCP connect to a couple of well-known anycast resolvers
+// on 443. RAW IPs (no DNS lookup) on purpose — DNS itself fails when the network
+// is down, so resolving a hostname would conflate "wifi down" with "DNS down" and
+// add latency; the IPs below are stable anycast addresses. Online = ANY target
+// accepts a TCP connection within the timeout. Never throws.
+//
+// The broker calls this probe for connection-fault retries; tests can stub it
+// directly where the retry loop is exercised, so the network state stays deterministic.
+import { Socket } from 'node:net';
+/** Anycast resolvers reachable from essentially any connected network. A single
+ *  success means the box has working internet; we don't care WHICH target. */
+const PROBE_TARGETS = [
+    { host: '1.1.1.1', port: 443 }, // Cloudflare
+    { host: '8.8.8.8', port: 443 }, // Google
+];
+/** Default per-target connect timeout. Short — a healthy network connects in
+ *  tens of ms; a down network should be declared down quickly so the daemon tick
+ *  isn't held up. */
+export const PROBE_TIMEOUT_MS = 3000;
+/** Resolve true iff a TCP connection to host:port completes within timeoutMs.
+ *  Any error/timeout resolves false (never rejects). The socket is always torn
+ *  down. Exported for unit testing against a local listener. */
+export function tcpReachable(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const sock = new Socket();
+        let settled = false;
+        const done = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* already torn down */
+            }
+            resolve(ok);
+        };
+        sock.setTimeout(timeoutMs);
+        sock.once('connect', () => done(true));
+        sock.once('timeout', () => done(false));
+        sock.once('error', () => done(false));
+        try {
+            sock.connect(port, host);
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+/** True when the box can reach the internet (any PROBE_TARGET accepts a TCP
+ *  connection within the timeout). The broker uses this for connection-fault
+ *  retries. Never throws. */
+export async function probeOnline(timeoutMs = PROBE_TIMEOUT_MS) {
+    try {
+        const results = await Promise.all(PROBE_TARGETS.map((t) => tcpReachable(t.host, t.port, timeoutMs)));
+        return results.some((ok) => ok);
+    }
+    catch {
+        // Promise.all only rejects if a target promise rejects — they never do, but
+        // be defensive: an unexpected throw reads as "can't tell", and "can't tell"
+        // must never claim the network is UP (which would nudge nodes into a retry
+        // that fails again). Treat as offline.
+        return false;
+    }
+}

package/dist/core/runtime/deliver-live.d.ts

@@ -0,0 +1,26 @@
+export interface LiveCustomMessage {
+    customType: string;
+    content: string;
+    /** Omitted → pushed straight onto the message list (lands first in an empty
+     *  session). `nextTurn` → folded into whatever turn comes next. */
+    deliverAs?: 'nextTurn';
+    /** Extension-only metadata, never sent to the LLM. */
+    details?: {
+        nodeId: string;
+    };
+}
+/** Deliver `message` into `nodeId`'s live session. Resolves without doing
+ *  anything when the node has no live broker. Rejects when a live broker cannot
+ *  be reached or refuses the frame — the caller decides what that means (for a
+ *  warm claim it is fatal: a node wearing the wrong bearings is worse than a
+ *  slow one, so the spare is abandoned and the create goes cold). */
+export declare function deliverCustomMessageLive(nodeId: string, message: LiveCustomMessage): Promise<void>;
+/** Build and deliver `nodeId`'s bearings into its live session. Called by the
+ *  warm-pool claim once the row already wears the claimant's kind/mode/name, so
+ *  the identity assertion, the knowledge catalog, and the `<project_context>`
+ *  environment snapshot are all built for the node being handed out.
+ *
+ *  The `details.nodeId` stamp is what the context-intro extension's idempotency
+ *  guard matches on, so a LATER revive of this node sees its own bearings
+ *  already on the branch and does not inject a second copy. */
+export declare function deliverBearingsLive(nodeId: string): Promise<void>;

package/dist/core/runtime/deliver-live.js

@@ -0,0 +1,63 @@
+// deliver-live.ts — push a custom message into a node's ALREADY-BOOTED session
+// without waking it. The answer to "what can a live engine still be told?" for
+// everything that is a CLAIM-time property of a warm spare rather than a
+// mint-time one.
+//
+// Two callers today, both on the warm-pool claim path:
+//   • bearings (`deliverBearingsLive`) — a spare mints with NO bearings, because
+//     a block built at mint would assert the SPARE's persona (always
+//     `general`/`base`) and a snapshot of the repo as it looked whenever the
+//     spare happened to boot. Built and delivered here instead, it is exact for
+//     the node actually handed out. Pushed with no delivery option, so at the
+//     idle start of a still-empty session it lands as the FIRST entry, exactly
+//     where the context-intro extension's session_start injection would have put
+//     it — ahead of the claimant's kickoff prompt.
+//   • situational context (`situational-live.ts`, which layers the durable
+//     sidecar write over this) — `nextTurn`, so it rides the claimant's first
+//     real turn instead of starting one nobody asked for.
+//
+// A DORMANT node needs neither: its next revive renders both into the kickoff.
+import { getNode } from '../canvas/index.js';
+import { oneShotControllerRequest } from './broker-request.js';
+import { isBrokerLive } from './model-swap.js';
+import { buildContextBearings, CONTEXT_INTRO_CUSTOM_TYPE } from './bearings.js';
+/** Deliver `message` into `nodeId`'s live session. Resolves without doing
+ *  anything when the node has no live broker. Rejects when a live broker cannot
+ *  be reached or refuses the frame — the caller decides what that means (for a
+ *  warm claim it is fatal: a node wearing the wrong bearings is worse than a
+ *  slow one, so the spare is abandoned and the create goes cold). */
+export async function deliverCustomMessageLive(nodeId, message) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        throw new Error(`deliverCustomMessageLive: unknown node ${nodeId}`);
+    if (!isBrokerLive(meta))
+        return;
+    await oneShotControllerRequest({
+        nodeId,
+        what: `the ${message.customType} delivery`,
+        ackFor: 'deliver_custom_message',
+        frame: () => ({
+            type: 'deliver_custom_message',
+            customType: message.customType,
+            content: message.content,
+            ...(message.deliverAs !== undefined ? { deliverAs: message.deliverAs } : {}),
+            ...(message.details !== undefined ? { details: message.details } : {}),
+        }),
+        result: () => undefined,
+    });
+}
+/** Build and deliver `nodeId`'s bearings into its live session. Called by the
+ *  warm-pool claim once the row already wears the claimant's kind/mode/name, so
+ *  the identity assertion, the knowledge catalog, and the `<project_context>`
+ *  environment snapshot are all built for the node being handed out.
+ *
+ *  The `details.nodeId` stamp is what the context-intro extension's idempotency
+ *  guard matches on, so a LATER revive of this node sees its own bearings
+ *  already on the branch and does not inject a second copy. */
+export async function deliverBearingsLive(nodeId) {
+    await deliverCustomMessageLive(nodeId, {
+        customType: CONTEXT_INTRO_CUSTOM_TYPE,
+        content: buildContextBearings(nodeId),
+        details: { nodeId },
+    });
+}

package/dist/core/runtime/fault-recovery-nudge.d.ts

@@ -0,0 +1,3 @@
+export declare const AUTH_FAULT_RECOVERY_BODY = "Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.";
+export declare const CONNECTION_FAULT_RECOVERY_BODY = "The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.";
+export declare const PROVIDER_FAULT_RECOVERY_BODY = "Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.";

package/dist/core/runtime/fault-recovery-nudge.js

@@ -0,0 +1,3 @@
+export const AUTH_FAULT_RECOVERY_BODY = 'Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.';
+export const CONNECTION_FAULT_RECOVERY_BODY = 'The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.';
+export const PROVIDER_FAULT_RECOVERY_BODY = 'Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.';

package/dist/core/runtime/fault-recovery.d.ts

@@ -0,0 +1,23 @@
+import type { Fault, FaultKind } from '../fault-classifier.js';
+export type FaultRecoveryGate = 'online' | 'time' | 'none';
+export interface FaultRecoveryPolicy {
+    kind: FaultKind;
+    gate: FaultRecoveryGate;
+    max: number;
+    baseDelayMs: number;
+    capDelayMs: number;
+    fatal: boolean;
+}
+export interface FaultRetryPlan {
+    fault: Fault;
+    attempt: number;
+    max: number;
+    nextAt: string;
+    delayMs: number;
+}
+export declare function policyFor(kind: FaultKind): FaultRecoveryPolicy;
+export declare function nextFaultRetry(fault: Fault, now: number, opts?: {
+    retryAfterMs?: number | null;
+    jitterMs?: (fault: Fault, attempt: number) => number;
+}): FaultRetryPlan | null;
+export declare function markFatalOnExhaust(fault: Fault): Fault;

package/dist/core/runtime/fault-recovery.js

@@ -0,0 +1,83 @@
+const POLICIES = {
+    connection: { kind: 'connection', gate: 'online', max: 8, baseDelayMs: 5_000, capDelayMs: 60_000, fatal: false },
+    'rate-limit': { kind: 'rate-limit', gate: 'time', max: 6, baseDelayMs: 30_000, capDelayMs: 5 * 60_000, fatal: false },
+    overloaded: { kind: 'overloaded', gate: 'time', max: 6, baseDelayMs: 10_000, capDelayMs: 2 * 60_000, fatal: false },
+    auth: { kind: 'auth', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    protocol: { kind: 'protocol', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    'context-overflow': { kind: 'context-overflow', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    other: { kind: 'other', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    // A wedge is a daemon-detected stall, never auto-retried — recovery is a
+    // deliberate agent/operator decision (kill the runaway subprocess), not a
+    // provider back-off.
+    wedged: { kind: 'wedged', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    // A launch-time model resolution failure (unregistered/unauthenticated spec) —
+    // never auto-retried, since retrying with the same unresolved model would just
+    // fail again identically. Fixing it requires a new --model or new credentials.
+    'model-not-found': { kind: 'model-not-found', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+};
+export function policyFor(kind) {
+    return POLICIES[kind];
+}
+function clampDelay(delayMs, capMs) {
+    if (!Number.isFinite(delayMs) || delayMs <= 0)
+        return 0;
+    return Math.min(Math.max(1, Math.round(delayMs)), capMs);
+}
+function defaultOverloadedJitterMs(fault, attempt) {
+    const seed = `${fault.link}|${fault.kind}|${fault.message}|${fault.since}|${attempt}`;
+    let hash = 0;
+    for (let i = 0; i < seed.length; i++) {
+        hash = (hash * 33 + seed.charCodeAt(i)) >>> 0;
+    }
+    return hash % 1_000;
+}
+function retryDelayMs(fault, attempt, opts) {
+    const policy = policyFor(fault.kind);
+    if (policy.fatal)
+        return 0;
+    if (fault.kind === 'rate-limit' && typeof opts?.retryAfterMs === 'number' && Number.isFinite(opts.retryAfterMs)) {
+        return clampDelay(opts.retryAfterMs, policy.capDelayMs);
+    }
+    const delay = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
+    const jitter = fault.kind === 'overloaded'
+        ? Math.max(0, Math.round(opts?.jitterMs?.(fault, attempt) ?? defaultOverloadedJitterMs(fault, attempt)))
+        : 0;
+    return clampDelay(delay + jitter, policy.capDelayMs);
+}
+export function nextFaultRetry(fault, now, opts) {
+    const policy = policyFor(fault.kind);
+    if (policy.fatal)
+        return null;
+    const attempt = (fault.retry.attempt ?? 0) + 1;
+    if (attempt > policy.max)
+        return null;
+    const delayMs = retryDelayMs(fault, attempt, opts);
+    return {
+        fault: {
+            ...fault,
+            retry: {
+                ...fault.retry,
+                disposition: 'auto',
+                by: fault.retry.by ?? 'daemon',
+                attempt,
+                max: policy.max,
+                nextAt: new Date(now + delayMs).toISOString(),
+            },
+        },
+        attempt,
+        max: policy.max,
+        nextAt: new Date(now + delayMs).toISOString(),
+        delayMs,
+    };
+}
+export function markFatalOnExhaust(fault) {
+    const retry = {
+        ...fault.retry,
+        disposition: 'fatal',
+        by: fault.retry.by ?? 'daemon',
+        max: policyFor(fault.kind).max,
+        attempt: fault.retry.attempt ?? 0,
+    };
+    delete retry.nextAt;
+    return { ...fault, retry };
+}

package/dist/core/runtime/fault.d.ts

@@ -0,0 +1,64 @@
+import { type Fault, type FaultKind, type FaultLink, type FaultRetry } from '../fault-classifier.js';
+export type { Fault, FaultKind, FaultLink, FaultRetry, FaultRetryDisposition, FaultRetryOwner } from '../fault-classifier.js';
+export declare const FAULT_QUIET_MS: number;
+export interface FaultRecordInput {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    operation_id?: string;
+    since?: string;
+    anchorEntryId?: string;
+}
+export declare function recordFault(nodeId: string, input: FaultRecordInput): void;
+export declare function recordFaultForCurrentNode(input: FaultRecordInput): boolean;
+export declare function clearFault(nodeId: string, opts?: {
+    link?: FaultLink;
+}): boolean;
+export declare function clearFaultForCurrentNode(opts?: {
+    link?: FaultLink;
+}): boolean;
+export declare function readFault(nodeId: string): Fault | null;
+export declare function readFaultAsync(nodeId: string): Promise<Fault | null>;
+export interface BootFaultAttempt {
+    /** The recorded fault's operation + message (e.g. an unresolvable `--model`
+     *  spec, or a model that disappeared mid-launch), scoped to THIS attempt, or
+     *  null when none applies. A broker that fatal-crashes before it binds its
+     *  view socket leaves the launching caller with only the opaque "socket
+     *  never bound" symptom; callers append this so the real cause surfaces
+     *  instead. Only a `crtr→pi` fatal launch fault with a non-empty op and
+     *  message qualifies — never a stale marker from an earlier attempt (see
+     *  `beginBootFaultAttempt`) and never an unrelated fault kind (e.g. a
+     *  viewer↔broker connect failure racing the same boot). */
+    explanation(): string | null;
+}
+/** Snapshot fault state immediately before a broker launch begins, returning a
+ *  reader that is only trustworthy for a fault recorded by THIS attempt.
+ *
+ *  `clearFault` can silently fail to remove a prior marker (its own removal
+ *  errors are swallowed, and its result goes unchecked by callers), so rather
+ *  than assume that call succeeded, this independently CONFIRMS no fault is
+ *  present at the moment of launch. Other processes (a viewer, a relay) can
+ *  still write THEIR OWN fault links after this snapshot, but `explanation()`
+ *  only ever accepts a fatal `crtr→pi` launch fault — the one shape only a
+ *  newly launched broker itself writes (`resolveLaunchModel` in `broker.ts`) —
+ *  so no ACCEPTED fault can exist before this snapshot without also surviving
+ *  a failed clear, which the snapshot already catches. When a stale fault
+ *  survives the clear, `explanation()` fails closed (returns null) rather than
+ *  risk surfacing an old, unrelated cause as if it were fresh.
+ *
+ *  Call this the instant before the launch call it is guarding, so the window
+ *  in which an unrelated write could occur stays as small as possible. */
+export declare function beginBootFaultAttempt(nodeId: string): BootFaultAttempt;
+/** True when a raw engine error says pi could not resolve a credential for the model's
+ *  provider at all. pi raises `Provider is not configured: <id>` whenever auth resolution
+ *  yields nothing, and `Credential store read/modify failed for <id>` when the store itself
+ *  errored — for crouter's managed providers both mean "the pool did not hand over a usable
+ *  credential just now", which is frequently transient (a refresh in flight, a momentary read
+ *  failure) and never something the agent can fix from inside its own turn. Classified as a
+ *  plain `other` fault it is FATAL, so the node parks and every wake re-fails on the same
+ *  provider; the broker instead substitutes an authenticated provider and re-drives. */
+export declare function isProviderUnconfiguredError(message: string): boolean;
+/** True when a raw engine error is the provider 404 "model missing" signal. */
+export declare function isModelNotFoundError(message: string): boolean;

package/dist/core/runtime/fault.js

@@ -0,0 +1,260 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from '../canvas/paths.js';
+import { errorClassFromFault, } from '../fault-classifier.js';
+import { emitEvent } from '../events/emit.js';
+import { operationIdContext, validateOperationId } from '../events/operation-id.js';
+export const FAULT_QUIET_MS = 5 * 60_000;
+const MESSAGE_CAP = 500;
+function faultPath(nodeId) {
+    return join(jobDir(nodeId), 'fault');
+}
+function clampMessage(message) {
+    return message.slice(0, MESSAGE_CAP);
+}
+function faultPriority(fault) {
+    if (fault.link === 'pi→provider' && fault.retry.disposition === 'auto' && fault.retry.by === 'daemon')
+        return 3;
+    if (fault.retry.disposition === 'fatal')
+        return 2;
+    return 1;
+}
+const faultLinks = ['pi→provider', 'viewer↔broker', 'relay↔broker', 'browser↔relay', 'cli→exa', 'daemon→node', 'crtr→pi'];
+const faultKinds = ['rate-limit', 'overloaded', 'connection', 'auth', 'protocol', 'context-overflow', 'other', 'wedged', 'model-not-found'];
+function parseFault(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!faultLinks.includes(parsed.link))
+            return null;
+        if (typeof parsed.op !== 'string' || parsed.op === '')
+            return null;
+        if (!faultKinds.includes(parsed.kind))
+            return null;
+        if (typeof parsed.message !== 'string' || typeof parsed.since !== 'string')
+            return null;
+        const operationId = validateOperationId(parsed.operation_id);
+        const retryRaw = parsed.retry;
+        if (retryRaw === undefined)
+            return null;
+        if (retryRaw.disposition !== 'auto' && retryRaw.disposition !== 'manual' && retryRaw.disposition !== 'fatal')
+            return null;
+        if (retryRaw.by !== undefined && retryRaw.by !== 'sdk' && retryRaw.by !== 'daemon' && retryRaw.by !== 'client')
+            return null;
+        if (retryRaw.attempt !== undefined && typeof retryRaw.attempt !== 'number')
+            return null;
+        if (retryRaw.max !== undefined && typeof retryRaw.max !== 'number')
+            return null;
+        if (retryRaw.nextAt !== undefined && typeof retryRaw.nextAt !== 'string')
+            return null;
+        if (parsed.anchorEntryId !== undefined && (typeof parsed.anchorEntryId !== 'string' || parsed.anchorEntryId === ''))
+            return null;
+        return {
+            link: parsed.link,
+            op: parsed.op,
+            kind: parsed.kind,
+            retry: {
+                disposition: retryRaw.disposition,
+                ...(retryRaw.by === undefined ? {} : { by: retryRaw.by }),
+                ...(retryRaw.attempt === undefined ? {} : { attempt: retryRaw.attempt }),
+                ...(retryRaw.max === undefined ? {} : { max: retryRaw.max }),
+                ...(retryRaw.nextAt === undefined ? {} : { nextAt: retryRaw.nextAt }),
+            },
+            message: parsed.message,
+            since: parsed.since,
+            operation_id: operationId,
+            ...(parsed.anchorEntryId === undefined ? {} : { anchorEntryId: parsed.anchorEntryId }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function currentFault(nodeId) {
+    try {
+        return parseFault(readFileSync(faultPath(nodeId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeFault(nodeId, fault) {
+    try {
+        mkdirSync(jobDir(nodeId), { recursive: true });
+        writeFileSync(faultPath(nodeId), JSON.stringify(fault));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function updateMarker(nodeId, fault) {
+    const current = currentFault(nodeId);
+    if (current !== null) {
+        if (current.link === fault.link && current.kind === fault.kind) {
+            const retry = { ...current.retry, ...fault.retry };
+            if (fault.retry.disposition === 'fatal' && !('nextAt' in fault.retry)) {
+                delete retry.nextAt;
+            }
+            fault = { ...fault, since: current.since, anchorEntryId: current.anchorEntryId ?? fault.anchorEntryId, retry };
+        }
+        else if (faultPriority(current) > faultPriority(fault)) {
+            return;
+        }
+    }
+    writeFault(nodeId, fault);
+}
+function resolveOperationId(explicit) {
+    if (explicit !== undefined)
+        return validateOperationId(explicit);
+    const current = operationIdContext.current();
+    if (current !== undefined)
+        return current;
+    return operationIdContext.fresh((operationId) => operationId);
+}
+export function recordFault(nodeId, input) {
+    const operationId = resolveOperationId(input.operation_id);
+    const fault = {
+        link: input.link,
+        op: input.op,
+        kind: input.kind,
+        retry: input.retry,
+        message: clampMessage(input.message),
+        since: input.since ?? new Date().toISOString(),
+        operation_id: operationId,
+        ...(typeof input.anchorEntryId === 'string' && input.anchorEntryId !== '' ? { anchorEntryId: input.anchorEntryId } : {}),
+    };
+    emitEvent({
+        level: fault.retry.disposition === 'fatal' ? 'error' : 'warn',
+        event: 'fault.recorded',
+        operation_id: operationId,
+        node_id: nodeId,
+        error_class: errorClassFromFault(fault),
+        fields: {
+            link: fault.link,
+            op: fault.op,
+            kind: fault.kind,
+            retry: fault.retry,
+            message: fault.message,
+            ...(fault.anchorEntryId === undefined ? {} : { anchor_entry_id: fault.anchorEntryId }),
+        },
+    });
+    updateMarker(nodeId, fault);
+}
+export function recordFaultForCurrentNode(input) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return false;
+    if (!existsSync(jobDir(nodeId)))
+        return false;
+    try {
+        recordFault(nodeId, input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function clearFault(nodeId, opts) {
+    try {
+        const current = currentFault(nodeId);
+        if (current === null)
+            return false;
+        if (opts?.link !== undefined && current.link !== opts.link)
+            return false;
+        rmSync(faultPath(nodeId));
+        const operationId = resolveOperationId();
+        emitEvent({
+            level: 'info',
+            event: 'fault.cleared',
+            operation_id: operationId,
+            node_id: nodeId,
+            error_class: errorClassFromFault(current),
+            fields: {
+                cleared_fault_operation_id: current.operation_id,
+                link: current.link,
+                op: current.op,
+                kind: current.kind,
+                retry: current.retry,
+                message: current.message,
+                since: current.since,
+                ...(current.anchorEntryId === undefined ? {} : { anchor_entry_id: current.anchorEntryId }),
+            },
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function clearFaultForCurrentNode(opts) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return false;
+    if (!existsSync(jobDir(nodeId)))
+        return false;
+    return clearFault(nodeId, opts);
+}
+export function readFault(nodeId) {
+    return currentFault(nodeId);
+}
+export async function readFaultAsync(nodeId) {
+    return readFault(nodeId);
+}
+/** Snapshot fault state immediately before a broker launch begins, returning a
+ *  reader that is only trustworthy for a fault recorded by THIS attempt.
+ *
+ *  `clearFault` can silently fail to remove a prior marker (its own removal
+ *  errors are swallowed, and its result goes unchecked by callers), so rather
+ *  than assume that call succeeded, this independently CONFIRMS no fault is
+ *  present at the moment of launch. Other processes (a viewer, a relay) can
+ *  still write THEIR OWN fault links after this snapshot, but `explanation()`
+ *  only ever accepts a fatal `crtr→pi` launch fault — the one shape only a
+ *  newly launched broker itself writes (`resolveLaunchModel` in `broker.ts`) —
+ *  so no ACCEPTED fault can exist before this snapshot without also surviving
+ *  a failed clear, which the snapshot already catches. When a stale fault
+ *  survives the clear, `explanation()` fails closed (returns null) rather than
+ *  risk surfacing an old, unrelated cause as if it were fresh.
+ *
+ *  Call this the instant before the launch call it is guarding, so the window
+ *  in which an unrelated write could occur stays as small as possible. */
+export function beginBootFaultAttempt(nodeId) {
+    const preLaunchClear = readFault(nodeId) === null;
+    return {
+        explanation() {
+            if (!preLaunchClear)
+                return null;
+            const fault = readFault(nodeId);
+            if (fault === null)
+                return null;
+            if (fault.link !== 'crtr\u2192pi' || fault.retry.disposition !== 'fatal')
+                return null;
+            const op = fault.op.trim();
+            const message = fault.message.trim();
+            if (op === '' || message === '')
+                return null;
+            return `${op}: ${message}`;
+        },
+    };
+}
+/** True when a raw engine error says pi could not resolve a credential for the model's
+ *  provider at all. pi raises `Provider is not configured: <id>` whenever auth resolution
+ *  yields nothing, and `Credential store read/modify failed for <id>` when the store itself
+ *  errored — for crouter's managed providers both mean "the pool did not hand over a usable
+ *  credential just now", which is frequently transient (a refresh in flight, a momentary read
+ *  failure) and never something the agent can fix from inside its own turn. Classified as a
+ *  plain `other` fault it is FATAL, so the node parks and every wake re-fails on the same
+ *  provider; the broker instead substitutes an authenticated provider and re-drives. */
+export function isProviderUnconfiguredError(message) {
+    const m = message ?? '';
+    if (/provider is not configured\b/i.test(m))
+        return true;
+    return /credential store (?:read|modify) failed\b/i.test(m);
+}
+/** True when a raw engine error is the provider 404 "model missing" signal. */
+export function isModelNotFoundError(message) {
+    const m = message ?? '';
+    if (/not_found_error/i.test(m))
+        return true;
+    if (/model[^.]{0,40}(not\s*found|does not exist|is not available|unavailable)|(no such|unknown) model/i.test(m))
+        return true;
+    return /\b404\b/.test(m) && /not\s*found|not available|does not exist/i.test(m);
+}

package/dist/core/runtime/fleet.d.ts

@@ -0,0 +1,57 @@
+import type { HostHandle } from './host.js';
+/** Real child-exit status, exactly as Node reports it. Codes/signals are
+ *  diagnostics only — never policy inputs (design D-4). */
+export interface FleetExitStatus {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+export interface FleetEntry {
+    /** The broker's supervised pid (never null — a launch with no pid is not
+     *  registered). */
+    pid: number;
+    /** Date.now() at spawn — the respawn throttle's uptime baseline. */
+    launchedAt: number;
+    /** The ChildProcess-backed handle (host.ts) whose `exited` promise is the
+     *  liveness authority. */
+    handle: HostHandle;
+    /** Respawn-throttle state at registration (consecutive short-lived exits
+     *  observed before this launch). The authoritative counter lives in the
+     *  daemon implementation and survives the entry's removal at exit. */
+    consecutiveFailures: number;
+}
+export interface FleetRegistry {
+    /** This daemon's epoch id — minted at boot, stamped into every broker's argv
+     *  (`--epoch <id>`) so the next daemon's startup census can reap every
+     *  prior-epoch broker without adoption. */
+    epoch(): string;
+    /** Record a just-spawned broker. Sync; THROWS if an entry already exists —
+     *  a second launch for a live node is a programming error, never silently
+     *  tolerated. */
+    register(nodeId: string, handle: HostHandle): void;
+    /** The reviveNode double-launch guard: a fleet entry IS liveness. */
+    has(nodeId: string): boolean;
+    /** Live-fleet checks pass (yield-stall, wedge, fatal-fault). */
+    get(nodeId: string): FleetEntry | undefined;
+    /** The capacity count (design D-7: capacity = fleet.size(), exact). */
+    size(): number;
+    entries(): Iterable<[string, FleetEntry]>;
+    /** Drop an entry without policy (terminal exits + close paths). */
+    forget(nodeId: string): void;
+    /** Wired by `headlessBrokerHost.launch` to the handle's `exited` promise.
+     *  Removes the entry (freeing the capacity slot), then enqueues an
+     *  exit-policy job on the daemon's serial work lane — policy never runs
+     *  inline on the Node event callback (design D-3). */
+    onChildExit(nodeId: string, status: FleetExitStatus): void;
+    /** Test seam — delivers a synthetic exit through the SAME path as
+     *  onChildExit, so fabricated-row tests drive policy without a process. */
+    deliverExit(nodeId: string, status: FleetExitStatus): void;
+}
+/** Inject the daemon's fleet registry. Idempotent for the same instance;
+ *  throws on a conflicting rebind (one registry per process, ever). */
+export declare function bindFleet(registry: FleetRegistry): void;
+/** The bound registry. Throws when unbound: broker launches happen only inside
+ *  crtrd (or a test harness that explicitly bound an in-process fleet). */
+export declare function boundFleet(): FleetRegistry;
+/** Test-only: clear the process-global binding, mirroring
+ *  resetEventSourceForTests. Production processes bind exactly once. */
+export declare function resetFleetForTests(): void;