@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/core/runtime/presence.js

@@ -0,0 +1,198 @@
+// 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, openShellWindow, closeWindow, ensureSession, nodeSession } 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 };
+}
+// ---------------------------------------------------------------------------
+// Demote — detach the agent in the caller's pane to the background
+// ---------------------------------------------------------------------------
+/** Send a node's running pi OUT of the caller's pane and into a window in the
+ *  shared global session, leaving a fresh shell where it was — the pane
+ *  "becomes a terminal" and the agent keeps running, detached, in the
+ *  background. The inverse of `focusNodeInPlace`; reversible via `node focus`.
+ *
+ *  Mechanism: open a shell window in the global session, then swap that shell
+ *  pane INTO the caller's pane — tmux exchanges the two panes, so the node's pi
+ *  pane lands in the shell's window (global session) and the shell lands in the
+ *  caller's pane. The node's meta is re-pointed to the new window so the daemon
+ *  keeps supervising it.
+ *
+ *  Best-effort; `demoted:false` when not in tmux or any tmux step fails. */
+export function demoteNode(nodeId, callerPane) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { demoted: false, session: null, window: null };
+    const pane = callerPane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (pane === undefined || pane === '') {
+        return { demoted: false, session: meta.tmux_session ?? null, window: meta.window ?? null };
+    }
+    const session = nodeSession();
+    ensureSession(session, meta.cwd);
+    const shell = openShellWindow({ session, name: meta.name, cwd: meta.cwd });
+    if (shell === null)
+        return { demoted: false, session, window: meta.window ?? null };
+    // Swap the fresh shell into the caller's pane; the node's pi pane is exchanged
+    // out into the shell's window (now living in the global session).
+    const ok = swapPaneInPlace(shell.pane, pane);
+    if (!ok) {
+        closeWindow(shell.window);
+        return { demoted: false, session, window: meta.window ?? null };
+    }
+    // The node's pi now occupies the shell window; re-point its meta there so
+    // liveness checks resolve the right window.
+    try {
+        updateNode(nodeId, { tmux_session: session, window: shell.window });
+    }
+    catch { /* best-effort */ }
+    // The caller pane reverted to a terminal — if this node held focus, clear it.
+    if (getFocus() === nodeId)
+        setFocus('');
+    return { demoted: true, session, window: shell.window };
+}

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,87 @@
+// 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, nodeSession, } from './tmux.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 the shared global session. Prefer its stored session
+    // (an inline root tracks its own real terminal session); fall back to the
+    // shared node session.
+    const session = meta.tmux_session ?? nodeSession();
+    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 ?? nodeSession();
+    // 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;

package/dist/core/runtime/roadmap.js

@@ -0,0 +1,52 @@
+// 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 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 function seedRoadmap(nodeId, opts = {}) {
+    const dir = contextDir(nodeId);
+    mkdirSync(dir, { recursive: true });
+    const body = `# Roadmap
+
+<!-- frozen core: set once, rarely changes -->
+## Goal
+${opts.goal?.trim() ?? '- (state the high-level goal you now own — write this as your first act)'}
+
+## Exit criteria
+${opts.exitCriteria?.trim() ?? '- (define what "done" looks like)'}
+
+<!-- evolving body: keep this current as you learn scope + intent -->
+## Scope assumptions / non-goals
+- (record what's out of scope and what's settled — e.g. "reuse existing auth", "security isn't a concern here" — so children inherit the framing)
+
+## Strategy / phases
+- (your high-level shape of how you reach the goal; the ordered phases from here to done, the current one carrying a one-line status. Each phase can become a child whose own roadmap is that phase)
+
+## Active context
+- (the context/ files currently relevant to the work, by path; none yet)
+`;
+    writeFileSync(roadmapPath(nodeId), body);
+    return body;
+}

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

@@ -0,0 +1,31 @@
+import { type NodeMeta, type Mode } from '../canvas/index.js';
+export interface BootRootOpts {
+    cwd: string;
+    kind?: string;
+    name?: string;
+    /** Optional starter prompt (bare `crtr` requires none). */
+    prompt?: string;
+    /** 'inline'  — exec pi in the current terminal (bare `crtr`).
+     *  'session' — create a dedicated tmux session and run pi there (`session new`). */
+    placement: 'inline' | 'session';
+}
+/** Create a root node and bring up its pi. Returns the node; for 'inline' this
+ *  only returns after pi exits (it took over the terminal). */
+export declare function bootRoot(opts: BootRootOpts): NodeMeta;
+export interface SpawnChildOpts {
+    kind: string;
+    mode?: Mode;
+    cwd: string;
+    name?: string;
+    prompt: string;
+    /** Override the parent (defaults to the calling node from env). */
+    parent?: string;
+}
+export interface SpawnChildResult {
+    node: NodeMeta;
+    window: string | null;
+    session: string;
+}
+/** Spawn a terminal worker as a background window under the root session.
+ *  The parent auto-subscribes (active) to it via spawnNode. */
+export declare function spawnChild(opts: SpawnChildOpts): SpawnChildResult;