@crouton-kit/crouter 0.3.12 → 0.3.14

package/dist/core/command.js

@@ -23,7 +23,26 @@ export function defineLeaf(opts) {
         render: opts.render,
     };
 }
+/** Number of a node's own non-hidden subcommands (direct children). Leaves and
+ *  childless branches return 0. */
+function visibleSubCount(def) {
+    if (def.kind !== 'branch')
+        return 0;
+    return def.help.children.filter((c) => (c.tier ?? 'normal') !== 'hidden').length;
+}
 export function defineBranch(opts) {
+    // Enrich each help-child entry with the count of its own non-hidden
+    // subcommands so renderBranch can show "[+N subcommands]" when a branch child
+    // is listed without expanding it. Match help entries to child defs by name;
+    // entries without a matching def (or whose def has no subcommands) stay bare.
+    for (const hc of opts.help.children) {
+        const childDef = opts.children.find((c) => c.name === hc.name);
+        if (childDef !== undefined) {
+            const n = visibleSubCount(childDef);
+            if (n > 0)
+                hc.subCount = n;
+        }
+    }
     return {
         kind: 'branch',
         name: opts.name,
@@ -60,13 +79,27 @@ export function defineRoot(opts) {
     // and dynamic block all travel with it.
     const commands = opts.subtrees
         .filter((s) => s.rootEntry !== undefined)
-        .map((s) => ({
-        name: s.name,
-        concept: s.rootEntry.concept,
-        desc: s.rootEntry.desc,
-        useWhen: s.rootEntry.useWhen,
-        dynamicState: s.rootEntry.dynamicState,
-    }));
+        .map((s) => {
+        // Promote this subtree's common/important children into root, and count
+        // how many other (non-hidden) direct subcommands stay behind `<name> -h`.
+        const visible = s.help.children.filter((c) => (c.tier ?? 'normal') !== 'hidden');
+        const promoted = visible
+            .filter((c) => c.tier === 'common' || c.tier === 'important')
+            .map((c) => ({
+            path: `${s.name} ${c.name}`,
+            // important carries its shortform desc; common shows the bare path.
+            desc: c.tier === 'important' ? c.desc : undefined,
+        }));
+        return {
+            name: s.name,
+            concept: s.rootEntry.concept,
+            desc: s.rootEntry.desc,
+            useWhen: s.rootEntry.useWhen,
+            dynamicState: s.rootEntry.dynamicState,
+            subcommands: promoted.length > 0 ? promoted : undefined,
+            otherSubcommandCount: visible.length - promoted.length,
+        };
+    });
     const help = {
         tagline: opts.tagline,
         commands,

package/dist/core/feed/feed.js

@@ -11,6 +11,7 @@ import { writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { reportsDir, subscribersOf, setStatus, updateNode, } from '../canvas/index.js';
 import { appendInbox } from './inbox.js';
+import { appendPassive } from './passive.js';
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -74,19 +75,20 @@ export async function push(nodeId, opts) {
     const ts = compactTs(now);
     // (a) Write the report.
     const reportPath = writeReport(nodeId, kind, ts, body);
-    // (b) Fan out inbox pointers to every subscriber (active and passive both
-    //     receive the pointer; the daemon decides whether to wake active ones).
+    // (b) Fan out a pointer to every subscriber. Active subscribers get it on
+    //     inbox.jsonl (the inbox-watcher polls that → a wake). Passive subscribers
+    //     get it on passive.jsonl instead — the watcher never polls that, so they
+    //     are NOT woken; the pointer accumulates until the node is next messaged,
+    //     when canvas-passive-context drains it as XML pre-text.
     const subscribers = subscribersOf(nodeId);
     const deliveredTo = [];
     const label = firstLine(body);
     for (const sub of subscribers) {
-        appendInbox(sub.node_id, {
-            from,
-            tier: tierFor(kind),
-            kind,
-            ref: reportPath,
-            label,
-        });
+        const entry = { from, tier: tierFor(kind), kind, ref: reportPath, label };
+        if (sub.active)
+            appendInbox(sub.node_id, entry);
+        else
+            appendPassive(sub.node_id, entry);
         deliveredTo.push(sub.node_id);
     }
     // (c) Finalise node when kind === 'final'.

package/dist/core/feed/passive.d.ts

@@ -0,0 +1,17 @@
+import type { InboxEntry } from './inbox.js';
+/**
+ * Atomically append one entry to `nodes/<nodeId>/passive.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export declare function appendPassive(nodeId: string, entry: Omit<InboxEntry, 'ts'>): InboxEntry;
+/** Return every accumulated passive entry (oldest first) without clearing. */
+export declare function readPassive(nodeId: string): InboxEntry[];
+/**
+ * Read AND clear the accumulator in one shot — the drain-on-message primitive.
+ *
+ * We rename the file aside before reading so a concurrent `appendPassive` (a
+ * publisher pushing at the same instant) starts a fresh file and is never lost
+ * to the truncate: at worst it lands in the next drain. The renamed snapshot is
+ * removed after a successful read. Returns the drained entries (oldest first).
+ */
+export declare function drainPassive(nodeId: string): InboxEntry[];

package/dist/core/feed/passive.js

@@ -0,0 +1,79 @@
+// Per-node passive-subscription accumulator for the pi-native canvas runtime.
+//
+// A PASSIVE subscription (the `active=false` flavor of a subscribes_to edge)
+// must never WAKE its subscriber. So when `push` fans out, a passive
+// subscriber's pointer is written here — to nodes/<id>/passive.jsonl — instead
+// of inbox.jsonl. The inbox-watcher polls only inbox.jsonl, so nothing here
+// triggers a turn.
+//
+// The accumulator is drained the moment the node is next MESSAGED: the
+// canvas-passive-context extension reads + clears this file on pi's `input`
+// event and injects every entry as timestamped XML pre-text before the message
+// reaches the LLM. Until then entries simply pile up, oldest first.
+//
+// Same entry shape as the inbox (InboxEntry) so the two stores stay symmetric
+// and a passive edge can be flipped active without reshaping data.
+import { appendFileSync, existsSync, readFileSync, renameSync, rmSync, mkdirSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { passivePath } from '../canvas/index.js';
+/**
+ * Atomically append one entry to `nodes/<nodeId>/passive.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export function appendPassive(nodeId, entry) {
+    const full = { ts: new Date().toISOString(), ...entry };
+    const line = JSON.stringify(full) + '\n';
+    const dir = dirname(passivePath(nodeId));
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    appendFileSync(passivePath(nodeId), line, { encoding: 'utf8', flag: 'a' });
+    return full;
+}
+/** Return every accumulated passive entry (oldest first) without clearing. */
+export function readPassive(nodeId) {
+    const p = passivePath(nodeId);
+    if (!existsSync(p))
+        return [];
+    return readFileSync(p, 'utf8')
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => JSON.parse(l));
+}
+/**
+ * Read AND clear the accumulator in one shot — the drain-on-message primitive.
+ *
+ * We rename the file aside before reading so a concurrent `appendPassive` (a
+ * publisher pushing at the same instant) starts a fresh file and is never lost
+ * to the truncate: at worst it lands in the next drain. The renamed snapshot is
+ * removed after a successful read. Returns the drained entries (oldest first).
+ */
+export function drainPassive(nodeId) {
+    const p = passivePath(nodeId);
+    if (!existsSync(p))
+        return [];
+    const snapshot = `${p}.draining`;
+    try {
+        renameSync(p, snapshot);
+    }
+    catch {
+        // Lost the race (file vanished) — nothing to drain.
+        return [];
+    }
+    let entries = [];
+    try {
+        entries = readFileSync(snapshot, 'utf8')
+            .split('\n')
+            .filter((l) => l.trim() !== '')
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        entries = [];
+    }
+    finally {
+        try {
+            rmSync(snapshot, { force: true });
+        }
+        catch { /* best-effort cleanup */ }
+    }
+    return entries;
+}

package/dist/core/help.d.ts

@@ -47,6 +47,29 @@ export interface ContextFileParam {
     shape?: string;
 }
 export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+/** How prominently a subcommand surfaces in ancestor (parent / root) -h
+ *  listings. Set per child in the parent branch's `help.children`. Default
+ *  'normal'.
+ *   - hidden    — never listed anywhere, not even in this branch's own -h.
+ *                 You must already know it exists to invoke it.
+ *   - normal    — listed in this branch's own -h only (the default).
+ *   - common    — ALSO promoted into the parent's -h, as a bare qualified name.
+ *   - important — ALSO promoted into the parent's -h, name + shortform desc. */
+export type SubTier = 'hidden' | 'normal' | 'common' | 'important';
+/** One child entry in a branch's -h listing. `desc`/`useWhen` are the shortform
+ *  copy shown there; `tier` governs promotion into ancestor listings. */
+export interface BranchChild {
+    name: string;
+    desc: string;
+    useWhen: string;
+    /** Visibility tier in ancestor listings (see SubTier). Default 'normal'. */
+    tier?: SubTier;
+    /** Computed at define time (defineBranch): how many non-hidden subcommands
+     *  this child itself owns. Drives the "[+N subcommands]" affordance shown when
+     *  a branch child is listed without expanding its own subcommands. Absent for
+     *  leaves and childless branches. Do not author by hand. */
+    subCount?: number;
+}
 /** A subtree's self-description at the parent (root) level. Each subtree owns
  *  the content that represents it one level up: its vocabulary line, its
  *  selection rubric, and any bounded block it contributes to the parent's -h.
@@ -75,18 +98,32 @@ export interface RootHelp {
      *  root, carrying the subtree's concept, selection rubric, and any nested
      *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
      *  root hardcodes none of it. */
-    commands: {
-        name: string;
-        concept: string;
-        desc: string;
-        useWhen: string;
-        dynamicState?: () => string | null;
-    }[];
+    commands: RootCommand[];
     globals: {
         name: string;
         desc: string;
     }[];
 }
+/** A single command block at root. Most fields come from the subtree's
+ *  RootEntry; `subcommands`/`otherSubcommandCount` are computed by defineRoot
+ *  from the subtree's children tiers. */
+export interface RootCommand {
+    name: string;
+    concept: string;
+    desc: string;
+    useWhen: string;
+    dynamicState?: () => string | null;
+    /** Promoted subcommands surfaced inline under this command at root, in
+     *  declaration order. `desc` is present only for 'important' tier; 'common'
+     *  tier carries the bare qualified path. */
+    subcommands?: {
+        path: string;
+        desc?: string;
+    }[];
+    /** How many of this command's other (non-hidden, not-promoted) direct
+     *  subcommands are not shown. Drives the "[+N (other) subcommands]" line. */
+    otherSubcommandCount?: number;
+}
 export interface BranchHelp {
     name: string;
     summary: string;
@@ -96,11 +133,7 @@ export interface BranchHelp {
      *  it with stateBlock), e.g. `<skills count="42">…</skills>`. Renderer
      *  soft-fails to omission if this returns null or throws. */
     dynamicState?: () => string | null;
-    children: {
-        name: string;
-        desc: string;
-        useWhen: string;
-    }[];
+    children: BranchChild[];
 }
 export interface LeafHelp {
     name: string;

package/dist/core/help.js

@@ -54,6 +54,31 @@ const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is
 const CAPABILITY_DISCOVERY = "If the user mentions or implies a crtr capability you don't fully understand, " +
     'do not guess or assume it is unsupported — run `-h` on the relevant command ' +
     '(append it anywhere along the path) to read the contract before acting.';
+/** Lines for a command's subcommand affordance at root: any promoted
+ *  (common/important) subcommands, then a remainder line naming how many other
+ *  subcommands exist behind `crtr <name> -h`. Returns [] when the command has
+ *  no listable subcommands at all. */
+function rootSubcommandLines(c) {
+    const promoted = c.subcommands ?? [];
+    const other = c.otherSubcommandCount ?? 0;
+    if (promoted.length === 0 && other === 0)
+        return [];
+    const out = [];
+    if (promoted.length > 0) {
+        const labelW = maxLen(promoted.map((s) => s.path));
+        for (const s of promoted) {
+            // important → padded name + shortform desc; common → bare name.
+            out.push(s.desc !== undefined && s.desc !== ''
+                ? `  ${pad(s.path, labelW)}  ${s.desc}`
+                : `  ${s.path}`);
+        }
+    }
+    if (other > 0) {
+        const word = promoted.length > 0 ? 'other subcommand' : 'subcommand';
+        out.push(`  [+${other} ${word}${other === 1 ? '' : 's'} — \`crtr ${c.name} -h\`]`);
+    }
+    return out;
+}
 export function renderRoot(h) {
     const lines = [];
     lines.push(`${h.tagline}`);
@@ -71,6 +96,11 @@ export function renderRoot(h) {
         lines.push(`<command name="${c.name}">`);
         lines.push(c.concept);
         lines.push(`use when ${c.useWhen}`);
+        // The command's subcommand surface: promoted (common/important) children
+        // inline, plus a "[+N other subcommands]" pointer to its own -h. Sits
+        // between the selection rubric and any live state block.
+        for (const l of rootSubcommandLines(c))
+            lines.push(l);
         // dynamicState returns a complete self-named element (e.g.
         // <skills count="42">…</skills>) — emit it as-is, nested in the command.
         const state = evalDynamic(c.dynamicState);
@@ -113,10 +143,18 @@ export function renderBranch(h) {
     }
     lines.push('');
     lines.push('Branches');
-    const nameW = maxLen(h.children.map((c) => c.name));
-    const descW = maxLen(h.children.map((c) => c.desc));
-    for (const c of h.children) {
-        lines.push(`  ${pad(c.name, nameW)}  ${pad(c.desc, descW)}  | use when ${c.useWhen}`);
+    // 'hidden' children never appear in any listing — drop them here.
+    const visible = h.children.filter((c) => (c.tier ?? 'normal') !== 'hidden');
+    const nameW = maxLen(visible.map((c) => c.name));
+    const descW = maxLen(visible.map((c) => c.desc));
+    for (const c of visible) {
+        let line = `  ${pad(c.name, nameW)}  ${pad(c.desc, descW)}  | use when ${c.useWhen}`;
+        // A branch child is listed without its own subcommands expanded — flag how
+        // many it has so the agent knows there is more depth behind `<child> -h`.
+        if (c.subCount !== undefined && c.subCount > 0) {
+            line += `  [+${c.subCount} subcommand${c.subCount === 1 ? '' : 's'}]`;
+        }
+        lines.push(line);
     }
     return lines.join('\n');
 }

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

@@ -0,0 +1,14 @@
+export interface DemoteResult {
+    /** True when the pane was recycled (a fresh root respawned in it). */
+    demoted: boolean;
+    /** True when a `final` report was pushed for the demoted node. */
+    finalized: boolean;
+    /** The fresh root node booted into the pane, or null on failure. */
+    newRoot: string | null;
+    /** Subscriber node ids that received the final report. */
+    delivered: string[];
+}
+/** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
+ *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
+ *  Best-effort; `demoted:false` when there is no pane to act on. */
+export declare function demoteNode(nodeId: string, callerPane?: string): Promise<DemoteResult>;

package/dist/core/runtime/demote.js

@@ -0,0 +1,103 @@
+// demote.ts — the "graduate this agent" action behind `crtr node demote`.
+//
+// Demote finishes the agent occupying a tmux pane and recycles that pane for
+// fresh work, in three steps:
+//
+//   1. Finalize — push the agent's last surfaced message as a `final` report so
+//      every subscriber/manager waiting on it is unblocked, and mark it done.
+//   2. Close    — kill the agent's pi (respawn-pane -k tears it down in place).
+//   3. Recycle  — boot a fresh resident root in that same pane (a new `crtr`).
+//
+// The agent's real conversation lives inside pi (not on disk), so the final
+// body is its newest report (which, on a natural stop, IS its last assistant
+// message) — falling back to a short note when it never reported.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getNode, updateNode } from '../canvas/index.js';
+import { reportsDir } from '../canvas/paths.js';
+import { pushFinal } from '../feed/feed.js';
+import { spawnNode } from './nodes.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { respawnPane, piCommand, paneLocation, nodeSession } from './tmux.js';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { getFocus, setFocus } from './presence.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+/** The agent's most recent surfaced message: the newest reports/*.md body with
+ *  its YAML frontmatter stripped. Empty string when the node never reported. */
+function lastReportBody(nodeId) {
+    try {
+        const dir = reportsDir(nodeId);
+        const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+        if (files.length === 0)
+            return '';
+        let newest = '';
+        let newestMs = -1;
+        for (const f of files) {
+            const ms = statSync(join(dir, f)).mtimeMs;
+            if (ms > newestMs) {
+                newestMs = ms;
+                newest = f;
+            }
+        }
+        const raw = readFileSync(join(dir, newest), 'utf8');
+        // Strip leading YAML frontmatter: ---\n …\n---\n<body>
+        const m = /^---\n[\s\S]*?\n---\n/.exec(raw);
+        return (m !== null ? raw.slice(m[0].length) : raw).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
+ *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
+ *  Best-effort; `demoted:false` when there is no pane to act on. */
+export async function demoteNode(nodeId, callerPane) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { demoted: false, finalized: false, newRoot: null, delivered: [] };
+    const pane = callerPane ?? process.env['TMUX_PANE'];
+    if (pane === undefined || pane === '') {
+        return { demoted: false, finalized: false, newRoot: null, delivered: [] };
+    }
+    // 1. Finalize — fan the agent's last message out as a `final`, mark it done.
+    const body = lastReportBody(nodeId) ||
+        `Closed via demote — no final summary was authored by ${meta.name}.`;
+    let delivered = [];
+    let finalized = false;
+    try {
+        const res = await pushFinal(nodeId, body);
+        delivered = res.deliveredTo;
+        finalized = true;
+    }
+    catch { /* recycle the pane even if the report failed */ }
+    // The demoted node no longer holds a window — the pane is being reclaimed.
+    try {
+        updateNode(nodeId, { window: null, tmux_session: null });
+    }
+    catch { /* best-effort */ }
+    if (getFocus() === nodeId)
+        setFocus('');
+    // 2 + 3. Recycle — boot a fresh resident root in the SAME pane.
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    const loc = paneLocation(pane);
+    const { launch } = buildLaunchSpec('general', 'base');
+    const root = spawnNode({
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: meta.cwd,
+        name: 'general',
+        parent: null,
+        launch,
+    });
+    if (loc !== null)
+        updateNode(root.node_id, { tmux_session: loc.session, window: loc.window });
+    const fresh = getNode(root.node_id);
+    const inv = buildPiArgv(fresh);
+    const env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), [FRONT_DOOR_ENV]: '1' };
+    const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
+    return { demoted: ok, finalized, newRoot: root.node_id, delivered };
+}

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

@@ -6,6 +6,15 @@ 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;
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;
+/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
+ *  The goal-capture extension skips any input starting with this so a kickoff
+ *  prompt is never mistaken for a user's first mandate. */
+export declare const REVIVE_KICKOFF_SENTINEL = "You have been revived fresh after a context refresh";
 /** 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;

package/dist/core/runtime/kickoff.js

@@ -41,6 +41,24 @@ export function writeGoal(nodeId, text) {
     mkdirSync(contextDir(nodeId), { recursive: true });
     writeFileSync(goalPath(nodeId), body + '\n', 'utf8');
 }
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export function captureGoalIfAbsent(nodeId, text) {
+    const existing = readGoal(nodeId);
+    if (existing !== null && existing.trim() !== '')
+        return false;
+    const body = text.trim();
+    if (body === '')
+        return false;
+    writeGoal(nodeId, body);
+    return true;
+}
+/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
+ *  The goal-capture extension skips any input starting with this so a kickoff
+ *  prompt is never mistaken for a user's first mandate. */
+export const REVIVE_KICKOFF_SENTINEL = 'You have been revived fresh after a context refresh';
 /** 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) {
@@ -112,7 +130,7 @@ export function buildReviveKickoff(meta) {
     // 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 ' +
+        `${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.',
     ];

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

@@ -2,9 +2,15 @@ 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;
+export declare const CANVAS_GOAL_CAPTURE_PATH: string;
+export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
+export declare const CANVAS_COMMANDS_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. */
+ *  graph chrome), goal-capture (persist the first user message as the goal),
+ *  passive-context (drain passive backlog as pre-text on the next message),
+ *  commands (the /promote slash-command). 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[];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */
@@ -24,6 +30,11 @@ export interface PiInvocation {
     /** env to merge into the process. */
     env: Record<string, string>;
 }
+/** The pi session display name — the editor label in the top-left. Shows the
+ *  node's name plus its current mode so base vs orchestrator reads at a glance
+ *  (e.g. `developer (orchestrator)`). Recomputed from `meta.mode` on every
+ *  revive, so a base→orchestrator polymorph updates the label. */
+export declare function editorLabel(meta: NodeMeta): 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).

package/dist/core/runtime/launch.js

@@ -27,13 +27,22 @@ function resolveExtension(name) {
 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');
+export const CANVAS_GOAL_CAPTURE_PATH = resolveExtension('canvas-goal-capture');
+export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-context');
+export const CANVAS_COMMANDS_PATH = resolveExtension('canvas-commands');
 /** 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. */
+ *  graph chrome), goal-capture (persist the first user message as the goal),
+ *  passive-context (drain passive backlog as pre-text on the next message),
+ *  commands (the /promote slash-command). All self-gate on CRTR_NODE_ID.
+ *  goal-capture precedes passive-context so it reads the raw user text. */
 export const CANVAS_EXTENSIONS = [
     CANVAS_STOPHOOK_PATH,
     CANVAS_INBOX_WATCHER_PATH,
     CANVAS_NAV_PATH,
+    CANVAS_GOAL_CAPTURE_PATH,
+    CANVAS_PASSIVE_CONTEXT_PATH,
+    CANVAS_COMMANDS_PATH,
 ];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */
@@ -59,6 +68,13 @@ export function buildLaunchSpec(kind, mode, opts = {}) {
     };
     return { launch, lifecycle: p.lifecycle, skills: p.skills };
 }
+/** The pi session display name — the editor label in the top-left. Shows the
+ *  node's name plus its current mode so base vs orchestrator reads at a glance
+ *  (e.g. `developer (orchestrator)`). Recomputed from `meta.mode` on every
+ *  revive, so a base→orchestrator polymorph updates the label. */
+export function editorLabel(meta) {
+    return `${meta.name} (${meta.mode})`;
+}
 /** 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).
@@ -69,7 +85,7 @@ export function buildPiArgv(meta, opts = {}) {
     for (const ext of spec?.extensions ?? CANVAS_EXTENSIONS) {
         argv.push('-e', ext);
     }
-    argv.push('-n', meta.name);
+    argv.push('-n', editorLabel(meta));
     if (opts.resumeSessionId !== undefined)
         argv.push('--resume', opts.resumeSessionId);
     if (spec?.model !== undefined)

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

@@ -31,7 +31,7 @@ export declare function focusNode(nodeId: string): {
  *
  *  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): {
+export declare function focusNodeInPlace(nodeId: string, callerPane?: string, callerNodeId?: string): {
     focused: boolean;
     session: string | null;
     inPlace: boolean;

package/dist/core/runtime/presence.js

@@ -99,7 +99,7 @@ export function focusNode(nodeId) {
  *
  *  Falls back to window focus when there is no caller pane (not inside tmux) or
  *  the target pane can't be resolved. `inPlace` reports which path ran. */
-export function focusNodeInPlace(nodeId, callerPane) {
+export function focusNodeInPlace(nodeId, callerPane, callerNodeId) {
     const meta = getNode(nodeId);
     // Always write the pointer so the dashboard reflects intent even on failure.
     setFocus(nodeId);
@@ -140,10 +140,12 @@ export function focusNodeInPlace(nodeId, callerPane) {
         catch { /* best-effort */ }
         // The caller is the node running this focus (its pi process owns callerPane).
         // Its pane moved to the target's old window, so re-point its window there.
-        const callerNodeId = process.env['CRTR_NODE_ID'];
-        if (callerNodeId !== undefined && callerNodeId.trim() !== '' && callerNodeId !== nodeId) {
+        // Prefer an explicit id (the `node cycle` tmux binding runs outside any pi,
+        // so CRTR_NODE_ID is unset there) and fall back to the env for `node focus`.
+        const cnid = callerNodeId ?? process.env['CRTR_NODE_ID'];
+        if (cnid !== undefined && cnid.trim() !== '' && cnid !== nodeId) {
             try {
-                updateNode(callerNodeId, { window });
+                updateNode(cnid, { window });
             }
             catch { /* best-effort */ }
         }

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

@@ -4,6 +4,10 @@ export interface PromoteResult {
     /** Orchestration guidance to surface into the node's current context now. */
     guidance: string;
     roadmapWritten: boolean;
+    /** Absolute path to the node's roadmap doc (context/roadmap.md). */
+    roadmapPath: string;
+    /** Absolute path to the node's goal doc (context/initial-prompt.md). */
+    goalPath: string;
 }
 /** Promote a node to resident orchestrator, optionally specializing its kind
  *  (e.g. a `general` worker becoming a `developer.orchestrator`). Idempotent: