@north-light/crouter 0.3.312 → 0.3.313

package/dist/core/runtime/recycle.js

@@ -17,7 +17,7 @@
 // message) — falling back to a short note when it never reported.
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, setPresence, setFocusOccupant, fullName, recordLaunch, recordPid } from '../canvas/index.js';
+import { abortExecution, beginExecution, getNode, setPresence, setFocusOccupant, fullName, recordExecutionPid, recordLaunch } from '../canvas/index.js';
 import { reportsDir } from '../canvas/paths.js';
 import { pushFinal } from '../feed/feed.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
@@ -25,6 +25,7 @@ import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { focusOf, respawnPaneSync, setPaneOption } from './placement.js';
 import { waitForBrokerViewSocket, viewerSplitEnv } from './placement-tmux.js';
 import { headlessBrokerHost } from './host.js';
+import { boundFleet } from './fleet.js';
 import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 import { invokeBirthLifecycleHooks } from './spawn.js';
@@ -137,17 +138,22 @@ export async function recycleNode(nodeId, callerPane) {
  *  broker. This direct birth path writes the same launch/pid coordinates as
  *  reviveNode, and a failed readiness probe terminalizes and tears it down. */
 async function launchRecycledBroker(fresh, inv) {
+    const executionId = beginExecution(fresh.node_id, { daemonEpoch: boundFleet().epoch() });
+    inv.env = { ...inv.env, CRTR_EXECUTION_ID: executionId };
     let placed;
     try {
         placed = headlessBrokerHost.launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
         if (placed.pid === null)
             throw new Error('broker host returned no pid');
         recordLaunch(fresh.node_id, new Date().toISOString());
-        recordPid(fresh.node_id, placed.pid);
+        if (recordExecutionPid(executionId, fresh.node_id, placed.pid) === 'shutdown') {
+            throw new Error('broker execution was superseded');
+        }
         if (await waitForBrokerViewSocket(fresh.node_id, placed.exited))
             return true;
     }
     catch {
+        abortExecution(executionId, { reason: 'launch_failed' });
         // The replacement never became usable; the finished root's broker remains
         // intact and this half-born row cannot remain active without a fleet handle.
     }

package/dist/core/runtime/reset.js

@@ -20,9 +20,10 @@
 // reserved for finish).
 //
 // Best-effort throughout: a tmux/fs failure on one node never aborts the reap.
-import { getNode, updateNode, recordLaunch, recordPid, fullName, closeFocusRow, view, } from '../canvas/index.js';
+import { getNode, beginExecution, recordExecutionPid, abortExecution, bindSession, recordLaunch, fullName, liveExecutionForNode, closeFocusRow, view, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost, requestBrokerTeardown } from './host.js';
+import { boundFleet } from './fleet.js';
 import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPane, renameWindow, } from './placement.js';
 import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
@@ -116,6 +117,8 @@ export async function relaunchRoot(oldId, deps = {}) {
         ...inv.env,
         CRTR_SUBTREE: rootOfSpine(newMeta.node_id),
     };
+    const executionId = beginExecution(newMeta.node_id, { daemonEpoch: boundFleet().epoch() });
+    inv.env = { ...inv.env, CRTR_EXECUTION_ID: executionId };
     let placed;
     try {
         placed = launchBroker(newMeta.node_id, inv, {
@@ -125,10 +128,12 @@ export async function relaunchRoot(oldId, deps = {}) {
         });
     }
     catch (error) {
+        abortExecution(executionId, { reason: 'launch_failed' });
         transition(newMeta.node_id, 'crash');
         throw error;
     }
     if (placed.pid == null) {
+        abortExecution(executionId, { reason: 'launch_failed' });
         // The new broker never started — crash the half-born node and BAIL. The old
         // root is still live and untouched (nothing below this point has run).
         transition(newMeta.node_id, 'crash');
@@ -138,7 +143,15 @@ export async function relaunchRoot(oldId, deps = {}) {
     // real exit, while the row gets the matching launch and pid coordinates before
     // readiness can observe an early exit.
     recordLaunch(newMeta.node_id, new Date().toISOString());
-    recordPid(newMeta.node_id, placed.pid);
+    if (recordExecutionPid(executionId, newMeta.node_id, placed.pid) === 'shutdown') {
+        abortExecution(executionId, { reason: 'superseded' });
+        try {
+            teardownBroker(newMeta.node_id);
+        }
+        catch { /* best-effort */ }
+        transition(newMeta.node_id, 'crash');
+        return null;
+    }
     let ready = false;
     try {
         ready = await waitForViewSocket(newMeta.node_id, placed.exited);
@@ -191,10 +204,13 @@ export function resetRoot(nodeId, newSessionId, newSessionFile) {
     if (meta === null || meta.parent == null)
         return empty; // unknown or a root
     if (newSessionId !== undefined) {
-        updateNode(nodeId, {
-            pi_session_id: newSessionId,
-            ...(newSessionFile !== undefined ? { pi_session_file: newSessionFile } : {}),
-        });
+        const execution = liveExecutionForNode(nodeId);
+        if (execution !== null)
+            bindSession(nodeId, {
+                executionId: execution.executionId,
+                sessionId: newSessionId,
+                transcriptPath: newSessionFile ?? null,
+            });
     }
     return empty;
 }

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',
@@ -289,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;
     }
@@ -312,225 +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;
-    // 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)) {
-        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 (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);
-        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.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, crtrHome, findNodeBySessionFile, getNode, fullName, jobDir, nodeDir, recordPid, reportsDir, 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';
@@ -390,6 +390,8 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch, afterNodeCrea
             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
@@ -402,6 +404,10 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch, afterNodeCrea
                 resuming: false,
             });
         }
+        catch (error) {
+            abortExecution(executionId, { reason: 'launch_failed' });
+            throw error;
+        }
         finally {
             fleet.releaseReservation(meta.node_id);
         }
@@ -411,10 +417,15 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch, afterNodeCrea
         // 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