@north-light/crouter 0.3.154

package/dist/core/runtime/launch.js

@@ -0,0 +1,442 @@
+// The launch spec — how a node becomes (or comes back as) a running pi process.
+//
+// pi-only. No claude branch — we are a super-opinionated system. A node's
+// LaunchSpec (persisted in meta.json) is the canonical recipe the daemon
+// replays to revive it faithfully: `--session <path>` (the saved conversation's
+// absolute .jsonl) to wake a done/idle node — a refresh-yield reuses the SAME
+// path plus `--crtr-new-cycle`, resetting the session tree's leaf and rooting a
+// fresh cycle as a new branch rather than starting a new file.
+// The spec is rewritten on every polymorph (base→orchestrator) so a node
+// always comes back as its *current* self.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readMergedLaunchConfig } from '../config.js';
+import { LAUNCH_SYSTEM_PROMPT } from './launch-prompt.js';
+import { nodeEnv } from './nodes.js';
+import { editorLabel } from '../canvas/index.js';
+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 { nodeDir } from '../canvas/paths.js';
+import { CANVAS_EXTENSIONS, mergeCanvasExtensions, assertMandatoryCanvasExtensions } from './canvas-extensions.js';
+import { modelLadders, defaultProvider, STRENGTH_ALIASES, MODEL_PROVIDER_KEYS, MODEL_STRENGTHS, THINKING_SUFFIXES, stripThinkingSuffix, } from './model-selection.js';
+// The pure model-selection primitives live in `model-selection.js` so CLI-side
+// consumers (`sys setup`) can resolve a portable selection without pulling this
+// file's openDb-reaching graph. Re-exported here so existing importers of these
+// launch.ts symbols keep working.
+export { OPENAI_PROVIDER_ENV, configuredLadderProviders, inferPortableModelSelection } from './model-selection.js';
+// ---------------------------------------------------------------------------
+// Two-axis model resolution: (provider × strength) → concrete `model:thinking`.
+//
+// A persona declares ONE `model:` field valued `provider/strength` (e.g.
+// `openai/strong`, `anthropic/light`). The provider is a fixed per-persona
+// property; the caller/persona thinks only in strength; the concrete model id
+// AND the thinking level both fall out of the per-provider ladder below. The
+// ladder itself and the default provider are user-configurable in config.json;
+// pi accepts the `:thinking` suffix on `--model` (off,minimal,low,medium,high,
+// xhigh — confirmed via `pi --help`), so the resolved spec is exactly the
+// string buildPiArgv passes to `--model`; no extra launch plumbing.
+// ---------------------------------------------------------------------------
+/** Model-ladder resolution goes through `readMergedLaunchConfig` — the SAME
+ *  project-stack > profile > user > builtin precedence `resolveKindConfig`
+ *  already uses for `kinds` — so a project/profile override of `modelLadders`
+ *  is honored identically to a kind override, instead of this file reading
+ *  only user config. */
+function ladderFor(provider, ladders = modelLadders()) {
+    return ladders[provider];
+}
+// Automatic turn-time fallback ordering + strength ranking stay local to the
+// launch recipe (not needed by the pure selection primitives).
+const FALLBACK_PROVIDER_KEYS = ['anthropic', 'openai'];
+const MODEL_STRENGTH_RANK = { light: 0, medium: 1, strong: 2, ultra: 3 };
+/** 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 function equivalentOtherProviderModel(currentModel, failedProviders = new Set()) {
+    const ladders = modelLadders();
+    const cell = findLadderCell(normalizeModel(currentModel), ladders, FALLBACK_PROVIDER_KEYS);
+    if (cell === null)
+        return null;
+    if (failedProviders.has(cell.provider))
+        return null;
+    const toProvider = cell.provider === 'anthropic' ? 'openai' : 'anthropic';
+    if (failedProviders.has(toProvider))
+        return null;
+    return { fromProvider: cell.provider, toProvider, strength: cell.strength, model: ladders[toProvider][cell.strength] };
+}
+/** Back-map a concrete model spec to the provider×strength ladder cell it came
+ *  from. Two cells may legitimately name the SAME model id at different thinking
+ *  levels (the openai ladder's `ultra` and `strong` are both gpt-5.6-sol, at
+ *  `max` and `high`), so the thinking level is part of the identity: every cell
+ *  is compared WITH its suffix first, and only when nothing matches exactly does
+ *  the id-only comparison decide — which keeps a spec whose thinking level has
+ *  since drifted (or was never set, as on a launch fallback picked straight off
+ *  the registry) mapping to its model's cell instead of to none. That bare-id
+ *  pass walks strengths from LIGHT UPWARD and so resolves a shared id to its
+ *  WEAKEST cell: back-mapping is used to pick a same-strength substitute during
+ *  an outage, and an ambiguous id must never silently promote a node onto a
+ *  costlier ladder rung than it asked for. Scans providers in the caller's
+ *  order; returns null when the spec is not a ladder cell. */
+function findLadderCell(normalized, ladders, providers) {
+    const bare = stripThinkingSuffix(normalized);
+    for (const exact of [true, false]) {
+        const strengths = exact ? MODEL_STRENGTHS : [...MODEL_STRENGTHS].sort((a, b) => MODEL_STRENGTH_RANK[a] - MODEL_STRENGTH_RANK[b]);
+        for (const provider of providers) {
+            for (const strength of strengths) {
+                const cell = ladders[provider][strength];
+                if (exact ? cell !== normalized : stripThinkingSuffix(cell) !== bare)
+                    continue;
+                return { provider, strength };
+            }
+        }
+    }
+    return null;
+}
+/** Resolve a persona/caller `model:` token to the concrete `model:thinking`
+ *  spec pi gets via `--model`, in order:
+ *   1. `provider/rest` — apply strength aliases to `rest`; if `provider` is
+ *      `anthropic`/`openai` AND `rest` is a strength, return that ladder cell
+ *      (the word `openai` maps to the openai-codex ladder). Otherwise it is a
+ *      concrete `provider/id` (incl. any `:thinking` suffix) → pass through.
+ *   2. Bare strength (incl. aliases normal/weak) → the default-provider ladder
+ *      cell (config default provider, then CRTR_MODEL_PROVIDER, else anthropic).
+ *   3. Bare family alias (opus/sonnet/haiku) → the Anthropic ladder's
+ *      strong/medium/light, ALWAYS anthropic (ignores the env/config default).
+ *   4. Anything else → pass through unchanged. */
+function modelTokenStrength(model) {
+    const rest = model.includes('/') ? model.slice(model.indexOf('/') + 1) : model;
+    const strength = STRENGTH_ALIASES[rest];
+    if (strength !== undefined)
+        return strength;
+    if (rest === 'opus')
+        return 'strong';
+    if (rest === 'sonnet')
+        return 'medium';
+    if (rest === 'haiku')
+        return 'light';
+    return null;
+}
+function resolvedModelStrength(model, ladders = modelLadders()) {
+    const tokenStrength = modelTokenStrength(model);
+    if (tokenStrength !== null)
+        return tokenStrength;
+    const cell = findLadderCell(normalizeModel(model, ladders), ladders, MODEL_PROVIDER_KEYS);
+    return cell?.strength ?? null;
+}
+function isReviewQualityKind(kind) {
+    return kind === 'review' || kind.startsWith('plan/reviewers/');
+}
+function floorReviewModel(kind, requestedModel, kindModel, ladders = modelLadders()) {
+    if (requestedModel === undefined)
+        return kindModel;
+    if (!isReviewQualityKind(kind) || kindModel === undefined)
+        return requestedModel;
+    const requestedStrength = resolvedModelStrength(requestedModel, ladders);
+    const floorStrength = resolvedModelStrength(kindModel, ladders);
+    if (requestedStrength === null || floorStrength === null)
+        return requestedModel;
+    return MODEL_STRENGTH_RANK[requestedStrength] < MODEL_STRENGTH_RANK[floorStrength]
+        ? kindModel
+        : requestedModel;
+}
+/** 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 function isProviderPinnedModelToken(model) {
+    return model.includes('/');
+}
+/** 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 function isPortableModelToken(model) {
+    if (model.includes('/')) {
+        const slash = model.indexOf('/');
+        const provider = model.slice(0, slash);
+        const rest = model.slice(slash + 1);
+        return (provider === 'anthropic' || provider === 'openai') && STRENGTH_ALIASES[rest] !== undefined;
+    }
+    return STRENGTH_ALIASES[model] !== undefined || model === 'opus' || model === 'sonnet' || model === 'haiku';
+}
+export function normalizeModel(model, ladders = modelLadders()) {
+    // 1. Qualified provider/rest.
+    if (model.includes('/')) {
+        const slash = model.indexOf('/');
+        const provider = model.slice(0, slash);
+        const rest = model.slice(slash + 1);
+        const strength = STRENGTH_ALIASES[rest];
+        if (strength !== undefined && (provider === 'anthropic' || provider === 'openai')) {
+            return ladderFor(provider, ladders)[strength];
+        }
+        // Concrete `provider/id` (optionally `...:thinking`) — pass through.
+        return model;
+    }
+    // 2. Bare strength → default-provider ladder.
+    const strength = STRENGTH_ALIASES[model];
+    if (strength !== undefined)
+        return ladderFor(defaultProvider(ladders), ladders)[strength];
+    // 3. Bare family alias → always Anthropic.
+    if (model === 'opus')
+        return ladders.anthropic.strong;
+    if (model === 'sonnet')
+        return ladders.anthropic.medium;
+    if (model === 'haiku')
+        return ladders.anthropic.light;
+    // 4. Unknown — pass through.
+    return model;
+}
+/** The thinking suffix of a ladder cell / model spec (`…:high` → `high`), or
+ *  undefined when the trailing `:token` is a model-id segment rather than a
+ *  known thinking level. */
+function thinkingSuffixOf(spec) {
+    const i = spec.lastIndexOf(':');
+    if (i <= 0)
+        return undefined;
+    const suffix = spec.slice(i + 1);
+    return THINKING_SUFFIXES.has(suffix) ? suffix : undefined;
+}
+/** 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 function interleavedLadderCycle(providers = MODEL_PROVIDER_KEYS) {
+    const walked = providers.length > 0 ? providers : MODEL_PROVIDER_KEYS;
+    const ladders = modelLadders();
+    const order = [];
+    for (const strength of MODEL_STRENGTHS) {
+        for (const provider of walked) {
+            order.push(ladders[provider][strength]);
+        }
+    }
+    return order;
+}
+/** 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 function nextLadderModel(currentSpec, direction = 1, providers) {
+    const order = interleavedLadderCycle(providers);
+    const normalized = normalizeModel(currentSpec);
+    const currentBare = stripThinkingSuffix(normalized);
+    const currentThinking = thinkingSuffixOf(normalized);
+    let idx = order.findIndex((ref) => stripThinkingSuffix(ref) === currentBare && thinkingSuffixOf(ref) === currentThinking);
+    if (idx === -1)
+        idx = order.findIndex((ref) => stripThinkingSuffix(ref) === currentBare);
+    if (idx === -1)
+        return order[0];
+    return order[(idx + direction + order.length) % order.length];
+}
+// ---------------------------------------------------------------------------
+// Build the launch spec from {kind, mode}
+// ---------------------------------------------------------------------------
+/** 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 function buildLaunchSpec(kind, mode, opts) {
+    const merged = readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null));
+    const kindConfig = merged.kinds[kind];
+    const ladders = merged.modelLadders;
+    const kindModel = mode === 'orchestrator' ? kindConfig?.orchestratorModel ?? kindConfig?.model : kindConfig?.model;
+    const chosenModel = opts.modelExact === true ? opts.model : floorReviewModel(kind, opts.model, kindModel, ladders);
+    const launch = {
+        model: opts.modelExact === true
+            ? chosenModel
+            : (chosenModel !== undefined ? normalizeModel(chosenModel, ladders) : undefined),
+        modelProviderPinned: opts.modelProviderPinned !== undefined
+            ? opts.modelProviderPinned
+            : opts.model !== undefined && isProviderPinnedModelToken(opts.model),
+        modelExact: opts.modelExact === true ? true : undefined,
+        tools: kindConfig?.tools ?? [],
+        extensions: mergeCanvasExtensions([...CANVAS_EXTENSIONS, ...(kindConfig?.extensions ?? [])]),
+        systemPrompt: LAUNCH_SYSTEM_PROMPT,
+        env: { ...(opts.extraEnv ?? {}) },
+    };
+    return { launch, lifecycle: opts.lifecycle };
+}
+// ---------------------------------------------------------------------------
+// Build the pi argv to launch / revive a node
+// ---------------------------------------------------------------------------
+/** Persist a node's (possibly large) system prompt to a file in its node dir and
+ *  return the absolute path, so callers can pass a short path to pi instead of
+ *  the inline text. Returns null if the write fails — the caller then falls back
+ *  to passing the prompt inline. Rewritten every launch so a polymorph's updated
+ *  prompt always lands. */
+function writeSystemPromptFile(nodeId, prompt) {
+    try {
+        const dir = nodeDir(nodeId);
+        mkdirSync(dir, { recursive: true });
+        const p = join(dir, 'system-prompt.md');
+        writeFileSync(p, prompt, 'utf8');
+        return p;
+    }
+    catch {
+        return null;
+    }
+}
+/** 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 function buildPiArgv(meta, opts = {}) {
+    const spec = meta.launch;
+    const extensions = mergeCanvasExtensions(spec?.extensions);
+    assertMandatoryCanvasExtensions(extensions);
+    const argv = [];
+    for (const ext of extensions) {
+        argv.push('-e', ext);
+    }
+    argv.push('-n', editorLabel(meta));
+    // pi's `--resume` is a bare toggle that opens the interactive picker; the
+    // flag that resumes a *specific* session is `--session <path|id>`. Prefer the
+    // absolute FILE path when present: pi resolves a bare id cwd-relative first
+    // and shows a cross-project "Fork? [y/N]" prompt when the revive cwd differs
+    // from the session's creation cwd, whereas a path (contains `/` or ends
+    // `.jsonl`) is opened directly — immune to any cwd discrepancy. In practice
+    // revive always passes the absolute path: a resume happens only when the saved
+    // `.jsonl` exists (resumeArgs), and the broker preflight rejects a bare id
+    // outright, so `resumeSessionId` is a generic builder param no live caller sets.
+    // `--fork <path|id>` is the spawn-time branch: pi copies the source session
+    // into a fresh one for this node (the source is untouched), then delivers the
+    // kickoff prompt as the next message. Mutually exclusive with `--session`
+    // (resume) — fork wins when both are somehow set, but in practice a spawn
+    // never resumes and a revive never forks.
+    if (opts.forkFrom !== undefined && opts.forkFrom !== '') {
+        argv.push('--fork', opts.forkFrom);
+    }
+    else {
+        const resumeArg = opts.resumeSessionPath ?? opts.resumeSessionId;
+        if (resumeArg !== undefined)
+            argv.push('--session', resumeArg);
+        if (opts.newCycle === true)
+            argv.push('--crtr-new-cycle');
+    }
+    if (spec?.model !== undefined)
+        argv.push('--model', spec.model);
+    if (spec?.modelProviderPinned === true)
+        argv.push('--crtr-model-provider-pinned');
+    if (spec?.modelExact === true)
+        argv.push('--crtr-model-exact');
+    if (spec?.tools !== undefined && spec.tools.length > 0)
+        argv.push('--tools', spec.tools.join(','));
+    if (spec?.systemPrompt !== undefined && spec.systemPrompt !== '') {
+        // pi's --append-system-prompt reads a FILE when the arg is an existing path,
+        // else treats the arg as literal text. Pass the prompt as a file path, not
+        // inline: an orchestrator persona is ~17KB, and passed inline it inflates the
+        // `tmux new-window 'pi …'` command past tmux's command-length limit, so the
+        // spawn dies with "command too long" and the node is marked dead before pi
+        // ever starts (base workers fit, orchestrator children don't). Writing it to
+        // the node dir keeps the command tiny. Falls back to inline if the write
+        // fails (e.g. an ephemeral meta with no node dir).
+        const promptArg = writeSystemPromptFile(meta.node_id, spec.systemPrompt) ?? spec.systemPrompt;
+        argv.push('--append-system-prompt', promptArg);
+    }
+    if (opts.prompt !== undefined && opts.prompt !== '')
+        argv.push(opts.prompt);
+    return { argv, env: nodeEnv(meta) };
+}
+/** 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 function piInvocationToSdkConfig(inv) {
+    for (const [k, v] of Object.entries(inv.env))
+        process.env[k] = v;
+    const cfg = {
+        cwd: inv.env['CRTR_NODE_CWD'] ?? process.cwd(),
+        extensionPaths: [],
+    };
+    const argv = inv.argv;
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        switch (tok) {
+            case '-e':
+                cfg.extensionPaths.push(argv[++i]);
+                break;
+            case '-n':
+                cfg.editorName = argv[++i];
+                break;
+            case '--fork':
+                cfg.forkFrom = argv[++i];
+                break;
+            case '--session': {
+                const v = argv[++i];
+                // A path (contains `/` or ends `.jsonl`) resumes via SessionManager.open.
+                // A bare uuid is classified here for completeness but is rejected by the
+                // broker preflight and never produced by revive — the live path is always
+                // the absolute path. Same classification buildPiArgv documents.
+                if (v.includes('/') || v.endsWith('.jsonl'))
+                    cfg.resumeSessionPath = v;
+                else
+                    cfg.resumeSessionId = v;
+                break;
+            }
+            case '--model':
+                cfg.model = argv[++i];
+                break;
+            case '--crtr-model-provider-pinned':
+                cfg.modelProviderPinned = true;
+                break;
+            case '--crtr-model-exact':
+                cfg.modelExact = true;
+                break;
+            case '--tools':
+                cfg.tools = argv[++i].split(',').filter((t) => t !== '');
+                break;
+            case '--append-system-prompt':
+                cfg.appendSystemPromptPath = argv[++i];
+                break;
+            case '--crtr-new-cycle':
+                cfg.newCycle = true;
+                break;
+            default:
+                // buildPiArgv consumes every flag's value via the cases above, so any
+                // token reaching here is the single trailing positional (the prompt).
+                cfg.firstPrompt = tok;
+                break;
+        }
+    }
+    return cfg;
+}

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

@@ -0,0 +1,12 @@
+import type { NodeMeta } from '../canvas/types.js';
+/** The lifecycle events — the only vocabulary for moving a node's status/intent.
+ *  Each maps (in the table below) to a target status and/or intent plus the set
+ *  of from-statuses it is legal from. */
+export type LifecycleEvent = 'finish' | 'cancel' | 'crash' | 'yield' | 'release' | 'refresh-launch' | 'revive';
+/** Enact a lifecycle event on a node: validate the from-status against the
+ *  table, then write status+intent in ONE atomic statement (so they can never
+ *  disagree). Returns the hydrated node view after the write.
+ *
+ *  Throws on an unknown node or an illegal move. The conditional update makes
+ *  legality authoritative at SQLite write time rather than at a stale read. */
+export declare function transition(nodeId: string, event: LifecycleEvent): NodeMeta;

package/dist/core/runtime/lifecycle.js

@@ -0,0 +1,121 @@
+// lifecycle.ts — the node status×intent state machine.
+//
+// ONE place defines which (status, intent) moves are legal and enacts them.
+// Before this, ~a dozen scattered setStatus()/setIntent() pairs across
+// reset/close/revive/feed/daemon/stophook/queue/promote re-derived the lifecycle
+// by hand, with no shared definition of "what move is legal." Here the legal
+// transition TABLE is the definition, and `transition(id, event)` is the single
+// writer of status+intent: it validates the from-status, then writes both fields
+// in ONE atomic statement (built on Phase 2's WAL'd row setters) so the two can
+// never disagree.
+//
+// This mirrors persona.ts: persona.ts is the single source of transition PROSE;
+// lifecycle.ts is the single source of which status/intent move is LEGAL. Two
+// parallel, legible state machines instead of scattered enactment.
+//
+// Crash-safety invariant (was a comment repeated in close/reapDescendants):
+// "flip status to a non-supervised value + clear intent BEFORE killing the
+// host" (tmux pane or headless broker) — the daemon only ever revives
+// active|idle nodes, so a teardown must
+// leave the node done/canceled first to close the revive race. That invariant is
+// now the DEFINITION of the `cancel` event: callers flip via transition()
+// and only THEN tear the host down.
+//
+// Unification (A5, human-confirmed 2026-06-06): an externally-reaped node — torn
+// down because the user moved on (close cascade) OR because a root relaunch
+// superseded its workers — ends `canceled`, NOT `done`. `done` is reserved for a
+// node that finished its OWN work (finish) — including a relaunched root, which
+// is parked `done` as history, not canceled. The old `reap` event (→ done) was
+// identical to `cancel` in every field and side effect once unified on status, so
+// it was COLLAPSED into `cancel`; reset.ts's reapDescendants routes through
+// `cancel`.
+//
+// Layering note: lifecycle.ts is runtime, but it is the canvas write surface's
+// `transition` verb (the only writer of status+intent), so it owns its atomic
+// row UPDATE directly via openDb — the one sanctioned exception to "only
+// canvas.ts touches the db" (see canvas/CLAUDE.md), exactly as db.ts's backfill
+// is the sanctioned exception for a data migration.
+import { openDb, getNode, cancelCronsOnWake } from '../canvas/index.js';
+const ANY = '*';
+/** The supervised statuses — a live node the daemon watches. */
+const LIVE = ['active', 'idle'];
+/** The legal transition table — derived directly from the (status, intent) pairs
+ *  the runtime actually wrote at its audited call sites, so behavior is preserved
+ *  by construction. Each entry's comment names its writer(s). */
+const TRANSITIONS = {
+    // markCleanExitDone (clean quit) · queue cancellation · relaunchRoot park-old.
+    finish: { status: 'done', intent: 'done', from: LIVE },
+    // closeNode cascade · reapDescendants. Forced teardown of a node that did NOT
+    // finish its own work → canceled, intent cleared. (A5: done is reserved for
+    // finish; every external reap unifies on canceled.)
+    cancel: { status: 'canceled', intent: null, from: ANY },
+    // daemon superviseTick: engine container gone (tmux pane or broker process)
+    // with no yield/release intent. Intent KEPT (the dead log line still reports it).
+    crash: { status: 'dead', from: LIVE },
+    // requestYield · relaunchRoot new-node safety net. Status KEPT (already active).
+    yield: { intent: 'refresh', from: LIVE },
+    // stophook idle-release: free the host, stay woken by the inbox.
+    release: { status: 'idle', intent: 'idle-release', from: LIVE },
+    // reviveNode provisional refresh launch: activate without committing the
+    // refresh until session_start proves the engine booted.
+    'refresh-launch': { status: 'active', intent: 'refresh', from: ANY },
+    // reviveNode ordinary launch · resetRoot · stophook boot confirmation.
+    revive: { status: 'active', intent: null, from: ANY },
+};
+/** Enact a lifecycle event on a node: validate the from-status against the
+ *  table, then write status+intent in ONE atomic statement (so they can never
+ *  disagree). Returns the hydrated node view after the write.
+ *
+ *  Throws on an unknown node or an illegal move. The conditional update makes
+ *  legality authoritative at SQLite write time rather than at a stale read. */
+export function transition(nodeId, event) {
+    const spec = TRANSITIONS[event];
+    const writeStatus = Object.prototype.hasOwnProperty.call(spec, 'status');
+    const writeIntent = Object.prototype.hasOwnProperty.call(spec, 'intent');
+    const assignments = [];
+    const values = [];
+    if (writeStatus) {
+        assignments.push('status = ?');
+        values.push(spec.status ?? null);
+    }
+    if (writeIntent) {
+        assignments.push('intent = ?');
+        values.push(spec.intent ?? null);
+    }
+    const predicates = ['node_id = ?'];
+    values.push(nodeId);
+    if (spec.from !== ANY) {
+        predicates.push(`status IN (${spec.from.map(() => '?').join(', ')})`);
+        values.push(...spec.from);
+    }
+    // A committed canonical result is protected from a concurrent close.
+    if (event === 'cancel')
+        predicates.push('final_report IS NULL');
+    const db = openDb();
+    const result = db.prepare(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`).run(...values);
+    if (result.changes === 0) {
+        const cur = getNode(nodeId);
+        if (cur === null)
+            throw new Error(`transition: unknown node ${nodeId}`);
+        if (event === 'cancel' && cur.final_report !== null && cur.final_report !== undefined)
+            return cur;
+        throw new Error(`illegal lifecycle transition: '${event}' from status='${cur.status}' (node ${nodeId})`);
+    }
+    // Wait-cron cleanup — writes a DIFFERENT table (crons) AFTER the atomic
+    // status/intent write above, so the single-(status,intent)-writer rule holds.
+    // Event-gated; exactly ONE delegated crons helper, never inline cron SQL here:
+    //   finish · cancel → cancelCronsOnWake: delete the cancel-on-wake crons
+    //     ANCHORED to this node — the deadlines it armed to bound a wait. Ending
+    //     the wait deliberately (finish) or having it ended for you (close cascade
+    //     · reapDescendants) settles that race, so the deadline must not fire
+    //     afterwards: on a finished node its urgent self-message hits
+    //     `assertNotFinalized`, fails, and escalates a spurious agent; on a closed
+    //     node it succeeds and revives a node the user deliberately shut. Only
+    //     cancel-on-wake rows go — a standing declarative cron (anchored or not)
+    //     SURVIVES a node ending.
+    //   crash → NOTHING. A fault is not a deliberate end-of-waiting; a pending
+    //     deadline MUST survive instance death so the wait still settles.
+    if (event === 'finish' || event === 'cancel')
+        cancelCronsOnWake(nodeId);
+    return getNode(nodeId);
+}

package/dist/core/runtime/managed-provider-cooling.d.ts

@@ -0,0 +1,38 @@
+import type { AssistantMessageDiagnostic } from "@earendil-works/pi-ai";
+/** Diagnostic `type` tag carrying the cooling deadline; also the wire contract the
+ *  stophook matches on. */
+export declare const MANAGED_PROVIDER_COOLING_DIAGNOSTIC = "crtr:managed-provider-cooling";
+/** Stable error code so a caller can recognize the typed error without message parsing. */
+export declare const MANAGED_PROVIDER_COOLING_CODE = "managed_provider_cooling";
+/**
+ * Broker-owned, live policy exposed to the jiti-loaded provider-rotation
+ * extension through its UI context. A callback (rather than a boot-time value)
+ * is required because an attached viewer can pin or unpin the running broker
+ * with `set_model`; the very next provider attempt must observe that decision.
+ */
+export declare const MANAGED_PROVIDER_ROTATION_POLICY_UI: unique symbol;
+export type ManagedProviderRotationPolicy = {
+    allowCrossProviderFallback: boolean;
+    reason?: "provider-pinned" | "model-exact";
+};
+export type ManagedProviderRotationPolicyControl = () => ManagedProviderRotationPolicy;
+/** Non-broker/test hosts retain the historical permissive fallback policy. */
+export declare function readManagedProviderRotationPolicy(ui: unknown): ManagedProviderRotationPolicy;
+/** Every managed provider pool tried this turn is cooling; `rateLimitedUntil` is
+ *  the earliest future deadline (epoch ms) across those pools. */
+export declare class ManagedProviderCoolingError extends Error {
+    readonly code = "managed_provider_cooling";
+    readonly rateLimitedUntil: number;
+    constructor(message: string, rateLimitedUntil: number);
+    /** The diagnostic to attach to the terminal assistant error so the deadline
+     *  reaches the stophook without regex-parsing the message. Built inline (not via
+     *  pi-ai's `createAssistantMessageDiagnostic`) to keep this module's runtime
+     *  import graph pi-free — the shape matches `AssistantMessageDiagnostic`. */
+    toDiagnostic(): AssistantMessageDiagnostic;
+}
+/** Strictly read the managed-cooling deadline (epoch ms) off an assistant
+ *  message's diagnostics. Returns the finite, strictly-positive `rateLimitedUntil`
+ *  from the first cooling diagnostic, or undefined when the message carries none
+ *  (or a malformed one). */
+export declare function hasManagedProviderCoolingDiagnostic(message: unknown): boolean;
+export declare function extractCoolingDeadline(message: unknown): number | undefined;