@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/core/runtime/close.js

@@ -30,8 +30,9 @@
 // to by the agent being closed", generalized to any depth via a fixpoint.
 import { getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
-import { tearDownNode } from './placement.js';
+import { hostFor } from './host.js';
 import { appendInbox } from '../feed/inbox.js';
+import { appendPassive } from '../feed/passive.js';
 /** The set of nodes to close: the root plus every descendant reachable down the
  *  subscriptions spine, all of whose managers are themselves in the set. Grown
  *  to a fixpoint — a node added this pass can qualify its own children next
@@ -128,11 +129,13 @@ export function closeNode(rootId) {
                 .filter((c) => closing.has(c));
             // 1) Canceled + intent cleared BEFORE the window dies (daemon race).
             transition(id, 'cancel');
-            // 2) Tear the node off its placement (pane-keyed): close any focus row it
-            //    occupies, kill its PANE (the window closes once its last pane goes, so
-            //    sibling nodes the user co-located in one window survive), and null its
-            //    LOCATION (closing the focus row is the record — no pointer to clear).
-            tearDownNode(id);
+            // 2) Tear the node's ENGINE down through the Host seam (hostFor): a tmux
+            //    node runs tearDownNode (close any focus row it occupies, kill its
+            //    PANE — the window closes once its last pane goes, so sibling nodes the
+            //    user co-located in one window survive — and null its LOCATION); a
+            //    broker node sends the `shutdown` frame so the broker PROCESS exits and
+            //    releases the sole .jsonl writer (a paneless node has no pane to kill).
+            hostFor(m).teardown(id);
             // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
             appendInbox(id, {
                 from: null,
@@ -141,6 +144,32 @@ export function closeNode(rootId) {
                 label: cancellationLabel(id === rootId, deadChildren),
                 data: { reason: 'user-close', cascade_root: rootId, canceled_children: deadChildren },
             });
+            // 4) Wake any SURVIVING manager subscribed to this node — the doctrine wake.
+            //    A node going dormant trusts the runtime to wake it on a child's
+            //    terminal outcome; D-1 found that `node close` notified ONLY the closed
+            //    node itself, never its subscribers, so a parent that delegated then
+            //    just stopped hangs forever when its child is closed out from under it.
+            //    Only the close ROOT can have a surviving subscriber (closingSet adds a
+            //    non-root node only when EVERY subscriber is itself closing), so this
+            //    reaches the still-living manager(s) of a deliberately-closed child and
+            //    never fires inside a self-contained cascade. Active → inbox (wakes a
+            //    dormant manager via its live watcher / the daemon's dormant-revive
+            //    second pass); passive → passive accumulator (delivered, not woken).
+            for (const sub of subscribersOf(id)) {
+                if (closing.has(sub.node_id))
+                    continue; // also being torn down — pointless
+                const notice = {
+                    from: id,
+                    tier: 'normal',
+                    kind: 'message',
+                    label: `Child closed — ${m.name} (${id}) was closed from the canvas and is no longer running.`,
+                    data: { reason: 'child-closed', child: id },
+                };
+                if (sub.active)
+                    appendInbox(sub.node_id, notice);
+                else
+                    appendPassive(sub.node_id, notice);
+            }
             closed.push(id);
         }
         catch {

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

@@ -0,0 +1,53 @@
+import { type NodeMeta, type NodeRow } from '../canvas/index.js';
+import type { PiInvocation } from './launch.js';
+/** View-side launch hints the legacy host needs beyond the PiInvocation. This is
+ *  today's ReviveLaunch (placement.ts) MINUS `command`/`env` — the host derives
+ *  `command = piCommand(inv.argv)` and `env = inv.env` from the PiInvocation
+ *  itself. The broker (Phase 3) uses only `cwd` + `resuming`. */
+export interface LaunchPlacement {
+    cwd: string;
+    name: string;
+    resuming: boolean;
+}
+/** A handle to a node's running engine container.
+ *  §3.2 specifies { kind, pid }; Phase 1 carries the placement coords too,
+ *  because launch REPLACES reviveIntoPlacement (which returned PlacementResult)
+ *  and reviveNode's unchanged ReviveResult is built from window+session. The
+ *  daemon never reads window/session/pane (it supervises via pid / isAlive); the
+ *  broker (Phase 3) returns window=null, pane=null. */
+export interface HostHandle {
+    kind: 'tmux' | 'broker';
+    /** Supervised pid (signal-0 target). null at launch for TmuxPaneHost: the
+     *  pane's fresh pi records its own pid via the stophook (session_start →
+     *  recordPid), and reviveNode clearPid()s right after launch — so no Phase-1
+     *  caller reads this. Present for the §3.2 contract + the daemon. */
+    pid: number | null;
+    window: string | null;
+    session: string;
+    pane: string | null;
+}
+export interface Host {
+    /** Bring a node's ENGINE into existence from its launch recipe; return a
+     *  supervisable handle. TmuxPaneHost ALSO performs placement (the pane IS the
+     *  engine container). */
+    launch(nodeId: string, inv: PiInvocation, opts: LaunchPlacement): HostHandle;
+    /** Is this node's engine container present? PURE / non-mutating. §3.2 types
+     *  this `NodeRow`; we keep `string | NodeRow` to match isNodePaneAlive (which
+     *  it IS) so both call sites — the guard (passes the id) and the Phase-2 daemon
+     *  (passes a row) — stay one-token changes. */
+    isAlive(node: string | NodeRow): boolean;
+    /** Tear the engine down (close/cancel teardown). */
+    teardown(nodeId: string): void;
+    /** Deliver an OS signal to the engine container — present so the daemon never
+     *  reaches around the abstraction. No Phase-1 call site. */
+    signal(nodeId: string, sig: NodeJS.Signals): void;
+}
+/** The sole Phase-1 host: today's behavior, wrapped. Stateless → a frozen
+ *  singleton, no class needed. Every method delegates verbatim. */
+export declare const tmuxPaneHost: Host;
+export declare const headlessBrokerHost: Host;
+/** Select the Host for a node by its persisted `host_kind` (NULL/'tmux' → the
+ *  tmux host; 'broker' → the headless broker host). The param is `NodeMeta |
+ *  NodeRow` so both call sites — reviveNode `hostFor(meta)` and the daemon
+ *  `hostFor(row)` — share one selector. */
+export declare function hostFor(node: NodeMeta | NodeRow): Host;

package/dist/core/runtime/host.js

@@ -0,0 +1,186 @@
+// src/core/runtime/host.ts
+//
+// The Host abstraction (design §3): owns an engine PROCESS's lifecycle, not its
+// display. TWO impls live here: TmuxPaneHost — a thin wrapper over today's
+// placement functions (the pane IS the engine container) — and, since Phase 3,
+// HeadlessBrokerHost — a detached broker process with no tmux pane. `host_kind`
+// (on the node row/meta since Wave 1) selects between them via hostFor().
+//
+// IMPORT-LINT (tmux-surface.test.ts §5.1): this file must NOT import './tmux.js'
+// directly. It reaches every driver verb (piCommand, reviveIntoPlacement,
+// isNodePaneAlive, tearDownNode) through placement.ts's re-exports — placement.ts
+// and tmux-chrome.ts are the only sanctioned tmux.ts importers. The broker host
+// needs no tmux verb at all.
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { connect } from 'node:net';
+import { reviveIntoPlacement, isNodePaneAlive, tearDownNode, piCommand, } from './placement.js';
+import { getNode } from '../canvas/index.js';
+import { nodeDir, jobDir } from '../canvas/paths.js';
+import { encodeFrame } from './broker-protocol.js';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { isPidAlive } from '../canvas/pid.js';
+/** The sole Phase-1 host: today's behavior, wrapped. Stateless → a frozen
+ *  singleton, no class needed. Every method delegates verbatim. */
+export const tmuxPaneHost = {
+    launch(nodeId, inv, opts) {
+        const placed = reviveIntoPlacement(nodeId, {
+            command: piCommand(inv.argv),
+            env: inv.env,
+            cwd: opts.cwd,
+            name: opts.name,
+            resuming: opts.resuming,
+        });
+        return { kind: 'tmux', pid: null, window: placed.window, session: placed.session, pane: placed.pane };
+    },
+    isAlive(node) {
+        return isNodePaneAlive(node);
+    },
+    teardown(nodeId) {
+        tearDownNode(nodeId);
+    },
+    signal(nodeId, sig) {
+        const pid = getNode(nodeId)?.pi_pid;
+        if (pid != null) {
+            try {
+                process.kill(pid, sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// HeadlessBrokerHost (design §3.3): a detached broker PROCESS, no tmux pane. It
+// boots the dedicated broker-cli entry directly (NEVER src/cli.ts), supervises
+// via the broker pid recorded as pi_pid, and tears down over the node's unix
+// socket (graceful `shutdown` frame, SIGTERM fallback).
+// ---------------------------------------------------------------------------
+/** Resolve the absolute path to the broker entry. At runtime this file is
+ *  dist/core/runtime/host.js; the entry lives at dist/core/runtime/broker-cli.js
+ *  (sibling in the same directory) — the manage.ts/resolveCrtrdEntry pattern. */
+function resolveBrokerEntry() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, 'broker-cli.js');
+}
+/** How long teardown waits after sending the graceful `shutdown` frame before
+ *  SIGTERMing a broker that connected but never exited (e.g. a hung dispose()). */
+const BROKER_SHUTDOWN_GRACE_MS = 2_000;
+export const headlessBrokerHost = {
+    launch(nodeId, inv, opts) {
+        const dir = nodeDir(nodeId);
+        mkdirSync(dir, { recursive: true });
+        // The broker reads this recipe back via runBroker(nodeId) → broker-launch.json.
+        writeFileSync(join(dir, 'broker-launch.json'), JSON.stringify(inv));
+        // Redirect the detached broker's stdout+stderr to a per-node log under the
+        // node's existing job/ dir (alongside log.jsonl / telemetry.json). Without
+        // this (stdio:'ignore') EVERY broker diagnostic — the version-skew warning,
+        // model-not-found, socket errors, first-prompt failure, and broker-cli's
+        // fatal-crash stack — goes to /dev/null, which is exactly what makes a boot
+        // failure invisible (review M-2). Append-mode so a crash-revive keeps history.
+        const logDir = jobDir(nodeId);
+        mkdirSync(logDir, { recursive: true });
+        const logFd = openSync(join(logDir, 'broker.log'), 'a');
+        const child = spawn(process.execPath, [resolveBrokerEntry(), nodeId], {
+            cwd: opts.cwd,
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env: { ...process.env, ...inv.env, [FRONT_DOOR_ENV]: '1' },
+        });
+        // The child holds its own dup of the fd; release the parent's copy so the
+        // launching process (CLI or daemon) never leaks it.
+        closeSync(logFd);
+        child.unref();
+        return { kind: 'broker', pid: child.pid ?? null, window: null, session: '', pane: null };
+    },
+    isAlive(node) {
+        return isPidAlive((typeof node === 'string' ? getNode(node) : node)?.pi_pid);
+    },
+    teardown(nodeId) {
+        // Graceful: connect to view.sock + send a `shutdown` frame → the broker
+        // dispose()s the engine, unlinks the socket, exits 0. Status is already
+        // flipped done/canceled by the caller (crash-safe ordering), so the daemon
+        // won't revive. On connect failure (broker dead/crashed) fall back to a
+        // SIGTERM of the broker pid + unlink the stale socket.
+        const sockPath = join(nodeDir(nodeId), 'view.sock');
+        const cleanupSocket = () => {
+            try {
+                if (existsSync(sockPath))
+                    unlinkSync(sockPath);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        };
+        const sock = connect(sockPath);
+        let connected = false;
+        sock.on('error', () => {
+            // A post-connect error (broker exiting after we sent shutdown) is benign
+            // and swallowed; only a connect failure triggers the SIGTERM fallback.
+            if (connected)
+                return;
+            const pid = getNode(nodeId)?.pi_pid;
+            if (pid != null) {
+                try {
+                    process.kill(pid, 'SIGTERM');
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            cleanupSocket();
+        });
+        sock.once('connect', () => {
+            connected = true;
+            try {
+                sock.write(encodeFrame({ type: 'shutdown' }));
+            }
+            catch {
+                /* the broker may have raced us to exit */
+            }
+            sock.end();
+            cleanupSocket();
+            // Bounded exit confirmation (review Mn-3): a broker that connects fine but
+            // then HANGS inside session.dispose() (disposeAndExit catches a throw, not
+            // a hang) would leak the process holding the sole .jsonl writer. Arm a
+            // short UNREF'd timer; if the captured pid is still alive when it fires,
+            // SIGTERM it. unref'd so the happy path adds NO latency — a short-lived CLI
+            // caller's loop is kept alive only by the still-open socket, i.e. precisely
+            // the hung case where the fallback must run.
+            const pid = getNode(nodeId)?.pi_pid;
+            if (pid != null) {
+                setTimeout(() => {
+                    if (isPidAlive(pid)) {
+                        try {
+                            process.kill(pid, 'SIGTERM');
+                        }
+                        catch {
+                            /* already gone */
+                        }
+                    }
+                }, BROKER_SHUTDOWN_GRACE_MS).unref();
+            }
+        });
+    },
+    signal(nodeId, sig) {
+        const pid = getNode(nodeId)?.pi_pid;
+        if (pid != null) {
+            try {
+                process.kill(pid, sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    },
+};
+/** Select the Host for a node by its persisted `host_kind` (NULL/'tmux' → the
+ *  tmux host; 'broker' → the headless broker host). The param is `NodeMeta |
+ *  NodeRow` so both call sites — reviveNode `hostFor(meta)` and the daemon
+ *  `hostFor(row)` — share one selector. */
+export function hostFor(node) {
+    return node.host_kind === 'broker' ? headlessBrokerHost : tmuxPaneHost;
+}

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

@@ -1,4 +1,5 @@
 import { type NodeMeta } from '../canvas/index.js';
+import { type WakeOrigin } from './bearings.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;
@@ -46,4 +47,4 @@ export declare function drainBearings(meta: NodeMeta): ReviveBearings;
  *  node's goal, roadmap, and context dir, framed so the revived node can rebuild
  *  its bearings in one turn. PURE: no state mutation, so calling it twice yields
  *  the same string and consumes nothing — drainBearings owns the one-shot reads. */
-export declare function buildReviveKickoff(meta: NodeMeta, bearings: ReviveBearings): string;
+export declare function buildReviveKickoff(meta: NodeMeta, bearings: ReviveBearings, wakeReason?: WakeOrigin): string;

package/dist/core/runtime/kickoff.js

@@ -19,8 +19,10 @@
 // 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, subscribersOf, } from '../canvas/index.js';
+import { homedir } from 'node:os';
+import { contextDir, reportsDir, getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
+import { buildWakeBearings } from './bearings.js';
 import { personaDrift, commitPersonaAck } from './persona.js';
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../feed/inbox.js';
 // ---------------------------------------------------------------------------
@@ -126,8 +128,60 @@ export function drainBearings(meta) {
     }
     return { yieldMsg, unreadDigest, driftGuidance };
 }
-/** Render the <feed> block PURELY: the live "awaiting" roster (a read) plus the
- *  already-drained unread digest (from drainBearings). No cursor write here. */
+// Fresh-revive catch-up bug: on a refresh-yield (resume:false) the old
+// conversation is gone AND the monotonic inbox cursor has already advanced past
+// everything drained pre-yield, so the revived node loses sight of reports its
+// subscriptions pushed BEFORE the yield. The bodies are never lost — they persist
+// at reports/<ts>-<kind>.md forever — but nothing pointed the revived node at
+// them. reportHistoryLines renders those existing on-disk paths so it can catch
+// up; PATHS ONLY (the node dereferences what it needs), no body read, no parse.
+const REPORT_HISTORY_PER_SOURCE = 5;
+const REPORT_HISTORY_TOTAL_CAP = 20;
+/** Collapse the home-dir prefix of an absolute path to a leading `~`, so report
+ *  paths render as `~/.crouter/canvas/nodes/<id>/reports/<ts>.md` instead of
+ *  repeating the long absolute home prefix on every catch-up line — cheaper
+ *  context, still dereferenceable by the revived node. A path NOT under the home
+ *  dir (e.g. a CRTR_HOME / project-scope home elsewhere) is returned unchanged,
+ *  so we never mangle a non-home path. */
+function tildify(p) {
+    const home = homedir();
+    return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+/** Recent report file PATHS (most-recent-first), grouped by publisher, for each
+ *  ACTIVE subscription of `nodeId` — independent of publisher liveness, so a
+ *  finished worker's history still surfaces for catch-up. Skips subscriptions
+ *  whose reports dir is empty/missing. Returns [] when the node has no active
+ *  subscriptions or none have reports yet (caller renders nothing extra). */
+function reportHistoryLines(nodeId) {
+    const lines = [];
+    let total = 0;
+    for (const sub of subscriptionsOf(nodeId).filter((s) => s.active)) {
+        if (total >= REPORT_HISTORY_TOTAL_CAP)
+            break;
+        const dir = reportsDir(sub.node_id);
+        if (!existsSync(dir))
+            continue;
+        const files = readdirSync(dir)
+            .filter((f) => f.endsWith('.md'))
+            .sort() // YYYYMMDDTHHmmss-<kind>.md — lexical sort = chronological
+            .reverse() // most recent first
+            .slice(0, REPORT_HISTORY_PER_SOURCE);
+        if (files.length === 0)
+            continue;
+        const pub = getNode(sub.node_id);
+        lines.push(`  ${pub !== null ? `${pub.name} (${sub.node_id})` : sub.node_id}:`);
+        for (const f of files) {
+            if (total >= REPORT_HISTORY_TOTAL_CAP)
+                break;
+            lines.push(`    ${tildify(join(dir, f))}`);
+            total++;
+        }
+    }
+    return lines;
+}
+/** Render the <feed> block PURELY: the live "awaiting" roster (a read), the
+ *  already-drained unread digest (from drainBearings), and the on-disk report
+ *  history of this node's subscriptions (catch-up pointers). No cursor write. */
 function feedBlock(nodeId, unreadDigest) {
     // Awaiting = active subscriptions whose publisher is still live (active|idle).
     const awaiting = subscriptionsOf(nodeId)
@@ -154,6 +208,17 @@ function feedBlock(nodeId, unreadDigest) {
         lines.push('Awaiting 0 nodes.');
         lines.push('', unreadDigest ?? '(no unread reports)');
     }
+    // Catch-up history. The unread digest above only covers what arrived since the
+    // cursor; on a refresh-revive the cursor has already passed everything drained
+    // pre-yield, so point the node at the durable report history that persists on
+    // disk. Renders nothing when the node has no active subscriptions with reports.
+    const history = reportHistoryLines(nodeId);
+    if (history.length > 0) {
+        lines.push('', 'Report history on disk — the nodes you subscribe to keep every push they made; ' +
+            'these persist across your context refresh (the unread digest above only covers ' +
+            'what arrived since your cursor). Most recent first; dereference any you need. ' +
+            '`crtr feed read --all` replays the full inbox history, cursor-independent.', ...history);
+    }
     return `<feed>\n${lines.join('\n')}\n</feed>`;
 }
 // ---------------------------------------------------------------------------
@@ -164,19 +229,40 @@ function feedBlock(nodeId, unreadDigest) {
  *  node's goal, roadmap, and context dir, framed so the revived node can rebuild
  *  its bearings in one turn. PURE: no state mutation, so calling it twice yields
  *  the same string and consumes nothing — drainBearings owns the one-shot reads. */
-export function buildReviveKickoff(meta, bearings) {
+export function buildReviveKickoff(meta, bearings, wakeReason) {
     const nodeId = meta.node_id;
     const parts = [
         `${REVIVE_KICKOFF_SENTINEL} — 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.',
     ];
+    // Wake provenance (Invariant B/D): when a scheduled bare self-alarm fired this
+    // revive, the <crtr-wake> block reframes the generic "you were revived" above
+    // into "a TIMER woke you" — placed right after the sentinel (so the kickoff
+    // still STARTS with REVIVE_KICKOFF_SENTINEL, which goal-capture keys on) and
+    // before the roadmap/disk bearings, so "why you woke" precedes "what to rebuild
+    // from". Only the daemon's bare-wake branch passes wakeReason.
+    if (wakeReason !== undefined)
+        parts.push(buildWakeBearings(wakeReason));
     // The roadmap is the source of truth on a fresh revive: its frozen core holds
     // the goal/exit criteria, its body the live plan the node kept current. The
     // original spawn prompt (context/initial-prompt.md) is deliberately NOT injected
     // — it lives on disk only as a log, and by now it is usually stale.
     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 hasRoadmapBody = roadmap !== null && roadmap.trim() !== '';
+    parts.push(`<roadmap file="${roadmapPath(nodeId)}">\n${hasRoadmapBody ? roadmap.trim() : '(no roadmap on disk yet)'}\n</roadmap>`);
+    // With NO roadmap the kickoff above carries no mandate at all, and an
+    // amnesiac fresh boot just stops (and is auto-finalized by the stop-guard) —
+    // observed when the daemon relaunches a spawned-but-never-launched node
+    // (audit 2026-06-09, Bug 4: mq45b6ch-9ecc2f03), whose only mandate on disk IS
+    // the goal. Surface the goal then. When a roadmap exists it stays the sole
+    // source of truth (the goal is usually stale by comparison) — unchanged.
+    if (!hasRoadmapBody) {
+        const goal = readGoal(nodeId);
+        if (goal !== null && goal.trim() !== '') {
+            parts.push(`<goal file="${goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);
+        }
+    }
     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, bearings.unreadDigest));

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

@@ -5,15 +5,20 @@ export declare const CANVAS_NAV_PATH: string;
 export declare const CANVAS_GOAL_CAPTURE_PATH: string;
 export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
 export declare const CANVAS_CONTEXT_INTRO_PATH: string;
+export declare const CANVAS_DOC_SUBSTRATE_PATH: string;
 export declare const CANVAS_COMMANDS_PATH: string;
 export declare const CANVAS_RESUME_PATH: string;
+export declare const CANVAS_VIEW_PATH: string;
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), goal-capture (persist the first user message as the goal),
  *  passive-context (drain passive backlog as pre-text on the next message),
  *  context-intro (inject the <crtr-context> bearings block as its own session
- *  message, once per brand-new chat), commands (the /promote slash-command),
- *  resume (the /resume-node whole-canvas picker → `crtr node focus`).
+ *  message, once per brand-new chat), doc-substrate (the unified document
+ *  substrate's two hooks: ## Skills + ## Preferences at boot, on-read context
+ *  injection), commands (the /promote slash-command), resume (the /resume-node
+ *  whole-canvas picker → `crtr node focus`), view (the /view popup → `crtr
+ *  view pick` / `crtr view run <name>`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export declare const CANVAS_EXTENSIONS: string[];
@@ -57,3 +62,41 @@ export declare function buildPiArgv(meta: NodeMeta, opts?: {
     resumeSessionPath?: string;
     forkFrom?: string;
 }): PiInvocation;
+/** The pi-SDK launch config the headless broker drives an in-process engine
+ *  with — the structural inverse of `buildPiArgv`'s flag vocabulary. Each field
+ *  maps one of buildPiArgv's emitted flags back to its SDK option:
+ *  `-e`→`extensionPaths`, `-n`→`editorName`, `--fork`→`forkFrom`,
+ *  `--session`→`resumeSessionPath|resumeSessionId`, `--model`→`model`,
+ *  `--tools`→`tools`, `--append-system-prompt`→`appendSystemPromptPath`, the
+ *  trailing positional→`firstPrompt`. */
+export interface BrokerSdkConfig {
+    /** The node's pinned working dir (from `CRTR_NODE_CWD`, else `process.cwd()`). */
+    cwd: string;
+    /** Absolute `.js` extension paths (the canvas extensions). */
+    extensionPaths: string[];
+    /** Session label (`-n`). */
+    editorName?: string;
+    /** Spawn-time fork source (`--fork <path|id>`). */
+    forkFrom?: string;
+    /** Resume by absolute `.jsonl` path (preferred — `SessionManager.open`). */
+    resumeSessionPath?: string;
+    /** Resume by bare session uuid (legacy fallback). */
+    resumeSessionId?: string;
+    /** Model spec, e.g. `anthropic/sonnet` (`--model`). */
+    model?: string;
+    /** Tool allowlist (`--tools a,b,c` → `['a','b','c']`). */
+    tools?: string[];
+    /** `--append-system-prompt` arg — a file path in practice (pi's loader
+     *  resolves a path or literal text identically). */
+    appendSystemPromptPath?: string;
+    /** The fresh-start kickoff message (the trailing positional). */
+    firstPrompt?: string;
+}
+/** Translate a `PiInvocation` (the recipe `buildPiArgv` produced) into the SDK
+ *  config the broker hosts an engine with. This is the EXACT inverse of
+ *  `buildPiArgv` and must track its flag set 1:1 — co-located here so the two
+ *  never drift. Safe because `buildPiArgv` is the SOLE producer of these flags
+ *  (we own both ends). SIDE EFFECT: merges `inv.env` into `process.env` so the
+ *  in-process engine + the bound canvas extensions see the same env a forked pi
+ *  would (CRTR_NODE_ID, CRTR_ROOT_SESSION, CRTR_SUBTREE, …). */
+export declare function piInvocationToSdkConfig(inv: PiInvocation): BrokerSdkConfig;

package/dist/core/runtime/launch.js

@@ -32,15 +32,20 @@ export const CANVAS_NAV_PATH = resolveExtension('canvas-nav');
 export const CANVAS_GOAL_CAPTURE_PATH = resolveExtension('canvas-goal-capture');
 export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-context');
 export const CANVAS_CONTEXT_INTRO_PATH = resolveExtension('canvas-context-intro');
+export const CANVAS_DOC_SUBSTRATE_PATH = resolveExtension('canvas-doc-substrate');
 export const CANVAS_COMMANDS_PATH = resolveExtension('canvas-commands');
 export const CANVAS_RESUME_PATH = resolveExtension('canvas-resume');
+export const CANVAS_VIEW_PATH = resolveExtension('canvas-view');
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), goal-capture (persist the first user message as the goal),
  *  passive-context (drain passive backlog as pre-text on the next message),
  *  context-intro (inject the <crtr-context> bearings block as its own session
- *  message, once per brand-new chat), commands (the /promote slash-command),
- *  resume (the /resume-node whole-canvas picker → `crtr node focus`).
+ *  message, once per brand-new chat), doc-substrate (the unified document
+ *  substrate's two hooks: ## Skills + ## Preferences at boot, on-read context
+ *  injection), commands (the /promote slash-command), resume (the /resume-node
+ *  whole-canvas picker → `crtr node focus`), view (the /view popup → `crtr
+ *  view pick` / `crtr view run <name>`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export const CANVAS_EXTENSIONS = [
@@ -50,8 +55,10 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_GOAL_CAPTURE_PATH,
     CANVAS_PASSIVE_CONTEXT_PATH,
     CANVAS_CONTEXT_INTRO_PATH,
+    CANVAS_DOC_SUBSTRATE_PATH,
     CANVAS_COMMANDS_PATH,
     CANVAS_RESUME_PATH,
+    CANVAS_VIEW_PATH,
 ];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */
@@ -158,3 +165,59 @@ export function buildPiArgv(meta, opts = {}) {
         argv.push(opts.prompt);
     return { argv, env: nodeEnv(meta) };
 }
+/** Translate a `PiInvocation` (the recipe `buildPiArgv` produced) into the SDK
+ *  config the broker hosts an engine with. This is the EXACT inverse of
+ *  `buildPiArgv` and must track its flag set 1:1 — co-located here so the two
+ *  never drift. Safe because `buildPiArgv` is the SOLE producer of these flags
+ *  (we own both ends). SIDE EFFECT: merges `inv.env` into `process.env` so the
+ *  in-process engine + the bound canvas extensions see the same env a forked pi
+ *  would (CRTR_NODE_ID, CRTR_ROOT_SESSION, CRTR_SUBTREE, …). */
+export function piInvocationToSdkConfig(inv) {
+    for (const [k, v] of Object.entries(inv.env))
+        process.env[k] = v;
+    const cfg = {
+        cwd: inv.env['CRTR_NODE_CWD'] ?? process.cwd(),
+        extensionPaths: [],
+    };
+    const argv = inv.argv;
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        switch (tok) {
+            case '-e':
+                cfg.extensionPaths.push(argv[++i]);
+                break;
+            case '-n':
+                cfg.editorName = argv[++i];
+                break;
+            case '--fork':
+                cfg.forkFrom = argv[++i];
+                break;
+            case '--session': {
+                const v = argv[++i];
+                // A path (contains `/` or ends `.jsonl`) resumes via SessionManager.open;
+                // a bare uuid is the legacy fallback. Same classification buildPiArgv
+                // documents (path preferred, immune to cwd discrepancy).
+                if (v.includes('/') || v.endsWith('.jsonl'))
+                    cfg.resumeSessionPath = v;
+                else
+                    cfg.resumeSessionId = v;
+                break;
+            }
+            case '--model':
+                cfg.model = argv[++i];
+                break;
+            case '--tools':
+                cfg.tools = argv[++i].split(',').filter((t) => t !== '');
+                break;
+            case '--append-system-prompt':
+                cfg.appendSystemPromptPath = argv[++i];
+                break;
+            default:
+                // buildPiArgv consumes every flag's value via the cases above, so any
+                // token reaching here is the single trailing positional (the prompt).
+                cfg.firstPrompt = tok;
+                break;
+        }
+    }
+    return cfg;
+}