@north-light/crouter 0.3.311 → 0.3.313

package/dist/core/runtime/revive.js

@@ -24,7 +24,7 @@
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
-import { findNodeBySessionFile, getNode, updateNode, clearPid, recordLaunch, recordPid, setFrozen, clearFrozen, fullName, subscribersOf, } from '../canvas/index.js';
+import { findNodeBySessionFile, getNode, updateNode, beginExecution, recordExecutionPid, abortExecution, endLiveExecution, unbindSession, recordLaunch, 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';
@@ -36,8 +36,7 @@ import { readRoadmap } from './roadmap.js';
 import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
 import { headlessBrokerHost } from './host.js';
 import { boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.js';
-import { clearFault, beginBootFaultAttempt } from './fault.js';
-import { clearTransportPoisonVerdict } from './busy.js';
+import { beginBootFaultAttempt, clearFault } from '../canvas/recovery.js';
 import { clearContextExposureState, initializeForkContextExposure, } from '../substrate/injected-store.js';
 import { rootOfSpine } from './nodes.js';
 import { isReviewCompanionBound } from '../review/companion.js';
@@ -228,7 +227,7 @@ async function decideRevive(nodeId, opts, wakeParked) {
             // every status surface. Clearing it is what makes `isFrozenRow` true and
             // what tells the tick this row has never launched OR has already been
             // written off, so the freeze lane owes it a launch rather than a verdict.
-            clearPid(nodeId);
+            endLiveExecution(nodeId, { reason: 'frozen' });
             emitEvent({
                 level: 'info',
                 event: 'broker.frozen',
@@ -278,10 +277,6 @@ async function launchRevive(nodeId, meta, opts) {
             next,
         });
     }
-    // This is the same durable distinction used to decide between a birth prompt
-    // and a revive kickoff below. Compute it before launch mutations so a stale
-    // session identity cannot make an ordinary fresh revive look like a birth.
-    const isBirth = isUnstartedBirth(nodeId);
     // Lazy host_kind coerce (§C): every launch now uses the broker host. Persist
     // that identity only after this call has passed the no-op liveness guard.
     if (meta.host_kind !== 'broker') {
@@ -293,7 +288,7 @@ async function launchRevive(nodeId, meta, opts) {
     // immutable fork instead of resuming an inherited transcript.
     const reviewCompanionUnbound = meta.review_binding != null && !isReviewCompanionBound(nodeId);
     if (reviewCompanionUnbound && (meta.pi_session_id != null || meta.pi_session_file != null)) {
-        updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
+        unbindSession(nodeId);
         meta.pi_session_id = null;
         meta.pi_session_file = null;
     }
@@ -316,220 +311,234 @@ async function launchRevive(nodeId, meta, opts) {
             next: `Restore ${forkSourceFile}, or update the node's fork source, then retry \`crtr node lifecycle revive ${nodeId}\`.`,
         });
     }
-    // Every (re)launch is a new cycle — bump the counter so CRTR_CYCLES and the
-    // footer stay in sync. Mutate the in-memory meta too so buildPiArgv below
-    // launches with the incremented count.
-    meta.cycles = (meta.cycles ?? 0) + 1;
-    updateNode(nodeId, { cycles: meta.cycles });
-    // Ordinary nodes choose resume/cycle/fresh from their recorded session.
-    // Persisted pending-refresh state (durable across a pre-session_start
-    // crash-retry) outranks a caller's strict-resume request. A parked node now
-    // resumes its transcript too: its isolated parking turn never entered the
-    // main session, so wake mail continues one intact conversation without a
-    // fresh-cycle handoff. resumeArgs then selects only an existing absolute
-    // session path: strict resume continues its leaf, while refresh/cycle mode
-    // roots a new one.
-    const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
-    const effectiveResume = refreshPending ? false : opts.resume;
-    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`
-    // keeps the STRICT true-resume-only meaning `ReviveResult.resumed` and the
-    // launch-placement hint below have always carried.
-    const hasSessionPath = resume.resumeSessionPath !== undefined;
-    const cycling = hasSessionPath && resume.newCycle === true;
-    const resuming = hasSessionPath && !cycling;
-    // A cycling launch is provisional until session_start confirms it. Once
-    // true, this marker is monotonic across failed retries; only that confirmed
-    // boot may clear it.
-    const cyclePending = meta.cycle_pending === true || cycling;
-    updateNode(nodeId, { cycle_pending: cyclePending });
-    meta.cycle_pending = cyclePending;
-    // A truly fresh launch — no `.jsonl` to resume OR cycle from —
-    // starts a NEW pi session, so the old session identity is dead. Clear it from meta NOW,
-    // before launch, so the recorded state matches what we're about to do. This
-    // is load-bearing for exit-policy classification (classifyDeadNode row 8):
-    // if this fresh broker dies BEFORE session_start (recording no new session),
-    // the exit-policy job reads pi_session_id=NULL → boot-failure, the correct
-    // terminal outcome (transition('crash') + surfaceBootFailure) — a leftover
-    // stale id would instead be misread as a resumable session and retried. A
-    // cycling refresh keeps BOTH ids — the `.jsonl` and its recorded session id
-    // are exactly what's being reused — so a cycling broker that dies
-    // pre-session_start classifies as a retryable respawn, same class as a
-    // resume revive.
-    if (!forkBirthPending && !hasSessionPath && (meta.pi_session_id != null || meta.pi_session_file != null)) {
-        updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
-        meta.pi_session_id = null;
-        meta.pi_session_file = null;
-    }
-    // A true resume needs no kickoff — the saved conversation just continues. A
-    // fresh revive OR a cycling refresh-yield both get one so the (re-rooted)
-    // window re-reads its roadmap and continues: drainBearings captures the
-    // yield note and consumes the feed/persona acknowledgements; the builder is
-    // then pure. `resume` carries `resumeSessionPath`/`newCycle` through
-    // unchanged (empty for true-fresh, both set for cycling) so buildPiArgv emits
-    // the right argv either way.
-    let inv;
-    // The provenance of whatever kickoff this branch composes, handed to the
-    // broker process through inv.env below. A promptless launch announces
-    // nothing — there is no message to stamp.
-    let kickoffOrigin = null;
-    const birthOrigin = () => ({
-        type: 'runtime',
-        kind: 'kickoff',
-        ...(meta.spawned_by != null && meta.spawned_by !== '' ? { spawnedBy: meta.spawned_by } : {}),
-    });
-    if (forkBirthPending) {
-        const goal = readGoal(nodeId);
-        inv = buildPiArgv(meta, {
-            forkFrom: forkSourceFile,
-            ...(goal != null && goal !== '' ? { prompt: goal } : {}),
-        });
-        if (goal != null && goal !== '')
-            kickoffOrigin = birthOrigin();
-        initializeForkContextExposure(nodeId, findNodeBySessionFile(forkSourceFile)?.node_id ?? null);
-    }
-    else if (resuming) {
-        inv = buildPiArgv(meta, {
-            ...resume,
-            ...(opts.wakeReason === 'runtime-restart-abort' ? { prompt: RUNTIME_RESTART_CONTINUATION } : {}),
-        });
-        if (opts.wakeReason === 'runtime-restart-abort') {
-            kickoffOrigin = { type: 'runtime', kind: 'restart-continuation' };
-        }
-    }
-    else if (!hasSessionPath &&
-        // A clock-driven wake must keep its <crtr-wake> kickoff — the schedule IS
-        // the instruction to take a turn, so it never degrades to a birth replay.
-        (opts.wakeReason === undefined || opts.wakeReason === 'runtime-restart-abort') &&
-        isUnstartedBirth(nodeId)) {
-        // Never conversed and nothing on disk to rebuild from — relaunch as a birth
-        // (see isUnstartedBirth). A node with a spawn mandate replays it; a bare
-        // interactive node boots promptless and takes no turn at all.
-        const goal = readGoal(nodeId)?.trim();
-        inv = buildPiArgv(meta, goal !== undefined && goal !== '' ? { prompt: goal } : {});
-        if (goal !== undefined && goal !== '')
-            kickoffOrigin = birthOrigin();
-        clearContextExposureState(nodeId);
-    }
-    else {
-        // Fresh or cycling: drain the one-shot bearings, then build the kickoff.
-        // When a scheduled bare self-alarm drove this revive, opts.wakeReason
-        // carries the wake provenance so the kickoff leads with a <crtr-wake> block
-        // ("a timer woke you"); every other reviveNode caller passes nothing → no
-        // block.
-        const bearings = drainBearings(meta);
-        inv = buildPiArgv(meta, {
-            ...resume,
-            prompt: buildReviveKickoff(meta, bearings, opts.wakeReason === 'runtime-restart-abort' ? undefined : opts.wakeReason),
-        });
-        kickoffOrigin = opts.wakeReason !== undefined && opts.wakeReason !== 'runtime-restart-abort'
-            ? { type: 'runtime', kind: 'wake', wake: opts.wakeReason }
-            : { type: 'runtime', kind: 'revive', cycle: meta.cycles ?? 0 };
-        clearContextExposureState(nodeId);
-    }
-    // Every lifecycle launch emits the authoritative spine root rather than
-    // inheriting whichever node happened to invoke reviveNode.
-    inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(nodeId) };
-    if (kickoffOrigin !== null)
-        inv.env[KICKOFF_ORIGIN_ENV] = encodeKickoffOrigin(kickoffOrigin);
-    // The broker host launches the detached engine. reviveNode keeps
-    // transition+clearPid around it (the crash-safety ordering, unchanged). It
-    // opens NO viewer — engine-only; existing viewers reconnect, and a viewer-less
-    // node is brought on screen by the next `focus`.
-    transition(nodeId, meta.intent === 'refresh' ? 'refresh-launch' : 'revive');
-    // Clear any active fault the instant this node is (re)launched — don't wait
-    // for the fresh agent_start. A revive (auto or on-demand) is the recovery
-    // 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, { 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
-    // revive. A recovery relaunch is not a wake: the broker instance died or was
-    // torn down and the daemon is putting the same waiting node back on its feet,
-    // with nothing external having arrived. The wait the deadline bounds is still
-    // open, so the deadline survives — the same rule lifecycle.ts applies to the
-    // `crash` transition (a deadline MUST survive instance death).
-    if (opts.recovery !== true)
-        cancelCronsOnWake(nodeId);
-    ensureNodeDirs(nodeId);
-    clearTransportPoisonVerdict(nodeId);
-    const lifecycleHooks = discoverLifecycleHookRegistry(meta.cwd, meta.profile_id).plans.get('node:start') ?? [];
-    await invokeLifecycleHooks(lifecycleHooks, {
-        node: {
-            id: nodeId,
-            name: meta.name,
-            kind: meta.kind,
-            mode: meta.mode,
-            lifecycle: meta.lifecycle,
-            cwd: meta.cwd,
-            nodeDir: nodeDir(nodeId),
-            contextDir: contextDir(nodeId),
-            jobDir: jobDir(nodeId),
-            reportsDir: reportsDir(nodeId),
-        },
-        runtime: {
-            isBirth,
-            canvasHome: crtrHome(),
-            profile: meta.profile_id ?? null,
-        },
-    });
-    let launched;
+    const executionId = beginExecution(nodeId, { daemonEpoch: boundFleet().epoch() });
     try {
-        launched = headlessBrokerHost.launch(nodeId, inv, {
-            cwd: meta.cwd,
-            name: fullName(meta),
-            resuming,
+        // Every (re)launch is a new cycle — bump the counter so CRTR_CYCLES and the
+        // footer stay in sync. Mutate the in-memory meta too so buildPiArgv below
+        // launches with the incremented count.
+        meta.cycles = (meta.cycles ?? 0) + 1;
+        updateNode(nodeId, { cycles: meta.cycles });
+        // Ordinary nodes choose resume/cycle/fresh from their recorded session.
+        // Persisted pending-refresh state (durable across a pre-session_start
+        // crash-retry) outranks a caller's strict-resume request. A parked node now
+        // resumes its transcript too: its isolated parking turn never entered the
+        // main session, so wake mail continues one intact conversation without a
+        // fresh-cycle handoff. resumeArgs then selects only an existing absolute
+        // session path: strict resume continues its leaf, while refresh/cycle mode
+        // roots a new one.
+        const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
+        const effectiveResume = refreshPending ? false : opts.resume;
+        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`
+        // keeps the STRICT true-resume-only meaning `ReviveResult.resumed` and the
+        // launch-placement hint below have always carried.
+        const hasSessionPath = resume.resumeSessionPath !== undefined;
+        const cycling = hasSessionPath && resume.newCycle === true;
+        const resuming = hasSessionPath && !cycling;
+        // Never conversed and nothing on disk to rebuild from — relaunch as a birth
+        // (see isUnstartedBirth). A clock-driven wake must keep its <crtr-wake>
+        // kickoff — the schedule IS the instruction to take a turn, so it never
+        // degrades to a birth replay. This one decision selects the kickoff below
+        // and is what the node:start hook payload reports as `isBirth`: a hook is
+        // told "birth" exactly when the node boots as one.
+        const birthReplay = !hasSessionPath
+            && (opts.wakeReason === undefined || opts.wakeReason === 'runtime-restart-abort')
+            && isUnstartedBirth(nodeId);
+        const isBirth = forkBirthPending || birthReplay;
+        // A cycling launch is provisional until session_start confirms it. Once
+        // true, this marker is monotonic across failed retries; only that confirmed
+        // boot may clear it.
+        const cyclePending = meta.cycle_pending === true || cycling;
+        updateNode(nodeId, { cycle_pending: cyclePending });
+        meta.cycle_pending = cyclePending;
+        // A truly fresh launch — no `.jsonl` to resume OR cycle from —
+        // starts a NEW pi session, so the old session identity is dead. Clear it from meta NOW,
+        // before launch, so the recorded state matches what we're about to do. This
+        // is load-bearing for exit-policy classification (classifyDeadNode row 8):
+        // if this fresh broker dies BEFORE session_start (recording no new session),
+        // the exit-policy job reads pi_session_id=NULL → boot-failure, the correct
+        // terminal outcome (transition('crash') + surfaceBootFailure) — a leftover
+        // stale id would instead be misread as a resumable session and retried. A
+        // cycling refresh keeps BOTH ids — the `.jsonl` and its recorded session id
+        // are exactly what's being reused — so a cycling broker that dies
+        // pre-session_start classifies as a retryable respawn, same class as a
+        // resume revive.
+        if (!forkBirthPending && !hasSessionPath && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+            unbindSession(nodeId);
+            meta.pi_session_id = null;
+            meta.pi_session_file = null;
+        }
+        // A true resume needs no kickoff — the saved conversation just continues. A
+        // fresh revive OR a cycling refresh-yield both get one so the (re-rooted)
+        // window re-reads its roadmap and continues: drainBearings captures the
+        // yield note and consumes the feed/persona acknowledgements; the builder is
+        // then pure. `resume` carries `resumeSessionPath`/`newCycle` through
+        // unchanged (empty for true-fresh, both set for cycling) so buildPiArgv emits
+        // the right argv either way.
+        let inv;
+        // The provenance of whatever kickoff this branch composes, handed to the
+        // broker process through inv.env below. A promptless launch announces
+        // nothing — there is no message to stamp.
+        let kickoffOrigin = null;
+        const birthOrigin = () => ({
+            type: 'runtime',
+            kind: 'kickoff',
+            ...(meta.spawned_by != null && meta.spawned_by !== '' ? { spawnedBy: meta.spawned_by } : {}),
         });
-        if (launched.pid === null) {
-            throw new Error(`broker host returned no pid for ${nodeId}`);
+        if (forkBirthPending) {
+            const goal = readGoal(nodeId);
+            inv = buildPiArgv(meta, {
+                forkFrom: forkSourceFile,
+                ...(goal != null && goal !== '' ? { prompt: goal } : {}),
+            });
+            if (goal != null && goal !== '')
+                kickoffOrigin = birthOrigin();
+            initializeForkContextExposure(nodeId, findNodeBySessionFile(forkSourceFile)?.node_id ?? null);
         }
-    }
-    catch (error) {
+        else if (resuming) {
+            inv = buildPiArgv(meta, {
+                ...resume,
+                ...(opts.wakeReason === 'runtime-restart-abort' ? { prompt: RUNTIME_RESTART_CONTINUATION } : {}),
+            });
+            if (opts.wakeReason === 'runtime-restart-abort') {
+                kickoffOrigin = { type: 'runtime', kind: 'restart-continuation' };
+            }
+        }
+        else if (birthReplay) {
+            // A node with a spawn mandate replays it; a bare interactive node boots
+            // promptless and takes no turn at all.
+            const goal = readGoal(nodeId)?.trim();
+            inv = buildPiArgv(meta, goal !== undefined && goal !== '' ? { prompt: goal } : {});
+            if (goal !== undefined && goal !== '')
+                kickoffOrigin = birthOrigin();
+            clearContextExposureState(nodeId);
+        }
+        else {
+            // Fresh or cycling: drain the one-shot bearings, then build the kickoff.
+            // When a scheduled bare self-alarm drove this revive, opts.wakeReason
+            // carries the wake provenance so the kickoff leads with a <crtr-wake> block
+            // ("a timer woke you"); every other reviveNode caller passes nothing → no
+            // block.
+            const bearings = drainBearings(meta, executionId);
+            inv = buildPiArgv(meta, {
+                ...resume,
+                prompt: buildReviveKickoff(meta, bearings, opts.wakeReason === 'runtime-restart-abort' ? undefined : opts.wakeReason),
+            });
+            kickoffOrigin = opts.wakeReason !== undefined && opts.wakeReason !== 'runtime-restart-abort'
+                ? { type: 'runtime', kind: 'wake', wake: opts.wakeReason }
+                : { type: 'runtime', kind: 'revive', cycle: meta.cycles ?? 0 };
+            clearContextExposureState(nodeId);
+        }
+        // Every lifecycle launch emits the authoritative spine root rather than
+        // inheriting whichever node happened to invoke reviveNode.
+        inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(nodeId) };
+        if (kickoffOrigin !== null)
+            inv.env[KICKOFF_ORIGIN_ENV] = encodeKickoffOrigin(kickoffOrigin);
+        // The broker host launches the detached engine. reviveNode keeps
+        // transition+clearPid around it (the crash-safety ordering, unchanged). It
+        // opens NO viewer — engine-only; existing viewers reconnect, and a viewer-less
+        // node is brought on screen by the next `focus`.
+        transition(nodeId, meta.intent === 'refresh' ? 'refresh-launch' : 'revive');
+        // Clear any active fault the instant this node is (re)launched — don't wait
+        // for the fresh agent_start. A revive (auto or on-demand) is the recovery
+        // 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, { preserveEpisode: 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
+        // revive. A recovery relaunch is not a wake: the broker instance died or was
+        // torn down and the daemon is putting the same waiting node back on its feet,
+        // with nothing external having arrived. The wait the deadline bounds is still
+        // open, so the deadline survives — the same rule lifecycle.ts applies to the
+        // `crash` transition (a deadline MUST survive instance death).
+        if (opts.recovery !== true)
+            cancelCronsOnWake(nodeId);
+        ensureNodeDirs(nodeId);
+        const lifecycleHooks = discoverLifecycleHookRegistry(meta.cwd, meta.profile_id).plans.get('node:start') ?? [];
+        await invokeLifecycleHooks(lifecycleHooks, {
+            node: {
+                id: nodeId,
+                name: meta.name,
+                kind: meta.kind,
+                mode: meta.mode,
+                lifecycle: meta.lifecycle,
+                cwd: meta.cwd,
+                nodeDir: nodeDir(nodeId),
+                contextDir: contextDir(nodeId),
+                jobDir: jobDir(nodeId),
+                reportsDir: reportsDir(nodeId),
+            },
+            runtime: {
+                isBirth,
+                canvasHome: crtrHome(),
+                profile: meta.profile_id ?? null,
+            },
+        });
+        inv.env = { ...inv.env, CRTR_EXECUTION_ID: executionId };
+        let launched;
         try {
-            transition(nodeId, 'crash', {
-                reason: 'launch_failed',
-                outcome: {
-                    detail: {
-                        schema: 'crtr.node-outcome-detail/v1',
-                        message: error instanceof Error ? error.message : String(error),
-                    },
-                },
+            launched = headlessBrokerHost.launch(nodeId, inv, {
+                cwd: meta.cwd,
+                name: fullName(meta),
+                resuming,
             });
-            // Doctrine wake: a launch-refusal here marks the node dead with NOTHING
-            // else fanning that out — the daemon's own auto-revive is the most common
-            // caller (superviseTick, best-effort try/catch, stderr-only on failure), so
-            // without this a manager waiting dormant on this child hangs forever,
-            // never told it will not come back on its own. Mirrors closeNode's step-4
-            // fan-out (same subscribers table, same active/passive split).
-            fanDoctrineWake(nodeId, subscribersOf(nodeId), `Child crashed — ${fullName(meta)} (${nodeId}) failed to relaunch and is now dead: ${error.message}\n\n` +
-                `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`, { reason: 'child-crashed', child: nodeId });
+            if (launched.pid === null) {
+                throw new Error(`broker host returned no pid for ${nodeId}`);
+            }
+        }
+        catch (error) {
+            try {
+                transition(nodeId, 'crash', {
+                    reason: 'launch_failed',
+                    outcome: {
+                        detail: {
+                            schema: 'crtr.node-outcome-detail/v1',
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    },
+                });
+                // Doctrine wake: a launch-refusal here marks the node dead with NOTHING
+                // else fanning that out — the daemon's own auto-revive is the most common
+                // caller (superviseTick, best-effort try/catch, stderr-only on failure), so
+                // without this a manager waiting dormant on this child hangs forever,
+                // never told it will not come back on its own. Mirrors closeNode's step-4
+                // fan-out (same subscribers table, same active/passive split).
+                fanDoctrineWake(nodeId, subscribersOf(nodeId), `Child crashed — ${fullName(meta)} (${nodeId}) failed to relaunch and is now dead: ${error.message}\n\n` +
+                    `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`, { reason: 'child-crashed', child: nodeId });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+            abortExecution(executionId, { reason: 'launch_failed' });
+            throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
         }
-        catch {
-            /* best-effort cleanup */
+        recordLaunch(nodeId, new Date().toISOString());
+        // The execution row owns the broker pid. A stale broker that reaches the
+        // daemon after its execution was superseded is stopped rather than claiming
+        // the current node process slot.
+        if (recordExecutionPid(executionId, nodeId, launched.pid) === 'shutdown') {
+            abortExecution(executionId, { reason: 'superseded' });
+            headlessBrokerHost.teardown(nodeId);
+            throw new Error(`[broker] refusing to revive ${nodeId}: execution was superseded during launch`);
         }
-        clearPid(nodeId);
-        throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
+        // A launch is the definition of not-frozen, and every launcher passes
+        // through here — so this is the one place the wait mark is retired.
+        clearFrozen(nodeId);
+        return {
+            window: null,
+            session: meta.tmux_session ?? null,
+            resumed: resuming,
+            launch: launched,
+            faultExplanation: bootFault.explanation,
+            outcome: 'launched',
+        };
+    }
+    catch (error) {
+        abortExecution(executionId, { reason: 'launch_failed' });
+        throw error;
     }
-    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,
-    // and status surfaces (canvas views, the daemon's identity rechecks at
-    // signal boundaries) still read it.
-    recordPid(nodeId, launched.pid);
-    // A launch is the definition of not-frozen, and every launcher passes
-    // through here — so this is the one place the wait mark is retired.
-    clearFrozen(nodeId);
-    return {
-        window: null,
-        session: meta.tmux_session ?? null,
-        resumed: resuming,
-        launch: launched,
-        faultExplanation: bootFault.explanation,
-        outcome: 'launched',
-    };
 }

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

@@ -127,8 +127,11 @@ export declare function resolveSpawner(parent: string | undefined, ctxNodeId: st
  *  to the spawner (it carries spawned_by=spawner for provenance only), brought
  *  forefront so a human can pick up the conversation directly. */
 type BeforeBrokerLaunch = (nodeId: string) => void;
-export declare function spawnChildPrepared(opts: SpawnChildOpts, beforeBrokerLaunch?: BeforeBrokerLaunch): Promise<SpawnChildResult>;
+type AfterNodeCreated = (nodeId: string) => void;
+export declare function spawnChildPrepared(opts: SpawnChildOpts, beforeBrokerLaunch?: BeforeBrokerLaunch, afterNodeCreated?: AfterNodeCreated): Promise<SpawnChildResult>;
 export declare function spawnChild(opts: SpawnChildOpts): Promise<SpawnChildResult>;
+/** Invoke the best-effort node-start plan before any cold broker launch. */
+export declare function invokeBirthLifecycleHooks(meta: NodeMeta): Promise<void>;
 /** Create an independent, idle root from a node's conversation and durable
  * context. Runtime/graph state is intentionally not inherited. */
 export declare function forkNode(sourceId: string): Promise<SpawnChildResult>;

package/dist/core/runtime/spawn.js

@@ -22,13 +22,13 @@ import { appendSituationalContext, formatSituationalProse } from './situational-
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
 import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
-import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid, setFrozen } from '../canvas/index.js';
+import { beginExecution, canonicalSessionFile, contextDir, crtrHome, findNodeBySessionFile, getNode, fullName, jobDir, nodeDir, recordExecutionPid, abortExecution, reportsDir, setFrozen } from '../canvas/index.js';
 import { boundFleet, brokerThresholdsForDaemon } from './fleet.js';
 import { emitEvent } from '../events/emit.js';
 import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
 import { waitForBrokerViewSocket } from './placement-tmux.js';
 import { transition } from './lifecycle.js';
-import { beginBootFaultAttempt } from './fault.js';
+import { beginBootFaultAttempt } from '../canvas/recovery.js';
 import { piSessionsRoot } from './pi-vendored.js';
 import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
@@ -37,6 +37,8 @@ import { modelRequestFromConfig, unregisteredConcreteModel } from '../model-rout
 import { openModelRegistry } from './model-registry.js';
 import { MODEL_SPEC_NEXT } from './model-selection.js';
 import { initializeForkContextExposure } from '../substrate/injected-store.js';
+import { discoverLifecycleHookRegistry } from '../command-hooks/discovery.js';
+import { invokeLifecycleHooks } from '../command-hooks/transport/exec-lifecycle.js';
 // Shared broker-launch wrapper — catch launch/preflight failures at the call
 // site, mark the node crashed, then rethrow a clear error.
 function launchFailureOutcome(error) {
@@ -210,7 +212,7 @@ export function resolveSpawner(parent, ctxNodeId, root) {
     }
     return spawner;
 }
-export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
+export async function spawnChildPrepared(opts, beforeBrokerLaunch, afterNodeCreated) {
     try {
         ensureDaemon();
     }
@@ -276,7 +278,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         if (wantsWorktree) {
             await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd: spawnCwd, profileId });
         }
-        const meta = spawnNode({
+        const meta = await spawnNode({
             kind: opts.kind,
             mode,
             lifecycle,
@@ -299,6 +301,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             ...(opts.outcomeDelivery === undefined ? {} : { outcomeDelivery: opts.outcomeDelivery }),
             launch,
         });
+        afterNodeCreated?.(meta.node_id);
         if (opts.forkFrom !== undefined) {
             try {
                 initializeForkContextExposure(meta.node_id, forkSourceNodeId);
@@ -345,6 +348,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         }
         // (The three scoped long-term memory stores are seeded for EVERY node at birth
         // in spawnNode — no orchestrator-gated seeding needed here.)
+        await invokeBirthLifecycleHooks(meta);
         const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
         // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
         // the subtree; the host sets CRTR_FRONT_DOOR itself.
@@ -386,6 +390,8 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             return { node: getNode(meta.node_id), frozen: true, window: null, session: null };
         }
         const bootFault = beginBootFaultAttempt(meta.node_id);
+        const executionId = beginExecution(meta.node_id, { daemonEpoch: fleet.epoch() });
+        inv.env = { ...inv.env, CRTR_EXECUTION_ID: executionId };
         // Broker is the only host: launch the detached broker ENGINE. A managed child
         // gets NO viewer — spawning it returns once the engine is launched and a human
         // opens a viewer on demand via `crtr surface node focus` / surface attach. A --root gets
@@ -398,6 +404,10 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                 resuming: false,
             });
         }
+        catch (error) {
+            abortExecution(executionId, { reason: 'launch_failed' });
+            throw error;
+        }
         finally {
             fleet.releaseReservation(meta.node_id);
         }
@@ -407,10 +417,15 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // spawnNode). Mirrors the old window===null crash.
         if (placed.pid === null) {
             const error = new Error(`broker host returned no pid for ${meta.node_id}`);
+            abortExecution(executionId, { reason: 'launch_failed' });
             transition(meta.node_id, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
             throw brokerLaunchFailed(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`, `Inspect canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`, then verify the pi engine can start in this environment.`);
         }
-        recordPid(meta.node_id, placed.pid);
+        if (recordExecutionPid(executionId, meta.node_id, placed.pid) === 'shutdown') {
+            abortExecution(executionId, { reason: 'superseded' });
+            headlessBrokerHost.teardown(meta.node_id);
+            throw brokerLaunchFailed(`broker execution was superseded for ${meta.node_id}`, 'Retry spawning the node.');
+        }
         // A root created through `node new --root` must accept viewers before the
         // command returns because its caller may attach immediately. Only that root
         // waits — a managed child (and every cron-launched
@@ -491,6 +506,29 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
 export async function spawnChild(opts) {
     return spawnChildPrepared(opts);
 }
+/** Invoke the best-effort node-start plan before any cold broker launch. */
+export async function invokeBirthLifecycleHooks(meta) {
+    const lifecycleHooks = discoverLifecycleHookRegistry(meta.cwd, meta.profile_id).plans.get('node:start') ?? [];
+    await invokeLifecycleHooks(lifecycleHooks, {
+        node: {
+            id: meta.node_id,
+            name: meta.name,
+            kind: meta.kind,
+            mode: meta.mode,
+            lifecycle: meta.lifecycle,
+            cwd: meta.cwd,
+            nodeDir: nodeDir(meta.node_id),
+            contextDir: contextDir(meta.node_id),
+            jobDir: jobDir(meta.node_id),
+            reportsDir: reportsDir(meta.node_id),
+        },
+        runtime: {
+            isBirth: true,
+            canvasHome: crtrHome(),
+            profile: meta.profile_id ?? null,
+        },
+    });
+}
 const FORK_CONTEXT_EXCLUDES = new Set(['initial-prompt.md', 'yield-message.md', 'result.json']);
 /** Create an independent, idle root from a node's conversation and durable
  * context. Runtime/graph state is intentionally not inherited. */

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

@@ -30,8 +30,8 @@ export interface WarmRequest {
     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
- *  fails the create. */
+ *  pool cannot serve it. The caller falls back to a cold spawn; a refused
+ *  create hook leaves the spare untouched and rejects the create. */
 export declare function claimWarmNode(request: WarmRequest, birth?: {
     deadlineAt?: string;
     outcomeDelivery?: OutcomeDeliveryBinding;