@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/revive.js

@@ -0,0 +1,739 @@
+// The revive primitive — restores a node to active status by relaunching its
+// broker engine. Used by both the supervisor daemon (on crash/refresh
+// detection) and the explicit `crtr node lifecycle revive` command (or `crtr canvas revive --all`).
+//
+// A revive replays the node's persisted LaunchSpec + cwd (the canonical recipe)
+// and launches the headless broker host (the only host after the
+// broker-is-the-host cut). It opens NO viewer — it relaunches the engine only;
+// existing viewer panes reconnect to the fresh broker on their own (attach
+// auto-reconnect), and a node with no viewer is brought on screen by the next
+// `focus`.
+//
+//   resume=true  → the caller prefers `pi --session <path>`, waking the saved
+//                  conversation when its absolute session-file path exists.
+//   resume=false → the caller prefers a fresh context. An existing `.jsonl` is
+//                  reused with `--crtr-new-cycle`; a node with no session file
+//                  gets a truly fresh pi invocation.
+//
+// These are requests. Durable `intent=refresh` or `cycle_pending=true` always
+// vetoes strict resume so focus and daemon callers cannot reopen an old
+// context while a fresh cycle is still unconfirmed. A parked node vetoes it
+// too, but only when the revival carries new input — unseen wake-worthy mail —
+// and there is goal/roadmap ground state to re-enter on.
+//
+// reviveNode remains the ONLY sanctioned launcher of the node engine.
+import { assertGranteeRunsHere } from './unsandboxed.js';
+import { existsSync } from 'node:fs';
+import { conversationIdFromPath, conversationStore, ConversationNotFoundError } from '../conversation-store/index.js';
+import { isAbsolute } from 'node:path';
+import { findNodeBySessionFile, getNode, updateNode, beginExecution, ExecutionAlreadyLive, recordExecutionPid, abortExecution, endLiveExecution, unbindSession, recordLaunch, setFrozen, clearFrozen, fullName, } from '../canvas/index.js';
+import { emitEvent } from '../events/emit.js';
+import { consumeDeadlineOnWake } from '../feed/messages.js';
+import { isParked, transition } from './lifecycle.js';
+import { publishNotice } from './close.js';
+import { InputError } from '../io.js';
+import { buildPiArgv } from './launch.js';
+import { buildReviveKickoff, drainBearings, hasRetainedReports, readGoal, readYieldMessage, RUNTIME_RESTART_CONTINUATION } from './kickoff.js';
+import { readRoadmap } from './roadmap.js';
+import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
+import { headlessBrokerHost, brokerLaunchJson } from './host.js';
+import { isCloudRole } from '../canvas/person.js';
+import { asNodePerson } from '../../daemon/reconcilers/node-lifecycle/node-person.js';
+import { processRunner } from './runner/process.js';
+import { runnerForEnvironment } from './runner/index.js';
+import { MachineLaunchUncertainError, MachineOfflineError } from './runner/machine/ops.js';
+import { blaxelEnvironmentOf } from './blaxel-environment.js';
+import { recordLaunchFailure } from '../../daemon/reconcilers/node-lifecycle/launch-failure.js';
+import { acceptedRelease, remoteMachineEnvironmentOf, checkBilledWake, EnvironmentImagePending, imageForWake } from '../../daemon/reconcilers/node-lifecycle/remote-wake.js';
+import { ExecutionCapReached, liveExecutionForNode, setExecutionLaunchJson } from '../canvas/executions.js';
+import { isDrained } from '../../daemon/drain.js';
+import { appMemoryFull, appMemoryTooSmall, boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.js';
+import { admitBrokerMemory } from './memory-admission.js';
+import { beginBootFaultAttempt, clearFault, hasAdmittedTurn, readFault } from '../canvas/recovery.js';
+import { clearNodeLedger, forkNodeLedger, noticeChangedWhileDone } from './ledger.js';
+import { forkSourceNode, rootOfSpine } from './nodes.js';
+import { ApiError } from '../../api/errors.js';
+import { grantSnapshotMissing } from '../../daemon/readiness.js';
+import { checkStart } from './start-check.js';
+import { isReviewCompanionBound } from '../review/companion.js';
+import { assertProfileActive } from '../profiles/manifest.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { crtrHome, jobDir } from '../canvas/paths.js';
+import { contextDir, ensureNodeDirs, nodeAgentDir } from '../canvas/node-agent-paths.js';
+import { discoverLifecycleHookRegistry } from '../command-hooks/discovery.js';
+import { invokeLifecycleHooks } from '../command-hooks/transport/exec-lifecycle.js';
+// resumeArgs — which session source a revive resumes from
+/** Pick the `--session` source for a revive. Both resume=true (a true resume)
+ *  and resume=false (a refresh-yield) resume by the absolute session-file path
+ *  (immune to cwd; pi opens it directly) — but ONLY when that file actually
+ *  exists on disk. A node's `pi_session_file` can be recorded in meta with
+ *  nothing ever written there (e.g. its first-boot engine died before
+ *  session_start ever ran), and `headlessBrokerHost.launch`'s preflight
+ *  (host.ts) fatally rejects handing pi a `--session` for a missing path OR a
+ *  bare id — either would crash the revive and strand the node dead with
+ *  nothing to recover it. So when there is no real `.jsonl` to resume, this
+ *  selects NEITHER source regardless of `resume`: the caller then falls
+ *  through to a truly fresh (`--fresh`-equivalent) launch, which is always
+ *  safe. The only difference between the two `resume` values (when the file
+ *  DOES exist) is `newCycle`: resume=false additionally roots a fresh cycle
+ *  branch (`--crtr-new-cycle`) rather than continuing the existing leaf. Pure
+ *  so the decision is unit-testable without tmux or a real filesystem fixture
+ *  beyond a temp file. */
+export async function resumeArgs(meta, resume) {
+    const path = meta.pi_session_file;
+    const id = path ? conversationIdFromPath(path) : null;
+    if (id === null)
+        return {};
+    try {
+        const recorded = await conversationStore().header(id);
+        return resume ? { resumeSessionPath: recorded.path } : { resumeSessionPath: recorded.path, newCycle: true };
+    }
+    catch (error) {
+        if (error instanceof ConversationNotFoundError)
+            return {};
+        throw error;
+    }
+}
+async function conversationExists(path) {
+    const id = conversationIdFromPath(path);
+    if (id === null)
+        return false;
+    try {
+        await conversationStore().header(id);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof ConversationNotFoundError)
+            return false;
+        throw error;
+    }
+}
+/** Whether the saved session holds any conversational message. The bearings
+ *  are a custom message, so a session that only ever took its session_start has
+ *  none; one that carries a user or assistant message has been conversed in. */
+async function sessionHasConversation(sessionFile) {
+    const id = conversationIdFromPath(sessionFile);
+    if (id === null)
+        return true;
+    return (await conversationStore().read(id)).entries.some((entry) => entry.type === 'message');
+}
+/** Return false only when a valid Pi session header positively names a cwd that
+ * has gone away. Missing/corrupt headers remain the engine's concern: old
+ * fixtures and partial transcripts do not prove a cwd mismatch. */
+async function sessionCwdExists(sessionFile) {
+    const id = conversationIdFromPath(sessionFile);
+    if (id === null)
+        return true;
+    const cwd = (await conversationStore().header(id)).header.cwd;
+    return typeof cwd !== 'string' || existsSync(cwd);
+}
+/** The session-file preflight has two ordered vetoes. A live owner wins before
+ * inspecting its transcript, so this node can never adopt or clear another
+ * broker's file. Only an unowned/dead-owner file then reaches the cwd check. */
+async function resumableSessionArgs(nodeId, meta, resume, 
+/** False for a sandbox node: its session cwd exists inside the sandbox, which the sandbox start script checks. */
+cwdIsLocal) {
+    const path = meta.pi_session_file;
+    if (!path || !await conversationExists(path))
+        return {};
+    const owner = await findNodeBySessionFile(path);
+    if (owner !== null && owner.node_id !== nodeId && isPidAlive(owner.pi_pid))
+        return {};
+    if (cwdIsLocal && !await sessionCwdExists(path))
+        return {};
+    return await resumeArgs(meta, resume);
+}
+// Return type
+/** A relaunch that has NO transcript to resume or branch from, and no durable
+ *  work state on disk (no roadmap, yield note, or retained report), is not a revive at all — the
+ *  node never got a conversation off the ground, so there is no "previous
+ *  in-memory context" that was lost. pi does not write a `.jsonl` until the
+ *  first turn, so an idle node the user never messaged is the common case: it
+ *  sits with only its injected bearings until a daemon restart tears its broker
+ *  down. Handing that node the fresh-revive kickoff tells it, falsely, that it
+ *  lost context and must rebuild from disk — and disk is empty — so it wakes,
+ *  flails over an empty context dir and reports itself confused. Relaunch it as
+ *  a BIRTH instead: replay the spawn mandate when it has one, or boot with no
+ *  prompt at all and leave it sitting exactly where it was. */
+async function isUnstartedBirth(nodeId) {
+    return await readRoadmap(nodeId) === null && await readYieldMessage(nodeId) === null && !await hasRetainedReports(nodeId);
+}
+/** Whether a fresh context window would have anything on disk to stand on: a
+ *  goal, a roadmap, or both. The negative is what makes a fresh cycle worse
+ *  than a resume — the new window would wake amnesiac, with no statement of
+ *  what it is for. Read by the parked-resident veto below and by the message
+ *  handler's explicit fresh-revive gate. */
+export async function hasFreshGroundState(nodeId) {
+    const goal = await readGoal(nodeId);
+    if (goal !== null && goal.trim() !== '')
+        return true;
+    const roadmap = await readRoadmap(nodeId);
+    return roadmap !== null && roadmap.trim() !== '';
+}
+// reviveNode
+/** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
+ *  meta. Opens no viewer (engine-only).
+ *
+ *  `recovery: true` marks a launch that only replaces a broker instance which
+ *  died or was torn down — the daemon's respawn after a broker exit, and the
+ *  `reviveAll` sweep over disconnected nodes. Nothing external arrived for the
+ *  node, so such a launch is NOT a wake and does not consume the node's armed
+ *  deadline (see the consumeDeadlineOnWake call below). A viewer attach (the
+ *  `viewerAttach` flag {@link decideAttachRevive} sets) is not a wake either.
+ *
+ *  Throws if the node does not exist. All other failures propagate as-is —
+ *  callers (daemon, command) decide how to handle.
+ */
+export async function reviveNode(nodeId, opts) {
+    const decision = await decideRevive(nodeId, opts, true);
+    if (decision.parked)
+        throw new Error(`reviveNode: internal parked decision for activating revive ${nodeId}`);
+    return decision.result;
+}
+/** The attach-specific entry to the revive boundary. A focus viewer may decline
+ * to wake an exact parked resident while preserving the ordinary activating
+ * attach default. The fleet check and parked decision are synchronous with the
+ * launch below, so an already-running broker wins before dormancy is observed.
+ *
+ * Attaching only to look is not a wake: every launch through this entry is
+ * marked `viewerAttach`, so it leaves the node's armed `node wait deadline`
+ * cron in place. Anything the person types reaches the node as a message, and
+ * that delivery is the wake that consumes the deadline. */
+export async function decideAttachRevive(nodeId, opts, wakeParked) {
+    return decideRevive(nodeId, { ...opts, viewerAttach: true }, wakeParked);
+}
+/** A cloud role serves many people and has none of its own: a revive there reads the person's settings and rotation rows, so it runs as
+ *  the node's person (its `sub`, or its profile's owner), with that person's snapshot loaded, exactly as the lifecycle lanes do. */
+async function decideRevive(nodeId, opts, wakeParked) {
+    const meta = isCloudRole() ? await getNode(nodeId) : null;
+    if (meta === null)
+        return await decideReviveAsCaller(nodeId, opts, wakeParked);
+    return await asNodePerson({ node_id: nodeId, sub: meta.sub ?? null, profile_id: meta.profile_id ?? null }, () => decideReviveAsCaller(nodeId, opts, wakeParked));
+}
+async function decideReviveAsCaller(nodeId, opts, wakeParked) {
+    let meta = await getNode(nodeId);
+    if (meta === null) {
+        throw new Error(`reviveNode: unknown node ${nodeId}`);
+    }
+    // Fresh durable snapshot immediately before the lifecycle guard.
+    meta = await getNode(nodeId) ?? meta;
+    if (meta.run_id && (await getNode(meta.run_id))?.deleting_at)
+        throw new Error('run is deleting');
+    // Refuse to revive a LATCHED node — the reopen gate at every
+    // legitimate caller (node message send, node lifecycle revive) already checked this
+    // before calling in, but a target can finalize in the gap between that
+    // check and this call. This authoritative snapshot closes that race;
+    // a genuine `--reopen` caller has already CAS-cleared the latch.
+    if (meta.final_report !== null) {
+        throw new Error(`reviveNode: refusing to revive ${nodeId} — its finalization latch is set (final_report=${meta.final_report}). A final landed between the caller's reopen-gate check and this revive; re-run with --reopen if this retask is still wanted.`);
+    }
+    assertProfileActive(meta.profile_id);
+    // An unsandboxed machine runs terminal agents only: refuse before any lifecycle hook or other prelaunch executable runs as the app.
+    assertGranteeRunsHere(meta.grantee);
+    // Double-launch guard: a fleet entry IS liveness (design D-1). A lifecycle
+    // hook is awaited before the broker can register, so its reservation also
+    // owns the node while launch is in flight; a second contender must not cross
+    // that awaited gap and start a second broker on the same session file.
+    const fleet = boundFleet();
+    // A terminal node's token is minted from the terminal grant, and a joined runtime holds none until its first directory snapshot
+    // commits. Read here, before the guard below, because nothing may await between that guard and the slot reservation.
+    const awaitingGrants = meta.grantee === 'app:terminal' && await grantSnapshotMissing();
+    // The start check: a dormant node woken by mail, a message or a person starts only when no limit covering every charge of its
+    // payer is reached. A refusal throws `402 cap_exhausted` naming the limit and leaves the node dormant. Replacing a dead broker
+    // only when it re-drives a turn already started (`runtime-restart-abort`) or attaches a viewer is it not new work: a recovery of
+    // an unlaunched birth or of pending mail starts a turn and is checked. It is awaited HERE, before the guard below, so nothing
+    // awaits between the guard and the slot reservation (a contender awaiting in that gap would launch a second broker); a node
+    // already live or claimed is not starting and is not checked.
+    if (!await fleet.has(nodeId) && !await fleet.isClaimed(nodeId) && opts.wakeReason !== 'runtime-restart-abort' && opts.viewerAttach !== true
+        && !(!wakeParked && meta.lifecycle === 'resident' && isParked(meta))) {
+        await checkStart(meta);
+        // A node in a Blaxel environment also passes the funding-bill check before any sandbox call (wake step 2).
+        if (await blaxelEnvironmentOf(meta.profile_id ?? null) !== null)
+            await checkBilledWake(meta);
+    }
+    if (await fleet.has(nodeId)) {
+        // The node is already running, but the ROW may still say terminal: a reopen
+        // or a retask lands on a live broker, and only this transition puts the row
+        // back where its liveness already is. Both specs accept any prior status,
+        // so this is a no-op for a row that is already active.
+        await transition(nodeId, meta.intent === 'refresh' ? 'refresh-launch' : 'revive');
+        return {
+            parked: false,
+            result: {
+                window: null,
+                session: meta.tmux_session ?? null,
+                resumed: false,
+                outcome: 'already-live',
+            },
+        };
+    }
+    if (await fleet.isClaimed(nodeId)) {
+        return {
+            parked: false,
+            result: {
+                window: null,
+                session: meta.tmux_session ?? null,
+                resumed: false,
+                outcome: 'already-live',
+            },
+        };
+    }
+    // Focus may establish a viewport without establishing an engine. This exact
+    // row has no final latch and no fleet owner; returning before reservation is
+    // what keeps lifecycle, cycle count, pid, inbox cursor, and session untouched.
+    if (!wakeParked && meta.lifecycle === 'resident' && isParked(meta)) {
+        return { parked: true };
+    }
+    // No snapshot yet is unknown authority, not a denial (the same rule as node creation): launching now would fail at the token mint
+    // and mark the node dead. Wait for the snapshot like a node waiting for a slot — frozen, relaunched by the tick once grants sync.
+    if (awaitingGrants) {
+        if (opts.capacity === 'refuse')
+            throw new ApiError(503, 'runtime_starting', 'the first grant snapshot from the directory has not committed');
+        await freezeForWait(nodeId, meta, { reason: 'grant_snapshot' });
+        return { parked: false, result: { window: null, session: meta.tmux_session ?? null, resumed: false, outcome: 'frozen' } };
+    }
+    // The cap, consulted BEFORE any mutation below: a node that cannot get a
+    // broker must not have its cycle counter bumped, its session identity
+    // cleared, or its bearings drained on the way to being turned away.
+    // A drained daemon (an import is dumping this install) wakes nothing: the row freezes as at a full cap, and the tick thaws it
+    // once the drain ends. A caller that must have a broker now is refused.
+    const drained = await isDrained();
+    if (drained && opts.capacity === 'refuse')
+        throw new Error(`the daemon is drained for an import; ${nodeId} cannot start until it ends`);
+    const slot = !drained && await fleet.reserveSlot(nodeId);
+    let memory = null;
+    if (slot) {
+        try {
+            memory = await admitBrokerMemory(nodeId);
+        }
+        catch (error) {
+            fleet.releaseReservation(nodeId);
+            throw error;
+        }
+        if (memory.verdict !== 'admitted')
+            fleet.releaseReservation(nodeId);
+    }
+    if (memory?.verdict === 'too_small')
+        throw appMemoryTooSmall(memory);
+    if (!slot || memory?.verdict === 'denied') {
+        if (opts.capacity === 'refuse') {
+            throw memory?.verdict === 'denied'
+                ? appMemoryFull(memory)
+                : brokerCapReached(brokerThresholdsForDaemon().automaticReviveCap, await fleet.occupancy());
+        }
+        await freezeForWait(nodeId, meta, drained ? { reason: 'drain' } : memory?.verdict === 'denied'
+            ? { reason: 'app_memory', free_bytes: memory.free_bytes, needed_bytes: memory.needed_bytes }
+            : { reason: 'broker_cap', live_count: await fleet.occupancy(), hard_cap: brokerThresholdsForDaemon().automaticReviveCap });
+        return {
+            parked: false,
+            result: {
+                window: null,
+                session: meta.tmux_session ?? null,
+                resumed: false,
+                outcome: 'frozen',
+            },
+        };
+    }
+    try {
+        return { parked: false, result: await launchRevive(nodeId, meta, opts) };
+    }
+    finally {
+        // The slot is either consumed by the fleet registration inside `launch`
+        // (making this a no-op) or given back here — the one release path covering
+        // every preflight refusal and launch failure between the claim and the
+        // registration.
+        fleet.releaseReservation(nodeId);
+    }
+}
+/** Freezing is durable and once-per-episode: the mark stays until a launch
+ *  clears it, so a node frozen across many saturated ticks announces itself
+ *  exactly once and keeps its original wait timestamp (the thaw order reads
+ *  it). */
+async function freezeForWait(nodeId, meta, fields) {
+    if (meta.frozen_at != null)
+        return;
+    await setFrozen(nodeId, new Date().toISOString());
+    // The row holds no engine and is not getting one this pass, so a pid left
+    // over from the instance that just died would read as stale-active on
+    // 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.
+    await endLiveExecution(nodeId, { reason: 'frozen' });
+    emitEvent({ level: 'info', event: 'broker.frozen', node_id: nodeId, fields });
+}
+/** A recorded cwd that no longer exists (e.g. a closed managed worktree whose tombstone dir was later
+ *  reaped) can never host a launch. Fail loud with a typed, user-visible error naming the path instead
+ *  of letting `headlessBrokerHost.launch` fail deep inside the crash/doctrine-wake catch, where it would
+ *  surface as an opaque `internal error` (toErrorBody masks every 5xx). Callers admit work to a node
+ *  with this before changing any state. Returns where the node runs: its Blaxel environment (null on a machine) and whether a remote machine hosts it. */
+export async function assertRecordedCwdExists(nodeId, meta) {
+    // A sandbox node's cwd is a path inside its sandbox: the sandbox start script checks it (`cwd_missing`), never this host.
+    const blaxelEnvironment = await blaxelEnvironmentOf(meta.profile_id ?? null);
+    // A cloud role's node whose profile points at a machine environment runs on that machine: its cwd is a path there, which the machine's start checks.
+    const remoteMachine = await remoteMachineEnvironmentOf(meta.profile_id ?? null) !== null;
+    const remote = blaxelEnvironment !== null || remoteMachine;
+    if (!remote && !existsSync(meta.cwd)) {
+        const next = meta.fork_from != null
+            ? `Restore ${meta.cwd}, then revive the fork normally with \`crtr node lifecycle revive ${nodeId}\`.`
+            : meta.managed_worktree?.state === 'open'
+                ? 'Restore or reconcile the recorded checkout, then use the managed-worktree close or abandon recovery.'
+                : `Recreate ${meta.cwd}, or repair it with \`crtr node config --cwd <path> --node ${nodeId}\`; durable node work resumes in a fresh conversation. Then retry \`crtr node lifecycle revive ${nodeId}\`.`;
+        throw new InputError({
+            error: 'cwd_missing',
+            message: `${nodeId} cannot be revived — its recorded cwd no longer exists: ${meta.cwd}`,
+            next,
+        });
+    }
+    return { blaxelEnvironment, remoteMachine };
+}
+/** The launch itself, from the cwd preflight through `recordPid`. Split out so
+ *  the capacity claim above has exactly one release path around it. */
+async function launchRevive(nodeId, meta, opts) {
+    const { blaxelEnvironment, remoteMachine } = await assertRecordedCwdExists(nodeId, meta);
+    const remote = blaxelEnvironment !== null || remoteMachine;
+    // 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') {
+        await updateNode(nodeId, { host_kind: 'broker' });
+        meta.host_kind = 'broker';
+    }
+    // A review companion's session coordinates are valid only after its durable
+    // visible boundary. Detach any markerless child so this launch replays the
+    // immutable fork instead of resuming an inherited transcript.
+    const reviewCompanionUnbound = meta.review_binding != null && !await isReviewCompanionBound(nodeId);
+    if (reviewCompanionUnbound && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+        await unbindSession(nodeId);
+        meta.pi_session_id = null;
+        meta.pi_session_file = null;
+    }
+    // An ordinary fork remains a birth until session_start records the child
+    // session. Every retry replays the resolved immutable source file.
+    const forkBirthUnbound = meta.fork_from != null && meta.pi_session_id == null;
+    const forkSourceFile = meta.fork_source_file;
+    if (forkBirthUnbound && (typeof forkSourceFile !== 'string' || !isAbsolute(forkSourceFile))) {
+        throw new InputError({
+            error: 'fork_source_invalid',
+            message: `${nodeId} cannot be revived — its resolved fork source file is missing or invalid.`,
+            next: `Restore the node's fork source metadata, then retry \`crtr node lifecycle revive ${nodeId}\`.`,
+        });
+    }
+    const forkBirthPending = forkBirthUnbound && typeof forkSourceFile === 'string';
+    if (forkBirthPending && !await conversationExists(forkSourceFile)) {
+        throw new InputError({
+            error: 'fork_from_missing',
+            message: `${nodeId} cannot be revived — its fork source no longer exists: ${forkSourceFile}`,
+            next: `Restore ${forkSourceFile}, or update the node's fork source, then retry \`crtr node lifecycle revive ${nodeId}\`.`,
+        });
+    }
+    const { automaticReviveCap } = brokerThresholdsForDaemon();
+    // A node whose profile points at a Blaxel environment launches through the Blaxel runner; a recipe with no built image
+    // starts nothing and leaves the node's mail pending (D95).
+    if (blaxelEnvironment !== null) {
+        const image = await imageForWake(blaxelEnvironment);
+        if (image.state === 'pending')
+            throw new EnvironmentImagePending(blaxelEnvironment, image.error);
+    }
+    const runner = blaxelEnvironment !== null ? runnerForEnvironment('blaxel') : remoteMachine ? runnerForEnvironment('machine') : processRunner;
+    let executionId;
+    try {
+        executionId = await beginExecution(nodeId, { daemonEpoch: boundFleet().epoch(), cap: automaticReviveCap,
+            ...(blaxelEnvironment !== null ? { runner: 'blaxel', release: acceptedRelease() } : remoteMachine ? { runner: 'machine', release: acceptedRelease() } : {}) });
+    }
+    catch (error) {
+        // Another daemon process took the last slot between the in-process check and the row insert.
+        if (error instanceof ExecutionCapReached)
+            throw brokerCapReached(error.cap, error.live);
+        // A concurrent caller (another API process) holds the node's live execution: it owns the launch, so this one adopts it.
+        if (error instanceof ExecutionAlreadyLive) {
+            return { window: null, session: meta.tmux_session ?? null, resumed: false, outcome: 'already-live' };
+        }
+        throw error;
+    }
+    try {
+        // 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;
+        await 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 ? {} : await resumableSessionArgs(nodeId, meta, effectiveResume, !remote);
+        // 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')
+            && await isUnstartedBirth(nodeId);
+        // A session file proves only that session_start wrote the bearings. A child
+        // whose broker died before its kickoff was admitted holds exactly that, so
+        // resuming it promptless would leave it idle forever. Replay the goal only
+        // when no execution ever admitted a turn AND the session has no conversation.
+        const unadmittedBirth = resuming
+            && (opts.wakeReason === undefined || opts.wakeReason === 'runtime-restart-abort')
+            && !await hasAdmittedTurn(nodeId)
+            // No recorded turn is not proof on its own: nodes that predate execution
+            // records worked without leaving one. Replay only when the session itself
+            // holds no conversation.
+            && !await sessionHasConversation(resume.resumeSessionPath);
+        const birthGoal = unadmittedBirth ? (await readGoal(nodeId))?.trim() : undefined;
+        const birthKickoffReplay = birthGoal !== undefined && birthGoal !== '';
+        const isBirth = forkBirthPending || birthReplay || birthKickoffReplay;
+        // 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;
+        await 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)) {
+            await 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 (forkBirthPending) {
+            const goal = await readGoal(nodeId);
+            // The daemon copies the source into a conversation this node owns before
+            // launch, as spawn does for an ordinary fork. The broker's store socket
+            // admits a node only to conversations it owns, so a broker-side `--fork`
+            // of a source it does not own (a review branch the daemon materialized)
+            // is refused as not-found and the broker dies on every retry.
+            const sourceId = conversationIdFromPath(forkSourceFile);
+            if (sourceId === null)
+                throw new Error(`invalid fork source ${forkSourceFile}`);
+            const forkSessionPath = (await conversationStore().header(await conversationStore().fork(sourceId, nodeId))).path;
+            inv = buildPiArgv(meta, {
+                resumeSessionPath: forkSessionPath,
+                ...(goal != null && goal !== '' ? { prompt: goal } : {}),
+            });
+            if (goal != null && goal !== '')
+                kickoffOrigin = birthOrigin();
+            await forkNodeLedger(nodeId, (await forkSourceNode(forkSourceFile))?.node_id ?? null);
+        }
+        else if (birthKickoffReplay) {
+            // Resume the bearings-only session and deliver the task it never admitted.
+            // The ledger is kept: the session is the one the node already owns.
+            inv = buildPiArgv(meta, { ...resume, prompt: birthGoal });
+            kickoffOrigin = birthOrigin();
+        }
+        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 = (await readGoal(nodeId))?.trim();
+            inv = buildPiArgv(meta, goal !== undefined && goal !== '' ? { prompt: goal } : {});
+            if (goal !== undefined && goal !== '')
+                kickoffOrigin = birthOrigin();
+            await clearNodeLedger(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 = await drainBearings(meta, executionId);
+            inv = buildPiArgv(meta, {
+                ...resume,
+                prompt: await buildReviveKickoff(meta, bearings, opts.wakeReason === 'runtime-restart-abort' ? undefined : opts.wakeReason),
+            });
+            if (meta.run_id && bearings.unreadMessageIds?.length)
+                inv.env['CRTR_KICKOFF_MESSAGE_IDS'] = JSON.stringify(bearings.unreadMessageIds);
+            kickoffOrigin = opts.wakeReason !== undefined && opts.wakeReason !== 'runtime-restart-abort'
+                ? { type: 'runtime', kind: 'wake', wake: opts.wakeReason }
+                : { type: 'runtime', kind: 'revive', cycle: meta.cycles ?? 0 };
+            await clearNodeLedger(nodeId);
+        }
+        // Every lifecycle launch emits the authoritative spine root rather than
+        // inheriting whichever node happened to invoke reviveNode.
+        inv.env = { ...inv.env, CRTR_SUBTREE: await 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`.
+        // A node coming back from done is told, through its inbox (a resumed session
+        // has no kickoff), which watched documents others revised while it was done.
+        // Read before the transition below rewrites the status. A reopen already
+        // queued this in commitReopenResident, so the row is active by now.
+        if (meta.status === 'done' && meta.last_settled_at != null)
+            await noticeChangedWhileDone(nodeId, meta.last_settled_at);
+        await 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.
+        // A conversation_write_failed fault is the one kept: it records why the last broker died, and the first successful turn of this
+        // launch clears it (canvas-stophook's progress report), so a control plane or harness can still read it after the revive.
+        if ((await readFault(nodeId))?.op !== 'conversation_write_failed')
+            await clearFault(nodeId, { preserveEpisode: true });
+        const bootFault = await 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 (including text a person types
+        // into a viewer, which arrives as a message) or an explicit revive. Two
+        // launches are NOT wakes, and the deadline survives both:
+        //  - a recovery relaunch: 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 same rule lifecycle.ts applies to the
+        //    `crash` transition (a deadline MUST survive instance death);
+        //  - a viewer attach/focus: a person opening the node to look delivers
+        //    nothing to it, so the wait the deadline bounds is still open.
+        if (opts.recovery !== true && opts.viewerAttach !== true)
+            await consumeDeadlineOnWake(nodeId);
+        await ensureNodeDirs(nodeId, meta.grantee);
+        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: await nodeAgentDir(nodeId),
+                contextDir: await contextDir(nodeId),
+                jobDir: jobDir(nodeId),
+            },
+            runtime: {
+                isBirth,
+                canvasHome: crtrHome(),
+                profile: meta.profile_id ?? null,
+            },
+        });
+        inv.env = { ...inv.env, CRTR_EXECUTION_ID: executionId };
+        const launchJson = await brokerLaunchJson(nodeId, inv, meta.cwd);
+        await setExecutionLaunchJson(executionId, launchJson);
+        let launched;
+        try {
+            const row = await liveExecutionForNode(nodeId);
+            const started = await runner.start({ executionId, nodeId, attempt: row?.attempt ?? 1, sandboxName: row?.sandboxName ?? null,
+                release: row?.release ?? '', launchJson, cwd: meta.cwd, resuming });
+            launched = started;
+            if (!remote && launched.pid === null) {
+                throw new Error(`broker host returned no pid for ${nodeId}`);
+            }
+        }
+        catch (error) {
+            // A machine with no live link started nothing: the node is not crashed, the caller leaves it dormant with its mail pending (the outer catch ends the execution).
+            if (error instanceof MachineOfflineError)
+                throw error;
+            try {
+                await 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).
+                await publishNotice(nodeId, 'notice.crash', `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 */
+            }
+            await abortExecution(executionId, { reason: 'launch_failed' });
+            throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
+        }
+        await recordLaunch(nodeId, new Date().toISOString());
+        if (remote) {
+            // The sandbox's (or machine's) broker reports `broker.started`; the runner holds no pid the row records.
+            await clearFrozen(nodeId);
+            return { window: null, session: meta.tmux_session ?? null, resumed: resuming, faultExplanation: bootFault.explanation, outcome: 'launched' };
+        }
+        // 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 (await recordExecutionPid(executionId, nodeId, launched.pid) === 'shutdown') {
+            await abortExecution(executionId, { reason: 'superseded' });
+            void headlessBrokerHost.teardown(nodeId);
+            throw new Error(`[broker] refusing to revive ${nodeId}: execution was superseded during launch`);
+        }
+        // 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.
+        await clearFrozen(nodeId);
+        return {
+            window: null,
+            session: meta.tmux_session ?? null,
+            resumed: resuming,
+            launch: launched,
+            faultExplanation: bootFault.explanation,
+            outcome: 'launched',
+        };
+    }
+    catch (error) {
+        // A forwarded start whose outcome is unknown leaves its execution launching: the Mac may have spawned the broker, and the lifecycle
+        // tick asks `status` of this execution after the link returns (adopt it when running, end it when gone) before any new one starts.
+        if (error instanceof MachineLaunchUncertainError)
+            throw error;
+        await abortExecution(executionId, { reason: 'launch_failed' });
+        // Best effort after the exit transition: a failed diagnostic write must neither leave the row live nor replace the launch error.
+        await recordLaunchFailure(executionId, error).catch((writeError) => {
+            emitEvent({ level: 'warn', event: 'broker.launch_failure.unrecorded', node_id: nodeId, error: writeError });
+        });
+        throw error;
+    }
+}