@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/runtime/nodes.js

@@ -0,0 +1,95 @@
+// Runtime node operations — the behavior layer above the canvas store.
+//
+// canvas/ is the pure data-access layer (nodes + edges). This is where the
+// design's *rules* live: how a node comes into being, the env contract its pi
+// process inherits, and the spawn-time wiring of the subscription spine.
+//
+// Two ways a node is born:
+//   • root  — a user-opened entry point (bare `crtr`).
+//             No parent; resident by default (it's a conversation you live in).
+//   • child — spawned by another node. Terminal until it must persist. On
+//             spawn the PARENT auto-subscribes (active) to the child, so it
+//             learns when the work finishes — this seeds the subscription
+//             graph to mirror the spawn structure. A `spawned_by` audit edge
+//             is also recorded.
+import { randomBytes } from 'node:crypto';
+import { createNode, getNode, subscribe, recordSpawn, } from '../canvas/index.js';
+/** Generate a node id in the same shape as job ids (time-sortable + random). */
+export function newNodeId() {
+    return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+}
+/** Read the current node's identity from the environment. A spawned pi process
+ *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
+ *  it by reading CRTR_NODE_ID as the parent. */
+export function currentNodeContext() {
+    const env = process.env;
+    return {
+        nodeId: env['CRTR_NODE_ID'] ?? null,
+        parentNodeId: env['CRTR_NODE_ID'] ?? null, // a child's parent is the live node
+        kind: env['CRTR_KIND'] ?? null,
+        mode: env['CRTR_MODE'] ?? null,
+    };
+}
+/** The env injected into a node's pi process. Self-gating extensions read
+ *  CRTR_KIND/CRTR_MODE to flip behavior on polymorph without a respawn; the
+ *  feed/inbox machinery reads CRTR_NODE_ID. */
+export function nodeEnv(meta) {
+    const env = {
+        CRTR_NODE_ID: meta.node_id,
+        CRTR_KIND: meta.kind,
+        CRTR_MODE: meta.mode,
+        CRTR_LIFECYCLE: meta.lifecycle,
+        CRTR_NODE_CWD: meta.cwd,
+    };
+    if (meta.parent)
+        env['CRTR_PARENT_NODE_ID'] = meta.parent;
+    // Propagate an explicit canvas home so children share the same canvas.
+    const home = process.env['CRTR_HOME'];
+    if (home !== undefined && home !== '')
+        env['CRTR_HOME'] = home;
+    // Propagate the root's tmux session so every descendant spawns its windows
+    // into the same root session.
+    const rootSession = process.env['CRTR_ROOT_SESSION'];
+    if (rootSession !== undefined && rootSession !== '')
+        env['CRTR_ROOT_SESSION'] = rootSession;
+    // Merge any launch-spec env last (it may override / extend).
+    return { ...env, ...(meta.launch?.env ?? {}) };
+}
+/** Create a node on the canvas and wire its spawn-time edges.
+ *
+ *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
+ *  (so it's woken when the child finishes), and a spawned_by audit edge is
+ *  recorded. For a root (no parent): no edges, resident by default. */
+export function spawnNode(opts) {
+    const parent = opts.parent ?? null;
+    const isRoot = parent === null;
+    const meta = {
+        node_id: opts.nodeId ?? newNodeId(),
+        name: opts.name ?? opts.kind,
+        created: new Date().toISOString(),
+        cwd: opts.cwd,
+        kind: opts.kind,
+        mode: opts.mode ?? 'base',
+        // A user-opened root is resident (a conversation you live in); a spawned
+        // node is terminal until it must persist (promotion handles that later).
+        lifecycle: opts.lifecycle ?? (isRoot ? 'resident' : 'terminal'),
+        status: 'active',
+        parent,
+        passive_default: opts.passiveDefault ?? false,
+        intent: null,
+        pi_session_id: null,
+        launch: opts.launch,
+    };
+    createNode(meta);
+    if (parent !== null) {
+        if (getNode(parent) === null) {
+            throw new Error(`cannot spawn under unknown parent node: ${parent}`);
+        }
+        // The load-bearing seed: parent subscribes (active) to child so it learns
+        // when the work finishes. This mirrors spawn structure into the spine.
+        subscribe(parent, meta.node_id, true);
+        // Audit-only provenance.
+        recordSpawn(meta.node_id, parent);
+    }
+    return meta;
+}

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

@@ -0,0 +1,38 @@
+import type { NodeMeta } from '../canvas/index.js';
+/** Persist `nodeId` as the currently focused node. Best-effort; never throws. */
+export declare function setFocus(nodeId: string): void;
+/** Read the currently focused node id, or null if the pointer is absent or
+ *  empty (no active focus). Best-effort; never throws. */
+export declare function getFocus(): string | null;
+/** True when the node's tmux window is alive.  A falsy tmux_session/window
+ *  always returns false so callers don't need to null-guard. */
+export declare function nodeLive(meta: NodeMeta): boolean;
+/** Bring a node's tmux window to the foreground and record it as focused.
+ *
+ * Strategy:
+ *   - If the node has no live window (`nodeLive` is false), still write the
+ *     focus pointer — the caller (e.g. revive logic) uses `focused:false` to
+ *     know it needs to open a window first.
+ *   - Otherwise call `switchClient` (lands us in the right session) then
+ *     `selectWindow` (picks the right window within it).  Both calls are
+ *     best-effort; the focus pointer is always written regardless.
+ *
+ * Returns:
+ *   focused — whether the tmux focus actually succeeded.
+ *   session — the tmux session name if one was attempted, null otherwise. */
+export declare function focusNode(nodeId: string): {
+    focused: boolean;
+    session: string | null;
+};
+/** Focus a node IN PLACE: bring its pane into the caller's current pane slot
+ *  (swap-pane) instead of navigating the client to the node's own window. This
+ *  is the default for `crtr node focus` and the nav-chrome spine jump — the
+ *  agent appears where you are.
+ *
+ *  Falls back to window focus when there is no caller pane (not inside tmux) or
+ *  the target pane can't be resolved. `inPlace` reports which path ran. */
+export declare function focusNodeInPlace(nodeId: string, callerPane?: string): {
+    focused: boolean;
+    session: string | null;
+    inPlace: boolean;
+};

package/dist/core/runtime/presence.js

@@ -0,0 +1,152 @@
+// presence.ts — focus pointer + per-node liveness helpers.
+//
+// The focus pointer (`<crtrHome>/focus.ptr`) is a plain-text file holding the
+// node id that currently "has focus" — meaning the user's terminal is showing
+// that node's tmux window. It is written on every explicit `focusNode()` call
+// and read by the dashboard / status-line to highlight the active node.
+//
+// This is intentionally a simple file-based pointer rather than a database
+// column: focus is transient UI state, not durable business data. A crash
+// leaves a stale pointer that the next focusNode() clobbers — harmless.
+//
+// focusNode() does two things:
+//   1. Ensures the user's terminal lands on the right tmux window by calling
+//      switchClient (cross-session) then selectWindow (in-session). Both are
+//      best-effort; we set the pointer regardless so the dashboard stays in sync.
+//   2. Persists the node id to focus.ptr so any process can quickly read "what
+//      is the user looking at?".
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { join } from 'node:path';
+import { crtrHome, getNode, updateNode } from '../canvas/index.js';
+import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swapPaneInPlace, windowOfPane } from './tmux.js';
+// ---------------------------------------------------------------------------
+// Focus pointer
+// ---------------------------------------------------------------------------
+/** Absolute path to the focus pointer file. */
+function focusPtrPath() {
+    return join(crtrHome(), 'focus.ptr');
+}
+/** Persist `nodeId` as the currently focused node. Best-effort; never throws. */
+export function setFocus(nodeId) {
+    try {
+        const p = focusPtrPath();
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, nodeId, 'utf8');
+    }
+    catch {
+        /* focus pointer is best-effort; never surface */
+    }
+}
+/** Read the currently focused node id, or null if the pointer is absent or
+ *  empty (no active focus). Best-effort; never throws. */
+export function getFocus() {
+    try {
+        const raw = readFileSync(focusPtrPath(), 'utf8').trim();
+        return raw !== '' ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Liveness
+// ---------------------------------------------------------------------------
+/** True when the node's tmux window is alive.  A falsy tmux_session/window
+ *  always returns false so callers don't need to null-guard. */
+export function nodeLive(meta) {
+    return windowAlive(meta.tmux_session, meta.window);
+}
+// ---------------------------------------------------------------------------
+// Focus
+// ---------------------------------------------------------------------------
+/** Bring a node's tmux window to the foreground and record it as focused.
+ *
+ * Strategy:
+ *   - If the node has no live window (`nodeLive` is false), still write the
+ *     focus pointer — the caller (e.g. revive logic) uses `focused:false` to
+ *     know it needs to open a window first.
+ *   - Otherwise call `switchClient` (lands us in the right session) then
+ *     `selectWindow` (picks the right window within it).  Both calls are
+ *     best-effort; the focus pointer is always written regardless.
+ *
+ * Returns:
+ *   focused — whether the tmux focus actually succeeded.
+ *   session — the tmux session name if one was attempted, null otherwise. */
+export function focusNode(nodeId) {
+    const meta = getNode(nodeId);
+    // Always write the pointer so the dashboard reflects intent even when focus
+    // fails (e.g. we're not currently inside tmux).
+    setFocus(nodeId);
+    if (meta === null || !nodeLive(meta)) {
+        // Node not found or window is gone — caller may need to revive.
+        return { focused: false, session: meta?.tmux_session ?? null };
+    }
+    // Both fields are non-null thanks to nodeLive() returning true.
+    const session = meta.tmux_session;
+    const window = meta.window;
+    // Cross-session hop first, then window selection within the session.
+    // switchClient may be a no-op when already in the same session but is
+    // always safe to call — tmux handles it gracefully.
+    const clientOk = switchClient(session);
+    const windowOk = selectWindow(session, window);
+    return { focused: clientOk && windowOk, session };
+}
+/** Focus a node IN PLACE: bring its pane into the caller's current pane slot
+ *  (swap-pane) instead of navigating the client to the node's own window. This
+ *  is the default for `crtr node focus` and the nav-chrome spine jump — the
+ *  agent appears where you are.
+ *
+ *  Falls back to window focus when there is no caller pane (not inside tmux) or
+ *  the target pane can't be resolved. `inPlace` reports which path ran. */
+export function focusNodeInPlace(nodeId, callerPane) {
+    const meta = getNode(nodeId);
+    // Always write the pointer so the dashboard reflects intent even on failure.
+    setFocus(nodeId);
+    if (meta === null || !nodeLive(meta)) {
+        return { focused: false, session: meta?.tmux_session ?? null, inPlace: false };
+    }
+    const session = meta.tmux_session;
+    const window = meta.window;
+    const pane = callerPane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    // No caller pane (not in tmux) — best we can do is bring the window forefront.
+    if (pane === undefined || pane === '') {
+        const ok = switchClient(session) && selectWindow(session, window);
+        return { focused: ok, session, inPlace: false };
+    }
+    const targetPane = paneOfWindow(session, window);
+    if (targetPane === null) {
+        const ok = switchClient(session) && selectWindow(session, window);
+        return { focused: ok, session, inPlace: false };
+    }
+    if (targetPane === pane)
+        return { focused: true, session, inPlace: true }; // already here
+    // The window the caller's pane currently sits in — the slot the target's pane
+    // is about to be swapped INTO.
+    const callerWindow = windowOfPane(pane);
+    const ok = swapPaneInPlace(targetPane, pane);
+    // Keep the canvas window mapping in sync with the physical swap. swap-pane
+    // exchanges the two PANES between their windows (pane ids are stable, windows
+    // are slots): after the swap the target's pane occupies the caller's window
+    // and the caller's pane occupies the target's old window. Without this update
+    // meta.window goes stale, and a later paneOfWindow(session, meta.window)
+    // resolves the WRONG pane — the bug that made focusing back to a manager a
+    // no-op (it kept resolving the pane already in view) and made a focused node's
+    // exit collapse the visible window instead of its background one.
+    if (ok && callerWindow !== null && callerWindow !== window) {
+        try {
+            updateNode(nodeId, { window: callerWindow });
+        }
+        catch { /* best-effort */ }
+        // The caller is the node running this focus (its pi process owns callerPane).
+        // Its pane moved to the target's old window, so re-point its window there.
+        const callerNodeId = process.env['CRTR_NODE_ID'];
+        if (callerNodeId !== undefined && callerNodeId.trim() !== '' && callerNodeId !== nodeId) {
+            try {
+                updateNode(callerNodeId, { window });
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    return { focused: ok, session, inPlace: true };
+}

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

@@ -0,0 +1,30 @@
+import { type NodeMeta } from '../canvas/index.js';
+export interface PromoteResult {
+    meta: NodeMeta;
+    /** Orchestration guidance to surface into the node's current context now. */
+    guidance: string;
+    roadmapWritten: boolean;
+}
+/** Promote a node to resident orchestrator, optionally specializing its kind
+ *  (e.g. a `general` worker becoming a `developer.orchestrator`). Idempotent:
+ *  re-promoting just rewrites the spec + returns fresh guidance. Seeds a
+ *  roadmap SCAFFOLD if absent (a boss with no map is a failure mode) — no goal
+ *  is forced here; authoring the goal + roadmap is the node's next act. */
+export declare function promote(nodeId: string, opts?: {
+    kind?: string;
+}): PromoteResult;
+export interface YieldResult {
+    meta: NodeMeta;
+    promoted: boolean;
+    /** Always true on success — the node will refresh-revive on its next stop. */
+    willRefresh: boolean;
+}
+/** Request a refresh-yield: discard in-memory context and revive fresh against
+ *  the roadmap. A *terminal* node that yields is choosing to persist — it
+ *  promotes first (refresh-with-open-work is the canonical promotion trigger),
+ *  so it comes back as an orchestrator, optionally specializing its kind. Sets
+ *  intent='refresh'; the stophook shuts the process down on the next stop and
+ *  the daemon revives it fresh. */
+export declare function requestYield(nodeId: string, opts?: {
+    kind?: string;
+}): YieldResult;

package/dist/core/runtime/promote.js

@@ -0,0 +1,105 @@
+// Promotion — terminal → resident, and the worker→orchestrator polymorph.
+//
+// Two stages (the pi-mode-switch pattern):
+//   1. Promotion → guidance dump (mid-turn, ephemeral). This call flips the
+//      node's mode/lifecycle and (optionally) its KIND, REWRITES its launch
+//      spec to that kind's orchestrator persona (so the next revive comes back
+//      as that orchestrator), seeds a roadmap scaffold, and RETURNS kind-
+//      specific orchestration + roadmap-shaping guidance — which enters the
+//      current context so the node can author its roadmap before any refresh.
+//   2. Refresh → persona swap (permanent). On the next fresh revive the node
+//      starts with the orchestrator system prompt baked in (because the launch
+//      spec now says orchestrator). The guidance dump bridges until then.
+//
+// Trigger is persistence-need (deliberate, or a refresh-yield with open work),
+// never the mere act of spawning a child.
+import { getNode, updateNode, hasActiveLiveSubscription } from '../canvas/index.js';
+import { buildLaunchSpec } from './launch.js';
+import { loadKernel, loadPersona } from '../personas/index.js';
+import { resolveSkill } from '../resolver.js';
+import { readText } from '../fs-utils.js';
+import { parseFrontmatter } from '../frontmatter.js';
+import { hasRoadmap, seedRoadmap, readRoadmap } from './roadmap.js';
+/** Load a skill's body text by name, or null if it can't be resolved. Used to
+ *  inline a kind's roadmap-shaping skill into the promotion guidance dump. */
+function loadSkillBody(name) {
+    try {
+        const skill = resolveSkill(name, {});
+        return parseFrontmatter(readText(skill.path)).body.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Build the mid-turn guidance dump, specialized to the node's (possibly
+ *  just-chosen) kind: the shared kernel + that kind's roadmap-shaping skill
+ *  (auto-loaded now, before the persona swap bakes in on revive) + the roadmap
+ *  scaffold the node must author. No goal is assumed — writing it is step one. */
+function orchestrationGuidance(nodeId, kind) {
+    const kernel = loadKernel();
+    const orch = loadPersona(kind, 'orchestrator');
+    const roadmapSkill = typeof orch?.frontmatter?.['roadmapSkill'] === 'string'
+        ? orch.frontmatter['roadmapSkill']
+        : undefined;
+    const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
+    const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
+    const parts = [
+        `You are now a RESIDENT ${kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
+        'Your job is to manage context and delegate — not to do the goal yourself.',
+        '',
+        kernel,
+    ];
+    if (skillBody) {
+        parts.push('', `--- How to shape a ${kind} roadmap (skill: ${roadmapSkill}) ---`, '', skillBody);
+    }
+    parts.push('', 'Your roadmap scaffold (`context/roadmap.md`) — author it now: state the goal, exit criteria, scope assumptions, and the phase skeleton, using the approach above:', '', roadmap, '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
+    return parts.join('\n');
+}
+/** Promote a node to resident orchestrator, optionally specializing its kind
+ *  (e.g. a `general` worker becoming a `developer.orchestrator`). Idempotent:
+ *  re-promoting just rewrites the spec + returns fresh guidance. Seeds a
+ *  roadmap SCAFFOLD if absent (a boss with no map is a failure mode) — no goal
+ *  is forced here; authoring the goal + roadmap is the node's next act. */
+export function promote(nodeId, opts = {}) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    // The node may specialize as it promotes; default to its current kind.
+    const targetKind = opts.kind ?? node.kind;
+    // Rewrite the launch spec to the target kind's orchestrator persona so the
+    // *next* revive comes back orchestrating in that kind (polymorph stage 2).
+    // nodeEnv reads meta.{kind,mode}, so CRTR_KIND/CRTR_MODE flip immediately for
+    // the live process's children too.
+    const { launch } = buildLaunchSpec(targetKind, 'orchestrator');
+    // Seed a roadmap scaffold if absent so the file exists for a refresh. The
+    // node fills in the goal/body next, guided by the kind skill dumped below.
+    let roadmapWritten = false;
+    if (!hasRoadmap(nodeId)) {
+        seedRoadmap(nodeId);
+        roadmapWritten = true;
+    }
+    const meta = updateNode(nodeId, { kind: targetKind, lifecycle: 'resident', mode: 'orchestrator', launch });
+    return { meta, guidance: orchestrationGuidance(nodeId, targetKind), roadmapWritten };
+}
+/** Request a refresh-yield: discard in-memory context and revive fresh against
+ *  the roadmap. A *terminal* node that yields is choosing to persist — it
+ *  promotes first (refresh-with-open-work is the canonical promotion trigger),
+ *  so it comes back as an orchestrator, optionally specializing its kind. Sets
+ *  intent='refresh'; the stophook shuts the process down on the next stop and
+ *  the daemon revives it fresh. */
+export function requestYield(nodeId, opts = {}) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    let promoted = false;
+    if (node.lifecycle === 'terminal') {
+        // Yielding with open work ⇒ must survive a context reset ⇒ promote
+        // (optionally specializing the kind).
+        promote(nodeId, opts.kind !== undefined ? { kind: opts.kind } : {});
+        promoted = true;
+    }
+    // Mark the intent; the stophook enacts the shutdown, the daemon the revive.
+    const meta = updateNode(nodeId, { intent: 'refresh' });
+    void hasActiveLiveSubscription; // (open-work signal, reserved for future gating)
+    return { meta, promoted, willRefresh: true };
+}

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

@@ -0,0 +1,13 @@
+export interface ResetRootResult {
+    /** Descendant node ids torn down (window killed + marked dead). */
+    reaped: string[];
+    /** Direct subscriptions dropped off the root. */
+    detached: string[];
+    /** True when the node was a root and a full reset ran. */
+    reset: boolean;
+}
+/** Reset a root node to a pristine, empty graph (the `/new` semantics).
+ *
+ *  For a non-root (spawned child), a `/new` is not a graph reset — we only
+ *  refresh its session id so a later `--resume` wakes the right conversation. */
+export declare function resetRoot(nodeId: string, newSessionId?: string): ResetRootResult;

package/dist/core/runtime/reset.js

@@ -0,0 +1,97 @@
+// Root reset — the `/new` equivalent.
+//
+// A live pi process is bound to one node via CRTR_NODE_ID (set at launch, not
+// rebindable mid-process). When the user runs `/new`, the conversation is reset
+// but the process — and thus the node id — stays the same. To make `/new`
+// behave like re-running `crtr` (a brand-new graph on the canvas) we reset the
+// root in place: reap its entire descendant sub-DAG, detach its subscriptions,
+// and wipe its working state, then re-point it at a fresh base persona and the
+// new pi session id. The node keeps its id; from the dashboard/nav it is a
+// pristine root with an empty graph.
+//
+// Best-effort throughout: a tmux/fs failure on one node never aborts the reset.
+import { existsSync, rmSync } from 'node:fs';
+import { getNode, updateNode, setStatus, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, } from '../canvas/index.js';
+import { closeWindow, windowAlive } from './tmux.js';
+import { buildLaunchSpec } from './launch.js';
+import { roadmapPath } from './roadmap.js';
+/** Reset a root node to a pristine, empty graph (the `/new` semantics).
+ *
+ *  For a non-root (spawned child), a `/new` is not a graph reset — we only
+ *  refresh its session id so a later `--resume` wakes the right conversation. */
+export function resetRoot(nodeId, newSessionId) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { reaped: [], detached: [], reset: false };
+    // Only roots own a graph in the "ran crtr again" sense.
+    if (meta.parent != null) {
+        if (newSessionId !== undefined) {
+            try {
+                updateNode(nodeId, { pi_session_id: newSessionId });
+            }
+            catch { /* */ }
+        }
+        return { reaped: [], detached: [], reset: false };
+    }
+    // 1) Reap the descendant sub-DAG. Mark dead + clear intent FIRST, then kill
+    //    the window: the daemon revives on a window-gone + intent==='refresh'
+    //    (or 'idle-release'), so flipping to dead before the window dies closes
+    //    the race where a descendant mid-yield gets revived as we tear it down.
+    const reaped = [];
+    for (const id of view(nodeId)) {
+        try {
+            const dmeta = getNode(id);
+            setStatus(id, 'dead');
+            updateNode(id, { intent: null });
+            if (dmeta !== null && windowAlive(dmeta.tmux_session, dmeta.window)) {
+                closeWindow(dmeta.window);
+            }
+            reaped.push(id);
+        }
+        catch {
+            /* one bad node never aborts the reset */
+        }
+    }
+    // 2) Detach the root's own subscriptions so its view is empty.
+    const detached = [];
+    for (const sub of subscriptionsOf(nodeId)) {
+        try {
+            unsubscribe(nodeId, sub.node_id);
+            detached.push(sub.node_id);
+        }
+        catch {
+            /* */
+        }
+    }
+    // 3) Wipe the root's working state (reports / inbox / roadmap).
+    for (const p of [
+        reportsDir(nodeId),
+        inboxPath(nodeId),
+        `${inboxPath(nodeId)}.cursor`,
+        roadmapPath(nodeId),
+    ]) {
+        try {
+            if (existsSync(p))
+                rmSync(p, { recursive: true, force: true });
+        }
+        catch {
+            /* */
+        }
+    }
+    // 4) Re-point the root at a fresh base persona + the new pi session id.
+    try {
+        const { launch } = buildLaunchSpec(meta.kind, 'base');
+        updateNode(nodeId, {
+            mode: 'base',
+            lifecycle: 'resident',
+            intent: null,
+            status: 'active',
+            launch,
+            ...(newSessionId !== undefined ? { pi_session_id: newSessionId } : {}),
+        });
+    }
+    catch {
+        /* */
+    }
+    return { reaped, detached, reset: true };
+}

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

@@ -0,0 +1,26 @@
+export interface ReviveResult {
+    /** The new tmux window id, or null if openNodeWindow failed. */
+    window: string | null;
+    /** The tmux session the node was placed in. */
+    session: string;
+    /** True when pi was instructed to resume its saved conversation (`--resume`). */
+    resumed: boolean;
+}
+/** Open a fresh background tmux window for `nodeId` and update canvas meta.
+ *
+ *  Throws if the node does not exist. All other failures (e.g. tmux not
+ *  available) propagate as-is — callers (daemon, command) decide how to handle.
+ */
+export declare function reviveNode(nodeId: string, opts: {
+    resume: boolean;
+}): ReviveResult;
+/** Re-exec a node's pi FRESH in its EXISTING tmux pane (the refresh-yield
+ *  path). Unlike `reviveNode`, this opens no new window: the pane's current pi
+ *  is replaced in place via `respawn-pane -k`, so a foreground/interactive
+ *  session keeps its terminal and a background node keeps its window. Always
+ *  fresh (no resume) — the node re-reads its roadmap/context dir.
+ *
+ *  `pane` is the target pane id (the yielding node reads it from $TMUX_PANE).
+ *  Throws on unknown node or when the respawn could not be dispatched, so the
+ *  caller can fall back to a plain shutdown (daemon revives in a new window). */
+export declare function reviveInPlace(nodeId: string, pane: string): ReviveResult;

package/dist/core/runtime/revive.js

@@ -0,0 +1,89 @@
+// The revive primitive — restores a node to active status under a fresh tmux
+// window. Used by both the supervisor daemon (on crash/refresh detection) and
+// the explicit `crtr canvas revive` command.
+//
+// A revive always opens a NEW window: the old one is gone (crashed, or the
+// node exited with intent=refresh). The node's persisted LaunchSpec and cwd
+// are the canonical recipe; reviveNode replays them faithfully.
+//
+//   resume=true  → `pi --resume <pi_session_id>` — wakes the saved conversation.
+//   resume=false → fresh pi invocation — the node re-reads its roadmap/context dir.
+import { getNode, updateNode, } from '../canvas/index.js';
+import { buildPiArgv } from './launch.js';
+import { buildReviveKickoff } from './kickoff.js';
+import { ensureSession, openNodeWindow, piCommand, respawnPane, } from './tmux.js';
+import { rootSessionName } from './spawn.js';
+// ---------------------------------------------------------------------------
+// reviveNode
+// ---------------------------------------------------------------------------
+/** Open a fresh background tmux window for `nodeId` and update canvas meta.
+ *
+ *  Throws if the node does not exist. All other failures (e.g. tmux not
+ *  available) propagate as-is — callers (daemon, command) decide how to handle.
+ */
+export function reviveNode(nodeId, opts) {
+    const meta = getNode(nodeId);
+    if (meta === null) {
+        throw new Error(`reviveNode: unknown node ${nodeId}`);
+    }
+    // The node lives in its root's tmux session. Prefer the stored session name;
+    // fall back to deriving it from the parent (or the node itself for roots).
+    const session = meta.tmux_session ??
+        rootSessionName((meta.parent ?? meta.node_id));
+    ensureSession(session, meta.cwd);
+    // Decide whether to wake the saved pi conversation or start fresh.
+    const resumeId = opts.resume && meta.pi_session_id != null
+        ? meta.pi_session_id
+        : undefined;
+    // A fresh revive (no resume) gets a kickoff prompt so it re-reads its roadmap
+    // and continues; resuming a saved conversation needs none.
+    const inv = resumeId !== undefined
+        ? buildPiArgv(meta, { resumeSessionId: resumeId })
+        : buildPiArgv(meta, { prompt: buildReviveKickoff(meta) });
+    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
+    const window = openNodeWindow({
+        session,
+        name: meta.name,
+        cwd: meta.cwd,
+        env,
+        command: piCommand(inv.argv),
+    });
+    updateNode(nodeId, {
+        status: 'active',
+        intent: null,
+        window,
+        tmux_session: session,
+    });
+    return { window, session, resumed: resumeId !== undefined };
+}
+// ---------------------------------------------------------------------------
+// reviveInPlace — refresh-yield without churning the window
+// ---------------------------------------------------------------------------
+/** Re-exec a node's pi FRESH in its EXISTING tmux pane (the refresh-yield
+ *  path). Unlike `reviveNode`, this opens no new window: the pane's current pi
+ *  is replaced in place via `respawn-pane -k`, so a foreground/interactive
+ *  session keeps its terminal and a background node keeps its window. Always
+ *  fresh (no resume) — the node re-reads its roadmap/context dir.
+ *
+ *  `pane` is the target pane id (the yielding node reads it from $TMUX_PANE).
+ *  Throws on unknown node or when the respawn could not be dispatched, so the
+ *  caller can fall back to a plain shutdown (daemon revives in a new window). */
+export function reviveInPlace(nodeId, pane) {
+    const meta = getNode(nodeId);
+    if (meta === null) {
+        throw new Error(`reviveInPlace: unknown node ${nodeId}`);
+    }
+    const session = meta.tmux_session ??
+        rootSessionName((meta.parent ?? meta.node_id));
+    // Fresh re-exec: same recipe as a no-resume reviveNode, with the kickoff so
+    // the node rebuilds its bearings from disk.
+    const inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta) });
+    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
+    const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
+    if (!ok) {
+        throw new Error(`reviveInPlace: respawn-pane dispatch failed for ${nodeId}`);
+    }
+    updateNode(nodeId, { status: 'active', intent: null, tmux_session: session });
+    // Window is unchanged (we re-execed in place); report the existing one.
+    return { window: meta.window ?? null, session, resumed: false };
+}

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

@@ -0,0 +1,12 @@
+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 roadmap SCAFFOLD. No goal is required — promotion lays this
+ *  down so the file exists for a refresh, and the owner authors the goal +
+ *  body as its next act (guided by its kind's roadmap skill). `goal`/
+ *  `exitCriteria` are optional overrides. 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;