@north-light/crouter 0.3.249 → 0.3.251

package/dist/core/runtime/fault.js

@@ -1,5 +1,5 @@
 import { envNodeId } from '../../shared/env.js';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { jobDir } from '../canvas/paths.js';
 import { errorClassFromFault, } from '../fault-classifier.js';
@@ -10,6 +10,17 @@ const MESSAGE_CAP = 500;
 function faultPath(nodeId) {
     return join(jobDir(nodeId), 'fault');
 }
+function providerRetryPath(nodeId) {
+    return join(jobDir(nodeId), 'provider-retry');
+}
+function canonicalSessionFile(sessionFile) {
+    try {
+        return realpathSync(sessionFile);
+    }
+    catch {
+        return sessionFile;
+    }
+}
 function clampMessage(message) {
     return message.slice(0, MESSAGE_CAP);
 }
@@ -78,30 +89,64 @@ function currentFault(nodeId) {
         return null;
     }
 }
+function currentProviderRetryEpisode(nodeId) {
+    try {
+        const parsed = JSON.parse(readFileSync(providerRetryPath(nodeId), 'utf8'));
+        if (parsed.state !== 'pending' && parsed.state !== 'admitted' && parsed.state !== 'invalidated')
+            return null;
+        if (typeof parsed.sessionFile !== 'string' || parsed.sessionFile === '')
+            return null;
+        if (parsed.anchorEntryId !== null && typeof parsed.anchorEntryId !== 'string')
+            return null;
+        const fault = parseFault(JSON.stringify(parsed.fault));
+        if (fault === null ||
+            fault.link !== 'pi→provider' ||
+            fault.retry.disposition !== 'auto' ||
+            fault.retry.by !== 'daemon' ||
+            (fault.anchorEntryId ?? null) !== parsed.anchorEntryId)
+            return null;
+        return { state: parsed.state, sessionFile: canonicalSessionFile(parsed.sessionFile), anchorEntryId: parsed.anchorEntryId, fault };
+    }
+    catch {
+        return null;
+    }
+}
 function writeFault(nodeId, fault) {
     try {
         mkdirSync(jobDir(nodeId), { recursive: true });
         writeFileSync(faultPath(nodeId), JSON.stringify(fault));
+        return true;
     }
     catch {
-        /* best-effort */
+        return false;
     }
 }
-function updateMarker(nodeId, fault) {
+function writeProviderRetryEpisode(nodeId, episode) {
+    try {
+        mkdirSync(jobDir(nodeId), { recursive: true });
+        writeFileSync(providerRetryPath(nodeId), JSON.stringify(episode));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolvedMarker(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;
+    if (current === null)
+        return fault;
+    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;
         }
+        return { ...fault, since: current.since, anchorEntryId: current.anchorEntryId ?? fault.anchorEntryId, retry };
     }
-    writeFault(nodeId, fault);
+    return faultPriority(current) > faultPriority(fault) ? null : fault;
+}
+function updateMarker(nodeId, fault) {
+    const resolved = resolvedMarker(nodeId, fault);
+    return resolved !== null && writeFault(nodeId, resolved) ? resolved : null;
 }
 function resolveOperationId(explicit) {
     if (explicit !== undefined)
@@ -111,22 +156,23 @@ function resolveOperationId(explicit) {
         return current;
     return operationIdContext.fresh((operationId) => operationId);
 }
-export function recordFault(nodeId, input) {
-    const operationId = resolveOperationId(input.operation_id);
-    const fault = {
+function storedFault(input) {
+    return {
         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,
+        operation_id: resolveOperationId(input.operation_id),
         ...(typeof input.anchorEntryId === 'string' && input.anchorEntryId !== '' ? { anchorEntryId: input.anchorEntryId } : {}),
     };
+}
+function emitRecordedFault(nodeId, fault) {
     emitEvent({
         level: fault.retry.disposition === 'fatal' ? 'error' : 'warn',
         event: 'fault.recorded',
-        operation_id: operationId,
+        operation_id: fault.operation_id,
         node_id: nodeId,
         error_class: errorClassFromFault(fault),
         fields: {
@@ -138,8 +184,29 @@ export function recordFault(nodeId, input) {
             ...(fault.anchorEntryId === undefined ? {} : { anchor_entry_id: fault.anchorEntryId }),
         },
     });
+}
+export function recordFault(nodeId, input) {
+    const fault = storedFault(input);
+    emitRecordedFault(nodeId, fault);
     updateMarker(nodeId, fault);
 }
+/** Atomically establishes the crash-recovery authority before publishing its
+ * ordinary marker, so a broker death can never leave only a retryable fault. */
+export function recordPendingProviderRetryFault(nodeId, sessionFile, input) {
+    const fault = storedFault(input);
+    emitRecordedFault(nodeId, fault);
+    const marker = resolvedMarker(nodeId, fault);
+    if (marker === null)
+        return null;
+    if (!writeProviderRetryEpisode(nodeId, {
+        state: 'pending',
+        sessionFile: canonicalSessionFile(sessionFile),
+        anchorEntryId: marker.anchorEntryId ?? null,
+        fault: marker,
+    }))
+        return null;
+    return writeFault(nodeId, marker) ? marker : null;
+}
 export function recordFaultForCurrentNode(input) {
     const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
@@ -162,6 +229,11 @@ export function clearFault(nodeId, opts) {
         if (opts?.link !== undefined && current.link !== opts.link)
             return false;
         rmSync(faultPath(nodeId));
+        if (opts?.preserveProviderRetryEpisode !== true) {
+            const episode = currentProviderRetryEpisode(nodeId);
+            if (episode?.fault.since === current.since)
+                rmSync(providerRetryPath(nodeId), { force: true });
+        }
         const operationId = resolveOperationId();
         emitEvent({
             level: 'info',
@@ -197,6 +269,44 @@ export function clearFaultForCurrentNode(opts) {
 export function readFault(nodeId) {
     return currentFault(nodeId);
 }
+export function readProviderRetryEpisode(nodeId) {
+    return currentProviderRetryEpisode(nodeId);
+}
+/** Persist a newly scheduled provider retry before its broker-local timer is armed. */
+export function recordPendingProviderRetryEpisode(nodeId, episode) {
+    return writeProviderRetryEpisode(nodeId, { ...episode, sessionFile: canonicalSessionFile(episode.sessionFile), state: 'pending' });
+}
+/** Admission is the irreversible boundary: an admitted retry is never replayed. */
+export function admitProviderRetryEpisode(nodeId, sessionFile, fault) {
+    const current = currentProviderRetryEpisode(nodeId);
+    if (current === null ||
+        current.state !== 'pending' ||
+        current.sessionFile !== canonicalSessionFile(sessionFile) ||
+        current.fault.since !== fault.since ||
+        current.anchorEntryId !== (fault.anchorEntryId ?? null))
+        return false;
+    return writeProviderRetryEpisode(nodeId, {
+        state: 'admitted',
+        sessionFile: current.sessionFile,
+        anchorEntryId: current.anchorEntryId,
+        fault,
+    });
+}
+/** A replacement explicitly invalidates its old transcript's retry episode. */
+export function invalidateProviderRetryEpisode(nodeId, sessionFile) {
+    const current = currentProviderRetryEpisode(nodeId);
+    if (current === null || current.sessionFile !== canonicalSessionFile(sessionFile) || current.state === 'invalidated')
+        return false;
+    return writeProviderRetryEpisode(nodeId, { ...current, state: 'invalidated' });
+}
+export function clearProviderRetryEpisode(nodeId) {
+    try {
+        rmSync(providerRetryPath(nodeId), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
 export async function readFaultAsync(nodeId) {
     return readFault(nodeId);
 }

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

@@ -22,15 +22,9 @@ 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

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

@@ -22,6 +22,9 @@ export interface HostHandle {
         signal: NodeJS.Signals | null;
     }>;
 }
+export interface TeardownOptions {
+    excludePid?: number;
+}
 export interface Host {
     /** Bring a node's ENGINE into existence from its launch recipe; return a
      *  supervisable handle. */
@@ -31,7 +34,7 @@ export interface Host {
      *  row) — share one selector. For the broker this IS isPidAlive(pi_pid). */
     isAlive(node: string | NodeRow): boolean;
     /** Tear the engine down (close/cancel teardown). */
-    teardown(nodeId: string): void;
+    teardown(nodeId: string, opts?: TeardownOptions): void;
     /** Deliver an OS signal to the engine container — present so the daemon never
      *  reaches around the abstraction. */
     signal(nodeId: string, sig: NodeJS.Signals): void;
@@ -40,4 +43,7 @@ export interface Host {
  *  the fast-fail seam for known module/path errors: a bad engine resolve or a
  *  missing plain session path throws here, before spawn(). */
 export declare function preflightBrokerLaunch(nodeId: string, inv: PiInvocation, cwd: string): void;
+/** Queue broker teardown onto the daemon event loop after the close response can
+ * settle. Repeated terminal reconciliation coalesces on the same node. */
+export declare function requestBrokerTeardown(nodeId: string, opts?: TeardownOptions): void;
 export declare const headlessBrokerHost: Host;

package/dist/core/runtime/host.js

@@ -189,6 +189,24 @@ function escalateBrokerTeardown(tree, identities) {
     killProcessTreePids(tree, 'SIGTERM', identities);
     pollUntil(() => isAnyPidAlive(tree), BROKER_SIGKILL_GRACE_MS, () => killProcessTreePids(tree, 'SIGKILL', identities));
 }
+const requestedTeardowns = new Map();
+/** Queue broker teardown onto the daemon event loop after the close response can
+ * settle. Repeated terminal reconciliation coalesces on the same node. */
+export function requestBrokerTeardown(nodeId, opts = {}) {
+    const existing = requestedTeardowns.get(nodeId);
+    if (existing !== undefined) {
+        if (existing.excludePid === undefined && opts.excludePid !== undefined)
+            existing.excludePid = opts.excludePid;
+        return;
+    }
+    requestedTeardowns.set(nodeId, { ...opts });
+    setImmediate(() => {
+        const request = requestedTeardowns.get(nodeId);
+        requestedTeardowns.delete(nodeId);
+        if (request !== undefined)
+            headlessBrokerHost.teardown(nodeId, request);
+    });
+}
 export const headlessBrokerHost = {
     launch(nodeId, inv, opts) {
         // Fast-fail known launch errors before we detach a broker process.
@@ -336,7 +354,7 @@ export const headlessBrokerHost = {
     isAlive(node) {
         return isPidAlive((typeof node === 'string' ? getNode(node) : node)?.pi_pid);
     },
-    teardown(nodeId) {
+    teardown(nodeId, opts = {}) {
         // Graceful: connect to view.sock + send a `shutdown` frame → the broker
         // dispose()s the engine, unlinks the socket, exits 0. Status is already
         // flipped done/canceled by the caller (crash-safe ordering), so the daemon
@@ -376,7 +394,7 @@ export const headlessBrokerHost = {
         // snapshot's `reused: true` comes back with an EMPTY tree, so nothing
         // below ever signals the stranger (or walks its process tree looking for
         // "descendants", which would be the stranger's children, not ours).
-        const snapshot = pid != null ? captureTeardownSnapshot(pid, node?.pi_pid_identity ?? null) : null;
+        const snapshot = pid != null ? captureTeardownSnapshot(pid, node?.pi_pid_identity ?? null, opts.excludePid) : null;
         if (snapshot?.reused === true) {
             emitEvent({
                 level: 'warn',

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

@@ -59,8 +59,12 @@ export interface SpawnNodeOpts {
     name?: string;
     /** Editor-label handle (2-4 word kebab-case) for the node's first prompt. */
     description?: string;
-    /** Parent node id. Omit for a user-opened root. */
+    /** Parent node id: the spine manager. Omit for a user-opened root. */
     parent?: string | null;
+    /** Actor that created this node. Unlike parent (manager) and spawnedBy
+     *  (audit provenance), it decides whether the parent gets a birth notice.
+     *  Null/omitted means an external process. */
+    creator?: string | null;
     /** Who spawned me (the `spawned_by` provenance edge), when it differs from
      *  `parent` — e.g. an independent root (parent=null) still records its
      *  spawner. Defaults to `parent`. */

package/dist/core/runtime/nodes.js

@@ -15,12 +15,14 @@
 import { envHomeOverride } from '../../shared/env.js';
 import { randomBytes } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
-import { createNode, getNode, getRow, subscribe, recordSpawn, contextDir, } from '../canvas/index.js';
+import { createNode, getNode, getRow, subscribe, recordSpawn, subscribersOf, contextDir, } from '../canvas/index.js';
 import { memoryDir } from './memory.js';
 import { resolveInstallId } from '../canvas/install-id.js';
 import { canvasDbPath } from '../canvas/paths.js';
 import { usage } from '../errors.js';
 import { assertProfileAvailableForBirth } from '../profiles/deletion-reservation.js';
+import { fanDoctrineWake } from './close.js';
+import { BIRTH_ANNOUNCEMENT_MARKER, birthAnnouncementBody } from '../../shared/birth-announcement.js';
 // crtrd sets this once at boot (setInstallId) and it wins unconditionally —
 // a daemon process only ever serves one canvas home for its whole lifetime,
 // so no keying is needed there. Every OTHER in-process caller (tests,
@@ -225,6 +227,7 @@ export function spawnNode(opts) {
     // Provenance is independent of the spine: a root has no parent but still
     // records who spawned it. A child's spawner is its parent unless overridden.
     const spawnedBy = opts.spawnedBy ?? parent;
+    const creator = opts.creator ?? null;
     const mode = opts.mode ?? 'base';
     // A user-opened root is resident (a conversation you live in); a spawned node
     // is terminal until it must persist (promotion handles that later).
@@ -248,6 +251,7 @@ export function spawnNode(opts) {
         status: 'active',
         parent,
         spawned_by: spawnedBy,
+        creator,
         fork_from: opts.forkFrom,
         fork_source_file: opts.forkSourceFile,
         review_binding: opts.reviewBinding,
@@ -265,6 +269,9 @@ export function spawnNode(opts) {
     if (parent !== null && getNode(parent) === null) {
         throw new Error(`cannot spawn under unknown parent node: ${parent}`);
     }
+    if (creator !== null && getNode(creator) === null) {
+        throw new Error(`cannot spawn from unknown creator node: ${creator}`);
+    }
     assertProfileAvailableForBirth(meta.profile_id ?? null);
     createNode(meta);
     // Create the node-local memory directory so substrate docs can be written
@@ -279,6 +286,22 @@ export function spawnNode(opts) {
         // A root (parent=null) gets NO subscription — nobody is woken by it.
         subscribe(parent, meta.node_id, true);
     }
+    if (parent !== null && creator !== parent) {
+        try {
+            fanDoctrineWake(meta.node_id, subscribersOf(meta.node_id), `Child created — ${meta.name} (${meta.node_id}, ${meta.kind})`, {
+                birth_announcement: BIRTH_ANNOUNCEMENT_MARKER,
+                body: birthAnnouncementBody({
+                    name: meta.name,
+                    nodeId: meta.node_id,
+                    kind: meta.kind,
+                    creator: creator === null ? 'an external process' : getNode(creator).name,
+                }),
+            }, 'deferred');
+        }
+        catch {
+            /* a failed birth announcement never prevents the child from existing */
+        }
+    }
     // Audit-only provenance edge — recorded for a root too (from its spawner).
     if (spawnedBy !== null && spawnedBy !== undefined && getNode(spawnedBy) !== null) {
         recordSpawn(meta.node_id, spawnedBy);

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

@@ -89,12 +89,12 @@ export declare function detachToBackground(nodeId: string, pane?: string): boole
 export declare function reapIfEmpty(nodeId: string, keepPane?: string): boolean;
 /** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
  *  behind `crtr canvas prune --empty`, for the husks that accumulated before
- *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), nodes
- *  mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a running
- *  engine is the daemon's domain and may have output not yet persisted, so bulk
- *  GC never kills one (the per-action {@link reapIfEmpty} does, since the user
- *  explicitly closed/detached that node). `dryRun` reports candidates without
- *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), dead rows,
+ *  nodes mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a
+ *  running engine is the daemon's domain and may have output not yet persisted,
+ *  so bulk GC never kills one (the per-action {@link reapIfEmpty} does, since
+ *  the user explicitly closed/detached that node). `dryRun` reports candidates
+ *  without deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
 export declare function reapEmptyNodes(opts?: {
     dryRun?: boolean;
 }): string[];

package/dist/core/runtime/placement.js

@@ -23,9 +23,10 @@
 //     model-over-driver. Raw driver access is confined to placement, its pure
 //     tmux half, the bindings owner, and tmux chrome.
 import { envNodeId } from '../../shared/env.js';
-import { getNode, fullName, deleteNode, listNodes, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
+import { getNode, fullName, deleteNode, listNodes, subscribersOf, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
 import { nodeHasAssistantMessage, isStreaming } from '../canvas/render-source.js';
 import { headlessBrokerHost } from './host.js';
+import { fanDoctrineWake } from './close.js';
 import { paneExists, paneLocation, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, respawnPaneSync, windowOfPane, renameWindow, } from './tmux-driver.js';
 // The PURE tmux + broker-socket half now lives in placement-tmux.ts. placement
 // composes the viewer OPENER over openViewerPane (tmux) + registerViewerFocus
@@ -351,12 +352,12 @@ export function reapIfEmpty(nodeId, keepPane) {
 }
 /** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
  *  behind `crtr canvas prune --empty`, for the husks that accumulated before
- *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), nodes
- *  mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a running
- *  engine is the daemon's domain and may have output not yet persisted, so bulk
- *  GC never kills one (the per-action {@link reapIfEmpty} does, since the user
- *  explicitly closed/detached that node). `dryRun` reports candidates without
- *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), dead rows,
+ *  nodes mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a
+ *  running engine is the daemon's domain and may have output not yet persisted,
+ *  so bulk GC never kills one (the per-action {@link reapIfEmpty} does, since
+ *  the user explicitly closed/detached that node). `dryRun` reports candidates
+ *  without deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
 export function reapEmptyNodes(opts = {}) {
     const dryRun = opts.dryRun ?? false;
     const selfId = envNodeId() ?? '';
@@ -364,9 +365,15 @@ export function reapEmptyNodes(opts = {}) {
     for (const row of listNodes()) {
         const id = row.node_id;
         const meta = getNode(id);
-        if (id === selfId || isPidAlive(row.pi_pid) || meta?.managed_worktree?.state === 'open' || !isEmptyNode(id))
+        if (id === selfId
+            || row.status === 'dead'
+            || isPidAlive(row.pi_pid)
+            || meta?.managed_worktree?.state === 'open'
+            || !isEmptyNode(id))
             continue;
+        const subscribers = subscribersOf(id);
         if (!dryRun) {
+            fanDoctrineWake(id, subscribers, `Child closed — ${meta?.name ?? id} (${id}) was closed from the canvas and is no longer running.`, { reason: 'child-closed', child: id });
             headlessBrokerHost.teardown(id);
             tearDownNode(id);
             if (!deleteNode(id).deleted)

package/dist/core/runtime/reset.js

@@ -22,7 +22,7 @@
 // Best-effort throughout: a tmux/fs failure on one node never aborts the reap.
 import { getNode, updateNode, fullName, closeFocusRow, view, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
-import { headlessBrokerHost } from './host.js';
+import { headlessBrokerHost, requestBrokerTeardown } from './host.js';
 import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPane, renameWindow, } from './placement.js';
 import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
@@ -51,7 +51,7 @@ export function reapDescendants(rootId) {
             // viewer pane + registry row (attach auto-reconnects, so the viewer must be
             // closed here or it lingers ~30s in a misleading "reconnecting…" state).
             transition(id, 'cancel', { reason: 'closed' });
-            headlessBrokerHost.teardown(id);
+            requestBrokerTeardown(id);
             tearDownNode(id);
             reaped.push(id);
         }

package/dist/core/runtime/revive.js

@@ -22,9 +22,9 @@
 // and there is goal/roadmap ground state to re-enter on.
 //
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
-import { findNodeBySessionFile, getNode, updateNode, clearPid, recordPid, setFrozen, clearFrozen, fullName, subscribersOf, } from '../canvas/index.js';
+import { findNodeBySessionFile, getNode, updateNode, clearPid, recordLaunch, recordPid, setFrozen, clearFrozen, fullName, subscribersOf, } from '../canvas/index.js';
 import { emitEvent } from '../events/emit.js';
 import { cancelCronsOnWake } from '../canvas/crons.js';
 import { isParked, transition } from './lifecycle.js';
@@ -41,6 +41,7 @@ import { clearContextExposureState, initializeForkContextExposure, } from '../su
 import { rootOfSpine } from './nodes.js';
 import { isReviewCompanionBound } from '../review/companion.js';
 import { assertProfileActive } from '../profiles/manifest.js';
+import { isPidAlive } from '../canvas/pid.js';
 // resumeArgs — which session source a revive resumes from
 /** Pick the `--session` source for a revive. Both resume=true (a true resume)
  *  and resume=false (a refresh-yield) resume by the absolute session-file path
@@ -64,6 +65,40 @@ export function resumeArgs(meta, resume) {
         return {};
     return resume ? { resumeSessionPath: path } : { resumeSessionPath: path, newCycle: true };
 }
+/** Return false only when a valid Pi session header positively names a cwd that
+ * has gone away. Missing/corrupt headers remain the engine's concern: old
+ * fixtures and partial transcripts do not prove a cwd mismatch. */
+function sessionCwdExists(sessionFile) {
+    try {
+        for (const line of readFileSync(sessionFile, 'utf8').split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const entry = JSON.parse(line);
+            if (entry.type !== 'session')
+                continue;
+            return typeof entry.cwd !== 'string' || existsSync(entry.cwd);
+        }
+    }
+    catch {
+        // The broker/engine owns malformed-transcript diagnostics; it is not proof
+        // that the stored cwd is absent.
+    }
+    return true;
+}
+/** The session-file preflight has two ordered vetoes. A live owner wins before
+ * inspecting its transcript, so this node can never adopt or clear another
+ * broker's file. Only an unowned/dead-owner file then reaches the cwd check. */
+function resumableSessionArgs(nodeId, meta, resume) {
+    const path = meta.pi_session_file;
+    if (path == null || path === '' || !existsSync(path))
+        return {};
+    const owner = findNodeBySessionFile(path);
+    if (owner !== null && owner.node_id !== nodeId && isPidAlive(owner.pi_pid))
+        return {};
+    if (!sessionCwdExists(path))
+        return {};
+    return resumeArgs(meta, resume);
+}
 // Return type
 /** A relaunch that has NO transcript to resume or branch from, and no durable
  *  work state on disk (no roadmap, no yield note), is not a revive at all — the
@@ -262,7 +297,7 @@ function launchRevive(nodeId, meta, opts) {
     const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
     const parkedReentry = isParked(meta) && hasFreshGroundState(nodeId) && hasUnseenWakeMail(nodeId);
     const effectiveResume = refreshPending || parkedReentry ? false : opts.resume;
-    const resume = forkBirthPending ? {} : resumeArgs(meta, effectiveResume);
+    const resume = forkBirthPending ? {} : resumableSessionArgs(nodeId, meta, effectiveResume);
     // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether
     // as a true resume OR a cycling refresh-yield (resumeArgs sets `newCycle` in
     // the latter case). cycling and resuming are mutually exclusive; `resuming`
@@ -354,7 +389,7 @@ function launchRevive(nodeId, meta, opts) {
     // this marker advertised. Snapshot the boot-fault attempt in the SAME
     // breath (see beginBootFaultAttempt): its own verification, not this call's
     // unchecked result, is what scopes a later diagnostic read to this attempt.
-    clearFault(nodeId);
+    clearFault(nodeId, { preserveProviderRetryEpisode: true });
     const bootFault = beginBootFaultAttempt(nodeId);
     // A cron armed --cancel-on-wake belongs to the dormancy being left, so a WAKE
     // of its anchor deletes it — an inbox delivery, an attach, an explicit
@@ -394,6 +429,7 @@ function launchRevive(nodeId, meta, opts) {
         clearPid(nodeId);
         throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
     }
+    recordLaunch(nodeId, new Date().toISOString());
     // Record the real broker pid. The pid is METADATA now (design D-13) — the
     // liveness authority is the fleet entry registered synchronously inside
     // `launch` above — but session_start re-records it after extension bind,

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

@@ -11,6 +11,9 @@ export interface SpawnChildOpts {
     prompt: string;
     /** Override the parent (defaults to the calling node from env). */
     parent?: string;
+    /** Actor that created this node. Unlike parent (manager) and spawned_by
+     *  (provenance), it controls the parent's birth announcement. */
+    creator?: string | null;
     /** Spawn an INDEPENDENT root instead of a managed child: parent=null, no
      *  subscription back to the spawner, spawned_by=spawner. Resident and brought
      *  forefront by default — see `rootLifecycle` for the unattended variant. */

package/dist/core/runtime/spawn.js

@@ -275,6 +275,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             // records spawned_by=spawner when a node (not a human shell) spawned it.
             // A child's parent IS its manager.
             parent: root ? null : spawner,
+            creator: opts.creator,
             spawnedBy: root ? (spawner ?? undefined) : undefined,
             profile_id: profileId,
             forkFrom: opts.forkFrom,

package/dist/core/runtime/warm-pool.d.ts

@@ -24,6 +24,10 @@ export interface WarmRequest {
     model: string | null;
     situationalContext: string | null;
     name: string | null;
+    /** Node that asked for this create, or null for an external process. Claim-time
+     *  identity like `name` — a spare is minted creator-less and adopts the
+     *  claimant's, so provenance survives the warm path. */
+    creator: string | null;
 }
 /** Claim a spare for `request`, reshaped onto its persona — or null when the
  *  pool cannot serve it. The caller falls back to a cold spawn; a claim never

package/dist/core/runtime/warm-pool.js

@@ -128,6 +128,7 @@ export async function claimWarmNode(request) {
         kind: request.kind,
         mode: request.mode,
         name: request.name ?? request.kind,
+        creator: request.creator,
         // The recipe a later revive replays — skip it and the node silently comes
         // back as the spare's persona.
         launch: recipe.launch,
@@ -354,6 +355,7 @@ export function prewarmRecentRecipes() {
                 model: null,
                 situationalContext: null,
                 name: null,
+                creator: null,
             }).then(mint).catch((err) => console.error(`[warm-pool] prewarm failed for ${candidate.cwd}: ${err.message}`));
         }
         catch (err) {

package/dist/core/worktree.d.ts

@@ -57,9 +57,10 @@ interface CleanEmptyProof {
  *  be a git-ancestor of (or equal to) the CURRENT tip of its recorded base
  *  branch — i.e. landing it would be a pure no-op. Any ambiguity (missing
  *  path, mid-rebase, wrong branch, an unresolvable base, or a real ancestry
- *  divergence) returns null: this function only ever proves a no-op land
- *  when a live git check establishes it, never on a heuristic guess, so real
- *  unlanded work always falls through to the explicit-close guard. The locked
+ *  divergence) returns null. A missing base is the one exception: equality
+ *  between the live HEAD and recorded creation SHA proves no work was added.
+ *  This function only ever proves a no-op land from live Git state, never on
+ *  a heuristic guess, so real unlanded work always falls through to the explicit-close guard. The locked
  *  path re-checks this predicate before recording deferred cleanup; production
  *  code must always go through `autoDropCleanManagedWorktree`. */
 export declare function proveCleanEmptyManagedWorktree(wt: ManagedWorktree): CleanEmptyProof | null;