@north-light/crouter 0.3.154

package/dist/core/runtime/kickoff.js

@@ -0,0 +1,289 @@
+// The revive kickoff — the message auto-injected as a node's first turn when it
+// comes back FRESH (a refresh-yield, or `node lifecycle revive --fresh`). The node's
+// in-memory context is gone, so this message IS its bearings: everything is
+// read from disk and framed so the node can rebuild and continue without a
+// round-trip. Resuming a saved conversation needs none of this (the
+// conversation already holds the context).
+//
+// Layout (the framing a revived node sees):
+//   <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> live wait state + unread/catch-up feed
+//   <yield-message>…</yield-message>       the note its prior self left on yield
+//
+// 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 (cleared when session_start confirms the revive).
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, readdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { contextDir, reportsDir, getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
+import { readRoadmap, roadmapPath } from './roadmap.js';
+import { buildWakeBearings } from './bearings.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
+// yield message (a note from the prior self to the revived self).
+// ---------------------------------------------------------------------------
+/** The goal file — the prompt/task a node was spawned with, persisted at birth
+ *  so a fresh revive can re-read its mandate. */
+export function goalPath(nodeId) {
+    return join(contextDir(nodeId), 'initial-prompt.md');
+}
+export function readGoal(nodeId) {
+    const p = goalPath(nodeId);
+    return existsSync(p) ? readFileSync(p, 'utf8') : 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 function writeGoal(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    mkdirSync(contextDir(nodeId), { recursive: true });
+    writeFileSync(goalPath(nodeId), body + '\n', 'utf8');
+}
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export function captureGoalIfAbsent(nodeId, text) {
+    const existing = readGoal(nodeId);
+    if (existing !== null && existing.trim() !== '')
+        return false;
+    const body = text.trim();
+    if (body === '')
+        return false;
+    writeGoal(nodeId, body);
+    return true;
+}
+/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
+ *  The goal-capture extension skips any input starting with this so a kickoff
+ *  prompt is never mistaken for a user's first mandate. */
+export const REVIVE_KICKOFF_SENTINEL = 'You have been revived fresh after a context refresh';
+/** Injected only when a broker cleanly persisted an aborted in-flight turn
+ * before a daemon restart. The transcript already carries the full picture, so
+ * this is a bare nudge — a longer explanation only destabilizes the resume. */
+export const RUNTIME_RESTART_CONTINUATION = 'continue';
+/** The yield-message file — a short note `crtr node yield` records for the next
+ *  fresh/cycling revive ("on wake, do X"). It remains durable through failed
+ *  launch attempts and is cleared only when session_start confirms a boot. */
+export function yieldMessagePath(nodeId) {
+    return join(contextDir(nodeId), 'yield-message.md');
+}
+export function writeYieldMessage(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    mkdirSync(contextDir(nodeId), { recursive: true });
+    writeFileSync(yieldMessagePath(nodeId), body + '\n', 'utf8');
+}
+/** Read the pending yield message without mutating its confirmation state. */
+export function readYieldMessage(nodeId) {
+    const p = yieldMessagePath(nodeId);
+    if (!existsSync(p))
+        return null;
+    const body = readFileSync(p, 'utf8').trim();
+    return body !== '' ? body : null;
+}
+/** Idempotently commit delivery of the yield message after a confirmed boot. */
+export function clearYieldMessage(nodeId) {
+    try {
+        rmSync(yieldMessagePath(nodeId));
+    }
+    catch { /* best-effort */ }
+}
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export function listContextDir(nodeId) {
+    const dir = contextDir(nodeId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).sort();
+}
+/** Capture revive bearings for `meta`: read the pending yield note, advance the
+ *  feed cursor past unread reports, and capture+commit external persona drift.
+ *  Revive paths call it once, then pass the result to the pure kickoff builder. */
+export function drainBearings(meta) {
+    const nodeId = meta.node_id;
+    // The note stays on disk until session_start confirms this launch.
+    const yieldMsg = readYieldMessage(nodeId);
+    // Drain the feed: read the physically ordered suffix after the cursor, then
+    // record its final entry so only later physical entries remain unread.
+    const cursorEntryId = readCursor(nodeId);
+    const entries = readInboxSince(nodeId, cursorEntryId);
+    let unreadDigest = null;
+    if (entries.length > 0) {
+        writeCursor(nodeId, entries.at(-1).entry_id);
+        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 };
+}
+// Fresh-revive catch-up bug: on a refresh-yield (resume:false) the old
+// conversation is gone AND the physical inbox cursor already covers everything
+// drained pre-yield, so the revived node loses sight of reports its
+// subscriptions pushed BEFORE the yield. The bodies are never lost — they persist
+// at reports/<ts>-<kind>.md forever — but a fresh revive needs a bounded index
+// that says history exists and how to expand it, not every path preloaded.
+const REPORT_HISTORY_SOURCE_CAP = 8;
+function reportKind(filename) {
+    return filename.match(/^[0-9]{8}T[0-9]{6}-(.+)\.md$/)?.[1] ?? 'report';
+}
+/** Condensed report-history index for each ACTIVE subscription of `nodeId` —
+ *  independent of publisher liveness, so a finished worker's history still
+ *  surfaces for catch-up. Each source carries only its count and newest report
+ *  ref; older refs stay one command away via `node inspect artifacts`. */
+function reportHistorySources(nodeId) {
+    const out = [];
+    for (const sub of subscriptionsOf(nodeId).filter((s) => s.active)) {
+        const dir = reportsDir(sub.node_id);
+        if (!existsSync(dir))
+            continue;
+        const files = readdirSync(dir)
+            .filter((f) => f.endsWith('.md'))
+            .sort() // YYYYMMDDTHHmmss-<kind>.md — lexical sort = chronological
+            .reverse(); // most recent first
+        if (files.length === 0)
+            continue;
+        const pub = getNode(sub.node_id);
+        out.push({
+            nodeId: sub.node_id,
+            name: pub?.name ?? sub.node_id,
+            count: files.length,
+            latest: files[0],
+        });
+    }
+    return out.sort((a, b) => b.latest.localeCompare(a.latest));
+}
+/** Render the <feed> block PURELY: the live "awaiting" roster (a read), the
+ *  already-drained unread digest (from drainBearings), and a progressive index
+ *  to on-disk report history. No cursor write. */
+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 = [];
+    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 explicitly, so there is
+        // no reason to check, poll, or verify separately.
+        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('Awaiting 0 nodes.');
+        lines.push('', unreadDigest ?? '(no unread reports)');
+    }
+    // Catch-up history. The unread digest above only covers what arrived after the
+    // physical cursor; on a refresh-revive it already covers everything drained
+    // pre-yield, so preserve the breadcrumb without preloading every old report.
+    const history = reportHistorySources(nodeId);
+    if (history.length > 0) {
+        const visible = history.slice(0, REPORT_HISTORY_SOURCE_CAP);
+        const hidden = history.length - visible.length;
+        const total = history.reduce((sum, h) => sum + h.count, 0);
+        lines.push('', `Report history on disk (collapsed): ${total} report${total === 1 ? '' : 's'} across ${history.length} subscribed node${history.length === 1 ? '' : 's'}. This is a catch-up index for reports your cursor already passed; read only what matters.`, ...visible.map((h) => {
+            const ref = `${h.nodeId}:reports/${h.latest}`;
+            return `  - ${h.name} (${h.nodeId}): ${h.count} report${h.count === 1 ? '' : 's'}; latest ${reportKind(h.latest)}: ${ref}`;
+        }), ...(hidden > 0 ? [`  - … ${hidden} more subscribed node${hidden === 1 ? '' : 's'} with reports hidden`] : []), 'Expand: `crtr canvas history read <ref>` for one listed report; `crtr node inspect artifacts <node-id> --type report` for that node\'s full report list; `crtr node inspect artifacts <node-id> --type inbox` for cursor-independent inbox history including full message bodies.');
+    }
+    return `<feed>\n${lines.join('\n')}\n</feed>`;
+}
+// ---------------------------------------------------------------------------
+// buildReviveKickoff — assemble the full fresh-revive first message.
+// ---------------------------------------------------------------------------
+/** 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, wakeReason) {
+    const nodeId = meta.node_id;
+    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.',
+    ];
+    // Wake provenance (Invariant B/D): when a scheduled bare self-alarm fired this
+    // revive, the <crtr-wake> block reframes the generic "you were revived" above
+    // into "a TIMER woke you" — placed right after the sentinel (so the kickoff
+    // still STARTS with REVIVE_KICKOFF_SENTINEL, which goal-capture keys on) and
+    // before the roadmap/disk bearings, so "why you woke" precedes "what to rebuild
+    // from". Only the daemon's bare-wake branch passes wakeReason.
+    if (wakeReason !== undefined)
+        parts.push(buildWakeBearings(wakeReason));
+    // 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);
+    const hasRoadmapBody = roadmap !== null && roadmap.trim() !== '';
+    parts.push(`<roadmap file="${roadmapPath(nodeId)}">\n${hasRoadmapBody ? roadmap.trim() : '(no roadmap on disk yet)'}\n</roadmap>`);
+    // With NO roadmap the kickoff above carries no mandate at all, and an
+    // amnesiac fresh boot just stops (and is auto-finalized by the stop-guard) —
+    // observed when the daemon relaunches a spawned-but-never-launched node
+    // (audit 2026-06-09, Bug 4: mq45b6ch-9ecc2f03), whose only mandate on disk IS
+    // the goal. Surface the goal then. When a roadmap exists it stays the sole
+    // source of truth (the goal is usually stale by comparison) — unchanged.
+    if (!hasRoadmapBody) {
+        const goal = readGoal(nodeId);
+        if (goal !== null && goal.trim() !== '') {
+            parts.push(`<goal file="${goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);
+        }
+    }
+    // The yield note is retained on disk until confirmed boot so a pre-session_start
+    // retry can replay it, but its addressable delivery is the inline block below.
+    const files = listContextDir(nodeId).filter((file) => file !== 'yield-message.md');
+    parts.push(`<context-dir path="${contextDir(nodeId)}">\n${files.length > 0 ? files.join('\n') : '(empty)'}\n</context-dir>`);
+    // Hidden applet/situation-origin ambient context (see situational-context.ts)
+    // is deliberately NOT injected here — this kickoff is the VISIBLE revive prompt.
+    // canvas-context-intro's session_start handler re-fires on every fresh/cycling
+    // revive (a new pi process boot) and re-injects buildContextIntro(), which
+    // already carries the sidecar as a hidden sibling of <crtr-bearings>; that seam
+    // covers this path, so duplicating it into the visible prompt would leak it.
+    parts.push(feedBlock(nodeId, bearings.unreadDigest));
+    parts.push(bearings.yieldMsg !== null
+        ? `<yield-message>\n${bearings.yieldMsg.trim()}\n</yield-message>`
+        : '<yield-message/>');
+    // 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 — pipe the result to `crtr push final` through a single-quoted heredoc " +
+            '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 config --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-prompt.d.ts

@@ -0,0 +1,8 @@
+/** The minimal static system prompt every node launches with — a thin launcher
+ *  frame keeping the `\n\nGuidelines:` anchor the `before_agent_start` substrate
+ *  hook (canvas-doc-substrate.ts) splices its `<memory kind="preference">` block
+ *  before. ALL runtime/spine/lifecycle/kind prompting now lives as gated builtin
+ *  memory docs (src/builtin-memory/), spliced in fresh every turn — this scaffold
+ *  must never duplicate that prose. Imported by launch.ts (its own systemPrompt)
+ *  and `sys prompt-review` so the two can never drift. */
+export declare const LAUNCH_SYSTEM_PROMPT: string;

package/dist/core/runtime/launch-prompt.js

@@ -0,0 +1,13 @@
+// launch-prompt.ts — the minimal static system-prompt scaffold, isolated from
+// launch.ts so CLI consumers (`sys prompt-review`) can import the exact string
+// boot uses WITHOUT pulling launch.ts's canvas-db reach (editorLabel et al.).
+// Pure: zero imports.
+/** The minimal static system prompt every node launches with — a thin launcher
+ *  frame keeping the `\n\nGuidelines:` anchor the `before_agent_start` substrate
+ *  hook (canvas-doc-substrate.ts) splices its `<memory kind="preference">` block
+ *  before. ALL runtime/spine/lifecycle/kind prompting now lives as gated builtin
+ *  memory docs (src/builtin-memory/), spliced in fresh every turn — this scaffold
+ *  must never duplicate that prose. Imported by launch.ts (its own systemPrompt)
+ *  and `sys prompt-review` so the two can never drift. */
+export const LAUNCH_SYSTEM_PROMPT = 'You are a node in the crtr canvas — an agentic runtime.\n\nGuidelines:\n' +
+    '- Use the crtr canvas and memory substrate according to injected context.';

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

@@ -0,0 +1,191 @@
+export { CANVAS_EXTENSIONS, CANVAS_STOPHOOK_PATH, CANVAS_INBOX_WATCHER_PATH, CANVAS_RECAP_PATH, CANVAS_GOAL_CAPTURE_PATH, CANVAS_PASSIVE_CONTEXT_PATH, CANVAS_CONTEXT_INTRO_PATH, CANVAS_DOC_SUBSTRATE_PATH, CANVAS_STRUCTURED_OUTPUT_PATH, CANVAS_BASH_VALVE_PATH, } from './canvas-extensions.js';
+import type { NodeMeta, LaunchSpec, Mode, Lifecycle } from '../canvas/index.js';
+import type { ModelProvider, ModelStrength, ScopeConfig } from '../../types.js';
+export { OPENAI_PROVIDER_ENV, configuredLadderProviders, inferPortableModelSelection } from './model-selection.js';
+export type { PortableModelSelection } from './model-selection.js';
+export interface EquivalentProviderModel {
+    fromProvider: ModelProvider;
+    toProvider: ModelProvider;
+    strength: ModelStrength;
+    model: string;
+}
+/** Map a concrete ladder model back to its provider×strength cell, then return
+ *  the other configured provider's model at the same strength. `failedProviders`
+ *  is per-turn state: once a provider has produced a retryable outage error, do
+ *  not bounce back to it or keep reattempting the same failed provider. */
+export declare function equivalentOtherProviderModel(currentModel: string, failedProviders?: ReadonlySet<ModelProvider>): EquivalentProviderModel | null;
+/** True when an explicit model token is QUALIFIED — a `<provider>/<model-id>`
+ *  or `<provider>/<tier>` raw token — the structural marker of a concrete exact
+ *  pick. Deliberately provider-agnostic: a real registry provider namespace
+ *  (`anthropic`, `openai-codex`, a user's own `amazon-bedrock`, …)
+ *  qualifies identically, so the rule never depends on a fixed provider
+ *  allowlist and never needs updating as providers are added. A bare tier
+ *  (`ultra`) or bare family alias (`opus`/`sonnet`/`haiku`) has no `/` and
+ *  stays unpinned. */
+export declare function isProviderPinnedModelToken(model: string): boolean;
+/** True when `model` is a PORTABLE ladder token — a bare strength/alias
+ *  (`ultra`, `normal`, `opus`, …) or a `anthropic|openai / strength` pair —
+ *  i.e. a form `normalizeModel` resolves through the ladders rather than
+ *  passing through as a concrete id. Portable tokens are safe to PERSIST as
+ *  defaults (`persistDefaultKindModel`): they re-resolve against whatever
+ *  ladder the running build ships, so they never freeze a stale concrete
+ *  model id to disk. Mirrors `normalizeModel`'s branch structure exactly. */
+export declare function isPortableModelToken(model: string): boolean;
+export declare function normalizeModel(model: string, ladders?: ScopeConfig['modelLadders']): string;
+/** The interleaved model-ladder cycle Alt+M / Alt+Shift+M walks: for each strength tier
+ *  from strongest to weakest, each offered provider before descending — anthropic/ultra,
+ *  openai/ultra, anthropic/strong, openai/strong, anthropic/medium, … Returns the
+ *  concrete `provider/id:thinking` ladder cells in that order. `providers` narrows the
+ *  cycle to the signed-in columns (`configuredLadderProviders`); an empty subset falls
+ *  back to every provider so the cycle can never go rungless. */
+export declare function interleavedLadderCycle(providers?: readonly ModelProvider[]): string[];
+/** The next model in the interleaved ladder cycle, starting from `currentSpec`
+ *  (a `provider/id:thinking` spec — pass `formatModelSpec(session.model,
+ *  session.thinkingLevel)`). `direction` is +1 (forward) or -1 (backward).
+ *
+ *  Rungs are matched on bare id AND thinking level first, so ladder cells that
+ *  share a bare model id (e.g. anthropic ultra=…:high vs strong=…:medium) don't
+ *  collapse onto each other; a bare-id-only match is the fallback. An off-ladder
+ *  current model — including a rung on a provider `providers` excludes — starts
+ *  the cycle at its top (the strongest offered rung). */
+export declare function nextLadderModel(currentSpec: string, direction?: 1 | -1, providers?: readonly ModelProvider[]): string;
+/** Compose a node's full pi launch recipe from the kind registry. The system
+ *  prompt is now a minimal static scaffold (`LAUNCH_SYSTEM_PROMPT`) — runtime/
+ *  spine/lifecycle/kind prose is spliced per-turn from gated builtin memory docs,
+ *  not baked in here. Launch KNOBS (model/tools/extensions) still come from the
+ *  kind registry (`resolveKindConfig`), keyed on the FULL kind string (top-level
+ *  or sub-kind). Model precedence, strongest to weakest:
+ *   1. Caller-supplied `opts.model` (durable on `meta.model_override`, re-passed
+ *      on every polymorph).
+ *   2. The kind's registered model — mode-aware: orchestrator mode prefers
+ *      `orchestratorModel`, falling back to `model`; base mode always uses
+ *      `model`.
+ *   3. Unset → pi default.
+ *  Callers pass the authoritative lifecycle + hasManager (`parent !== null`) so
+ *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
+ *  as-given — it is no longer persona-frontmatter-derived. The two canvas
+ *  extensions are always first; kind-declared extensions follow. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
+    lifecycle: Lifecycle;
+    hasManager: boolean;
+    extraEnv?: Record<string, string>;
+    model?: string;
+    /** The TARGET node's cwd — anchors the project-scope stack for kind/ladder
+     *  resolution. Defaults to this process's own cwd, which is correct only
+     *  when the caller IS resolving for itself; spawn/polymorph paths must
+     *  pass the node's own cwd (same rule as `readMergedLaunchConfig`). */
+    cwd?: string;
+    /** The TARGET node's profile id — REQUIRED for a profile's kind/ladder
+     *  overrides (e.g. a `/model` default persisted by
+     *  `persistDefaultKindModel`) to be honored. Defaults to the ambient
+     *  `CRTR_PROFILE_ID`, which is EMPTY for a front-door shell invocation —
+     *  exactly the path that creates the user's sessions — so callers that
+     *  know the node's profile must pass it explicitly (null = no profile). */
+    profileId?: string | null;
+    /** Carry an EXISTING node's pin verbatim through a rebuild that supplies
+     *  no NEW `--model` override (a polymorph/lifecycle/kind change, or a
+     *  fresh-root relaunch). When set (including `false`), this wins over the
+     *  token-shape derivation below — the pin is decided exactly once, at the
+     *  moment of an explicit user model change, from that change's RAW token;
+     *  every other rebuild must preserve it rather than re-infer it from
+     *  `opts.model`, which may be a portablized `model_override` whose shape
+     *  no longer reflects the original raw pick (e.g. a concrete pin that
+     *  happens to byte-equal a ladder tier cell). Leave undefined for genuine
+     *  first-spawn and for an explicit new `--model` override on
+     *  promote/config, where `opts.model`'s shape IS the raw token and
+     *  legitimately re-decides the pin. */
+    modelProviderPinned?: boolean;
+    /** Exact-consult launch: pass the captured `provider/id:thinking` spec
+     *  verbatim as `launch.model`, skipping `floorReviewModel`/`normalizeModel`
+     *  entirely (avoids any tier-collision reinterpretation). `opts.model` MUST
+     *  be defined when this is true. Sets `launch.modelExact = true`, which the
+     *  broker's launch-time/turn-time resolution paths must bypass every
+     *  fallback for and fail closed on unavailability. */
+    modelExact?: boolean;
+}): {
+    launch: LaunchSpec;
+    lifecycle: 'terminal' | 'resident';
+};
+export interface PiInvocation {
+    /** argv after the `pi` binary. */
+    argv: string[];
+    /** env to merge into the process. */
+    env: Record<string, string>;
+}
+/** Construct the pi invocation for a node.
+ *  - fresh start: pass `prompt` (the node's first user message), no resume.
+ *  - 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) to
+ *    `--session` (keeps conversation). `resumeSessionId` (a bare uuid) is
+ *    accepted here too, but revive.ts's `resumeArgs` never produces one —
+ *    `headlessBrokerHost`'s preflight (host.ts) fatally rejects a bare
+ *    `--session` id before ever spawning the broker, so a real revive only
+ *    ever resumes by path (or falls through to fresh when no path exists).
+ *  - refresh-yield: same `.jsonl` (`resumeSessionPath`) PLUS `newCycle` —
+ *    emits the valueless `--crtr-new-cycle` token alongside `--session`. The
+ *    broker resets the session-tree leaf and roots the new cycle as a fresh
+ *    sibling branch instead of starting a new file; the node re-reads its
+ *    roadmap exactly as a fresh launch would. */
+export declare function buildPiArgv(meta: NodeMeta, opts?: {
+    prompt?: string;
+    resumeSessionId?: string;
+    resumeSessionPath?: string;
+    forkFrom?: string;
+    newCycle?: boolean;
+}): PiInvocation;
+/** The pi-SDK launch config the headless broker drives an in-process engine
+ *  with — the structural inverse of `buildPiArgv`'s flag vocabulary. Each field
+ *  maps one of buildPiArgv's emitted flags back to its SDK option:
+ *  `-e`→`extensionPaths`, `-n`→`editorName`, `--fork`→`forkFrom`,
+ *  `--session`→`resumeSessionPath|resumeSessionId`, `--crtr-new-cycle`→
+ *  `newCycle`, `--model`→`model`, `--crtr-model-provider-pinned`→
+ *  `modelProviderPinned`, `--crtr-model-exact`→`modelExact`, `--tools`→`tools`,
+ *  `--append-system-prompt`→`appendSystemPromptPath`, the trailing
+ *  positional→`firstPrompt`. */
+export interface BrokerSdkConfig {
+    /** The node's pinned working dir (from `CRTR_NODE_CWD`, else `process.cwd()`). */
+    cwd: string;
+    /** Absolute `.js` extension paths (the canvas extensions). */
+    extensionPaths: string[];
+    /** Session label (`-n`). */
+    editorName?: string;
+    /** Spawn-time fork source (`--fork <path|id>`). */
+    forkFrom?: string;
+    /** Resume by absolute `.jsonl` path (preferred — `SessionManager.open`). */
+    resumeSessionPath?: string;
+    /** Resume by bare session uuid. Accepted by the generic builder, but no live
+     *  caller sets it — revive resumes by absolute path only, and the broker
+     *  preflight rejects a bare `--session`. */
+    resumeSessionId?: string;
+    /** A refresh-yield's marker: reset the session-tree leaf and root a fresh
+     *  cycle as a new branch of the SAME resumed `.jsonl`, instead of starting a
+     *  new session file (`--crtr-new-cycle`). Only meaningful alongside
+     *  `resumeSessionPath`; never set together with `forkFrom`. */
+    newCycle?: boolean;
+    /** Model spec, e.g. `anthropic/sonnet` (`--model`). */
+    model?: string;
+    /** A caller explicitly pinned `--model` to a provider; only a managed launch cooldown permits fallback. */
+    modelProviderPinned?: boolean;
+    /** Exact-consult launch (`--crtr-model-exact`): `model` must run verbatim —
+     *  every launch-time/turn-time fallback is bypassed and unavailability must
+     *  fail rather than substitute. */
+    modelExact?: boolean;
+    /** Tool allowlist (`--tools a,b,c` → `['a','b','c']`). */
+    tools?: string[];
+    /** `--append-system-prompt` arg — a file path in practice (pi's loader
+     *  resolves a path or literal text identically). */
+    appendSystemPromptPath?: string;
+    /** The fresh-start kickoff message (the trailing positional). */
+    firstPrompt?: string;
+}
+/** Translate a `PiInvocation` (the recipe `buildPiArgv` produced) into the SDK
+ *  config the broker hosts an engine with. This is the EXACT inverse of
+ *  `buildPiArgv` and must track its flag set 1:1 — co-located here so the two
+ *  never drift. Safe because `buildPiArgv` is the SOLE producer of these flags
+ *  (we own both ends). SIDE EFFECT: merges `inv.env` into `process.env` so the
+ *  in-process engine + the bound canvas extensions see the same env a forked pi
+ *  would (CRTR_NODE_ID, CRTR_SUBTREE, …). */
+export declare function piInvocationToSdkConfig(inv: PiInvocation): BrokerSdkConfig;