@north-light/crouter 0.3.317 → 0.3.319

package/dist/core/runtime/revive.js

@@ -1,544 +1,4 @@
-// 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 { existsSync, readFileSync } from 'node:fs';
-import { isAbsolute } from 'node:path';
-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';
-import { fanDoctrineWake } 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 } from './host.js';
-import { boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.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';
-import { assertProfileActive } from '../profiles/manifest.js';
-import { isPidAlive } from '../canvas/pid.js';
-import { crtrHome, contextDir, ensureNodeDirs, jobDir, nodeDir, reportsDir } from '../canvas/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 function resumeArgs(meta, resume) {
-    const path = meta.pi_session_file;
-    if (path == null || path === '' || !existsSync(path))
-        return {};
-    return resume ? { resumeSessionPath: path } : { resumeSessionPath: path, newCycle: true };
-}
-/** Return false only when a valid Pi session header positively names a cwd that
- * has gone away. Missing/corrupt headers remain the engine's concern: old
- * fixtures and partial transcripts do not prove a cwd mismatch. */
-function sessionCwdExists(sessionFile) {
-    try {
-        for (const line of readFileSync(sessionFile, 'utf8').split('\n')) {
-            if (line.trim() === '')
-                continue;
-            const entry = JSON.parse(line);
-            if (entry.type !== 'session')
-                continue;
-            return typeof entry.cwd !== 'string' || existsSync(entry.cwd);
-        }
-    }
-    catch {
-        // The broker/engine owns malformed-transcript diagnostics; it is not proof
-        // that the stored cwd is absent.
-    }
-    return true;
-}
-/** The session-file preflight has two ordered vetoes. A live owner wins before
- * inspecting its transcript, so this node can never adopt or clear another
- * broker's file. Only an unowned/dead-owner file then reaches the cwd check. */
-function resumableSessionArgs(nodeId, meta, resume) {
-    const path = meta.pi_session_file;
-    if (path == null || path === '' || !existsSync(path))
-        return {};
-    const owner = findNodeBySessionFile(path);
-    if (owner !== null && owner.node_id !== nodeId && isPidAlive(owner.pi_pid))
-        return {};
-    if (!sessionCwdExists(path))
-        return {};
-    return resumeArgs(meta, resume);
-}
-// Return type
-/** A relaunch that has NO transcript to resume or branch from, and no durable
- *  work state on disk (no roadmap, 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. */
-function isUnstartedBirth(nodeId) {
-    return readRoadmap(nodeId) === null && readYieldMessage(nodeId) === null && !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 function hasFreshGroundState(nodeId) {
-    const goal = readGoal(nodeId);
-    if (goal !== null && goal.trim() !== '')
-        return true;
-    const roadmap = 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 cancelCronsOnWake call below).
- *
- *  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. */
-export async function decideAttachRevive(nodeId, opts, wakeParked) {
-    return decideRevive(nodeId, opts, wakeParked);
-}
-async function decideRevive(nodeId, opts, wakeParked) {
-    let meta = getNode(nodeId);
-    if (meta === null) {
-        throw new Error(`reviveNode: unknown node ${nodeId}`);
-    }
-    // Fresh durable snapshot immediately before the lifecycle guard.
-    meta = getNode(nodeId) ?? meta;
-    // 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);
-    // 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();
-    if (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.
-        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 (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 };
-    }
-    // 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.
-    if (!fleet.reserveSlot(nodeId)) {
-        if (opts.capacity === 'refuse') {
-            throw brokerCapReached(brokerThresholdsForDaemon().automaticReviveCap, fleet.size());
-        }
-        // 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).
-        if (meta.frozen_at == null) {
-            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.
-            endLiveExecution(nodeId, { reason: 'frozen' });
-            emitEvent({
-                level: 'info',
-                event: 'broker.frozen',
-                node_id: nodeId,
-                fields: { live_count: fleet.size(), 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);
-    }
-}
-/** 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) {
-    // Preflight, before any state mutation below: 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 below, where it would
-    // surface as an opaque `internal error` (toErrorBody masks every 5xx).
-    if (!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,
-        });
-    }
-    // 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') {
-        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 && !isReviewCompanionBound(nodeId);
-    if (reviewCompanionUnbound && (meta.pi_session_id != null || meta.pi_session_file != null)) {
-        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 && !existsSync(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 executionId = beginExecution(nodeId, { daemonEpoch: boundFleet().epoch() });
-    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;
-        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 (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, 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 {
-            launched = headlessBrokerHost.launch(nodeId, inv, {
-                cwd: meta.cwd,
-                name: fullName(meta),
-                resuming,
-            });
-            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}`);
-        }
-        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`);
-        }
-        // 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;
-    }
-}
+var G=Object.defineProperty;var s=(e,r)=>G(e,"name",{value:r,configurable:!0});import{existsSync as p,readFileSync as j}from"node:fs";import{isAbsolute as M}from"node:path";import{findNodeBySessionFile as C,getNode as N,updateNode as _,beginExecution as W,recordExecutionPid as J,abortExecution as y,endLiveExecution as V,unbindSession as F,recordLaunch as X,setFrozen as Y,clearFrozen as q,fullName as D,subscribersOf as Q}from"../canvas/index.js";import{emitEvent as Z}from"../events/emit.js";import{cancelCronsOnWake as I}from"../canvas/crons.js";import{isParked as ee,transition as g}from"./lifecycle.js";import{fanDoctrineWake as re}from"./close.js";import{InputError as b}from"../io.js";import{buildPiArgv as m}from"./launch.js";import{buildReviveKickoff as ie,drainBearings as ne,hasRetainedReports as oe,readGoal as R,readYieldMessage as te,RUNTIME_RESTART_CONTINUATION as se}from"./kickoff.js";import{readRoadmap as O}from"./roadmap.js";import{encodeKickoffOrigin as le,KICKOFF_ORIGIN_ENV as ce}from"./stamp/protocol.js";import{headlessBrokerHost as P}from"./host.js";import{boundFleet as A,brokerCapReached as ue,brokerThresholdsForDaemon as B}from"./fleet.js";import{beginBootFaultAttempt as ae,clearFault as fe}from"../canvas/recovery.js";import{clearContextExposureState as T,initializeForkContextExposure as pe}from"../substrate/injected-store.js";import{rootOfSpine as he}from"./nodes.js";import{isReviewCompanionBound as ve}from"../review/companion.js";import{assertProfileActive as we}from"../profiles/manifest.js";import{isPidAlive as de}from"../canvas/pid.js";import{crtrHome as me,contextDir as ke,ensureNodeDirs as _e,jobDir as ye,nodeDir as ge,reportsDir as be}from"../canvas/paths.js";import{discoverLifecycleHookRegistry as Re}from"../command-hooks/discovery.js";import{invokeLifecycleHooks as xe}from"../command-hooks/transport/exec-lifecycle.js";function Ee(e,r){const i=e.pi_session_file;return i==null||i===""||!p(i)?{}:r?{resumeSessionPath:i}:{resumeSessionPath:i,newCycle:!0}}s(Ee,"resumeArgs");function $e(e){try{for(const r of j(e,"utf8").split(`
+`)){if(r.trim()==="")continue;const i=JSON.parse(r);if(i.type==="session")return typeof i.cwd!="string"||p(i.cwd)}}catch{}return!0}s($e,"sessionCwdExists");function Se(e,r,i){const n=r.pi_session_file;if(n==null||n===""||!p(n))return{};const t=C(n);return t!==null&&t.node_id!==e&&de(t.pi_pid)?{}:$e(n)?Ee(r,i):{}}s(Se,"resumableSessionArgs");function Ce(e){return O(e)===null&&te(e)===null&&!oe(e)}s(Ce,"isUnstartedBirth");function er(e){const r=R(e);if(r!==null&&r.trim()!=="")return!0;const i=O(e);return i!==null&&i.trim()!==""}s(er,"hasFreshGroundState");async function rr(e,r){const i=await z(e,r,!0);if(i.parked)throw new Error(`reviveNode: internal parked decision for activating revive ${e}`);return i.result}s(rr,"reviveNode");async function ir(e,r,i){return z(e,r,i)}s(ir,"decideAttachRevive");async function z(e,r,i){let n=N(e);if(n===null)throw new Error(`reviveNode: unknown node ${e}`);if(n=N(e)??n,n.final_report!==null)throw new Error(`reviveNode: refusing to revive ${e} \u2014 its finalization latch is set (final_report=${n.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.`);we(n.profile_id);const t=A();if(t.has(e))return g(e,n.intent==="refresh"?"refresh-launch":"revive"),{parked:!1,result:{window:null,session:n.tmux_session??null,resumed:!1,outcome:"already-live"}};if(t.isClaimed(e))return{parked:!1,result:{window:null,session:n.tmux_session??null,resumed:!1,outcome:"already-live"}};if(!i&&n.lifecycle==="resident"&&ee(n))return{parked:!0};if(!t.reserveSlot(e)){if(r.capacity==="refuse")throw ue(B().automaticReviveCap,t.size());return n.frozen_at==null&&(Y(e,new Date().toISOString()),V(e,{reason:"frozen"}),Z({level:"info",event:"broker.frozen",node_id:e,fields:{live_count:t.size(),hard_cap:B().automaticReviveCap}})),{parked:!1,result:{window:null,session:n.tmux_session??null,resumed:!1,outcome:"frozen"}}}try{return{parked:!1,result:await Ne(e,n,r)}}finally{t.releaseReservation(e)}}s(z,"decideRevive");async function Ne(e,r,i){if(!p(r.cwd)){const h=r.fork_from!=null?`Restore ${r.cwd}, then revive the fork normally with \`crtr node lifecycle revive ${e}\`.`:r.managed_worktree?.state==="open"?"Restore or reconcile the recorded checkout, then use the managed-worktree close or abandon recovery.":`Recreate ${r.cwd}, or repair it with \`crtr node config --cwd <path> --node ${e}\`; durable node work resumes in a fresh conversation. Then retry \`crtr node lifecycle revive ${e}\`.`;throw new b({error:"cwd_missing",message:`${e} cannot be revived \u2014 its recorded cwd no longer exists: ${r.cwd}`,next:h})}r.host_kind!=="broker"&&(_(e,{host_kind:"broker"}),r.host_kind="broker"),r.review_binding!=null&&!ve(e)&&(r.pi_session_id!=null||r.pi_session_file!=null)&&(F(e),r.pi_session_id=null,r.pi_session_file=null);const t=r.fork_from!=null&&r.pi_session_id==null,c=r.fork_source_file;if(t&&(typeof c!="string"||!M(c)))throw new b({error:"fork_source_invalid",message:`${e} cannot be revived \u2014 its resolved fork source file is missing or invalid.`,next:`Restore the node's fork source metadata, then retry \`crtr node lifecycle revive ${e}\`.`});const f=t&&typeof c=="string";if(f&&!p(c))throw new b({error:"fork_from_missing",message:`${e} cannot be revived \u2014 its fork source no longer exists: ${c}`,next:`Restore ${c}, or update the node's fork source, then retry \`crtr node lifecycle revive ${e}\`.`});const u=W(e,{daemonEpoch:A().epoch()});try{r.cycles=(r.cycles??0)+1,_(e,{cycles:r.cycles});const U=r.intent==="refresh"||r.cycle_pending===!0?!1:i.resume,v=f?{}:Se(e,r,U),w=v.resumeSessionPath!==void 0,x=w&&v.newCycle===!0,k=w&&!x,E=!w&&(i.wakeReason===void 0||i.wakeReason==="runtime-restart-abort")&&Ce(e),H=f||E,$=r.cycle_pending===!0||x;_(e,{cycle_pending:$}),r.cycle_pending=$,!f&&!w&&(r.pi_session_id!=null||r.pi_session_file!=null)&&(F(e),r.pi_session_id=null,r.pi_session_file=null);let l,a=null;const S=s(()=>({type:"runtime",kind:"kickoff",...r.spawned_by!=null&&r.spawned_by!==""?{spawnedBy:r.spawned_by}:{}}),"birthOrigin");if(f){const o=R(e);l=m(r,{forkFrom:c,...o!=null&&o!==""?{prompt:o}:{}}),o!=null&&o!==""&&(a=S()),pe(e,C(c)?.node_id??null)}else if(k)l=m(r,{...v,...i.wakeReason==="runtime-restart-abort"?{prompt:se}:{}}),i.wakeReason==="runtime-restart-abort"&&(a={type:"runtime",kind:"restart-continuation"});else if(E){const o=R(e)?.trim();l=m(r,o!==void 0&&o!==""?{prompt:o}:{}),o!==void 0&&o!==""&&(a=S()),T(e)}else{const o=ne(r,u);l=m(r,{...v,prompt:ie(r,o,i.wakeReason==="runtime-restart-abort"?void 0:i.wakeReason)}),a=i.wakeReason!==void 0&&i.wakeReason!=="runtime-restart-abort"?{type:"runtime",kind:"wake",wake:i.wakeReason}:{type:"runtime",kind:"revive",cycle:r.cycles??0},T(e)}l.env={...l.env,CRTR_SUBTREE:he(e)},a!==null&&(l.env[ce]=le(a)),g(e,r.intent==="refresh"?"refresh-launch":"revive"),fe(e,{preserveEpisode:!0});const K=ae(e);i.recovery!==!0&&I(e),_e(e);const L=Re(r.cwd,r.profile_id).plans.get("node:start")??[];await xe(L,{node:{id:e,name:r.name,kind:r.kind,mode:r.mode,lifecycle:r.lifecycle,cwd:r.cwd,nodeDir:ge(e),contextDir:ke(e),jobDir:ye(e),reportsDir:be(e)},runtime:{isBirth:H,canvasHome:me(),profile:r.profile_id??null}}),l.env={...l.env,CRTR_EXECUTION_ID:u};let d;try{if(d=P.launch(e,l,{cwd:r.cwd,name:D(r),resuming:k}),d.pid===null)throw new Error(`broker host returned no pid for ${e}`)}catch(o){try{g(e,"crash",{reason:"launch_failed",outcome:{detail:{schema:"crtr.node-outcome-detail/v1",message:o instanceof Error?o.message:String(o)}}}),re(e,Q(e),`Child crashed \u2014 ${D(r)} (${e}) failed to relaunch and is now dead: ${o.message}
+
+It stays dead until you revive it \u2014 \`crtr node lifecycle revive ${e}\`.`,{reason:"child-crashed",child:e})}catch{}throw y(u,{reason:"launch_failed"}),new Error(`[broker] refusing to revive ${e}: ${o.message}`)}if(X(e,new Date().toISOString()),J(u,e,d.pid)==="shutdown")throw y(u,{reason:"superseded"}),P.teardown(e),new Error(`[broker] refusing to revive ${e}: execution was superseded during launch`);return q(e),{window:null,session:r.tmux_session??null,resumed:k,launch:d,faultExplanation:K.explanation,outcome:"launched"}}catch(h){throw y(u,{reason:"launch_failed"}),h}}s(Ne,"launchRevive");export{ir as decideAttachRevive,er as hasFreshGroundState,Ee as resumeArgs,rr as reviveNode};

package/dist/core/runtime/roadmap.js

@@ -1,45 +1,11 @@
-// The roadmap — one document, two temperatures. A small frozen core (goal +
-// exit criteria) and an evolving body (scope, strategy, active context) the
-// owner keeps current. It holds how you intend to reach the goal and where you
-// are right now — not a journal of what you did or a queue of what's next. It
-// is what lets a resident node survive a refresh-yield: revive with no memory,
-// re-read the map, continue.
-//
-// Written at resident-promotion (a born-resident root, or a spawned node's
-// first refresh-with-open-work). Leaf/terminal workers write nothing.
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { contextDir } from '../canvas/paths.js';
-export function roadmapPath(nodeId) {
-    return join(contextDir(nodeId), 'roadmap.md');
-}
-export function hasRoadmap(nodeId) {
-    return existsSync(roadmapPath(nodeId));
-}
-export function readRoadmap(nodeId) {
-    const p = roadmapPath(nodeId);
-    return existsSync(p) ? readFileSync(p, 'utf8') : null;
-}
-/** Seed a fresh, EXTREMELY BAREBONES roadmap scaffold — just the section
- *  skeleton with one-line prompts. Promotion lays this down so the file exists
- *  for a refresh; the owner fleshes it out as its next act (guided by its
- *  roadmap memory doc). `goal`/`exitCriteria` pre-fill those sections when
- *  known (e.g. from the node's goal doc). Idempotent only if you intend it —
- *  call sites guard on hasRoadmap to avoid clobbering an evolved map. */
-export function seedRoadmap(nodeId, opts = {}) {
-    const dir = contextDir(nodeId);
-    mkdirSync(dir, { recursive: true });
-    const body = `# Roadmap
+var c=Object.defineProperty;var e=(r,o)=>c(r,"name",{value:o,configurable:!0});import{existsSync as a,readFileSync as d,writeFileSync as s,mkdirSync as u}from"node:fs";import{join as p}from"node:path";import{contextDir as i}from"../canvas/paths.js";function t(r){return p(i(r),"roadmap.md")}e(t,"roadmapPath");function y(r){return a(t(r))}e(y,"hasRoadmap");function w(r){const o=t(r);return a(o)?d(o,"utf8"):null}e(w,"readRoadmap");function R(r,o={}){const m=i(r);u(m,{recursive:!0});const n=`# Roadmap
 
 ## Goal
-${opts.goal?.trim() ?? '(the goal you now own)'}
+${o.goal?.trim()??"(the goal you now own)"}
 
 ## Exit criteria
-${opts.exitCriteria?.trim() ?? '(what "done" looks like)'}
+${o.exitCriteria?.trim()??'(what "done" looks like)'}
 
 ## Phases
 (ordered phases from here to done; the current one carries a one-line status)
-`;
-    writeFileSync(roadmapPath(nodeId), body);
-    return body;
-}
+`;return s(t(r),n),n}e(R,"seedRoadmap");export{y as hasRoadmap,w as readRoadmap,t as roadmapPath,R as seedRoadmap};