@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/core/runtime/front-door.js

@@ -0,0 +1,97 @@
+// The front door — bare `crtr` boots a resident root node.
+//
+//   crtr                         → boot a root in this terminal (no prompt)
+//   crtr [dir]                   → root pinned to dir
+//   crtr [dir] ["prompt"]        → root with a starter prompt
+//   crtr --name NAME ...         → named root
+//   crtr <subcommand> ...        → falls through to the normal dispatcher
+//   crtr -h | --help             → root help (dispatcher)
+//
+// This is the only place that distinguishes "I want to live here" (root) from
+// the subcommand surface. It runs before the dispatcher; if it boots, pi takes
+// over the terminal and the process never returns.
+import { existsSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { bootRoot } from './spawn.js';
+function isDir(p) {
+    try {
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse `[dir] [prompt]` positionals + `--name`/`--kind` flags out of the
+ *  leftover tokens after the bare `crtr`. */
+function parseRootArgs(tokens) {
+    let cwd = process.cwd();
+    let name;
+    let kind;
+    const positionals = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === '--name') {
+            name = tokens[++i];
+        }
+        else if (t === '--kind') {
+            kind = tokens[++i];
+        }
+        else if (t.startsWith('--')) {
+            // ignore unknown flags for the front door
+        }
+        else {
+            positionals.push(t);
+        }
+    }
+    // First positional that is an existing dir → cwd; the rest → prompt.
+    if (positionals.length > 0 && isDir(resolvePath(positionals[0]))) {
+        cwd = resolvePath(positionals.shift());
+    }
+    const prompt = positionals.length > 0 ? positionals.join(' ') : undefined;
+    return { cwd, prompt, name, kind };
+}
+/** Env marker set on every pi the front door boots. Its presence means we are
+ *  already inside a front-door-booted root, so a nested front-door launch must
+ *  be refused — otherwise a removed/renamed subcommand that a child pi re-runs
+ *  (e.g. `crtr node -h`) fork-bombs pi until the machine must be rebooted. */
+export const FRONT_DOOR_ENV = 'CRTR_FRONT_DOOR';
+/** If this invocation is a front-door (root) launch, boot it and never return.
+ *  Returns false when it's a recognized subcommand / help / unknown token (let
+ *  the dispatcher handle it — for unknown tokens it errors cleanly). */
+export function maybeBootRoot(root, argv) {
+    const tokens = argv.slice(2);
+    const first = tokens[0];
+    // Recursion guard: never boot a root from inside a front-door-booted pi.
+    // This is the hard backstop against fork bombs — even a future footgun where
+    // a child re-invokes a removed subcommand cannot loop, because the second
+    // boot is refused and falls through to the dispatcher.
+    if (process.env[FRONT_DOOR_ENV])
+        return false;
+    // `crtr -h` / `crtr --help` / `crtr --version` → dispatcher (root help).
+    if (first === '-h' || first === '--help' || first === '--version' || first === '-v') {
+        return false;
+    }
+    // A recognized subcommand → dispatcher.
+    const subtreeNames = new Set(root.subtrees.map((s) => s.name));
+    if (first !== undefined && subtreeNames.has(first))
+        return false;
+    // The front door boots pi ONLY on an unambiguous "live here" signal:
+    //   • bare `crtr`                  (no tokens)
+    //   • `crtr <dir> [prompt]`        (first positional is an existing dir)
+    //   • `crtr "multi word prompt"`   (first token contains whitespace)
+    // Anything else — a bare word like `job`, or a leading flag — is treated as a
+    // mistyped/removed subcommand and handed to the dispatcher, which errors with
+    // "unknown subcommand: <token>". Booting pi for such tokens is what let the
+    // renamed `agent`/`job` subcommands fork-bomb the front door.
+    if (first !== undefined) {
+        const looksLikePrompt = /\s/.test(first);
+        const looksLikeDir = !first.startsWith('-') && isDir(resolvePath(first));
+        if (!looksLikePrompt && !looksLikeDir)
+            return false;
+    }
+    // Unambiguous front-door launch → boot a resident root inline (exec pi in
+    // this terminal). Does not return.
+    const args = parseRootArgs(tokens);
+    bootRoot({ ...args, placement: 'inline' });
+    return true;
+}

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

@@ -0,0 +1,23 @@
+import { type NodeMeta } from '../canvas/index.js';
+/** The goal file — the prompt/task a node was spawned with, persisted at birth
+ *  so a fresh revive can re-read its mandate. */
+export declare function goalPath(nodeId: string): string;
+export declare function readGoal(nodeId: string): string | null;
+/** Persist the spawning prompt as the node's goal. No-op for an empty prompt
+ *  (e.g. a bare root). Idempotent enough — call once at spawn/boot. */
+export declare function writeGoal(nodeId: string, text: string): void;
+/** The yield-message file — a short note `crtr node yield` records for the next
+ *  revive ("on wake, do X"). Consumed (deleted) when the revive reads it. */
+export declare function yieldMessagePath(nodeId: string): string;
+export declare function writeYieldMessage(nodeId: string, text: string): void;
+/** Read AND delete the yield message — it is a one-shot handoff to the next
+ *  revive, so a later crash-revive never resurfaces a stale note. */
+export declare function consumeYieldMessage(nodeId: string): string | null;
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export declare function listContextDir(nodeId: string): string[];
+/** Build the auto-injected first message for a FRESH revive of `meta`. Reads
+ *  the node's goal, roadmap, context dir, feed, and one-shot yield message off
+ *  disk and frames them so the revived node can rebuild its bearings in one
+ *  turn. Side effects: consumes the yield message and advances the feed cursor
+ *  (both are "read" by surfacing them here). */
+export declare function buildReviveKickoff(meta: NodeMeta): string;

package/dist/core/runtime/kickoff.js

@@ -0,0 +1,134 @@
+// The revive kickoff — the message auto-injected as a node's first turn when it
+// comes back FRESH (a refresh-yield, or `canvas revive --fresh`). The node's
+// in-memory context is gone, so this message IS its bearings: everything is
+// read from disk and framed so the node can rebuild and continue without a
+// round-trip. Resuming a saved conversation needs none of this (the
+// conversation already holds the context).
+//
+// Layout (the framing a revived node sees):
+//   <goal file=…>…</goal>                  the mandate it was spawned with
+//   <roadmap file=…>…</roadmap>            its evolving plan
+//   <context-dir path=…>…</context-dir>    what artifacts exist on disk
+//   <feed>Awaiting N nodes … digest</feed> who it waits on + unread reports
+//   <yield-message>…</yield-message>       the note its prior self left on yield
+//
+// The goal + yield-message are companion files in the node's context dir; the
+// yield-message is one-shot (consumed on the next revive).
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, readdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { contextDir, getNode, subscriptionsOf, } from '../canvas/index.js';
+import { readRoadmap, roadmapPath } from './roadmap.js';
+import { readInboxSince, readCursor, writeCursor, coalesce, } from '../feed/inbox.js';
+// ---------------------------------------------------------------------------
+// Companion context files: the goal (the spawning mandate) and the one-shot
+// yield message (a note from the prior self to the revived self).
+// ---------------------------------------------------------------------------
+/** The goal file — the prompt/task a node was spawned with, persisted at birth
+ *  so a fresh revive can re-read its mandate. */
+export function goalPath(nodeId) {
+    return join(contextDir(nodeId), 'initial-prompt.md');
+}
+export function readGoal(nodeId) {
+    const p = goalPath(nodeId);
+    return existsSync(p) ? readFileSync(p, 'utf8') : null;
+}
+/** Persist the spawning prompt as the node's goal. No-op for an empty prompt
+ *  (e.g. a bare root). Idempotent enough — call once at spawn/boot. */
+export function writeGoal(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    mkdirSync(contextDir(nodeId), { recursive: true });
+    writeFileSync(goalPath(nodeId), body + '\n', 'utf8');
+}
+/** The yield-message file — a short note `crtr node yield` records for the next
+ *  revive ("on wake, do X"). Consumed (deleted) when the revive reads it. */
+export function yieldMessagePath(nodeId) {
+    return join(contextDir(nodeId), 'yield-message.md');
+}
+export function writeYieldMessage(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    mkdirSync(contextDir(nodeId), { recursive: true });
+    writeFileSync(yieldMessagePath(nodeId), body + '\n', 'utf8');
+}
+/** Read AND delete the yield message — it is a one-shot handoff to the next
+ *  revive, so a later crash-revive never resurfaces a stale note. */
+export function consumeYieldMessage(nodeId) {
+    const p = yieldMessagePath(nodeId);
+    if (!existsSync(p))
+        return null;
+    const body = readFileSync(p, 'utf8');
+    try {
+        rmSync(p);
+    }
+    catch { /* best-effort */ }
+    return body.trim() !== '' ? body : null;
+}
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export function listContextDir(nodeId) {
+    const dir = contextDir(nodeId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).sort();
+}
+// ---------------------------------------------------------------------------
+// Feed block — who the node is awaiting, plus a drained digest of unread
+// reports. Draining here advances the cursor: the revived node has now "read"
+// the feed, so a later `crtr feed read` shows only what arrives afterward.
+// ---------------------------------------------------------------------------
+function feedBlock(nodeId) {
+    // Awaiting = active subscriptions whose publisher is still live (active|idle).
+    const awaiting = subscriptionsOf(nodeId)
+        .filter((s) => s.active)
+        .map((s) => getNode(s.node_id))
+        .filter((m) => m !== null && (m.status === 'active' || m.status === 'idle'));
+    const lines = [];
+    lines.push(`Awaiting ${awaiting.length} node${awaiting.length === 1 ? '' : 's'}.`);
+    for (const m of awaiting)
+        lines.push(`  - ${m.name} (${m.node_id}) — ${m.status}`);
+    const cursor = readCursor(nodeId);
+    const entries = readInboxSince(nodeId, cursor);
+    if (entries.length > 0) {
+        writeCursor(nodeId, entries[entries.length - 1].ts);
+        lines.push('', coalesce(entries));
+    }
+    else {
+        lines.push('', '(no unread reports)');
+    }
+    return `<feed>\n${lines.join('\n')}\n</feed>`;
+}
+// ---------------------------------------------------------------------------
+// buildReviveKickoff — assemble the full fresh-revive first message.
+// ---------------------------------------------------------------------------
+/** Build the auto-injected first message for a FRESH revive of `meta`. Reads
+ *  the node's goal, roadmap, context dir, feed, and one-shot yield message off
+ *  disk and frames them so the revived node can rebuild its bearings in one
+ *  turn. Side effects: consumes the yield message and advances the feed cursor
+ *  (both are "read" by surfacing them here). */
+export function buildReviveKickoff(meta) {
+    const nodeId = meta.node_id;
+    // Consume the one-shot yield note first so it never shows in the dir listing.
+    const yieldMsg = consumeYieldMessage(nodeId);
+    const parts = [
+        'You have been revived fresh after a context refresh — your previous in-memory ' +
+            'context is gone, by design. Everything below was just read from disk; it is your ' +
+            'full bearings. Rebuild from it and continue toward your goal.',
+    ];
+    const goal = readGoal(nodeId);
+    if (goal !== null && goal.trim() !== '') {
+        parts.push(`<goal file="${goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);
+    }
+    const roadmap = readRoadmap(nodeId);
+    parts.push(`<roadmap file="${roadmapPath(nodeId)}">\n${roadmap !== null && roadmap.trim() !== '' ? roadmap.trim() : '(no roadmap on disk yet)'}\n</roadmap>`);
+    const files = listContextDir(nodeId);
+    parts.push(`<context-dir path="${contextDir(nodeId)}">\n${files.length > 0 ? files.join('\n') : '(empty)'}\n</context-dir>`);
+    parts.push(feedBlock(nodeId));
+    parts.push(yieldMsg !== null
+        ? `<yield-message>\n${yieldMsg.trim()}\n</yield-message>`
+        : '<yield-message/>');
+    parts.push('If there is work to do, perform it. Otherwise stop — `crtr push final "<result>"` ' +
+        'if the goal is met, or end your turn to stay dormant awaiting your workers.');
+    return parts.join('\n\n');
+}

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

@@ -0,0 +1,34 @@
+import type { NodeMeta, LaunchSpec, Mode } from '../canvas/index.js';
+export declare const CANVAS_STOPHOOK_PATH: string;
+export declare const CANVAS_INBOX_WATCHER_PATH: string;
+export declare const CANVAS_NAV_PATH: string;
+/** The canvas extensions every node loads, in order: stophook (routing +
+ *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
+ *  graph chrome). All self-gate on CRTR_NODE_ID. */
+export declare const CANVAS_EXTENSIONS: string[];
+/** Bare model aliases resolve to the anthropic provider under pi (avoids the
+ *  bedrock default). Anything with a `/` or an unknown name passes through. */
+export declare function normalizeModel(model: string): string;
+/** Compose a node's full pi launch recipe from its persona. The two canvas
+ *  extensions are always first; persona-declared extensions follow. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts?: {
+    extraEnv?: Record<string, string>;
+}): {
+    launch: LaunchSpec;
+    lifecycle: 'terminal' | 'resident';
+    skills: string[];
+};
+export interface PiInvocation {
+    /** argv after the `pi` binary. */
+    argv: string[];
+    /** env to merge into the process. */
+    env: Record<string, string>;
+}
+/** Construct the pi invocation for a node.
+ *  - fresh start: pass `prompt` (the node's first user message), no resume.
+ *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).
+ *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
+export declare function buildPiArgv(meta: NodeMeta, opts?: {
+    prompt?: string;
+    resumeSessionId?: string;
+}): PiInvocation;

package/dist/core/runtime/launch.js

@@ -0,0 +1,85 @@
+// The launch spec — how a node becomes (or comes back as) a running pi process.
+//
+// pi-only. No claude branch — we are a super-opinionated system. A node's
+// LaunchSpec (persisted in meta.json) is the canonical recipe the daemon
+// replays to revive it faithfully: `--resume` to wake a done/idle node (keeps
+// its conversation), or fresh (against the context dir) for a refresh-yield.
+// The spec is rewritten on every polymorph (base→orchestrator) so a node
+// always comes back as its *current* self.
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolve as resolvePersona } from '../personas/index.js';
+import { nodeEnv } from './nodes.js';
+// ---------------------------------------------------------------------------
+// The two canvas pi-extensions every node loads. They self-gate on the live
+// {kind,mode} env, so the worker→orchestrator polymorph flips hook behavior
+// with no respawn.
+// ---------------------------------------------------------------------------
+function resolveExtension(name) {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/core/runtime or src/core/runtime
+    const candidates = [
+        join(here, '..', '..', 'pi-extensions', `${name}.js`),
+        join(here, '..', '..', 'pi-extensions', `${name}.ts`),
+    ];
+    return candidates.find((p) => existsSync(p)) ?? candidates[0];
+}
+export const CANVAS_STOPHOOK_PATH = resolveExtension('canvas-stophook');
+export const CANVAS_INBOX_WATCHER_PATH = resolveExtension('canvas-inbox-watcher');
+export const CANVAS_NAV_PATH = resolveExtension('canvas-nav');
+/** The canvas extensions every node loads, in order: stophook (routing +
+ *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
+ *  graph chrome). All self-gate on CRTR_NODE_ID. */
+export const CANVAS_EXTENSIONS = [
+    CANVAS_STOPHOOK_PATH,
+    CANVAS_INBOX_WATCHER_PATH,
+    CANVAS_NAV_PATH,
+];
+/** Bare model aliases resolve to the anthropic provider under pi (avoids the
+ *  bedrock default). Anything with a `/` or an unknown name passes through. */
+export function normalizeModel(model) {
+    const bare = new Set(['sonnet', 'opus', 'haiku']);
+    if (bare.has(model))
+        return `anthropic/${model}`;
+    return model;
+}
+// ---------------------------------------------------------------------------
+// Build the launch spec from {kind, mode}
+// ---------------------------------------------------------------------------
+/** Compose a node's full pi launch recipe from its persona. The two canvas
+ *  extensions are always first; persona-declared extensions follow. */
+export function buildLaunchSpec(kind, mode, opts = {}) {
+    const p = resolvePersona(kind, mode);
+    const launch = {
+        model: p.model !== undefined ? normalizeModel(p.model) : undefined,
+        tools: p.tools,
+        extensions: [...CANVAS_EXTENSIONS, ...p.extensions],
+        systemPrompt: p.systemPrompt,
+        env: { ...(opts.extraEnv ?? {}) },
+    };
+    return { launch, lifecycle: p.lifecycle, skills: p.skills };
+}
+/** Construct the pi invocation for a node.
+ *  - fresh start: pass `prompt` (the node's first user message), no resume.
+ *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).
+ *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
+export function buildPiArgv(meta, opts = {}) {
+    const spec = meta.launch;
+    const argv = [];
+    for (const ext of spec?.extensions ?? CANVAS_EXTENSIONS) {
+        argv.push('-e', ext);
+    }
+    argv.push('-n', meta.name);
+    if (opts.resumeSessionId !== undefined)
+        argv.push('--resume', opts.resumeSessionId);
+    if (spec?.model !== undefined)
+        argv.push('--model', spec.model);
+    if (spec?.tools !== undefined && spec.tools.length > 0)
+        argv.push('--tools', spec.tools.join(','));
+    if (spec?.systemPrompt !== undefined && spec.systemPrompt !== '') {
+        argv.push('--append-system-prompt', spec.systemPrompt);
+    }
+    if (opts.prompt !== undefined && opts.prompt !== '')
+        argv.push(opts.prompt);
+    return { argv, env: nodeEnv(meta) };
+}

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

@@ -0,0 +1,38 @@
+import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec } from '../canvas/index.js';
+/** Generate a node id in the same shape as job ids (time-sortable + random). */
+export declare function newNodeId(): string;
+export interface NodeContext {
+    nodeId: string | null;
+    parentNodeId: string | null;
+    kind: string | null;
+    mode: Mode | null;
+}
+/** 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 declare function currentNodeContext(): NodeContext;
+/** 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 declare function nodeEnv(meta: NodeMeta): Record<string, string>;
+export interface SpawnNodeOpts {
+    kind: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    cwd: string;
+    name?: string;
+    /** Parent node id. Omit for a user-opened root. */
+    parent?: string | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passiveDefault?: boolean;
+    /** Resolved pi launch recipe (from resolve(kind,mode)). */
+    launch?: LaunchSpec;
+    /** Override the generated id (e.g. when a caller pre-allocates one). */
+    nodeId?: string;
+}
+/** 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 declare function spawnNode(opts: SpawnNodeOpts): NodeMeta;

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;
+};