@crouton-kit/crouter 0.3.12 → 0.3.14

package/dist/core/runtime/promote.js

@@ -19,7 +19,8 @@ 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';
+import { hasRoadmap, seedRoadmap, readRoadmap, roadmapPath } from './roadmap.js';
+import { readGoal, goalPath } from './kickoff.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) {
@@ -43,16 +44,21 @@ function orchestrationGuidance(nodeId, kind) {
         : undefined;
     const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
+    const rmPath = roadmapPath(nodeId);
+    const goal = readGoal(nodeId);
     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 (goal !== null && goal.trim() !== '') {
+        parts.push('', `--- Your goal (${goalPath(nodeId)}) ---`, '', goal.trim());
+    }
     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.');
+    parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', 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
@@ -71,15 +77,24 @@ export function promote(nodeId, opts = {}) {
     // 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.
+    // Seed a barebones roadmap scaffold if absent so the file exists for a
+    // refresh. Pre-fill its Goal from the node's goal doc when present (set at
+    // spawn, or captured from the first user message); the node fleshes out the
+    // body next, guided by the kind skill dumped below.
     let roadmapWritten = false;
     if (!hasRoadmap(nodeId)) {
-        seedRoadmap(nodeId);
+        const goal = readGoal(nodeId);
+        seedRoadmap(nodeId, goal !== null && goal.trim() !== '' ? { goal: goal.trim() } : {});
         roadmapWritten = true;
     }
     const meta = updateNode(nodeId, { kind: targetKind, lifecycle: 'resident', mode: 'orchestrator', launch });
-    return { meta, guidance: orchestrationGuidance(nodeId, targetKind), roadmapWritten };
+    return {
+        meta,
+        guidance: orchestrationGuidance(nodeId, targetKind),
+        roadmapWritten,
+        roadmapPath: roadmapPath(nodeId),
+        goalPath: goalPath(nodeId),
+    };
 }
 /** Request a refresh-yield: discard in-memory context and revive fresh against
  *  the roadmap. A *terminal* node that yields is choosing to persist — it

package/dist/core/runtime/revive.js

@@ -11,8 +11,7 @@
 import { getNode, updateNode, } from '../canvas/index.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, respawnPane, } from './tmux.js';
-import { rootSessionName } from './spawn.js';
+import { ensureSession, openNodeWindow, piCommand, respawnPane, nodeSession, } from './tmux.js';
 // ---------------------------------------------------------------------------
 // reviveNode
 // ---------------------------------------------------------------------------
@@ -26,10 +25,10 @@ export function reviveNode(nodeId, opts) {
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
     }
-    // The node lives in its root's tmux session. Prefer the stored session name;
-    // fall back to deriving it from the parent (or the node itself for roots).
-    const session = meta.tmux_session ??
-        rootSessionName((meta.parent ?? meta.node_id));
+    // 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
@@ -73,8 +72,7 @@ export function reviveInPlace(nodeId, pane) {
     if (meta === null) {
         throw new Error(`reviveInPlace: unknown node ${nodeId}`);
     }
-    const session = meta.tmux_session ??
-        rootSessionName((meta.parent ?? meta.node_id));
+    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) });

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

@@ -1,10 +1,11 @@
 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 —
+/** Seed a fresh, EXTREMELY BAREBONES roadmap scaffold — just the section
+ *  skeleton with one-line prompts. Promotion lays this down so the file exists
+ *  for a refresh; the owner fleshes it out as its next act (guided by its
+ *  kind's roadmap skill). `goal`/`exitCriteria` pre-fill those sections when
+ *  known (e.g. from the node's goal doc). Idempotent only if you intend it —
  *  call sites guard on hasRoadmap to avoid clobbering an evolved map. */
 export declare function seedRoadmap(nodeId: string, opts?: {
     goal?: string;

package/dist/core/runtime/roadmap.js

@@ -20,32 +20,25 @@ 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 —
+/** Seed a fresh, EXTREMELY BAREBONES roadmap scaffold — just the section
+ *  skeleton with one-line prompts. Promotion lays this down so the file exists
+ *  for a refresh; the owner fleshes it out as its next act (guided by its
+ *  kind's roadmap skill). `goal`/`exitCriteria` pre-fill those sections when
+ *  known (e.g. from the node's goal doc). Idempotent only if you intend it —
  *  call sites guard on hasRoadmap to avoid clobbering an evolved map. */
 export function seedRoadmap(nodeId, opts = {}) {
     const dir = contextDir(nodeId);
     mkdirSync(dir, { recursive: true });
     const body = `# Roadmap
 
-<!-- frozen core: set once, rarely changes -->
 ## Goal
-${opts.goal?.trim() ?? '- (state the high-level goal you now own — write this as your first act)'}
+${opts.goal?.trim() ?? '(the goal you now own)'}
 
 ## Exit criteria
-${opts.exitCriteria?.trim() ?? '- (define what "done" looks like)'}
+${opts.exitCriteria?.trim() ?? '(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)
+## Phases
+(ordered phases from here to done; the current one carries a one-line status)
 `;
     writeFileSync(roadmapPath(nodeId), body);
     return body;

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

@@ -1,6 +1,4 @@
 import { type NodeMeta, type Mode } from '../canvas/index.js';
-/** A root's tmux session name — its home; every descendant is a window in it. */
-export declare function rootSessionName(rootId: string): string;
 export interface BootRootOpts {
     cwd: string;
     kind?: string;

package/dist/core/runtime/spawn.js

@@ -11,13 +11,9 @@ import { FRONT_DOOR_ENV } from './front-door.js';
 import { spawnNode, currentNodeContext } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, } from './tmux.js';
+import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, installMenuBinding, installNavBindings, } from './tmux.js';
 import { updateNode, getNode } from '../canvas/index.js';
 import { ensureDaemon } from '../../daemon/manage.js';
-/** A root's tmux session name — its home; every descendant is a window in it. */
-export function rootSessionName(rootId) {
-    return `crtr-${rootId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 12)}`;
-}
 /** 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 function bootRoot(opts) {
@@ -44,9 +40,22 @@ export function bootRoot(opts) {
     // mandate (bare `crtr` has none — writeGoal no-ops on empty).
     if (opts.prompt !== undefined)
         writeGoal(meta.node_id, opts.prompt);
-    const session = rootSessionName(meta.node_id);
+    // Every node window — root or child — lives in the one shared session.
+    const session = nodeSession();
+    ensureSession(session, opts.cwd);
+    // Make the Alt+C action menu + Alt+] / Alt+[ nav keys live on this server
+    // (idempotent, in-tmux only).
+    if (inTmux()) {
+        try {
+            installMenuBinding();
+        }
+        catch { /* best-effort */ }
+        try {
+            installNavBindings();
+        }
+        catch { /* best-effort */ }
+    }
     if (opts.placement === 'session') {
-        ensureSession(session, opts.cwd);
         updateNode(meta.node_id, { tmux_session: session });
         const withSession = getNode(meta.node_id);
         const inv = buildPiArgv(withSession, { prompt: opts.prompt });
@@ -61,14 +70,16 @@ export function bootRoot(opts) {
         updateNode(meta.node_id, { window: win });
         return getNode(meta.node_id);
     }
-    // inline: the root adopts the current tmux session (if any) as its home, so
-    // children spawn as windows alongside it. Then exec pi in this terminal.
+    // inline: the root's pi takes over THIS terminal, so its own window stays
+    // where the user is (its tmux_session tracks that real pane so supervision
+    // sees it alive). But its children spawn into the shared global session via
+    // CRTR_ROOT_SESSION — they never clutter the user's working session.
     const here = currentTmux();
     const adopted = here?.session ?? session;
     updateNode(meta.node_id, { tmux_session: adopted, window: here?.window ?? null });
     const withSession = getNode(meta.node_id);
     const inv = buildPiArgv(withSession, { prompt: opts.prompt });
-    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: adopted, [FRONT_DOOR_ENV]: '1' };
+    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
     const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
     process.exit(r.status ?? 0);
 }
@@ -97,13 +108,12 @@ export function spawnChild(opts) {
     });
     // Persist the task as the child's goal for a fresh revive to re-read.
     writeGoal(meta.node_id, opts.prompt);
-    // Resolve the root session: inherited from env, else derive + create one.
+    // Children always land in the shared global session: inherited from the
+    // parent's CRTR_ROOT_SESSION, else the default node session.
     let session = process.env['CRTR_ROOT_SESSION'];
-    if (session === undefined || session === '') {
-        const here = inTmux() ? currentTmux() : null;
-        session = here?.session ?? rootSessionName(parent);
-        ensureSession(session, opts.cwd);
-    }
+    if (session === undefined || session === '')
+        session = nodeSession();
+    ensureSession(session, opts.cwd);
     const inv = buildPiArgv(meta, { prompt: opts.prompt });
     const env = { ...inv.env, CRTR_ROOT_SESSION: session };
     const window = openNodeWindow({

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

@@ -1,6 +1,11 @@
 /** POSIX single-quote escaping for one shell word. */
 export declare function shellQuote(s: string): string;
 export declare function inTmux(): boolean;
+/** The single, shared tmux session that ALL canvas node windows live in.
+ *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
+ *  child opens a window here rather than cluttering the user's own working
+ *  session — switch to it to browse the whole live graph, ignore it otherwise. */
+export declare function nodeSession(): string;
 export interface TmuxLocation {
     session: string;
     window: string;
@@ -46,6 +51,12 @@ export declare function paneOfWindow(session: string, window: string): string |
  *  are not, so the node→window mapping must be re-derived from the pane. Returns
  *  null if the pane is gone or tmux fails. */
 export declare function windowOfPane(pane: string): string | null;
+/** The session + window a pane currently lives in. Used by demote to place the
+ *  recycled root's meta on the pane it respawns into. Null if tmux fails. */
+export declare function paneLocation(pane: string): {
+    session: string;
+    window: string;
+} | null;
 /** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
  *  caller's window active, so the target's pane appears where the caller is
  *  rather than navigating the client off to the target's window. The caller's
@@ -86,3 +97,10 @@ export declare function selectWindow(session: string, window: string): boolean;
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
 export declare function switchClient(session: string): boolean;
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+export declare function installMenuBinding(): boolean;
+/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
+ *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
+ *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
+ */
+export declare function installNavBindings(): boolean;

package/dist/core/runtime/tmux.js

@@ -26,6 +26,14 @@ function tmux(args) {
 export function inTmux() {
     return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
 }
+/** The single, shared tmux session that ALL canvas node windows live in.
+ *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
+ *  child opens a window here rather than cluttering the user's own working
+ *  session — switch to it to browse the whole live graph, ignore it otherwise. */
+export function nodeSession() {
+    const v = process.env['CRTR_NODE_SESSION'];
+    return v !== undefined && v !== '' ? v : 'crtr';
+}
 /** Where the caller currently is, or null if not inside tmux. */
 export function currentTmux() {
     if (!inTmux())
@@ -118,6 +126,17 @@ export function windowOfPane(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{window_id}']);
     return r.ok && r.stdout !== '' ? r.stdout : null;
 }
+/** The session + window a pane currently lives in. Used by demote to place the
+ *  recycled root's meta on the pane it respawns into. Null if tmux fails. */
+export function paneLocation(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{session_name}\t#{window_id}']);
+    if (!r.ok)
+        return null;
+    const [session, window] = r.stdout.split('\t');
+    if (session === undefined || session === '' || window === undefined || window === '')
+        return null;
+    return { session, window };
+}
 /** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
  *  caller's window active, so the target's pane appears where the caller is
  *  rather than navigating the client off to the target's window. The caller's
@@ -196,3 +215,61 @@ export function selectWindow(session, window) {
 export function switchClient(session) {
     return tmux(['switch-client', '-t', session]).ok;
 }
+// ---------------------------------------------------------------------------
+// Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
+// actions. Installed on the running server at root boot; idempotent (a re-bind
+// overwrites the previous one). Items shell out to `crtr`, passing the active
+// pane so an action targets the agent currently in front of you.
+// ---------------------------------------------------------------------------
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+export function installMenuBinding() {
+    const sess = nodeSession();
+    const title = ' crtr ';
+    const items = [
+        // Promote types `/promote` into the agent's pane rather than shelling out:
+        // the slash command delivers the orchestration guidance into the node's
+        // context, which a bare `run-shell` (output discarded) could not.
+        { name: 'promote to orchestrator', key: 'o', cmd: `send-keys -t '#{pane_id}' '/promote' Enter` },
+        { name: 'finish agent + recycle pane', key: 'd', cmd: `run-shell "crtr node demote --pane '#{pane_id}'"` },
+        { name: 'browse background agents', key: 'g', cmd: `switch-client -t ${sess}` },
+    ];
+    // tmux's -x sets the menu's LEFT edge. To sit the box INSIDE the pane's
+    // top-right corner, shift x left by the box width (longest line + tmux chrome:
+    // borders + padding + the right-aligned mnemonic-key column) via format math.
+    const boxW = Math.max(title.length, ...items.map((i) => i.name.length)) + 6;
+    // Fine-tune nudges off the pane's top-right corner: a hair further left and
+    // one row down so the box doesn't kiss the pane border.
+    const nudgeX = 1; // extra columns left
+    const nudgeY = 3; // rows down
+    const args = [
+        'bind-key', '-n', 'M-c', 'display-menu',
+        '-T', `#[align=centre]${title}`,
+        '-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`,
+        '-y', `#{e|+:#{pane_top},${nudgeY}}`,
+    ];
+    for (const it of items)
+        args.push(it.name, it.key, it.cmd);
+    return tmux(args).ok;
+}
+// ---------------------------------------------------------------------------
+// Nav bindings — Alt+] / Alt+[ DFS-walk the canvas one window at a time. Each
+// key shells out to `crtr node cycle`, passing the active pane so the walk is
+// relative to the agent in front of you; cycle then swaps the next/prev node
+// into that pane (like `node focus`). Output is discarded so the keypress never
+// pops a results view. Installed at root boot alongside the Alt+C menu.
+// ---------------------------------------------------------------------------
+/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
+ *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
+ *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
+ */
+export function installNavBindings() {
+    const next = tmux([
+        'bind-key', '-n', 'M-]', 'run-shell',
+        `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    const prev = tmux([
+        'bind-key', '-n', 'M-[', 'run-shell',
+        `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    return next && prev;
+}

package/dist/pi-extensions/canvas-commands.d.ts

@@ -0,0 +1,34 @@
+interface AutocompleteItem {
+    value: string;
+    label?: string;
+}
+interface CommandUI {
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void;
+    setStatus(key: string, text: string | undefined): void;
+}
+interface CommandCtx {
+    ui: CommandUI;
+}
+interface CustomMessage {
+    customType: string;
+    content: string;
+    display?: boolean;
+}
+interface PiLike {
+    registerCommand(name: string, options: {
+        description?: string;
+        getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null;
+        handler: (args: string, ctx: CommandCtx) => Promise<void>;
+    }): void;
+    sendMessage(message: CustomMessage, options?: {
+        triggerTurn?: boolean;
+    }): void;
+}
+/**
+ * Register the canvas slash-commands on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasCommands(pi: PiLike): void;
+export default registerCanvasCommands;

package/dist/pi-extensions/canvas-commands.js

@@ -0,0 +1,100 @@
+// canvas-commands.ts — pi extension registering canvas slash-commands on nodes.
+//
+//   /promote [kind]  — promote THIS node to a resident orchestrator. Runs
+//     `crtr node promote --json` for CRTR_NODE_ID (optionally specializing its
+//     kind), then injects the orchestration guidance the command returns into
+//     context and triggers a turn, so the node authors its roadmap immediately.
+//     This is the same mid-turn guidance dump the node would get by running the
+//     command itself by hand — surfaced as a one-keystroke affordance.
+//
+// The Alt+C tmux action menu's "promote to orchestrator" item (key `o`) simply
+// send-keys `/promote` into the active pane, so the menu and the slash command
+// share this one implementation.
+//
+// INERT when CRTR_NODE_ID is absent (a plain pi session, not a canvas node).
+//
+// Plain TS-with-types — no imports from @earendil-works/* so this compiles
+// inside crouter's own tsc build without a dep on the pi packages (mirrors
+// canvas-nav.ts). The only crouter import is availableKinds, used to offer
+// `/promote <kind>` completions.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { availableKinds } from '../core/personas/index.js';
+const pexec = promisify(execFile);
+// Kinds for `/promote <kind>` completions — computed once (persona dirs rarely
+// change within a session), best-effort so a loader hiccup never breaks input.
+let cachedKinds = null;
+function kinds() {
+    if (cachedKinds === null) {
+        try {
+            cachedKinds = availableKinds();
+        }
+        catch {
+            cachedKinds = [];
+        }
+    }
+    return cachedKinds;
+}
+/**
+ * Register the canvas slash-commands on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export function registerCanvasCommands(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    pi.registerCommand('promote', {
+        description: 'Promote this node to a resident orchestrator — /promote, or /promote <kind> to specialize',
+        getArgumentCompletions: (prefix) => {
+            const items = kinds()
+                .filter((k) => k.startsWith(prefix))
+                .map((k) => ({ value: k, label: k }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const kind = args.trim().toLowerCase();
+            ctx.ui.setStatus('crtr-promote', kind ? `promoting → ${kind}…` : 'promoting…');
+            const argv = ['node', 'promote', '--json'];
+            if (kind !== '')
+                argv.push('--kind', kind);
+            // Run promote out-of-process. On a non-zero exit, crtr still prints the
+            // structured error to stdout, so prefer its `message` over the raw throw.
+            let result = null;
+            let errMsg = null;
+            try {
+                const { stdout } = await pexec('crtr', argv, { timeout: 15_000, maxBuffer: 4 * 1024 * 1024 });
+                result = JSON.parse(stdout);
+            }
+            catch (err) {
+                const e = err;
+                const stdout = typeof e.stdout === 'string' ? e.stdout : '';
+                try {
+                    const payload = JSON.parse(stdout);
+                    errMsg = typeof payload.message === 'string' ? payload.message : null;
+                }
+                catch {
+                    /* stdout wasn't JSON */
+                }
+                if (errMsg === null)
+                    errMsg = typeof e.message === 'string' ? e.message : String(err);
+            }
+            ctx.ui.setStatus('crtr-promote', '');
+            if (result === null) {
+                ctx.ui.notify(`promote failed: ${errMsg ?? 'unknown error'}`, 'error');
+                return;
+            }
+            const rmPath = (result.roadmap_path ?? '').trim();
+            ctx.ui.notify(`Promoted to ${result.kind ?? 'orchestrator'} orchestrator — authoring roadmap${rmPath !== '' ? ` (${rmPath})` : ''}.`, 'info');
+            // The guidance is operating instructions for the node, not the user.
+            // Inject it silently and trigger a turn so the node acts on it now —
+            // exactly what happens when the node runs `crtr node promote` by hand.
+            const guidance = (result.guidance ?? '').trim();
+            if (guidance === '')
+                return;
+            pi.sendMessage({ customType: 'crtr-promote', content: guidance, display: false }, { triggerTurn: true });
+        },
+    });
+}
+export default registerCanvasCommands;

package/dist/pi-extensions/canvas-goal-capture.d.ts

@@ -0,0 +1,18 @@
+interface InputEventLike {
+    type: 'input';
+    text: string;
+    images?: unknown[];
+    source: 'interactive' | 'rpc' | 'extension';
+}
+interface PiLike {
+    on: (event: 'input', handler: (event: InputEventLike, ctx: any) => void) => void;
+}
+/**
+ * Register the goal-capture handler on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: on the first interactive message of a goal-less node,
+ * persist it as the goal.
+ */
+export declare function registerCanvasGoalCapture(pi: PiLike): void;
+export default registerCanvasGoalCapture;

package/dist/pi-extensions/canvas-goal-capture.js

@@ -0,0 +1,53 @@
+// canvas-goal-capture.ts — pi extension for pi-native canvas agent nodes.
+//
+// Loaded into every canvas node's pi process via the node's launch.extensions
+// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
+//
+// A node spawned with a prompt has its goal persisted at birth (writeGoal in
+// spawn.ts). A bare root (`crtr` with no prompt) starts goal-less — its mandate
+// only arrives when the human types their first message. This extension closes
+// that gap: on the FIRST interactive user message, if the node has no goal yet,
+// it persists that message as context/initial-prompt.md. Subsequent messages
+// never clobber it (captureGoalIfAbsent is guarded), and a fresh-revive kickoff
+// prompt is skipped via its sentinel so it can never be mistaken for a mandate.
+//
+// Pure observation — it writes the goal file as a side effect and always lets
+// the message through unchanged (returns nothing ⇒ continue). Registered before
+// canvas-passive-context so it reads the raw user text, not a backlog-prepended
+// transform.
+//
+// Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
+// crouter's own tsc build without a dep on the pi packages.
+import { captureGoalIfAbsent, REVIVE_KICKOFF_SENTINEL } from '../core/runtime/kickoff.js';
+/**
+ * Register the goal-capture handler on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: on the first interactive message of a goal-less node,
+ * persist it as the goal.
+ */
+export function registerCanvasGoalCapture(pi) {
+    pi.on('input', (event) => {
+        try {
+            const nodeId = process.env['CRTR_NODE_ID'];
+            if (nodeId === undefined || nodeId.trim() === '')
+                return; // not a canvas node
+            // Only a genuine human-typed prompt seeds the mandate — never an RPC or an
+            // extension-injected message (inbox wakes, steering nudges, kickoffs).
+            if (event.source !== 'interactive')
+                return;
+            const text = (event.text ?? '').trim();
+            if (text === '')
+                return;
+            // A fresh-revive kickoff is delivered as the launch prompt; never let it
+            // masquerade as the user's first mandate.
+            if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
+                return;
+            captureGoalIfAbsent(nodeId, text);
+        }
+        catch {
+            // Best-effort: a capture failure must never drop or alter the message.
+        }
+    });
+}
+export default registerCanvasGoalCapture;

package/dist/pi-extensions/canvas-passive-context.d.ts

@@ -0,0 +1,32 @@
+import type { InboxEntry } from '../core/feed/inbox.js';
+interface InputEventLike {
+    type: 'input';
+    text: string;
+    images?: unknown[];
+    source: 'interactive' | 'rpc' | 'extension';
+}
+type InputEventResultLike = {
+    action: 'continue';
+} | {
+    action: 'transform';
+    text: string;
+    images?: unknown[];
+} | {
+    action: 'handled';
+};
+interface PiLike {
+    on: (event: 'input', handler: (event: InputEventLike, ctx: any) => InputEventResultLike | void) => void;
+}
+/**
+ * Render drained passive entries (oldest first) into one XML pre-text block.
+ * Each accumulated message is its own timestamped `<update>` element.
+ */
+export declare function formatPassive(entries: InboxEntry[]): string;
+/**
+ * Register the passive-context drain on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: drain on every message, prepend when non-empty.
+ */
+export declare function registerCanvasPassiveContext(pi: PiLike): void;
+export default registerCanvasPassiveContext;