@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/core/personas/resolve.d.ts

@@ -14,11 +14,10 @@
  *       If even the base is missing, fall back to general defaults + kernel.
  *
  * Frontmatter from whichever file is the primary source (orchestrator.md >
- * base.md) supplies model/lifecycle/skills/extensions/tools.
- *
- * Lifecycle defaults:
- *   base         → 'terminal'
- *   orchestrator → 'resident'
+ * base.md) supplies model/skills/extensions/tools. Lifecycle and spine position
+ * are INPUTS (the caller decides them — root/child, terminal/resident), not
+ * derived here; they select the lifecycle/spine protocol fragments spliced
+ * ahead of the persona body.
  */
 export interface ResolvedPersona {
     systemPrompt: string;
@@ -33,4 +32,12 @@ export interface ResolvedPersona {
  *
  * Never throws for missing files — missing personas produce sensible defaults.
  */
-export declare function resolve(kind: string, mode: 'base' | 'orchestrator'): ResolvedPersona;
+export interface ResolveOpts {
+    /** The node's lifecycle axis — selects the "how you end" fragment. */
+    lifecycle: 'terminal' | 'resident';
+    /** Whether the node reports up to a manager (parent !== null) — selects the
+     *  spine fragment (`has-manager` teaches the push family; `no-manager` omits
+     *  it entirely). */
+    hasManager: boolean;
+}
+export declare function resolve(kind: string, mode: 'base' | 'orchestrator', opts: ResolveOpts): ResolvedPersona;

package/dist/core/personas/resolve.js

@@ -14,13 +14,12 @@
  *       If even the base is missing, fall back to general defaults + kernel.
  *
  * Frontmatter from whichever file is the primary source (orchestrator.md >
- * base.md) supplies model/lifecycle/skills/extensions/tools.
- *
- * Lifecycle defaults:
- *   base         → 'terminal'
- *   orchestrator → 'resident'
+ * base.md) supplies model/skills/extensions/tools. Lifecycle and spine position
+ * are INPUTS (the caller decides them — root/child, terminal/resident), not
+ * derived here; they select the lifecycle/spine protocol fragments spliced
+ * ahead of the persona body.
  */
-import { loadPersona, loadKernel, loadRuntimeBase } from './loader.js';
+import { loadPersona, loadKernel, loadRuntimeBase, loadSpineFragment, loadLifecycleFragment, subKindsFor } from './loader.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -32,48 +31,62 @@ function toStringArray(v) {
 function toOptionalString(v) {
     return typeof v === 'string' ? v : undefined;
 }
-function toLifecycle(v, defaultValue) {
-    if (v === 'terminal' || v === 'resident')
-        return v;
-    return defaultValue;
-}
 /** The bare-minimum system prompt used when no persona file is found at all. */
 function fallbackBasePrompt(kind) {
     return `You are a ${kind} agent. Complete the task you have been given.`;
 }
-/** Prepend the base runtime protocol (push/finish/delegate/feed/ask) to a
- *  persona's prompt — every node, every kind, every mode gets it first. */
-function withBase(personaPrompt) {
-    const base = loadRuntimeBase();
-    return base ? `${base}\n\n---\n\n${personaPrompt}` : personaPrompt;
+/** Compose the runtime protocol that precedes every persona body: the
+ *  lifecycle-neutral base (identity/delegate/ask/promote), then the spine
+ *  fragment (report-up vs. silent, keyed on whether the node has a manager),
+ *  then the lifecycle fragment (finish-with-`push final` vs. dormant/wake). The
+ *  kind×mode persona body follows after a rule. Empty fragments drop out. */
+/** Render the "sub-kinds you may spawn" menu for a kind that owns a roster.
+ *  Returns '' when the kind owns none. Data-driven: one line per sub-kind, its
+ *  spawn string + its `summary`. Adding a roster file makes it appear here. */
+function renderSubKindMenu(kind) {
+    const subs = subKindsFor(kind);
+    if (subs.length === 0)
+        return '';
+    const lines = subs.map((s) => `- \`${s.kind}\` — ${s.summary}`);
+    return [
+        '## Reviewer sub-kinds you may spawn',
+        '',
+        `These specialist reviewers exist only in the ${kind} kind's world — no other kind sees them. Spawn one with \`crtr node new --kind <sub-kind> "<scope>"\`, giving it only its scope, never your suspicions: a reviewer handed a hint anchors on it instead of finding problems independently.`,
+        '',
+        ...lines,
+    ].join('\n');
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Resolve a fully composed persona for the given `kind` and `mode`.
- *
- * Never throws for missing files — missing personas produce sensible defaults.
- */
-export function resolve(kind, mode) {
+function composeProtocol(personaPrompt, kind, lifecycle, hasManager) {
+    const menu = renderSubKindMenu(kind);
+    const body = menu ? `${personaPrompt}\n\n${menu}` : personaPrompt;
+    const protocol = [
+        loadRuntimeBase(),
+        loadSpineFragment(hasManager),
+        loadLifecycleFragment(lifecycle),
+    ]
+        .filter((s) => s.length > 0)
+        .join('\n\n');
+    return protocol ? `${protocol}\n\n---\n\n${body}` : body;
+}
+export function resolve(kind, mode, opts) {
     if (mode === 'base') {
         const persona = loadPersona(kind, 'base');
         if (!persona) {
             // No persona file for this kind — use minimal defaults.
             return {
-                systemPrompt: withBase(fallbackBasePrompt(kind)),
+                systemPrompt: composeProtocol(fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
                 extensions: [],
                 skills: [],
-                lifecycle: 'terminal',
+                lifecycle: opts.lifecycle,
             };
         }
         const fm = persona.frontmatter ?? {};
         return {
-            systemPrompt: withBase(persona.body || fallbackBasePrompt(kind)),
+            systemPrompt: composeProtocol(persona.body || fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
             extensions: toStringArray(fm['extensions']),
             skills: toStringArray(fm['skills']),
             model: toOptionalString(fm['model']),
-            lifecycle: toLifecycle(fm['lifecycle'], 'terminal'),
+            lifecycle: opts.lifecycle,
             tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
         };
     }
@@ -83,11 +96,11 @@ export function resolve(kind, mode) {
         // Orchestrator file exists; @include was already inlined by the loader.
         const fm = orchestratorPersona.frontmatter ?? {};
         return {
-            systemPrompt: withBase(orchestratorPersona.body || fallbackBasePrompt(kind)),
+            systemPrompt: composeProtocol(orchestratorPersona.body || fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
             extensions: toStringArray(fm['extensions']),
             skills: toStringArray(fm['skills']),
             model: toOptionalString(fm['model']),
-            lifecycle: toLifecycle(fm['lifecycle'], 'resident'),
+            lifecycle: opts.lifecycle,
             tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
         };
     }
@@ -99,12 +112,11 @@ export function resolve(kind, mode) {
     // Append the kernel to the base body (with separator if kernel is non-empty).
     const systemPrompt = kernel ? `${baseBody}\n\n${kernel}` : baseBody;
     return {
-        systemPrompt: withBase(systemPrompt),
+        systemPrompt: composeProtocol(systemPrompt, kind, opts.lifecycle, opts.hasManager),
         extensions: toStringArray(fm['extensions']),
         skills: toStringArray(fm['skills']),
         model: toOptionalString(fm['model']),
-        // Override lifecycle to 'resident' — this node is being used as an orchestrator.
-        lifecycle: 'resident',
+        lifecycle: opts.lifecycle,
         tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
     };
 }

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

@@ -0,0 +1,20 @@
+/** Base framing — present for every node. No path baked in: the caller carries
+ *  the dir in the <crtr-context dir="…"> attribute. */
+export declare const BASE_CONTEXT_NOTE: string;
+/** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
+ *  so its context dir is also where a future cycle of itself resumes the work.
+ *  Used inside the bearings block AND in the promotion guidance dump, so a
+ *  promoted node gets the same note a born-orchestrator gets. */
+export declare function orchestratorContextNote(nodeId: string): string;
+/** The <memory> block (orchestrators only): the scoped stores merged, each a
+ *  `label · dir` header over its live index pointer lines. A memory's `type`
+ *  decides which store it lands in — the mapping + the how-to live once in the
+ *  orchestration kernel ("Your long-term memory"); here we carry only the live
+ *  data + a one-line pointer back to it. user-global rides in when the node has
+ *  a user store, project when it has a project store, node-local always (the
+ *  orchestrator gate). */
+export declare function buildMemoryBlock(nodeId: string, cwd: string): string;
+/** The full <crtr-context> bearings block: base framing always, plus the
+ *  orchestrator addendum + the merged three-store <memory> block when the node
+ *  has a node-local memory store (the orchestrator gate). */
+export declare function buildContextBearings(nodeId: string): string;

package/dist/core/runtime/bearings.js

@@ -0,0 +1,92 @@
+// bearings.ts — the <crtr-context> framing prose, shared by the two paths that
+// deliver it so they can never drift:
+//
+//   • the context-intro pi-extension injects buildContextBearings() as the
+//     node's first session message in every brand-new chat;
+//   • promote.ts folds orchestratorContextNote() into the promotion guidance
+//     dump, so a node that becomes an orchestrator MID-LIFE gets the
+//     orchestrator framing it never received at spawn — it spawned as a base
+//     worker, and the bearings already in its history carry only the base note.
+//
+// Base framing (every node): the context dir is durable, shared scratch — the
+// one place other nodes on the canvas can read from, so it is for documents
+// worth a shared reference, NOT a task tracker, and NOT a "future memory-wiped
+// you" stash (a terminal worker has no future cycle — that framing only makes
+// sense once a node is a resident orchestrator).
+//
+// Orchestrator addendum (resident orchestrators — i.e. nodes that have a
+// node-local memory store): the dir ALSO survives refresh cycles, so it is where
+// a future cycle of the orchestrator resumes; durable cross-goal lessons live in
+// the three scoped memory stores, whose index pointer lines are inlined into
+// <memory> (the how-to lives once in the kernel, not here).
+import { contextDir, getNode } from '../canvas/index.js';
+import { hasMemory, memoryDir, readMemory, hasUserMemory, userMemoryDir, readUserMemory, hasProjectMemory, projectMemoryDir, readProjectMemory, } from './memory.js';
+/** Base framing — present for every node. No path baked in: the caller carries
+ *  the dir in the <crtr-context dir="…"> attribute. */
+export const BASE_CONTEXT_NOTE = 'This is your context directory — durable scratch space on disk, and the one place the other ' +
+    'nodes on the canvas can read from. Put documents here that you want to share by reference ' +
+    'instead of re-explaining them in a prompt: specs, designs, findings, notes worth pointing a ' +
+    'sibling, child, or parent at. It is a shared document store, not a task tracker.';
+/** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
+ *  so its context dir is also where a future cycle of itself resumes the work.
+ *  Used inside the bearings block AND in the promotion guidance dump, so a
+ *  promoted node gets the same note a born-orchestrator gets. */
+export function orchestratorContextNote(nodeId) {
+    return (`Because you persist across refresh cycles, your context directory (${contextDir(nodeId)}) is ` +
+        `also where a future cycle of you resumes the work — keep the working notes and decisions a ` +
+        `refreshed you would need there, alongside the docs you share with the nodes you spawn.`);
+}
+/** One labeled store stanza inside <memory>: a compact `label · dir` header (the
+ *  scope name + where to WRITE this kind of memory), then the LIVE pointer lines
+ *  extracted fresh from the store's index — only lines matching `- [...` — with
+ *  the index's how-to boilerplate dropped (it lives once in the kernel) and
+ *  detail files loaded on demand. Falls back to `(empty)` when the index carries
+ *  no pointers, which also covers the not-seeded / template-only case. */
+function memoryStanza(label, dir, index) {
+    const pointers = (index ?? '')
+        .split('\n')
+        .filter((line) => /^\s*-\s*\[/.test(line))
+        .map((line) => line.trim());
+    const body = pointers.length > 0 ? pointers.join('\n') : '(empty)';
+    return `${label} · ${dir}\n${body}`;
+}
+/** The <memory> block (orchestrators only): the scoped stores merged, each a
+ *  `label · dir` header over its live index pointer lines. A memory's `type`
+ *  decides which store it lands in — the mapping + the how-to live once in the
+ *  orchestration kernel ("Your long-term memory"); here we carry only the live
+ *  data + a one-line pointer back to it. user-global rides in when the node has
+ *  a user store, project when it has a project store, node-local always (the
+ *  orchestrator gate). */
+export function buildMemoryBlock(nodeId, cwd) {
+    const stanzas = [];
+    if (hasUserMemory()) {
+        stanzas.push(memoryStanza('user-global', userMemoryDir(), readUserMemory()));
+    }
+    if (hasProjectMemory(cwd)) {
+        stanzas.push(memoryStanza('project', projectMemoryDir(cwd), readProjectMemory(cwd)));
+    }
+    stanzas.push(memoryStanza('node-local', memoryDir(nodeId), readMemory(nodeId)));
+    const n = stanzas.length;
+    return ('<memory>\n' +
+        `Long-term memory, ${n} scope${n === 1 ? '' : 's'}. Each line ` +
+        '`- [Title](slug.md) — hook`; load a detail file by slug from the scope dir on demand. ' +
+        'Write a new fact to the scope matching its `type` (see "Your long-term memory").\n\n' +
+        stanzas.join('\n\n') +
+        '\n</memory>');
+}
+/** The full <crtr-context> bearings block: base framing always, plus the
+ *  orchestrator addendum + the merged three-store <memory> block when the node
+ *  has a node-local memory store (the orchestrator gate). */
+export function buildContextBearings(nodeId) {
+    const dir = contextDir(nodeId);
+    if (!hasMemory(nodeId)) {
+        // A terminal worker (no memory store): base framing only, no memory block.
+        return `<crtr-context dir="${dir}">\n${BASE_CONTEXT_NOTE}\n</crtr-context>`;
+    }
+    // An orchestrator: across-cycles framing + the merged three-store memory. The
+    // project store is keyed off the node's cwd (its working dir on disk).
+    const cwd = getNode(nodeId)?.cwd ?? process.cwd();
+    return (`<crtr-context dir="${dir}">\n` +
+        `${BASE_CONTEXT_NOTE}\n${orchestratorContextNote(nodeId)}\n${buildMemoryBlock(nodeId, cwd)}\n` +
+        '</crtr-context>');
+}

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

@@ -0,0 +1,14 @@
+export interface CloseNodeResult {
+    /** The focused node that was closed — the cascade root. */
+    root: string;
+    /** Every node torn down (root + cascaded descendants), in kill order
+     *  (leaves first, root last). */
+    closed: string[];
+    /** Descendants left alive because a manager outside the subtree still
+     *  subscribes to them. */
+    spared: string[];
+}
+/** Close `rootId` and its exclusive subtree. Best-effort throughout: a tmux/db
+ *  failure on one node never aborts the cascade. Throws only on an unknown root
+ *  so the command can surface a clean not-found error. */
+export declare function closeNode(rootId: string): CloseNodeResult;

package/dist/core/runtime/close.js

@@ -0,0 +1,151 @@
+// close.ts — the "close this node + its subtree" action behind `crtr node close`.
+//
+// Closing a node tears down the focused node and every descendant it
+// EXCLUSIVELY owns, walking DOWN the subscribes_to spine (subscriptionsOf = a
+// node's reports/children). Nothing is deleted: pi_session_id, the canvas
+// edges, and all on-disk state persist, so any closed node can later be revived
+// (`crtr canvas revive` / focus → `pi --session <id>`). A close is a pause, not a reap.
+//
+// Per node, in this order — the order matters twice:
+//
+//   1. Mark `canceled` + clear intent. Done BEFORE the window dies: the daemon
+//      only ever revives an active|idle node, so flipping to canceled first
+//      closes the race where the supervisor sees a window-gone live node and
+//      either revives it or marks it dead (overwriting our canceled).
+//   2. Kill its tmux PANE (the window closes once its last pane goes) — which
+//      kills pi and, with it, the inbox watcher. Pane-granular so that nodes
+//      the user co-located as panes in ONE window (via swap-pane focus) are not
+//      all taken down when one of them is closed.
+//   3. Append the cancellation notice to its inbox AFTER the watcher is gone.
+//      The watcher advances its cursor when it READS an entry, so appending
+//      while it is still live would let it consume + skip the notice (cursor
+//      moves past it, never delivered). Killed first, the cursor stays put;
+//      on the node's next resume a fresh watcher seeds from that frozen cursor,
+//      finds the notice, and injects it — the agent learns its children died.
+//
+// The cascade is GUARDED: a descendant is closed only when EVERY node that
+// subscribes to it (its managers, subscribersOf — active OR passive) is itself
+// inside the closing set. A node still subscribed to by a manager outside the
+// subtree is left running — "only kill the children if they are only subscribed
+// 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 { appendInbox } from '../feed/inbox.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
+ *  pass. Cycle-safe via the membership skip. */
+function closingSet(root) {
+    const closing = new Set([root]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const parent of [...closing]) {
+            for (const sub of subscriptionsOf(parent)) {
+                const child = sub.node_id;
+                if (closing.has(child))
+                    continue;
+                // Close the child only if NOBODY outside the closing set subscribes to
+                // it. (subscriptionsOf always yields child→parent, so `parent` is one
+                // of child's managers and is in `closing` — the check is never vacuous.)
+                if (subscribersOf(child).every((m) => closing.has(m.node_id))) {
+                    closing.add(child);
+                    changed = true;
+                }
+            }
+        }
+    }
+    return closing;
+}
+/** BFS the closing set from root, then reverse: leaves die first, the focused
+ *  root dies last ("cascades up"). The root being killed last also keeps the
+ *  user's foreground window — the one they invoked the close from — open until
+ *  every background descendant is gone. */
+function killOrder(root, closing) {
+    const order = [];
+    const seen = new Set([root]);
+    const queue = [root];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        order.push(id);
+        for (const sub of subscriptionsOf(id)) {
+            if (closing.has(sub.node_id) && !seen.has(sub.node_id)) {
+                seen.add(sub.node_id);
+                queue.push(sub.node_id);
+            }
+        }
+    }
+    // Any closing node a cycle kept BFS from reaching still gets torn down.
+    for (const id of closing)
+        if (!seen.has(id))
+            order.push(id);
+    return order.reverse();
+}
+/** The inbox notice a closed node reads on its next resume. */
+function cancellationLabel(isRoot, deadChildren) {
+    const who = isRoot
+        ? 'You were CLOSED by the user from the canvas'
+        : 'You were CANCELED — an ancestor of yours was closed from the canvas';
+    if (deadChildren.length === 0) {
+        return `${who}. Your pi session is preserved; this resume reopened it.`;
+    }
+    const names = deadChildren.slice(0, 4).map((c) => {
+        const n = getNode(c);
+        return n !== null ? `${n.name} (${c})` : c;
+    });
+    const more = deadChildren.length > names.length ? ` +${deadChildren.length - names.length} more` : '';
+    return (`${who}. ${deadChildren.length} child node(s) you subscribe to were canceled with you and are no ` +
+        `longer running: ${names.join(', ')}${more}. Resuming will NOT restore them — re-spawn if you ` +
+        `still need that work.`);
+}
+/** Close `rootId` and its exclusive subtree. Best-effort throughout: a tmux/db
+ *  failure on one node never aborts the cascade. Throws only on an unknown root
+ *  so the command can surface a clean not-found error. */
+export function closeNode(rootId) {
+    if (getNode(rootId) === null)
+        throw new Error(`closeNode: unknown node ${rootId}`);
+    const closing = closingSet(rootId);
+    const order = killOrder(rootId, closing);
+    // Descendants reachable from the subtree but kept alive (shared managers).
+    const spared = [];
+    for (const id of closing) {
+        for (const sub of subscriptionsOf(id)) {
+            if (!closing.has(sub.node_id) && !spared.includes(sub.node_id)) {
+                spared.push(sub.node_id);
+            }
+        }
+    }
+    const closed = [];
+    for (const id of order) {
+        try {
+            const m = getNode(id);
+            if (m === null)
+                continue;
+            // This node's reports that are dying with it (for the resume notice).
+            const deadChildren = subscriptionsOf(id)
+                .map((s) => s.node_id)
+                .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), null its
+            //    LOCATION, and clear focus.ptr if it was the current focus.
+            tearDownNode(id);
+            // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
+            appendInbox(id, {
+                from: null,
+                tier: 'normal',
+                kind: 'message',
+                label: cancellationLabel(id === rootId, deadChildren),
+                data: { reason: 'user-close', cascade_root: rootId, canceled_children: deadChildren },
+            });
+            closed.push(id);
+        }
+        catch {
+            /* one bad node never aborts the cascade */
+        }
+    }
+    return { root: rootId, closed, spared };
+}

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,120 @@
+// 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, setPresence, updateNode, setFocusOccupant, fullName } 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 { piCommand, paneLocation, nodeSession } from './tmux.js';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { getFocus, setFocus } from './presence.js';
+import { focusOf, recycleFocusPane } from './placement.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 */ }
+    // Capture M's focus viewport (if any) BEFORE nulling — the fresh root inherits
+    // it (the SAME focus row + pane). The demoted node no longer holds a pane: it is
+    // being reclaimed.
+    const f = focusOf(nodeId);
+    try {
+        setPresence(nodeId, { pane: null, window: null, tmux_session: null });
+    }
+    catch { /* best-effort */ }
+    // 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', { lifecycle: 'resident', hasManager: false });
+    const root = spawnNode({
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: meta.cwd,
+        name: 'general',
+        parent: null,
+        launch,
+    });
+    // REVIVE-HOME: a demote-recycled root's durable revive target is the session
+    // of the pane it was recycled into (the one place home_session is rewritten
+    // after birth). Falls back to the backstage when the pane can't be located.
+    updateNode(root.node_id, { home_session: loc?.session ?? nodeSession() });
+    // Hand the viewport to the fresh root: reuse M's focus row over the SAME pane
+    // (respawn-pane -k below keeps the %id), so the user keeps watching this slot.
+    if (f !== null) {
+        try {
+            setFocusOccupant(f.focus_id, root.node_id);
+            setFocus(root.node_id);
+        }
+        catch { /* best-effort */ }
+    }
+    else if (getFocus() === nodeId)
+        setFocus('');
+    const fresh = getNode(root.node_id);
+    const inv = buildPiArgv(fresh);
+    const env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), [FRONT_DOOR_ENV]: '1' };
+    const ok = recycleFocusPane(root.node_id, pane, {
+        command: piCommand(inv.argv), env, cwd: meta.cwd, name: fullName(fresh), resuming: false,
+    });
+    return { demoted: ok, finalized, newRoot: root.node_id, delivered };
+}

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

@@ -92,6 +92,6 @@ export function maybeBootRoot(root, argv) {
     // Unambiguous front-door launch → boot a resident root inline (exec pi in
     // this terminal). Does not return.
     const args = parseRootArgs(tokens);
-    bootRoot({ ...args, placement: 'inline' });
+    bootRoot({ ...args });
     return true;
 }

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;
@@ -15,9 +24,26 @@ export declare function writeYieldMessage(nodeId: string, text: string): void;
 export declare function consumeYieldMessage(nodeId: string): string | null;
 /** List the node's context/ dir (filenames, sorted). Empty when absent. */
 export declare function listContextDir(nodeId: string): string[];
-/** Build the auto-injected first message for a FRESH revive of `meta`. Reads
- *  the node's goal, roadmap, context dir, feed, and one-shot yield message off
- *  disk and frames them so the revived node can rebuild its bearings in one
- *  turn. Side effects: consumes the yield message and advances the feed cursor
- *  (both are "read" by surfacing them here). */
-export declare function buildReviveKickoff(meta: NodeMeta): string;
+export interface ReviveBearings {
+    /** The one-shot yield note left by the prior self (already consumed/deleted). */
+    yieldMsg: string | null;
+    /** Coalesced digest of unread reports, or null when the feed was empty. The
+     *  cursor has already been advanced past these. */
+    unreadDigest: string | null;
+    /** Persona-transition guidance to surface when the node's role was changed
+     *  while it was away (its ack has already been committed), else null. */
+    driftGuidance: string | null;
+}
+/** Drain the one-shot revive bearings for `meta`: consume the yield note, advance
+ *  the feed cursor past the unread reports, and capture+commit any external
+ *  persona drift. The CONSUMING step of a fresh revive — the revive paths call it
+ *  ONCE, then pass the result to buildReviveKickoff (which is then pure; building
+ *  twice eats nothing). Calling drainBearings a second time would drain an
+ *  already-empty note/feed, so ONLY the revive paths call it. */
+export declare function drainBearings(meta: NodeMeta): ReviveBearings;
+/** Assemble the auto-injected first message for a FRESH revive of `meta` from its
+ *  already-drained `bearings` (see drainBearings) plus pure on-disk reads of the
+ *  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;