@north-light/crouter 0.3.154

package/dist/core/runtime/placement.js

@@ -0,0 +1,394 @@
+// placement.ts — the VIEWER REGISTRY + the model-over-driver tmux front door.
+//
+// After the broker-is-the-host cut the engine NEVER lives in a tmux pane: every
+// node is a detached `headlessBrokerHost` process that binds `view.sock`. A tmux
+// pane is only a surface-attach viewer of that broker, exactly like a web tab. So
+// the whole engine-in-pane placement machinery (hot-swap, resume-into-focus,
+// backstage relocation, remain-on-exit freeze, spread, node-row reconcile) is
+// gone. What remains is:
+//
+//   • The VIEWER REGISTRY — the `focuses` table, schema unchanged, now read as
+//     "node_id -> the node's one viewer %pane in `session`" (UNIQUE(node_id) =
+//     one viewer per node). focusOf/isFocused/focusByPane/focusedNodes/
+//     listFocuses read it (lazily GC'ing rows whose pane is gone or no longer
+//     carries this node's `@crtr_node` tag); registerViewerFocus writes it.
+//   • focus(nodeId) — ensure the broker engine is alive (injected reviver) +
+//     wait view.sock, then ensure the node's ONE viewer pane is forefront: reuse
+//     it wherever it already lives (switching sessions when needed), else open
+//     one beside the caller.
+//   • openViewerWindow / registerViewerFocus — the shared viewer-pane opener +
+//     row registrar used by BOTH spawn (a background viewer window) and focus.
+//   • tearDownNode / detachToBackground — close a node's viewer pane + row.
+//   • The chrome/viewer tmux re-exports (§2.1): placement stays the sanctioned
+//     model-over-driver so the §5.1 import-lint ("only placement.ts /
+//     tmux-chrome.ts import tmux.ts") holds — every other module reaches the
+//     driver verbs through here.
+import { getNode, fullName, deleteNode, listNodes, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
+import { nodeHasAssistantMessage, isNodeStreaming } from '../canvas/render.js';
+import { headlessBrokerHost } from './host.js';
+import { paneExists, paneLocation, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, respawnPaneSync, windowOfPane, renameWindow, } from './tmux.js';
+// The PURE tmux + broker-socket half now lives in placement-tmux.ts. placement
+// composes the viewer OPENER over openViewerPane (tmux) + registerViewerFocus
+// (the db write). viewerSplitEnv + waitForBrokerViewSocket are re-exported here
+// (below) so placement's existing importers (daemon runtime, handlers) are
+// unchanged.
+import { openViewerPane, viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
+import { newJobId } from './nodes.js';
+import { isPidAlive } from '../canvas/pid.js';
+// Placement is the sanctioned model-over-driver (§2.1): non-placement runtime /
+// command modules that legitimately need a raw driver verb get it from here, so
+// the §5.1 lint can hold "only placement.ts / tmux-chrome.ts import tmux.ts".
+// These are the chrome + viewer verbs that survive the cut (the engine-in-pane
+// verbs — respawnPane, respawnPaneDetached, swapPaneInPlace, breakPaneToSession,
+// joinPane, setWindowOption, setRemainOnExit — are deleted). `breakPane` +
+// `selectLayout` are FRESH minimal viewer-chrome helpers (not the deleted
+// engine-in-pane `breakPaneToSession`): `surface tmux-spread` breaks the caller's
+// viewer pane into its own window and tiles sibling viewers beside it.
+// `piCommand` + `paneCurrentPath` are KEPT: the sessionless surface-view system
+// (view-cycle.ts / view-run.ts) builds its pane commands with them, and the §5.1
+// import-lint forbids those commands importing tmux.ts directly — they must reach
+// the driver through placement. (They are NOT engine-in-pane; the design's
+// "nothing keeps" classification missed the view consumers.) `shellQuote` is
+// re-exported for the same reason — callers building the seam's expected
+// bundled-pi command string (e.g. the M1 seam test) need the identical quoting
+// piCommand uses internally, without importing tmux.ts directly.
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, installTmuxBindings, 
+// Compile seam for viewer.ts, which still calls installMenuBinding();
+// deleted when the attach unit imports installTmuxBindings directly.
+installTmuxBindings as installMenuBinding, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
+// ---------------------------------------------------------------------------
+// Viewer registry reads — COMPOSE over the canvas focuses table (§2.3/§4).
+//
+// placement is the front door for "which nodes have a viewer on screen"; the SQL
+// lives in the canvas layer (canvas/focuses.ts) and placement just reads it. A
+// node has at most one viewer (UNIQUE node_id), so focusOf returns a single row.
+//
+// GC is lazy on read: a row whose viewer pane no longer exists (the user closed
+// the window, the attach client died) is pruned the next time it is read, so the
+// registry self-heals without a sweeper.
+// ---------------------------------------------------------------------------
+/** Prune a viewer row whose pane is gone; return it iff its pane is still live. */
+function liveOrPrune(f) {
+    if (f === null)
+        return null;
+    if (f.pane !== null && !paneExists(f.pane)) {
+        closeFocusRow(f.focus_id);
+        return null;
+    }
+    return f;
+}
+/** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
+export function focusOf(nodeId) {
+    return liveOrPrune(getFocusByNode(nodeId));
+}
+/** Does this node have a live viewer on screen? */
+export function isFocused(nodeId) {
+    return focusOf(nodeId) !== null;
+}
+/** The viewer realized by a given pane (`%id`), or null. */
+export function focusByPane(pane) {
+    return liveOrPrune(getFocusByPane(pane));
+}
+/** The set of node ids that currently have a live viewer. */
+export function focusedNodes() {
+    return new Set(listFocuses().map((f) => f.node_id));
+}
+/** Every live viewer row (GC'ing any whose pane has gone). */
+export function listFocuses() {
+    const live = [];
+    for (const f of listFocusRows()) {
+        if (liveOrPrune(f) !== null)
+            live.push(f);
+    }
+    return live;
+}
+function newFocusId() {
+    return `f-${newJobId()}`;
+}
+/** Register a `crtr surface attach` VIEWER pane as the node's one viewer focus row.
+ *  UNIQUE(node_id) ⇒ one viewer per node: returns
+ *  the existing row (no insert) when the pane or the node is already registered.
+ *  `window` is accepted for the call contract (spawn passes it) but not stored —
+ *  the focuses table keys on pane + session only. The attach client self-tags the
+ *  pane `@crtr_node` on connect, so `nodeInPane` resolves it either way. */
+export function registerViewerFocus(nodeId, pane, session, window) {
+    void window;
+    const byPane = getFocusByPane(pane);
+    if (byPane !== null)
+        return byPane;
+    const byNode = getFocusByNode(nodeId);
+    if (byNode !== null)
+        return byNode;
+    const focusId = newFocusId();
+    openFocusRow(focusId, pane, session, nodeId);
+    return getFocusById(focusId);
+}
+/** Open a surface-attach viewer for `nodeId` and register its viewer focus row —
+ *  the shared opener used by `focus` (a split beside the caller) and by a --root
+ *  spawn (a fresh window in the caller's current session). Wraps `ensureSession`
+ *  + `openNodeWindow`/`splitWindow` + `registerViewerFocus`. The attach client
+ *  connects to the node's `view.sock` and renders/drives the live broker engine
+ *  — it NEVER launches the engine (the one-writer invariant; the caller ensures
+ *  the broker is alive first). Returns the registered viewer row, or null if tmux
+ *  refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
+ *      open-beside-the-caller path); `session` is then only a fallback. */
+export function openViewerWindow(nodeId, session, opts = {}) {
+    const opened = openViewerPane(nodeId, session, opts);
+    if (opened === null)
+        return null;
+    return registerViewerFocus(nodeId, opened.pane, opened.session, opened.window);
+}
+// ---------------------------------------------------------------------------
+// focus — the front door for `surface node focus` / `surface node cycle` / nav (§A.4)
+// ---------------------------------------------------------------------------
+/** Bring a node's ONE viewer pane forefront (§A.4). Every node is a detached
+ *  broker, so there is no engine pane to swap into the caller's viewport — focus
+ *  instead ensures the node's single surface-attach viewer is on screen beside (or
+ *  navigated to) the caller:
+ *    (a) ensure the broker ENGINE is alive (idempotent injected reviver) and its
+ *        view.sock is ACCEPTING (closes the cold-start race against attach's
+ *        single connect) — without this the freshly-opened viewer would exit
+ *        "no broker".
+ *    (b) `--new-pane` → always a fresh viewer beside the caller (e.g. two
+ *        different nodes side by side); drop any prior viewer first (UNIQUE).
+ *    (c) the node already has a live viewer ⇒ navigate to it in place
+ *        (switchClient+selectWindow+selectPane), including when it lives in a
+ *        different session. The viewer's established spatial home wins over
+ *        opening or moving a duplicate beside the caller.
+ *    (d) no live viewer ⇒ open one beside the caller and register the row.
+ *
+ *  crtr is tmux-only: with no caller pane there is no viewport to open and no
+ *  non-tmux fallback — report not-focused. */
+/** After a viewer pane is opened/moved beside the caller, make it the ACTIVE
+ *  pane and rebalance its window's panes to an even side-by-side layout — so
+ *  picking a node (e.g. from the alt+g graph) lands the keyboard on the fresh
+ *  viewer and the panes are evenly sized again, not halved. Best-effort. */
+function surfaceNewPane(pane) {
+    const win = paneLocation(pane)?.window ?? null;
+    if (win !== null)
+        selectLayout(win, 'even-horizontal');
+    selectPane(pane);
+}
+export async function focus(nodeId, opts) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { focused: false, session: null, inPlace: false, revived: false };
+    const callerPane = opts.pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (callerPane === undefined || callerPane === '') {
+        return { focused: false, session: null, inPlace: false, revived: false };
+    }
+    // (a) Ensure the broker engine is alive + its view.sock accepts. Capture prior
+    //     liveness so the result reports whether THIS focus had to launch it.
+    const wasAlive = isPidAlive(meta.pi_pid ?? null);
+    const revivedLaunch = opts.revive(nodeId);
+    const revived = !wasAlive;
+    if (!(await waitForBrokerViewSocket(nodeId, revivedLaunch?.launch?.exited))) {
+        return { focused: false, session: null, inPlace: false, revived };
+    }
+    // focus always opens BESIDE the caller pane, so `fallbackSession` is only the
+    // session name openViewerWindow falls back to if it cannot read the freshly
+    // split pane's location — the caller's own session.
+    const callerSession = paneLocation(callerPane)?.session ?? null;
+    const fallbackSession = callerSession ?? '';
+    // (b0) --in-place → the CALLER pane BECOMES this node's viewer, replacing
+    //      whatever it showed (the attach subagent scroll+swap: ↓ into the reports
+    //      roster, Enter dives into that child right here, no new split). This
+    //      re-execs the caller pane via `respawn-pane -k`, so it MUST be driven
+    //      from OUTSIDE that pane's process tree (the viewer shells this through
+    //      `tmux run-shell`, never a direct child) — else the respawn kills its own
+    //      driver mid-call. Move the child's viewer here if it had one elsewhere
+    //      (UNIQUE one-viewer-per-node) and drop the caller pane's prior viewer row
+    //      (that node's broker keeps running headless, reconnectable by a later
+    //      focus). The respawned `crtr surface attach` replays scrollback from the
+    //      welcome snapshot and self-tags the pane `@crtr_node`.
+    if (opts.inPlace === true) {
+        const prior = focusOf(nodeId);
+        if (prior !== null) {
+            if (prior.pane !== null && prior.pane !== callerPane && paneExists(prior.pane))
+                closePane(prior.pane);
+            closeFocusRow(prior.focus_id);
+        }
+        const here = getFocusByPane(callerPane);
+        if (here !== null && here.node_id !== nodeId)
+            closeFocusRow(here.focus_id);
+        // Clear the stale tag before respawn so it never names the wrong node during
+        // the gap before the fresh attach re-tags on connect.
+        try {
+            setPaneOption(callerPane, '@crtr_node', '');
+        }
+        catch { /* best-effort */ }
+        const window = windowOfPane(callerPane);
+        // Continuity: the fresh viewer highlights the previously open node, which
+        // becomes visible in its self-excluding roster after the swap.
+        const priorNodeId = here?.node_id;
+        const env = priorNodeId === undefined
+            ? viewerSplitEnv()
+            : { ...viewerSplitEnv(), CRTR_ATTACH_ROSTER: priorNodeId };
+        const ok = respawnPaneSync({ pane: callerPane, cwd: meta.cwd, env, command: `crtr surface attach to ${nodeId}` });
+        if (ok) {
+            if (window !== null)
+                renameWindow(window, fullName(meta));
+            registerViewerFocus(nodeId, callerPane, callerSession, window);
+        }
+        return { focused: ok, session: callerSession, inPlace: true, revived };
+    }
+    // (b) --new-pane → always a fresh viewer beside the caller. Drop any prior
+    //     viewer this node holds elsewhere (UNIQUE(node_id): one viewer per node).
+    if (opts.newPane === true) {
+        const prior = focusOf(nodeId);
+        if (prior !== null) {
+            if (prior.pane !== null && paneExists(prior.pane))
+                closePane(prior.pane);
+            closeFocusRow(prior.focus_id);
+        }
+        const opened = openViewerWindow(nodeId, fallbackSession, { cwd: meta.cwd, besidePane: callerPane });
+        if (opened === null)
+            return { focused: false, session: null, inPlace: false, revived };
+        if (opened.pane !== null)
+            surfaceNewPane(opened.pane);
+        return { focused: true, session: opened.session, inPlace: false, revived };
+    }
+    // (c) Reuse / move the node's one live viewer — but ONLY a pane that still
+    //     carries THIS node's `@crtr_node` tag. `paneExists` is not enough: the
+    //     front-door root registers the user's own terminal as its viewer pane and
+    //     runs `crtr surface attach` inline; on a clean detach the pane returns to the
+    //     user's shell (attach clears the tag) yet the pane — and the row — survive,
+    //     and a reused pane carries some OTHER node's tag. Navigating to / closing
+    //     such a pane would strand the user on (or kill) their shell. So verify the
+    //     tag names this node; on mismatch the row is stale → prune it and fall
+    //     through to open a fresh viewer beside the caller.
+    const existing = focusOf(nodeId);
+    if (existing !== null && existing.pane !== null) {
+        if (getPaneOption(existing.pane, '@crtr_node') === nodeId) {
+            const loc = paneLocation(existing.pane);
+            if (loc !== null) {
+                // Navigate to the viewer wherever it already lives. For a cross-session
+                // target, switch-client carries this tmux client to that session; for a
+                // same-session target it is an idempotent no-op. Never destroy and reopen
+                // a viewer merely because its established pane lives in another session.
+                switchClient(loc.session);
+                selectWindow(loc.session, loc.window);
+                selectPane(existing.pane);
+                return { focused: true, session: loc.session, inPlace: true, revived };
+            }
+            // The row names a pane that vanished between focusOf() and paneLocation().
+            // Prune it and fall through to opening the node's one viewer beside caller.
+            closeFocusRow(existing.focus_id);
+        }
+        else {
+            // Pane survived but no longer hosts this node's viewer (clean detach left
+            // the user's shell, or the pane was reused) — drop the stale row only; do
+            // NOT closePane (it is the user's shell / another node's viewer).
+            closeFocusRow(existing.focus_id);
+        }
+    }
+    // (d) No live viewer → open one beside the caller and register the row.
+    const opened = openViewerWindow(nodeId, fallbackSession, { cwd: meta.cwd, besidePane: callerPane });
+    if (opened === null)
+        return { focused: false, session: null, inPlace: false, revived };
+    if (opened.pane !== null)
+        surfaceNewPane(opened.pane);
+    return { focused: true, session: opened.session, inPlace: false, revived };
+}
+// ---------------------------------------------------------------------------
+// Teardown / detach — close a node's viewer pane + row
+// ---------------------------------------------------------------------------
+/** Tear a node off its viewer (close/reset/cancel teardown). The broker engine
+ *  is killed by its own host teardown over view.sock — this only closes the
+ *  on-screen viewer: kill its pane (the window collapses once its last pane goes)
+ *  and drop its registry row. Best-effort tmux; the DB write always lands. No-op
+ *  when the node has no viewer. */
+export function tearDownNode(nodeId, keepPane) {
+    const f = focusOf(nodeId);
+    if (f === null)
+        return; // no viewer (focusOf already GC'd a gone one)
+    // `keepPane` is a BORROWED pane crtr did not create — the front-door root's
+    // viewer runs inside the user's own pre-existing shell pane (bootRoot registers
+    // that shell pane as the viewer focus). Killing it here would take the user's
+    // shell down with the node, closing the whole tmux pane on a plain ctrl+c
+    // detach. crtr must never kill a pane it merely borrowed: drop the row, let the
+    // pane fall back to its shell when the viewer process exits.
+    if (f.pane !== null && f.pane !== keepPane && paneExists(f.pane))
+        closePane(f.pane);
+    closeFocusRow(f.focus_id);
+}
+/** Detach a node from the foreground (the `node lifecycle demote --detach` / Alt+C → D
+ *  half). Every node is a headless broker — the only thing on screen is its
+ *  surface-attach viewer pane — so "detach" means STOP FOREGROUNDING it: close the
+ *  viewer pane (and drop its row) and leave the broker engine running untouched,
+ *  reconnectable by a later `focus`. `pane` is the authoritative pane the caller
+ *  acts on (the Alt+C menu's `#{pane_id}`); falls back to the node's registered
+ *  viewer pane. No-op (false) when there is no live viewer pane to close. */
+export function detachToBackground(nodeId, pane) {
+    const viewer = pane ?? focusOf(nodeId)?.pane ?? null;
+    if (viewer === null || !paneExists(viewer))
+        return false;
+    const f = focusByPane(viewer);
+    if (f !== null)
+        closeFocusRow(f.focus_id);
+    const closed = closePane(viewer);
+    // A node the user detached from that never produced any AI output is a useless
+    // shell taking up graph + disk space — reap it (engine + row + dir) outright
+    // rather than leaving an empty broker running headless off-screen.
+    reapIfEmpty(nodeId);
+    return closed;
+}
+// ---------------------------------------------------------------------------
+// Reaping empty nodes (no AI output) on close / detach
+// ---------------------------------------------------------------------------
+/** Is this node an EMPTY SHELL right now — a node whose engine never produced an
+ *  assistant message? Such nodes are pure dead weight on the graph. A node
+ *  actively generating its FIRST turn is NOT empty (its output just hasn't landed
+ *  on disk yet), so streaming nodes are spared. */
+function isEmptyNode(nodeId) {
+    const m = getNode(nodeId);
+    if (m === null)
+        return false;
+    if (isNodeStreaming(nodeId))
+        return false;
+    return !nodeHasAssistantMessage(m.pi_session_file);
+}
+/** Reap `nodeId` IFF it is an empty shell (see {@link isEmptyNode}): tear down its
+ *  broker engine, close any viewer, and hard-delete its row (edges cascade) + dir.
+ *  The user closing or detaching from a node that never said anything wants it
+ *  GONE, not parked as a canceled husk — except an OPEN managed worktree keeps
+ *  its node identity so the worktree remains owned and can later be closed.
+ *  Returns true when it reaped. No-op (false) on a node that produced output,
+ *  is mid-first-turn, owns an open managed worktree, or no longer exists. */
+export function reapIfEmpty(nodeId, keepPane) {
+    const meta = getNode(nodeId);
+    if (meta?.managed_worktree?.state === 'open' || !isEmptyNode(nodeId))
+        return false;
+    headlessBrokerHost.teardown(nodeId);
+    tearDownNode(nodeId, keepPane);
+    return deleteNode(nodeId).deleted;
+}
+/** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
+ *  behind `crtr canvas prune --empty`, for the husks that accumulated before
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), nodes
+ *  mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a running
+ *  engine is the daemon's domain and may have output not yet persisted, so bulk
+ *  GC never kills one (the per-action {@link reapIfEmpty} does, since the user
+ *  explicitly closed/detached that node). `dryRun` reports candidates without
+ *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+export function reapEmptyNodes(opts = {}) {
+    const dryRun = opts.dryRun ?? false;
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const reaped = [];
+    for (const row of listNodes()) {
+        const id = row.node_id;
+        const meta = getNode(id);
+        if (id === selfId || isPidAlive(row.pi_pid) || meta?.managed_worktree?.state === 'open' || !isEmptyNode(id))
+            continue;
+        if (!dryRun) {
+            headlessBrokerHost.teardown(id);
+            tearDownNode(id);
+            if (!deleteNode(id).deleted)
+                continue;
+        }
+        reaped.push(id);
+    }
+    return reaped;
+}

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

@@ -0,0 +1,44 @@
+import { type NodeMeta } from '../canvas/index.js';
+export interface PromoteResult {
+    meta: NodeMeta;
+    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 an orchestrator (mode→orchestrator), optionally
+ *  specializing its kind (e.g. a `general` worker becoming a
+ *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
+ *  re-promoting just rewrites the spec. Seeds a roadmap SCAFFOLD if absent (a
+ *  boss with no map is a failure mode) — no goal is forced here; authoring the
+ *  goal + roadmap is the node's next act. The transition guidance is injected
+ *  centrally by the persona injector at the next turn boundary, not returned. */
+export declare function promote(nodeId: string, opts?: {
+    kind?: string;
+    resident?: boolean;
+    model?: string;
+}): PromoteResult;
+export interface YieldResult {
+    meta: NodeMeta;
+    /** True iff `promote:true` was passed — a plain yield never flips mode. */
+    promoted: boolean;
+    /** Always true on success — the node will refresh-revive on its next stop. */
+    willRefresh: boolean;
+}
+/** Request a refresh-yield: discard in-memory context and revive fresh, mode
+ *  and lifecycle UNCHANGED, against the roadmap if one exists else the
+ *  original goal (`buildReviveKickoff` falls back to it). A plain yield is
+ *  always mode-preserving — a base node comes back base, still working the
+ *  same task hands-on. Pass `promote:true` to ALSO become an orchestrator in
+ *  the same refresh (the one-step form of yield + promote), which rides the
+ *  same path `crtr node promote` would — mode flips to orchestrator and a
+ *  roadmap scaffold is seeded. Sets intent='refresh'; the stophook shuts the
+ *  process down on the next stop and the daemon revives it fresh. */
+export declare function requestYield(nodeId: string, opts?: {
+    kind?: string;
+    model?: string;
+    promote?: boolean;
+}, deps?: {
+    ensure?: () => void;
+}): YieldResult;

package/dist/core/runtime/promote.js

@@ -0,0 +1,176 @@
+// Promotion — the worker→orchestrator polymorph (mode→orchestrator).
+//
+// Two stages:
+//   1. Promotion → mode flips to orchestrator (mid-turn). This call flips the
+//      node's mode and (optionally) its KIND, REWRITES its launch spec to that
+//      kind's orchestrator persona (so the next revive comes back as that
+//      orchestrator), and seeds a roadmap scaffold.
+//      The transition guidance the node needs is injected CENTRALLY by the
+//      persona injector (runtime/persona.ts) at the turn boundary — promote()
+//      itself no longer returns or hand-emits guidance.
+//   2. Refresh → persona swap (permanent). On the next fresh revive the node
+//      starts with the orchestrator system prompt baked in (because the launch
+//      spec now says orchestrator). The injected guidance bridges until then.
+//
+// Mode and lifecycle are ORTHOGONAL: promotion flips mode only. Lifecycle stays
+// whatever it was (a promoted child is terminal/orchestrator — still reports up
+// + reaps) unless the caller passes `resident:true` to also make it resident.
+//
+// Trigger is persistence-need (deliberate, or a refresh-yield with open work),
+// never the mere act of spawning a child.
+import { getNode, updateNode } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+import { buildLaunchSpec } from './launch.js';
+import { hasRoadmap, seedRoadmap, roadmapPath } from './roadmap.js';
+import { readGoal, goalPath } from './kickoff.js';
+/** Shared reshape machinery: rewrite kind and/or model tier — and, when the
+ *  caller supplies them, mode/lifecycle — by rebuilding the launch spec so the
+ *  change is durable across a future revive. MODE-PRESERVING by default (omit
+ *  `mode`/`lifecycle` and the node's own current values carry through) — this
+ *  is what a plain `crtr node yield --kind/--model` reshape rides, with no
+ *  mode flip and no roadmap seeding. `promote()` below is a thin wrapper that
+ *  also forces mode→orchestrator and seeds the roadmap. */
+function reshapeNode(nodeId, opts = {}, beforePersist) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    // The node may specialize as it reshapes; default to its current kind.
+    const targetKind = opts.kind ?? node.kind;
+    // ...and may raise/change its model tier; default to its current pin (so a
+    // reshape with no --model preserves whatever it was running on).
+    const targetModel = opts.model ?? node.model_override ?? undefined;
+    const targetMode = opts.mode ?? node.mode;
+    const targetLifecycle = opts.lifecycle ?? node.lifecycle;
+    // Rewrite the launch spec to the target kind/mode's persona so the *next*
+    // revive comes back as this exact shape (polymorph stage 2). nodeEnv reads
+    // meta.{kind,mode}, so CRTR_KIND/CRTR_MODE flip immediately for the live
+    // process's children too.
+    const { launch } = buildLaunchSpec(targetKind, targetMode, {
+        lifecycle: targetLifecycle,
+        hasManager: node.parent !== null,
+        // A model tier chosen on this call (opts.model) overrides the persona
+        // default and is persisted below; absent one, the existing pin carries
+        // across the polymorph (the persona default is recomputed fresh for
+        // targetKind).
+        model: targetModel,
+        // opts.model given — an explicit new pick — lets buildLaunchSpec re-decide
+        // the pin from ITS raw shape (undefined here). No opts.model — targetModel
+        // just re-supplies the current value for resolution, not a new user
+        // choice — so carry the node's existing pin verbatim instead.
+        modelProviderPinned: opts.model === undefined ? node.launch?.modelProviderPinned : undefined,
+        // Resolve kind/ladder config against the NODE's own cwd + profile, not
+        // this process's ambient scope.
+        cwd: node.cwd,
+        profileId: node.profile_id,
+    });
+    // Promotion seeds after its target launch has been built but before the
+    // mutation is persisted, preserving the original promote() failure order.
+    beforePersist?.();
+    // If the handle is still the spawn-time kind default (name === old kind),
+    // carry it to the new kind so the "name === kind ⇒ default, drop it" invariant
+    // in fullName() holds across a kind change. Otherwise a node spawned `general`
+    // (name="general") that reshapes to `plan` would surface a stale "general"
+    // handle in front of its real description.
+    const carriesDefaultHandle = node.name === node.kind && targetKind !== node.kind;
+    return updateNode(nodeId, {
+        kind: targetKind,
+        mode: targetMode,
+        lifecycle: targetLifecycle,
+        launch,
+        ...(carriesDefaultHandle ? { name: targetKind } : {}),
+        // Persist a newly-chosen tier so it is durable across future revives; omit
+        // when unchanged so the existing pin (or persona default) stands.
+        ...(opts.model !== undefined ? { model_override: opts.model } : {}),
+    });
+}
+/** Promote a node to an orchestrator (mode→orchestrator), optionally
+ *  specializing its kind (e.g. a `general` worker becoming a
+ *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
+ *  re-promoting just rewrites the spec. Seeds a roadmap SCAFFOLD if absent (a
+ *  boss with no map is a failure mode) — no goal is forced here; authoring the
+ *  goal + roadmap is the node's next act. The transition guidance is injected
+ *  centrally by the persona injector at the next turn boundary, not returned. */
+export function promote(nodeId, opts = {}) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    // Flip mode→orchestrator + kind + launch spec via the shared reshape.
+    // Lifecycle is independent: only set resident when the caller asked for it
+    // (the common self-promotion stays terminal/orchestrator — it still reports
+    // up + reaps). Seed a barebones roadmap scaffold after the target launch is
+    // valid but before persisting the promotion. Pre-fill its Goal from the
+    // node's goal doc when present (set at spawn, or captured from the first user
+    // message); the node fleshes out the body next, guided by the kind's roadmap
+    // memory doc dumped below.
+    let roadmapWritten = false;
+    const meta = reshapeNode(nodeId, {
+        ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+        ...(opts.model !== undefined ? { model: opts.model } : {}),
+        mode: 'orchestrator',
+        lifecycle: opts.resident === true ? 'resident' : node.lifecycle,
+    }, () => {
+        if (!hasRoadmap(nodeId)) {
+            const goal = readGoal(nodeId);
+            seedRoadmap(nodeId, goal !== null && goal.trim() !== '' ? { goal: goal.trim() } : {});
+            roadmapWritten = true;
+        }
+    });
+    return {
+        meta,
+        roadmapWritten,
+        roadmapPath: roadmapPath(nodeId),
+        goalPath: goalPath(nodeId),
+    };
+}
+/** Request a refresh-yield: discard in-memory context and revive fresh, mode
+ *  and lifecycle UNCHANGED, against the roadmap if one exists else the
+ *  original goal (`buildReviveKickoff` falls back to it). A plain yield is
+ *  always mode-preserving — a base node comes back base, still working the
+ *  same task hands-on. Pass `promote:true` to ALSO become an orchestrator in
+ *  the same refresh (the one-step form of yield + promote), which rides the
+ *  same path `crtr node promote` would — mode flips to orchestrator and a
+ *  roadmap scaffold is seeded. Sets intent='refresh'; the stophook shuts the
+ *  process down on the next stop and the daemon revives it fresh. */
+export function requestYield(nodeId, opts = {}, deps = {}) {
+    const ensure = deps.ensure ?? ensureDaemon;
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    // --kind/--model combine with either form. With --promote, they ride the
+    // promote() path (mode flips to orchestrator + roadmap seeded). Without it,
+    // they still apply but MODE-PRESERVINGLY via the shared reshape — no mode
+    // flip, no roadmap seeding. "promoted" is true iff the caller asked for it
+    // (even if the node was already an orchestrator — a no-op reshape, not an
+    // error), never inferred from the node's prior mode.
+    const reshaping = opts.kind !== undefined || opts.model !== undefined;
+    let promoted = false;
+    if (opts.promote === true) {
+        promote(nodeId, {
+            ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+            ...(opts.model !== undefined ? { model: opts.model } : {}),
+        });
+        promoted = true;
+    }
+    else if (reshaping) {
+        reshapeNode(nodeId, {
+            ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+            ...(opts.model !== undefined ? { model: opts.model } : {}),
+        });
+    }
+    // The refresh-revive is the DAEMON's job: the stophook shuts this broker down
+    // on its next stop, and crtrd then sees the dead pid + intent='refresh' and
+    // relaunches it fresh. That handoff is silent if the daemon isn't running — the
+    // broker exits and nothing ever revives it (the viewer redials its view.sock
+    // for ~30s and reports "broker gone"). So ensure the supervisor is alive HERE,
+    // before we arm the yield — the same best-effort ensure spawn/recycle do, on
+    // the one other path that hands a node off to the daemon. Runs in the fresh
+    // `crtr node yield` subprocess, so it always uses current dist (never a stale
+    // in-process hook). Injectable for the regression test that locks in this
+    // ensure (default = ensureDaemon).
+    ensure();
+    // Mark the intent; the stophook enacts the shutdown, the daemon the revive.
+    transition(nodeId, 'yield');
+    const meta = getNode(nodeId);
+    return { meta, promoted, willRefresh: true };
+}

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

@@ -0,0 +1,8 @@
+/** Ask pi headlessly for a concise briefing of `conversation`, async. Invokes
+ *  `onRecap` with the parsed string on success, or never (silent) on any
+ *  failure — non-zero exit, timeout, empty/garbled output. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads stdin,
+ *  and execFile's default stdin is an OPEN pipe that never closes, so without
+ *  this pi blocks waiting for EOF and the call exits non-zero (the same gotcha
+ *  naming.ts documents). */
+export declare function generateRecap(conversation: string, onRecap: (briefing: string) => void, liveModel?: string, roadmap?: string): void;