@crouton-kit/crouter 0.3.14 → 0.3.16

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), and null its
+            //    LOCATION (closing the focus row is the record — no pointer to clear).
+            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.js

@@ -13,14 +13,13 @@
 // 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 { 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 { spawnNode, nodeSession } 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 { focusOf, recycleFocusPane, piCommand, paneLocation } 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. */
@@ -70,20 +69,21 @@ export async function demoteNode(nodeId, callerPane) {
         finalized = true;
     }
     catch { /* recycle the pane even if the report failed */ }
-    // The demoted node no longer holds a window — the pane is being reclaimed.
+    // 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 {
-        updateNode(nodeId, { window: null, tmux_session: null });
+        setPresence(nodeId, { pane: null, 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 { launch } = buildLaunchSpec('general', 'base', { lifecycle: 'resident', hasManager: false });
     const root = spawnNode({
         kind: 'general',
         mode: 'base',
@@ -93,11 +93,23 @@ export async function demoteNode(nodeId, callerPane) {
         parent: null,
         launch,
     });
-    if (loc !== null)
-        updateNode(root.node_id, { tmux_session: loc.session, window: loc.window });
+    // 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);
+        }
+        catch { /* best-effort */ }
+    }
     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) });
+    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

@@ -24,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;

package/dist/core/runtime/kickoff.js

@@ -6,18 +6,22 @@
 // conversation already holds the context).
 //
 // Layout (the framing a revived node sees):
-//   <goal file=…>…</goal>                  the mandate it was spawned with
-//   <roadmap file=…>…</roadmap>            its evolving plan
+//   <roadmap file=…>…</roadmap>            its evolving plan — the source of truth
 //   <context-dir path=…>…</context-dir>    what artifacts exist on disk
 //   <feed>Awaiting N nodes … digest</feed> who it waits on + unread reports
 //   <yield-message>…</yield-message>       the note its prior self left on yield
 //
-// The goal + yield-message are companion files in the node's context dir; the
+// The roadmap (NOT the original spawn prompt) carries the goal on a refresh: its
+// frozen core holds goal + exit criteria, its body the live plan. context/
+// initial-prompt.md is NEVER injected into a node's prompts — it lives on disk
+// purely as a log of the original mandate; by the time a node is running it is
+// usually stale, and the roadmap is the doc the node keeps current. The
 // yield-message is one-shot (consumed on the next revive).
 import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, readdirSync, } from 'node:fs';
 import { join } from 'node:path';
-import { contextDir, getNode, subscriptionsOf, } from '../canvas/index.js';
+import { contextDir, getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
+import { personaDrift, commitPersonaAck } from './persona.js';
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../feed/inbox.js';
 // ---------------------------------------------------------------------------
 // Companion context files: the goal (the spawning mandate) and the one-shot
@@ -91,62 +95,114 @@ export function listContextDir(nodeId) {
         return [];
     return readdirSync(dir).sort();
 }
-// ---------------------------------------------------------------------------
-// Feed block — who the node is awaiting, plus a drained digest of unread
-// reports. Draining here advances the cursor: the revived node has now "read"
-// the feed, so a later `crtr feed read` shows only what arrives afterward.
-// ---------------------------------------------------------------------------
-function feedBlock(nodeId) {
+/** 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 function drainBearings(meta) {
+    const nodeId = meta.node_id;
+    // Consume the one-shot yield note (deleted on read) BEFORE the kickoff lists
+    // the context dir, so it never shows up there.
+    const yieldMsg = consumeYieldMessage(nodeId);
+    // Drain the feed: read unread since the cursor and advance it past them, so a
+    // later `crtr feed read` shows only what arrives afterward.
+    const cursor = readCursor(nodeId);
+    const entries = readInboxSince(nodeId, cursor);
+    let unreadDigest = null;
+    if (entries.length > 0) {
+        writeCursor(nodeId, entries[entries.length - 1].ts);
+        unreadDigest = coalesce(entries);
+    }
+    // Capture + commit any external persona drift (the second of the two delivery
+    // sites). Committing the ack here is the mutation; the guidance is surfaced by
+    // the pure builder from this captured value.
+    const drift = personaDrift(nodeId);
+    let driftGuidance = null;
+    if (drift !== null) {
+        driftGuidance = drift.guidance;
+        commitPersonaAck(nodeId, drift.to);
+    }
+    return { yieldMsg, unreadDigest, driftGuidance };
+}
+/** Render the <feed> block PURELY: the live "awaiting" roster (a read) plus the
+ *  already-drained unread digest (from drainBearings). No cursor write here. */
+function feedBlock(nodeId, unreadDigest) {
     // Awaiting = active subscriptions whose publisher is still live (active|idle).
     const awaiting = subscriptionsOf(nodeId)
         .filter((s) => s.active)
         .map((s) => getNode(s.node_id))
         .filter((m) => m !== null && (m.status === 'active' || m.status === 'idle'));
     const lines = [];
-    lines.push(`Awaiting ${awaiting.length} node${awaiting.length === 1 ? '' : 's'}.`);
-    for (const m of awaiting)
-        lines.push(`  - ${m.name} (${m.node_id}) — ${m.status}`);
-    const cursor = readCursor(nodeId);
-    const entries = readInboxSince(nodeId, cursor);
-    if (entries.length > 0) {
-        writeCursor(nodeId, entries[entries.length - 1].ts);
-        lines.push('', coalesce(entries));
+    if (awaiting.length > 0) {
+        const n = awaiting.length;
+        const subj = n === 1 ? 'it is' : 'they are';
+        const pron = n === 1 ? 'it' : 'they';
+        const verb = n === 1 ? 'pushes' : 'push';
+        // State aliveness + the automatic wake at the source. Bare status ("— active")
+        // left earlier revives unsure whether the worker was really live, so they
+        // burned a turn on `feed read`/`feed peek` to confirm. Asserting it here
+        // removes the reason to check.
+        lines.push(`Awaiting ${n} node${n === 1 ? '' : 's'} — ${subj} alive and running right now, and will wake you the moment ${pron} ${verb}. The wake is automatic; nothing to check, poll, or verify.`);
+        for (const m of awaiting)
+            lines.push(`  - ${m.name} (${m.node_id}) — ${m.status}`);
+        lines.push('', unreadDigest ??
+            '(no unread reports yet — expected while they run: a worker leaves no pointer until it pushes, so an empty feed means still working, not stalled)');
     }
     else {
-        lines.push('', '(no unread reports)');
+        lines.push('Awaiting 0 nodes.');
+        lines.push('', unreadDigest ?? '(no unread reports)');
     }
     return `<feed>\n${lines.join('\n')}\n</feed>`;
 }
 // ---------------------------------------------------------------------------
 // buildReviveKickoff — assemble the full fresh-revive first message.
 // ---------------------------------------------------------------------------
-/** Build the auto-injected first message for a FRESH revive of `meta`. Reads
- *  the node's goal, roadmap, context dir, feed, and one-shot yield message off
- *  disk and frames them so the revived node can rebuild its bearings in one
- *  turn. Side effects: consumes the yield message and advances the feed cursor
- *  (both are "read" by surfacing them here). */
-export function buildReviveKickoff(meta) {
+/** 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 function buildReviveKickoff(meta, bearings) {
     const nodeId = meta.node_id;
-    // Consume the one-shot yield note first so it never shows in the dir listing.
-    const yieldMsg = consumeYieldMessage(nodeId);
     const parts = [
         `${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.',
     ];
-    const goal = readGoal(nodeId);
-    if (goal !== null && goal.trim() !== '') {
-        parts.push(`<goal file="${goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);
-    }
+    // The roadmap is the source of truth on a fresh revive: its frozen core holds
+    // the goal/exit criteria, its body the live plan the node kept current. The
+    // original spawn prompt (context/initial-prompt.md) is deliberately NOT injected
+    // — it lives on disk only as a log, and by now it is usually stale.
     const roadmap = readRoadmap(nodeId);
     parts.push(`<roadmap file="${roadmapPath(nodeId)}">\n${roadmap !== null && roadmap.trim() !== '' ? roadmap.trim() : '(no roadmap on disk yet)'}\n</roadmap>`);
     const files = listContextDir(nodeId);
     parts.push(`<context-dir path="${contextDir(nodeId)}">\n${files.length > 0 ? files.join('\n') : '(empty)'}\n</context-dir>`);
-    parts.push(feedBlock(nodeId));
-    parts.push(yieldMsg !== null
-        ? `<yield-message>\n${yieldMsg.trim()}\n</yield-message>`
+    parts.push(feedBlock(nodeId, bearings.unreadDigest));
+    parts.push(bearings.yieldMsg !== null
+        ? `<yield-message>\n${bearings.yieldMsg.trim()}\n</yield-message>`
         : '<yield-message/>');
-    parts.push('If there is work to do, perform it. Otherwise stop — `crtr push final "<result>"` ' +
-        'if the goal is met, or end your turn to stay dormant awaiting your workers.');
+    // A node that reports UP the spine (has subscribers awaiting its result)
+    // finishes with `push final`. A human-attended node (no subscribers — a root
+    // conversation working directly with the user) has no result to submit and
+    // must not be told to finish: it stays resident and keeps working with the
+    // user.
+    const reportsUp = subscribersOf(nodeId).length > 0;
+    parts.push(reportsUp
+        ? 'If there is work to do, perform it. Otherwise stop — `crtr push final "<result>"` ' +
+            'if the goal is met, or end your turn to stay dormant awaiting your workers.'
+        : 'If there is work to do, perform it. Otherwise end your turn — you are working ' +
+            'directly with the user, so stay available and continue the conversation when they ' +
+            'write back.');
+    // Persona-transition catch-up. If the node's mode/lifecycle was changed
+    // EXTERNALLY while it was dormant (e.g. a human ran `crtr node lifecycle` /
+    // `node promote --node` on it), it never saw the turn_end injector. drainBearings
+    // captured the guidance for its new persona and committed the ack (the second
+    // and only other delivery site); we just surface it. A clean fresh revive has
+    // no drift, so this is empty unless a real external change happened.
+    if (bearings.driftGuidance !== null) {
+        parts.push(`<persona-transition>\nYour role was changed while you were away. ${bearings.driftGuidance}\n</persona-transition>`);
+    }
     return parts.join('\n\n');
 }

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

@@ -1,23 +1,35 @@
-import type { NodeMeta, LaunchSpec, Mode } from '../canvas/index.js';
+import type { NodeMeta, LaunchSpec, Mode, Lifecycle } 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_CONTEXT_INTRO_PATH: string;
 export declare const CANVAS_COMMANDS_PATH: string;
+export declare const CANVAS_RESUME_PATH: string;
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), goal-capture (persist the first user message as the goal),
  *  passive-context (drain passive backlog as pre-text on the next message),
- *  commands (the /promote slash-command). All self-gate on CRTR_NODE_ID.
- *  goal-capture precedes passive-context so it reads the raw user text. */
+ *  context-intro (inject the <crtr-context> bearings block as its own session
+ *  message, once per brand-new chat), commands (the /promote slash-command),
+ *  resume (the /resume-node whole-canvas picker → `crtr node focus`).
+ *  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. */
 export declare function normalizeModel(model: string): string;
-/** Compose a node's full pi launch recipe from its persona. The two canvas
- *  extensions are always first; persona-declared extensions follow. */
-export declare function buildLaunchSpec(kind: string, mode: Mode, opts?: {
+/** Compose a node's full pi launch recipe from its persona. The system prompt
+ *  is composed from FOUR inputs: kind×mode (the persona body) plus lifecycle
+ *  (terminal/resident — the finish contract) and spine position (hasManager —
+ *  whether the push-up family is taught at all). Callers pass the authoritative
+ *  lifecycle + hasManager (`parent !== null`) so a polymorph/flip rebuilds the
+ *  prompt faithfully. The two canvas extensions are always first; persona-
+ *  declared extensions follow. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
+    lifecycle: Lifecycle;
+    hasManager: boolean;
     extraEnv?: Record<string, string>;
 }): {
     launch: LaunchSpec;
@@ -30,16 +42,18 @@ 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).
+ *  - fork start: pass `forkFrom` (absolute .jsonl path or partial uuid) to `--fork`
+ *    — pi COPIES that conversation into a NEW session for this node, then `prompt`
+ *    is delivered as the next message. One-shot at birth: the node thereafter
+ *    captures its OWN pi_session_file and revives by `--session` like any other.
+ *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path, preferred)
+ *    or `resumeSessionId` (bare uuid fallback) to `--session` (keeps conversation).
  *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
 export declare function buildPiArgv(meta: NodeMeta, opts?: {
     prompt?: string;
     resumeSessionId?: string;
+    resumeSessionPath?: string;
+    forkFrom?: string;
 }): PiInvocation;