@north-light/crouter 0.3.154

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

@@ -0,0 +1,58 @@
+import { type NodeMeta } from '../canvas/index.js';
+import type { WakeOrigin } from './bearings.js';
+/** A true session resume normally needs no prompt. A broker-certified runtime
+ * abort is the one exception: continue the persisted transcript with a factual
+ * warning rather than creating a fresh cycle. */
+export type ReviveWakeReason = WakeOrigin | 'runtime-restart-abort';
+import { headlessBrokerHost } from './host.js';
+/** 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 declare function resumeArgs(meta: NodeMeta, resume: boolean): {
+    resumeSessionPath?: string;
+    newCycle?: boolean;
+};
+export interface ReviveResult {
+    /** Always null — the broker engine is never placed in a tmux window. Kept on
+     *  the result for caller back-compat. */
+    window: string | null;
+    /** The node's last live LOCATION session, or null — the broker engine has no
+     *  tmux session of its own (it opens no viewer). Kept for caller back-compat. */
+    session: string | null;
+    /** True only for a TRUE resume — pi replays the saved conversation history
+     *  from its absolute session-file path. False for a fresh launch AND for an
+     *  in-place cycle (which also passes `--session <path>`, but to open a new
+     *  branch rather than replay the old one). */
+    resumed: boolean;
+    /** Launch handle for the detached broker, so callers can fail fast on its real
+     *  exit before the socket appears. */
+    launch?: ReturnType<typeof headlessBrokerHost.launch>;
+    /** Reads a fatal launch fault recorded by THIS revive attempt, scoped via
+     *  `beginBootFaultAttempt` at the exact clear-then-launch boundary below.
+     *  Present only when a fresh launch actually happened (absent on the
+     *  double-revive no-op, where nothing was cleared or relaunched). */
+    faultExplanation?: () => string | null;
+}
+/** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
+ *  meta. Opens no viewer (engine-only).
+ *
+ *  Throws if the node does not exist. All other failures propagate as-is —
+ *  callers (daemon, command) decide how to handle.
+ */
+export declare function reviveNode(nodeId: string, opts: {
+    resume: boolean;
+    wakeReason?: ReviveWakeReason;
+}): ReviveResult;

package/dist/core/runtime/revive.js

@@ -0,0 +1,357 @@
+// 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.
+//
+// reviveNode remains the ONLY sanctioned launcher of the node engine.
+import { existsSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { getNode, updateNode, clearPid, recordPid, fullName, subscribersOf, getHumanWorkRow, } from '../canvas/index.js';
+import { cancelCronsOnWake } from '../canvas/crons.js';
+import { transition } from './lifecycle.js';
+import { fanDoctrineWake } from './close.js';
+import { InputError } from '../io.js';
+import { buildPiArgv } from './launch.js';
+import { buildReviveKickoff, drainBearings, readGoal, readYieldMessage, RUNTIME_RESTART_CONTINUATION } from './kickoff.js';
+import { readRoadmap } from './roadmap.js';
+import { headlessBrokerHost } from './host.js';
+import { boundFleet } from './fleet.js';
+import { clearFault, beginBootFaultAttempt } from './fault.js';
+import { clearInjectedDocs } from '../substrate/injected-store.js';
+import { rootOfSpine } from './nodes.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 type
+// ---------------------------------------------------------------------------
+function isHumanWorkTarget(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const target = value;
+    return ((target.work_kind === 'follow_up' || target.work_kind === 'visual') &&
+        typeof target.dir === 'string' && target.dir !== '' &&
+        typeof target.request_id === 'string' && target.request_id !== '' &&
+        typeof target.root === 'string' && target.root !== '');
+}
+/** A relaunch that has NO transcript to resume or branch from, and no durable
+ *  work state on disk (no roadmap, no yield note), 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;
+}
+// ---------------------------------------------------------------------------
+// reviveNode
+// ---------------------------------------------------------------------------
+/** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
+ *  meta. Opens no viewer (engine-only).
+ *
+ *  Throws if the node does not exist. All other failures propagate as-is —
+ *  callers (daemon, command) decide how to handle.
+ */
+export function reviveNode(nodeId, opts) {
+    let meta = getNode(nodeId);
+    if (meta === null) {
+        throw new Error(`reviveNode: unknown node ${nodeId}`);
+    }
+    // Fresh durable snapshot immediately before the guard. A private fork's
+    // session_start hook may have atomically changed fork_pending →
+    // session_started since the caller's read; launching from a stale phase
+    // would fork provenance a second time instead of resuming the
+    // now-authoritative child session.
+    meta = getNode(nodeId) ?? meta;
+    // #339/#340: 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.`);
+    }
+    // Double-launch guard: a fleet entry IS liveness (design D-1). reviveNode
+    // runs fully SYNCHRONOUSLY on the daemon thread — this check, the launch,
+    // and the fleet registration inside `headlessBrokerHost.launch` complete
+    // with no awaited gap, so no second contender can interleave past this
+    // check before the first's registration lands. A node with a live fleet
+    // entry was already revived by another path — re-launching would put a
+    // SECOND broker on the same session file.
+    if (boundFleet().has(nodeId)) {
+        return {
+            window: null,
+            session: meta.tmux_session ?? null,
+            resumed: false,
+        };
+    }
+    // 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)) {
+        throw new InputError({
+            error: 'cwd_missing',
+            message: `${nodeId} cannot be revived — its recorded cwd no longer exists: ${meta.cwd}`,
+            next: `Recreate ${meta.cwd}, or update the node's cwd, then retry \`crtr node lifecycle revive ${nodeId}\`.`,
+        });
+    }
+    // Lazy host_kind coerce (§C): every launch now uses the broker host. Persist
+    // that identity only after this call has passed the no-op liveness guard.
+    if (meta.host_kind !== 'broker') {
+        updateNode(nodeId, { host_kind: 'broker' });
+        meta.host_kind = 'broker';
+    }
+    // Private human-work forks have one explicit two-phase recipe. Before a
+    // child session is bound, every attempt MUST replay the same immutable
+    // `--fork` birth + kickoff regardless of the caller's requested resume mode.
+    // After bind, provenance is never a launch source again: recovery goes only
+    // through the recorded writable child session. The target + exact-model
+    // assertions make malformed partial claims fail closed rather than silently
+    // becoming an ordinary fresh node.
+    const privateForkPending = meta.private_fork_phase === 'fork_pending';
+    const privateForkStarted = meta.private_fork_phase === 'session_started';
+    const hasPrivateClaim = meta.human_work_target != null || meta.private_fork_phase != null || meta.private_fork_recipe != null;
+    if (hasPrivateClaim && !privateForkPending && !privateForkStarted) {
+        throw new Error(`reviveNode: private fork ${nodeId} has no recognized phase`);
+    }
+    if (privateForkPending || privateForkStarted) {
+        if (!isHumanWorkTarget(meta.human_work_target)) {
+            throw new Error(`reviveNode: private fork ${nodeId} has no recognized human_work_target`);
+        }
+        if (meta.private_fork_recipe == null || meta.private_fork_recipe.kickoff.trim() === '') {
+            throw new Error(`reviveNode: private fork ${nodeId} has no persisted kickoff recipe`);
+        }
+        if (meta.launch?.modelExact !== true || typeof meta.launch.model !== 'string' || meta.launch.model.trim() === '') {
+            throw new Error(`reviveNode: private fork ${nodeId} has no exact persisted model`);
+        }
+    }
+    if (privateForkPending) {
+        // A Visual child is deliberately born inert. Its start handler rechecks
+        // Humanloop after persisting the node, then this locked gate consumes the
+        // still-armed claim immediately before launch. A cancel changes the claim
+        // to visual_retired before it can acknowledge, so it can never wake a
+        // canceled fork after the fact.
+        const work = getHumanWorkRow(nodeId);
+        const expectedStatus = meta.human_work_target.work_kind === 'visual' ? 'visual_armed' : 'armed';
+        if (work === null || work.work_kind !== meta.human_work_target.work_kind || work.status !== expectedStatus) {
+            throw new Error(`reviveNode: private fork ${nodeId} is no longer launchable`);
+        }
+        if (typeof meta.fork_from !== 'string' || !isAbsolute(meta.fork_from)) {
+            throw new Error(`reviveNode: pending private fork ${nodeId} requires an absolute fork_from provenance file`);
+        }
+        if (meta.pi_session_id != null || meta.pi_session_file != null) {
+            throw new Error(`reviveNode: pending private fork ${nodeId} cannot already have a bound child session`);
+        }
+    }
+    if (privateForkStarted) {
+        if (typeof meta.pi_session_id !== 'string' || meta.pi_session_id === '' ||
+            typeof meta.pi_session_file !== 'string' || meta.pi_session_file === '' ||
+            !existsSync(meta.pi_session_file)) {
+            throw new Error(`reviveNode: bound private fork ${nodeId} requires its recorded child session file`);
+        }
+    }
+    // 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. A
+    // pending private fork deliberately has no child session yet and takes the
+    // dedicated immutable birth branch below instead. Persisted pending-refresh
+    // state (durable across a pre-session_start crash-retry) outranks a caller's
+    // strict-resume request; a bound private fork's forced resume outranks both.
+    // resumeArgs then selects only an existing absolute session path: strict
+    // resume continues its leaf, while fresh/cycle mode roots a new one.
+    const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
+    const effectiveResume = privateForkStarted ? true : (refreshPending ? false : opts.resume);
+    const resume = privateForkPending ? {} : resumeArgs(meta, effectiveResume);
+    // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether
+    // as a true resume OR a cycling refresh-yield (resumeArgs sets `newCycle` in
+    // the latter case). cycling and resuming are mutually exclusive; `resuming`
+    // keeps the STRICT true-resume-only meaning `ReviveResult.resumed` and the
+    // launch-placement hint below have always carried.
+    const hasSessionPath = resume.resumeSessionPath !== undefined;
+    const cycling = hasSessionPath && resume.newCycle === true;
+    const resuming = hasSessionPath && !cycling;
+    // A cycling launch is provisional until session_start confirms it. Once
+    // true, this marker is monotonic across failed retries; only that confirmed
+    // boot may clear it.
+    const cyclePending = meta.cycle_pending === true || cycling;
+    updateNode(nodeId, { cycle_pending: cyclePending });
+    meta.cycle_pending = cyclePending;
+    // A truly fresh ordinary 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 (!privateForkPending && !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;
+    if (privateForkPending) {
+        inv = buildPiArgv(meta, {
+            prompt: meta.private_fork_recipe.kickoff,
+            forkFrom: meta.fork_from,
+        });
+        // A fork birth creates a new LLM context just like an ordinary fresh
+        // launch; retries before bind must not inherit an injected-doc cache from
+        // a failed process.
+        clearInjectedDocs(nodeId);
+    }
+    else if (resuming) {
+        inv = buildPiArgv(meta, {
+            ...resume,
+            ...(opts.wakeReason === 'runtime-restart-abort' ? { prompt: RUNTIME_RESTART_CONTINUATION } : {}),
+        });
+    }
+    else if (!hasSessionPath &&
+        // A clock-driven wake must keep its <crtr-wake> kickoff — the schedule IS
+        // the instruction to take a turn, so it never degrades to a birth replay.
+        (opts.wakeReason === undefined || opts.wakeReason === 'runtime-restart-abort') &&
+        isUnstartedBirth(nodeId)) {
+        // Never conversed and nothing on disk to rebuild from — relaunch as a birth
+        // (see isUnstartedBirth). A node with a spawn mandate replays it; a bare
+        // interactive node boots promptless and takes no turn at all.
+        const goal = readGoal(nodeId)?.trim();
+        inv = buildPiArgv(meta, goal !== undefined && goal !== '' ? { prompt: goal } : {});
+        clearInjectedDocs(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),
+        });
+        // Fresh or cycling revive starts a NEW LLM context — reset the on-read doc
+        // dedup so it surfaces docs from scratch (a true resume above instead KEEPS
+        // the persisted set, continuing the same transcript).
+        clearInjectedDocs(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) };
+    // 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);
+    const bootFault = beginBootFaultAttempt(nodeId);
+    // A cron armed --cancel-on-wake belongs to the dormancy being left, so any
+    // revive of its anchor deletes it.
+    cancelCronsOnWake(nodeId);
+    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');
+            // 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 */
+        }
+        clearPid(nodeId);
+        throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
+    }
+    // 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);
+    return {
+        window: null,
+        session: meta.tmux_session ?? null,
+        resumed: resuming,
+        launch: launched,
+        faultExplanation: bootFault.explanation,
+    };
+}

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

@@ -0,0 +1,13 @@
+export declare function roadmapPath(nodeId: string): string;
+export declare function hasRoadmap(nodeId: string): boolean;
+export declare function readRoadmap(nodeId: string): string | 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 declare function seedRoadmap(nodeId: string, opts?: {
+    goal?: string;
+    exitCriteria?: string;
+}): string;

package/dist/core/runtime/roadmap.js

@@ -0,0 +1,45 @@
+// 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/index.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
+
+## Goal
+${opts.goal?.trim() ?? '(the goal you now own)'}
+
+## Exit criteria
+${opts.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;
+}

package/dist/core/runtime/session-branch.d.ts

@@ -0,0 +1,13 @@
+export interface HumanForkCoordinates {
+    sourceFile: string;
+    sourceSessionId: string;
+    leafId: string;
+}
+/**
+ * Materialize one immutable root-to-leaf Pi session branch without touching the
+ * source broker's manager. The SDK creates its branch in the supplied session
+ * directory, so opening the source through a detached manager directs the staged
+ * file straight into the ticket directory. Publication is an exclusive hard link:
+ * an existing destination is never read or replaced.
+ */
+export declare function materializeSessionBranchAt(coordinates: HumanForkCoordinates, destination: string): void;

package/dist/core/runtime/session-branch.js

@@ -0,0 +1,46 @@
+import { chmodSync, linkSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { SessionManager } from './broker-sdk.js';
+/**
+ * Materialize one immutable root-to-leaf Pi session branch without touching the
+ * source broker's manager. The SDK creates its branch in the supplied session
+ * directory, so opening the source through a detached manager directs the staged
+ * file straight into the ticket directory. Publication is an exclusive hard link:
+ * an existing destination is never read or replaced.
+ */
+export function materializeSessionBranchAt(coordinates, destination) {
+    if (!isAbsolute(coordinates.sourceFile) || !isAbsolute(destination)) {
+        throw new Error('session branch paths must be absolute');
+    }
+    if (coordinates.sourceSessionId === '' || coordinates.leafId === '') {
+        throw new Error('session branch coordinates require source session and leaf ids');
+    }
+    const finalPath = resolve(destination);
+    const detached = SessionManager.open(coordinates.sourceFile, dirname(finalPath));
+    if (detached.getSessionId() !== coordinates.sourceSessionId) {
+        throw new Error('source session id does not match captured coordinates');
+    }
+    let stagedPath;
+    try {
+        stagedPath = detached.createBranchedSession(coordinates.leafId);
+        if (stagedPath === undefined)
+            throw new Error('Pi did not persist the selected session branch');
+        stagedPath = resolve(stagedPath);
+        if (dirname(stagedPath) !== dirname(finalPath)) {
+            throw new Error('Pi staged the session branch outside the destination directory');
+        }
+        chmodSync(stagedPath, 0o600);
+        if ((statSync(stagedPath).mode & 0o777) !== 0o600) {
+            throw new Error('staged session branch does not have mode 0600');
+        }
+        const branch = SessionManager.open(stagedPath);
+        if (branch.getSessionFile() !== stagedPath || branch.getSessionId() === '') {
+            throw new Error('Pi produced an invalid session branch');
+        }
+        linkSync(stagedPath, finalPath);
+    }
+    finally {
+        if (stagedPath !== undefined)
+            unlinkSync(stagedPath);
+    }
+}

package/dist/core/runtime/session-cycles.d.ts

@@ -0,0 +1,30 @@
+import { type SessionEntry } from '@earendil-works/pi-coding-agent';
+import type { BrokerSnapshot } from './broker-protocol.js';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export declare const CRTR_CYCLE_CUSTOM_TYPE = "crtr-cycle";
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export declare const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = "crtr-cycle-divider";
+type SnapshotMessage = BrokerSnapshot['messages'][number];
+/** The structural slice of pi's SessionManager cycle rendering needs. The
+ *  broker's fake-engine test fixture implements only `buildSessionContext`, so
+ *  the tree accessors are optional — absent ⇒ single-cycle behavior. */
+export interface CycleSessionManagerLike {
+    buildSessionContext(): {
+        messages: SnapshotMessage[];
+    };
+    getEntries?(): SessionEntry[];
+    /** Walk from `fromId` (default: the current leaf) to its root; returns the
+     *  path root-first. */
+    getBranch?(fromId?: string): SessionEntry[];
+}
+/** The full multi-cycle message history for display: prior cycles (oldest
+ *  first, each closed by a divider), then the live cycle's context. Falls back
+ *  to plain `buildSessionContext()` when the session has no cycle markers, when
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export declare function cycleAwareMessages(sm: CycleSessionManagerLike): SnapshotMessage[];
+export {};

package/dist/core/runtime/session-cycles.js

@@ -0,0 +1,77 @@
+// Cycle-aware session history — one node, one `.jsonl`, many cycles.
+//
+// A refresh-yield does not start a new session file: reviveNode reuses the
+// node's existing `.jsonl` (buildPiArgv's `--crtr-new-cycle`), and the broker
+// resets the session-tree leaf, appending a `crtr-cycle` custom entry as the
+// new cycle's ROOT. Custom entries never participate in LLM context, so the
+// refreshed window is exactly as clean as a brand-new session — but every
+// cycle lives in the same tree as a sibling root branch, so the /tree
+// navigator shows previous cycles natively.
+//
+// `cycleAwareMessages()` is the display-side counterpart: it rebuilds the FULL
+// node history — each prior cycle's messages (via pi's own `buildSessionContext`,
+// so a compacted prior cycle renders correctly), a synthetic divider message per
+// boundary, then the live cycle's context — so the broker welcome snapshot
+// (broker.ts) and the dormant snapshot (node-snapshot.ts) both render one
+// continuous conversation.
+import { buildSessionContext } from '@earendil-works/pi-coding-agent';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export const CRTR_CYCLE_CUSTOM_TYPE = 'crtr-cycle';
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = 'crtr-cycle-divider';
+function cycleDivider(cycle, timestamp) {
+    const label = cycle !== undefined ? `cycle ${cycle}` : 'new cycle';
+    return {
+        role: 'custom',
+        customType: CRTR_CYCLE_DIVIDER_CUSTOM_TYPE,
+        content: `yielded — ${label} begins with a fresh context window`,
+        display: true,
+        timestamp: new Date(timestamp).getTime(),
+    };
+}
+/** The full multi-cycle message history for display: prior cycles (oldest
+ *  first, each closed by a divider), then the live cycle's context. Falls back
+ *  to plain `buildSessionContext()` when the session has no cycle markers, when
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export function cycleAwareMessages(sm) {
+    const current = sm.buildSessionContext().messages;
+    if (typeof sm.getEntries !== 'function' || typeof sm.getBranch !== 'function')
+        return current;
+    // File order = append order = chronological cycle order.
+    const entries = sm.getEntries();
+    const markers = entries.filter((e) => e.type === 'custom' && e.customType === CRTR_CYCLE_CUSTOM_TYPE);
+    if (markers.length === 0)
+        return current;
+    // The current cycle's root: first entry on the leaf→root path. When it is
+    // not a cycle marker, the leaf sits in the ORIGINAL (pre-yield) branch —
+    // render just that branch. Otherwise replay every cycle up to and including
+    // the one the marker closes.
+    const currentRootId = sm.getBranch()[0]?.id;
+    const rootMarkerIndex = markers.findIndex((m) => m.id === currentRootId);
+    if (rootMarkerIndex === -1)
+        return current;
+    // Shared byId map — buildSessionContext would otherwise rebuild one from
+    // `entries` on every call; one pass here amortizes it across every replayed
+    // marker.
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const out = [];
+    for (let i = 0; i <= rootMarkerIndex; i++) {
+        const marker = markers[i];
+        const fromLeaf = marker.data?.fromLeaf;
+        if (typeof fromLeaf === 'string' && fromLeaf !== '') {
+            // Replay this prior cycle's own branch through pi's canonical context
+            // builder — preserving compaction semantics (one compactionSummary +
+            // kept + post-compaction messages only) exactly like the live cycle
+            // below.
+            out.push(...buildSessionContext(entries, fromLeaf, byId).messages);
+        }
+        out.push(cycleDivider(marker.data?.cycle, marker.timestamp));
+    }
+    out.push(...current);
+    return out;
+}