@north-light/crouter 0.3.248 → 0.3.250

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`

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[];