@north-light/crouter 0.3.249 → 0.3.251

package/dist/core/runtime/broker/fault-retry.d.ts

@@ -4,6 +4,7 @@ import type { BrokerSdkConfig } from '../launch.js';
 import type { BrokerToClient } from '../broker-protocol.js';
 import type { BrokerSession } from './read-ops.js';
 import type { SubscriptionGeneration } from './rebind.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
 type FaultRetryDeps = {
     nodeId: string;
     cfg: BrokerSdkConfig;
@@ -14,6 +15,7 @@ type FaultRetryDeps = {
     registryOf: (services: AgentSessionServices) => ModelRegistry;
     formatModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
     broadcastModelChanged: (persist?: boolean) => Promise<void>;
+    turnAdmission: TurnAdmissionGate;
 };
 /** Owns provider fallback and daemon-driven fault retry state for one broker session. */
 export declare class FaultRetry {
@@ -29,9 +31,16 @@ export declare class FaultRetry {
     onEvent(event: BrokerToClient): void;
     isActiveAutoFault(fault: ReturnType<typeof readFault>): fault is NonNullable<ReturnType<typeof readFault>>;
     publishSettledProviderFault(generation: SubscriptionGeneration): void;
+    /** Startup re-drive reads only a durable pending episode. Revive deliberately
+     * clears the ordinary fault marker before this boundary, so the episode is
+     * the recovery authority and admitted/invalidated records remain inert. */
+    recoverPendingOnStartup(): void;
     schedule(): void;
     private maybeSwitchProviderForRetry;
     private maybeFallbackOnUnusableModel;
+    private recordPendingProviderFault;
+    private sessionFile;
+    private pendingEpisodeMatches;
     private faultRetryDelayMs;
     private clearAndArmFaultRetry;
     private runFaultRetry;

package/dist/core/runtime/broker/fault-retry.js

@@ -1,7 +1,8 @@
+import { realpathSync } from 'node:fs';
 import { envModelIntent, envNodeCwd, envProfileId } from '../../../shared/env.js';
 import { isContextOverflow } from '@earendil-works/pi-ai';
 import { classify } from '../../fault-classifier.js';
-import { clearFault, isModelNotFoundError, isProviderUnconfiguredError, readFault, recordFault } from '../fault.js';
+import { admitProviderRetryEpisode, clearFault, clearProviderRetryEpisode, invalidateProviderRetryEpisode, isModelNotFoundError, isProviderUnconfiguredError, readFault, readProviderRetryEpisode, recordFault, recordPendingProviderRetryFault, } from '../fault.js';
 import { extractCoolingDeadline } from '../managed-provider-cooling.js';
 import { expandModelCandidates, modelRequestFromConfig, probeRouteAvailability } from '../../model-routes.js';
 import { operationIdContext } from '../../events/operation-id.js';
@@ -77,7 +78,7 @@ export class FaultRetry {
             return;
         }
         if (watchdogAbort && last?.stopReason === 'aborted') {
-            recordFault(this.deps.nodeId, {
+            this.recordPendingProviderFault(settledSession, {
                 link: 'pi→provider', op: 'generation turn', kind: 'connection',
                 retry: { disposition: 'auto', by: 'daemon', ...(episode?.attempt !== undefined ? { attempt: episode.attempt } : {}) },
                 message: typeof last.errorMessage === 'string' ? last.errorMessage : 'engine error (no errorMessage recorded)',
@@ -101,7 +102,7 @@ export class FaultRetry {
         const coolingDeadline = extractCoolingDeadline(last);
         if (uncompactedOverflow)
             clearFault(this.deps.nodeId, { link: 'pi→provider' });
-        recordFault(this.deps.nodeId, {
+        const faultInput = {
             link: 'pi→provider', op: 'generation turn', kind: uncompactedOverflow ? 'context-overflow' : classified.kind,
             retry: uncompactedOverflow
                 ? { disposition: 'fatal' }
@@ -117,7 +118,35 @@ export class FaultRetry {
             anchorEntryId: !uncompactedOverflow && classified.disposition === 'auto' && episode?.anchorEntryId !== undefined
                 ? episode.anchorEntryId
                 : settledSession.sessionManager.getLeafId?.() ?? undefined,
-        });
+        };
+        if (faultInput.retry.disposition === 'auto')
+            this.recordPendingProviderFault(settledSession, faultInput);
+        else
+            recordFault(this.deps.nodeId, faultInput);
+    }
+    /** Startup re-drive reads only a durable pending episode. Revive deliberately
+     * clears the ordinary fault marker before this boundary, so the episode is
+     * the recovery authority and admitted/invalidated records remain inert. */
+    recoverPendingOnStartup() {
+        const generation = this.deps.installedGeneration();
+        if (generation === undefined)
+            return;
+        const episode = readProviderRetryEpisode(this.deps.nodeId);
+        const sessionFile = this.sessionFile(generation.session);
+        // A new-cycle launch deliberately roots a new transcript branch even though
+        // it reuses the same .jsonl. Its old anchor is no longer a valid recovery
+        // coordinate, so mark the episode invalid rather than inferring that from
+        // the shared path or letting startup re-drive into the fresh cycle.
+        if (this.deps.cfg.newCycle === true) {
+            if (episode !== null && sessionFile !== null && episode.sessionFile === sessionFile) {
+                invalidateProviderRetryEpisode(this.deps.nodeId, sessionFile);
+            }
+            return;
+        }
+        if (episode === null || sessionFile === null || episode.state !== 'pending' || episode.sessionFile !== sessionFile)
+            return;
+        recordFault(this.deps.nodeId, episode.fault);
+        this.schedule();
     }
     schedule() {
         const generation = this.deps.installedGeneration();
@@ -125,7 +154,11 @@ export class FaultRetry {
         if (generation === undefined || session.isStreaming || this.timer !== null)
             return;
         const fault = readFault(this.deps.nodeId);
-        if (!this.isActiveAutoFault(fault)) {
+        // A live session without a durable transcript path still owns its ordinary
+        // in-process timer; it simply cannot survive broker death. Once a path
+        // exists, require its pending episode so admitted/invalidated retries stay
+        // inert even before a replacement broker starts.
+        if (!this.isActiveAutoFault(fault) || (this.sessionFile(session) !== null && !this.pendingEpisodeMatches(session, fault))) {
             this.clearTimer();
             return;
         }
@@ -215,7 +248,7 @@ export class FaultRetry {
                 return;
             if (unconfigured)
                 clearFault(this.deps.nodeId, { link: 'pi→provider' });
-            await operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', {}, formatModelFallbackRecovery(currentSpec, resolved, unconfigured ? 'credential' : 'not-found'))));
+            await this.deps.turnAdmission.admit((release) => operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', {}, formatModelFallbackRecovery(currentSpec, resolved, unconfigured ? 'credential' : 'not-found')), { preflightResult: release })));
         })().catch((err) => {
             emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `${unconfigured ? 'unconfigured-provider' : 'not_found'} fallback failed: ${err instanceof Error ? err.message : String(err)}` } });
         }).finally(() => {
@@ -224,6 +257,36 @@ export class FaultRetry {
         });
         this.notFoundFallbackInFlight = fallbackPromise;
     }
+    recordPendingProviderFault(session, input) {
+        const sessionFile = this.sessionFile(session);
+        // A pathless session cannot be crash-recovered, but its live broker still
+        // owns the ordinary auto-retry timer.
+        if (sessionFile === null) {
+            recordFault(this.deps.nodeId, input);
+            return;
+        }
+        recordPendingProviderRetryFault(this.deps.nodeId, sessionFile, input);
+    }
+    sessionFile(session) {
+        if (typeof session.sessionFile !== 'string' || session.sessionFile === '')
+            return null;
+        try {
+            return realpathSync(session.sessionFile);
+        }
+        catch {
+            return session.sessionFile;
+        }
+    }
+    pendingEpisodeMatches(session, fault) {
+        const sessionFile = this.sessionFile(session);
+        const episode = readProviderRetryEpisode(this.deps.nodeId);
+        return sessionFile !== null &&
+            episode !== null &&
+            episode.state === 'pending' &&
+            episode.sessionFile === sessionFile &&
+            episode.fault.since === fault.since &&
+            episode.anchorEntryId === (fault.anchorEntryId ?? null);
+    }
     faultRetryDelayMs(fault, now) {
         if (fault.retry.nextAt !== undefined) {
             const ms = Date.parse(fault.retry.nextAt) - now;
@@ -280,11 +343,13 @@ export class FaultRetry {
         const policy = policyFor(fault.kind);
         if (attempt >= policy.max) {
             recordFault(this.deps.nodeId, markFatalOnExhaust(fault));
+            clearProviderRetryEpisode(this.deps.nodeId);
             return;
         }
         const plan = nextFaultRetry(fault, Date.now());
         if (plan === null) {
             recordFault(this.deps.nodeId, markFatalOnExhaust(fault));
+            clearProviderRetryEpisode(this.deps.nodeId);
             return;
         }
         if (fault.anchorEntryId !== undefined) {
@@ -301,7 +366,28 @@ export class FaultRetry {
         }
         if (this.deps.installedGeneration() !== generation || this.deps.currentSession() !== candidateSession)
             return;
-        recordFault(this.deps.nodeId, plan.fault);
-        await operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', {}, fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY)));
+        await this.deps.turnAdmission.admit((release) => {
+            const current = readFault(this.deps.nodeId);
+            if (this.deps.installedGeneration() !== generation ||
+                this.deps.currentSession() !== candidateSession ||
+                candidateSession.isStreaming ||
+                !this.isActiveAutoFault(current) ||
+                current.since !== fault.since) {
+                release();
+                return Promise.resolve();
+            }
+            // This is the admission point: all generation/session/streaming/fault
+            // revalidation above has passed, and only now may the durable episode
+            // become admitted. Writing it before prompt() fails closed across a broker
+            // death in the narrow handoff to the SDK — replaying there could duplicate
+            // an already accepted recovery turn.
+            const sessionFile = this.sessionFile(candidateSession);
+            if (sessionFile !== null && !admitProviderRetryEpisode(this.deps.nodeId, sessionFile, plan.fault)) {
+                release();
+                return Promise.resolve();
+            }
+            recordFault(this.deps.nodeId, plan.fault);
+            return operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', {}, fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY), { preflightResult: release }));
+        });
     }
 }

package/dist/core/runtime/broker/frame-dispatch.d.ts

@@ -5,6 +5,7 @@ import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
 import type { BrokerSession } from './read-ops.js';
 import { type DriveFrame } from './engine-drive.js';
 import { type PendingDialog } from './frame-client.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
 import type { ToolGroupTracker } from './tool-groups.js';
 import type { EventProjection } from './event-projection.js';
 import type { RebindDriver } from './rebind.js';
@@ -28,6 +29,7 @@ export type FrameDispatchDeps = {
     registryOf: (services: AgentSessionServices) => ModelRegistry;
     formatModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
     formatExactModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
+    turnAdmission: TurnAdmissionGate;
     resolveLaunchModel: (services: AgentSessionServices, cfg: BrokerSdkConfig) => Promise<{
         model: NonNullable<ReturnType<ModelRegistry['find']>>;
         thinkingLevel: string | undefined;

package/dist/core/runtime/broker/frame-dispatch.js

@@ -9,7 +9,7 @@ import { createSessionHandler } from './frame-session.js';
 import { createKickoffDriver, createPromptDispatchTracker, createTurnAcceptanceGate, } from './turn-ignition.js';
 /** Owns frame-local input state while dispatching through explicit broker collaborators. */
 export function createFrameDispatchContext(deps) {
-    const { nodeId, cfg, registry, toolGroups, projection, rebind, boundaryReviewId, pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, reWelcomeAll, disposeAndExit, persistModelChoice, broadcastModelChanged, registryOf, formatModelSpec, formatExactModelSpec, resolveLaunchModel, } = deps;
+    const { nodeId, cfg, registry, toolGroups, projection, rebind, boundaryReviewId, pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, reWelcomeAll, disposeAndExit, persistModelChoice, broadcastModelChanged, registryOf, formatModelSpec, formatExactModelSpec, turnAdmission, resolveLaunchModel, } = deps;
     const currentSession = () => rebind.session();
     const currentServices = () => rebind.services();
     // The reply vocabulary every handler below answers a client with.
@@ -21,6 +21,7 @@ export function createFrameDispatchContext(deps) {
     const kickoffDriver = createKickoffDriver({
         session: currentSession,
         dispatches,
+        turnAdmission,
     });
     const authReloadGate = createAuthReloadGate({
         nodeId,
@@ -33,6 +34,7 @@ export function createFrameDispatchContext(deps) {
         formatModelSpec,
         resolveLaunchModel,
         driveKickoff: kickoffDriver.drivePending,
+        turnAdmission,
     });
     const driveEngine = createEngineDriver({
         registry,
@@ -44,6 +46,7 @@ export function createFrameDispatchContext(deps) {
         rebind,
         projection,
         toolGroups,
+        turnAdmission,
     });
     const handleDriveFrame = (client, frame) => {
         if (notWritable(client, 'drive the engine'))

package/dist/core/runtime/broker/held-deferred-inbox.d.ts

@@ -0,0 +1,9 @@
+export declare const HELD_DEFERRED_INBOX_PROMPT_JOIN: unique symbol;
+export type HeldDeferredInboxPromptJoin = (session: {
+    sendCustomMessage: (message: {
+        customType: string;
+        content: string;
+        display: boolean;
+    }) => Promise<void>;
+}) => Promise<void>;
+export declare function heldDeferredInboxPromptJoin(): HeldDeferredInboxPromptJoin | undefined;

package/dist/core/runtime/broker/held-deferred-inbox.js

@@ -0,0 +1,8 @@
+// The inbox watcher is a Pi extension loaded through Jiti, while the broker is
+// native ESM. They therefore cannot share a module singleton. This process-global
+// symbol names the watcher-owned join function across that loader boundary.
+export const HELD_DEFERRED_INBOX_PROMPT_JOIN = Symbol.for('@crouton-kit/crtr:held-deferred-inbox-prompt-join');
+export function heldDeferredInboxPromptJoin() {
+    const join = globalThis[HELD_DEFERRED_INBOX_PROMPT_JOIN];
+    return typeof join === 'function' ? join : undefined;
+}

package/dist/core/runtime/broker/inbox.js

@@ -3,6 +3,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { inboxPath, nodeDir } from '../../canvas/paths.js';
 import { formatInboxCard } from '../../../shared/generated-context.js';
+import { renderBirthAnnouncementBody } from '../../../shared/birth-announcement.js';
 const ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 const BODY_MAX_LINES = 12;
 const BODY_MAX_CHARS = 1000;
@@ -140,6 +141,9 @@ function inlineReport(entry, reportNodes) {
 /** One entry's card body: an inlined short report, a bounded inline message
  *  body, or the label when the entry carries neither. */
 function entryBody(entry, reportNodes) {
+    const birth = renderBirthAnnouncementBody(entry.data, entry.ts);
+    if (birth !== null)
+        return birth;
     const report = inlineReport(entry, reportNodes);
     if (report !== null)
         return report.trimEnd();

package/dist/core/runtime/broker/rebind.js

@@ -5,6 +5,7 @@ import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
 import { installPersonaTransitionGate } from '../broker-persona-guidance.js';
 import { abortSessionFromExtension } from './extension-abort.js';
+import { clearFault, invalidateProviderRetryEpisode, readFault } from '../fault.js';
 const MAX_ADMITTED_REPLACEMENTS = 2;
 const REPLACEMENT_DEADLINE_MS = 30_000;
 const REPLACEMENT_DEADLINE_EXCEEDED = Symbol('replacement-deadline-exceeded');
@@ -95,6 +96,22 @@ export class RebindDriver {
         const task = this.rebindTail.then(async () => {
             if (ticket !== this.latestRebindRequest)
                 return;
+            // A replacement changes the conversation coordinate. The initial bind has
+            // no prior generation and must retain a crash-surviving pending episode;
+            // every later rebind explicitly marks the old session's episode invalid.
+            if (this.installed !== undefined) {
+                if (typeof this.sessionValue.sessionFile === 'string' && this.sessionValue.sessionFile !== '') {
+                    invalidateProviderRetryEpisode(this.deps.nodeId, this.sessionValue.sessionFile);
+                }
+                // A daemon-owned auto marker belongs to the outgoing session whether
+                // that session has a durable path or not. Retaining it lets the
+                // replacement inherit an old anchor, attempts, and backoff; fatal and
+                // manual markers stay visible.
+                const fault = readFault(this.deps.nodeId);
+                if (fault?.link === 'pi→provider' && fault.retry.disposition === 'auto' && fault.retry.by === 'daemon') {
+                    clearFault(this.deps.nodeId, { link: 'pi→provider', preserveProviderRetryEpisode: true });
+                }
+            }
             this.installed?.executingTools.clear();
             this.removeInstalledSubscription();
             this.deps.setActiveSession(candidateSession);
@@ -192,6 +209,7 @@ export class RebindDriver {
                 this.executeSubscriptionCallback(generation, event);
             });
             this.installed = generation;
+            this.deps.projection().rearmIfStreaming(generation);
             this.captureSystemPrompt(candidateSession);
         });
         this.rebindTail = task.catch(() => undefined);

package/dist/core/runtime/broker/turn-admission.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serializes entry into AgentSession.prompt() until its preflight has decided
+ * whether it will start (or join) a run. AgentSession.isStreaming stays false
+ * through asynchronous preflight, so checking it before entering prompt() lets
+ * two calls reach the SDK's active-run ownership race. Each waiter therefore
+ * re-reads live state only after the preceding prompt has reported preflight.
+ */
+export type TurnAdmissionGate = {
+    admit<T>(start: (release: () => void) => Promise<T>): Promise<T>;
+};
+export declare function createTurnAdmissionGate(): TurnAdmissionGate;

package/dist/core/runtime/broker/turn-admission.js

@@ -0,0 +1,31 @@
+export function createTurnAdmissionGate() {
+    let tail = Promise.resolve();
+    return {
+        admit(start) {
+            const previous = tail;
+            let resolveAdmission;
+            const admitted = new Promise((resolve) => {
+                resolveAdmission = resolve;
+            });
+            tail = previous.then(() => admitted);
+            return previous.then(() => {
+                let released = false;
+                const release = () => {
+                    if (released)
+                        return;
+                    released = true;
+                    resolveAdmission();
+                };
+                try {
+                    const attempt = start(release);
+                    void attempt.then(release, release);
+                    return attempt;
+                }
+                catch (error) {
+                    release();
+                    throw error;
+                }
+            });
+        },
+    };
+}

package/dist/core/runtime/broker/turn-ignition.d.ts

@@ -1,4 +1,5 @@
 import type { BrokerSession } from './read-ops.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
 /**
  * Prompt dispatches whose promise has not yet settled. `session.prompt()` does
  * async setup (input transforms, model/auth validation, compaction) BEFORE
@@ -39,4 +40,5 @@ export type KickoffDriver = {
 export declare function createKickoffDriver(deps: {
     session: () => BrokerSession;
     dispatches: PromptDispatchTracker;
+    turnAdmission: TurnAdmissionGate;
 }): KickoffDriver;

package/dist/core/runtime/broker/turn-ignition.js

@@ -41,28 +41,38 @@ export function createTurnAcceptanceGate() {
     };
 }
 export function createKickoffDriver(deps) {
-    const { session, dispatches } = deps;
+    const { session, dispatches, turnAdmission } = deps;
     let pendingPrompt;
     let inFlight = false;
     const sessionHasNoModel = () => session().model === undefined || isUnknownModel(session().model);
     const drivePending = () => {
         if (pendingPrompt === undefined || inFlight || sessionHasNoModel())
             return;
-        const prompt = pendingPrompt;
-        pendingPrompt = undefined;
         inFlight = true;
-        dispatches.track(operationIdContext.fresh(() => session()
-            .prompt(prompt)
-            .catch((err) => {
-            emitEvent({
-                level: 'error',
-                event: 'broker.prompt.first_failed',
-                error: err,
-            });
-        })
-            .finally(() => {
-            inFlight = false;
-        })));
+        void turnAdmission.admit((release) => {
+            const prompt = pendingPrompt;
+            if (prompt === undefined || sessionHasNoModel()) {
+                release();
+                inFlight = false;
+                return Promise.resolve();
+            }
+            pendingPrompt = undefined;
+            return dispatches.track(operationIdContext.fresh(() => session()
+                .prompt(prompt, {
+                preflightResult: release,
+                ...(session().isStreaming ? { streamingBehavior: 'steer' } : {}),
+            })
+                .catch((err) => {
+                emitEvent({
+                    level: 'error',
+                    event: 'broker.prompt.first_failed',
+                    error: err,
+                });
+            })
+                .finally(() => {
+                inFlight = false;
+            })));
+        });
     };
     return {
         kickoff(prompt) {

package/dist/core/runtime/broker.js

@@ -35,7 +35,7 @@ import { resolveBundledPiPackageDir } from './pi-cli.js';
 import { captureSessionChatCapabilities } from './command-surface.js';
 import { PoolCredentialStore } from '../pool-credential-store.js';
 import { clearCleanAbort, markBusy, markCleanAbort } from './busy.js';
-import { recordFaultForCurrentNode } from './fault.js';
+import { clearFault, recordFaultForCurrentNode } from './fault.js';
 import { modelRequestFromConfig, selectInitialModelRoute, unregisteredConcreteModel } from '../model-routes.js';
 import { KNOWN_STREAM_WAIT_UI } from './stream-watchdog.js';
 import { probeOnline as probeOnlineReal } from './connectivity.js';
@@ -46,6 +46,7 @@ import { BrokerClientRegistry } from './broker/client-registry.js';
 import { ToolGroupTracker } from './broker/tool-groups.js';
 import { onNodeNamed } from './broker/node-named.js';
 import { FaultRetry } from './broker/fault-retry.js';
+import { createTurnAdmissionGate } from './broker/turn-admission.js';
 import { EventProjection } from './broker/event-projection.js';
 import { createFrameDispatchContext, handleFrame, } from './broker/frame-dispatch.js';
 import { hydratePersistedAdvertisedCommandMessages, installAdvertisedCommandInvocationContract, } from './advertised-command-invocation.js';
@@ -325,6 +326,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         const spec = persist ? await persistModelChoice(pinnedOverride, userSelected) : liveSpec;
         registry.broadcast({ type: 'model_changed', model: isUnknownModel(liveSession.model) ? undefined : liveSession.model, spec });
     };
+    const turnAdmission = createTurnAdmissionGate();
     faultRetry = new FaultRetry({
         nodeId,
         cfg,
@@ -335,6 +337,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         registryOf,
         formatModelSpec,
         broadcastModelChanged,
+        turnAdmission,
     });
     projection = new EventProjection({
         registry,
@@ -527,7 +530,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         nodeId, cfg, registry, toolGroups, projection, rebind, boundaryReviewId,
         pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, reWelcomeAll, disposeAndExit,
         persistModelChoice, broadcastModelChanged, registryOf, formatModelSpec,
-        formatExactModelSpec, resolveLaunchModel,
+        formatExactModelSpec, turnAdmission, resolveLaunchModel,
     });
     notifyTurnAccepted = frameDispatch.notifyTurnAccepted;
     resetFrameState = frameDispatch.resetForSession;
@@ -591,6 +594,22 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         disposeAndExit('socket-error', 1);
     });
     server.listen(sockPath, () => {
+        // Binding view.sock is the exact inverse of a `connect ENOENT view.sock`
+        // fault, so the moment the listener accepts, any socket-absence marker a
+        // viewer/relay recorded during the revive→bind gap is provably stale. The
+        // broker owns this socket, so it clears those markers here rather than
+        // waiting for a client to reconnect — a headless node with nobody attached
+        // never gets that reconnect, which is how the stale ⚠ leaked. A genuine
+        // post-bind failure is re-recorded by the next failed client op.
+        clearFault(nodeId, { link: 'viewer↔broker' });
+        clearFault(nodeId, { link: 'relay↔broker' });
+        // The listener is also the broker startup boundary: a pending provider
+        // episode recovered after an instance death is re-armed only once this
+        // replacement can accept its normal viewer/daemon traffic. Independent of
+        // the link faults cleared above — those are viewer/relay socket markers,
+        // this is the provider retry episode. Admitted and invalidated records are
+        // intentionally inert inside FaultRetry.
+        faultRetry.recoverPendingOnStartup();
         // A launch prompt delivers only after the listener is accepting, so a
         // root-spawn readiness proof and prompt admission share one boundary. This
         // includes the one continuation carried by a clean runtime-abort resume.

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

@@ -1,13 +1,14 @@
 import { type SubscriptionRef } from '../canvas/index.js';
-/** The doctrine wake: fan a system notice to every given subscriber of a node
- *  whose lifecycle just ended out from under it (closed, or crashed to dead) —
- *  the runtime guarantee that a manager waiting dormant on a child always
- *  learns of its terminal outcome instead of hanging forever. Active subscriber
- *  → inbox (wakes a dormant manager via its live watcher / the daemon's
- *  dormant-revive pass); passive → the passive accumulator (delivered, not
- *  woken). Shared by closeNode (step 4, below) and reviveNode's launch-refusal
- *  crash path (revive.ts). */
-export declare function fanDoctrineWake(fromId: string, subscribers: readonly SubscriptionRef[], label: string, data: Record<string, unknown>): void;
+import { type InboxTier } from '../feed/inbox.js';
+/** Fan a lifecycle or birth notice to every given subscriber. Active subscribers
+ *  receive inbox mail; passive subscribers receive passive mail. Shared by
+ *  terminal-outcome paths and externally created children, so callers preserve
+ *  the existing subscription's delivery mode rather than inventing a wake path.
+ *
+ *  `tier` defaults to a waking `normal`. A caller whose outcome is not worth
+ *  starting a manager's cycle passes `deferred`, which rides the manager's next
+ *  natural cycle instead. */
+export declare function fanDoctrineWake(fromId: string, subscribers: readonly SubscriptionRef[], label: string, data: Record<string, unknown>, tier?: InboxTier): void;
 export interface CloseNodeResult {
     /** The focused node that was closed — the cascade root. */
     root: string;
@@ -31,4 +32,5 @@ export interface CloseNodeResult {
  *      status keeps it (finish is only legal from a live status). */
 export declare function closeNode(rootId: string, opts?: {
     rootEvent?: 'cancel' | 'finish';
+    callerPid?: number;
 }): CloseNodeResult;

package/dist/core/runtime/close.js

@@ -30,26 +30,33 @@
 // inside the closing set. A node still subscribed to by a manager outside the
 // subtree is left running — "only kill the children if they are only subscribed
 // to by the agent being closed", generalized to any depth via a fixpoint.
-import { getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
+import { cancelCronsOnWake, getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
-import { headlessBrokerHost } from './host.js';
+import { requestBrokerTeardown } from './host.js';
 import { tearDownNode, reapIfEmpty } from './placement.js';
 import { appendInbox } from '../feed/inbox.js';
 import { appendPassive } from '../feed/passive.js';
-/** The doctrine wake: fan a system notice to every given subscriber of a node
- *  whose lifecycle just ended out from under it (closed, or crashed to dead) —
- *  the runtime guarantee that a manager waiting dormant on a child always
- *  learns of its terminal outcome instead of hanging forever. Active subscriber
- *  → inbox (wakes a dormant manager via its live watcher / the daemon's
- *  dormant-revive pass); passive → the passive accumulator (delivered, not
- *  woken). Shared by closeNode (step 4, below) and reviveNode's launch-refusal
- *  crash path (revive.ts). */
-export function fanDoctrineWake(fromId, subscribers, label, data) {
+/** Fan a lifecycle or birth notice to every given subscriber. Active subscribers
+ *  receive inbox mail; passive subscribers receive passive mail. Shared by
+ *  terminal-outcome paths and externally created children, so callers preserve
+ *  the existing subscription's delivery mode rather than inventing a wake path.
+ *
+ *  `tier` defaults to a waking `normal`. A caller whose outcome is not worth
+ *  starting a manager's cycle passes `deferred`, which rides the manager's next
+ *  natural cycle instead. */
+export function fanDoctrineWake(fromId, subscribers, label, data, tier = 'normal') {
     for (const sub of subscribers) {
         try {
-            const notice = { from: fromId, tier: 'normal', kind: 'message', label, data };
-            if (sub.active)
+            const notice = { from: fromId, tier, kind: 'message', label, data };
+            if (sub.active) {
                 appendInbox(sub.node_id, notice);
+                // A wake-capable notice consumes the subscriber's cancel-on-wake
+                // deadline: the thing it was waiting for arrived. `deferred` is the
+                // exception — it never wakes a node, riding the next natural cycle
+                // instead, so the deadline it was racing must survive.
+                if (tier !== 'deferred')
+                    cancelCronsOnWake(sub.node_id);
+            }
             else
                 appendPassive(sub.node_id, notice);
         }
@@ -190,12 +197,9 @@ export function closeNode(rootId, opts = {}) {
                 else {
                     transition(id, 'cancel', { reason: 'closed' });
                 }
-                // 2) Tear the node's ENGINE down: send the `shutdown` frame so the broker
-                //    PROCESS exits and releases the sole .jsonl writer. Then proactively
-                //    close the viewer pane + registry row — attach auto-reconnects, so on a
-                //    deliberate close the viewer must be torn down here or it lingers ~30s
-                //    showing a misleading "reconnecting…" instead of going away at once.
-                headlessBrokerHost.teardown(id);
+                // 2) Ask the daemon to tear the engine down after this close response
+                //    settles. The root caller's shell is excluded from its own broker tree.
+                requestBrokerTeardown(id, id === rootId ? { excludePid: opts.callerPid } : {});
                 tearDownNode(id);
                 // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
                 appendInbox(id, {

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

@@ -11,15 +11,36 @@ export interface FaultRecordInput {
     since?: string;
     anchorEntryId?: string;
 }
+/** A provider-retry episode outlives its broker-local timer. Its transcript
+ * path and anchor are explicit coordinates, so replacement invalidation never
+ * has to guess which conversation a marker belongs to. */
+export interface ProviderRetryEpisode {
+    state: 'pending' | 'admitted' | 'invalidated';
+    sessionFile: string;
+    anchorEntryId: string | null;
+    fault: Fault;
+}
 export declare function recordFault(nodeId: string, input: FaultRecordInput): void;
+/** Atomically establishes the crash-recovery authority before publishing its
+ * ordinary marker, so a broker death can never leave only a retryable fault. */
+export declare function recordPendingProviderRetryFault(nodeId: string, sessionFile: string, input: FaultRecordInput): Fault | null;
 export declare function recordFaultForCurrentNode(input: FaultRecordInput): boolean;
 export declare function clearFault(nodeId: string, opts?: {
     link?: FaultLink;
+    preserveProviderRetryEpisode?: boolean;
 }): boolean;
 export declare function clearFaultForCurrentNode(opts?: {
     link?: FaultLink;
 }): boolean;
 export declare function readFault(nodeId: string): Fault | null;
+export declare function readProviderRetryEpisode(nodeId: string): ProviderRetryEpisode | null;
+/** Persist a newly scheduled provider retry before its broker-local timer is armed. */
+export declare function recordPendingProviderRetryEpisode(nodeId: string, episode: Omit<ProviderRetryEpisode, 'state'>): boolean;
+/** Admission is the irreversible boundary: an admitted retry is never replayed. */
+export declare function admitProviderRetryEpisode(nodeId: string, sessionFile: string, fault: Fault): boolean;
+/** A replacement explicitly invalidates its old transcript's retry episode. */
+export declare function invalidateProviderRetryEpisode(nodeId: string, sessionFile: string): boolean;
+export declare function clearProviderRetryEpisode(nodeId: string): void;
 export declare function readFaultAsync(nodeId: string): Promise<Fault | null>;
 export interface BootFaultAttempt {
     /** The recorded fault's operation + message (e.g. an unresolvable `--model`