@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/launch.js

@@ -0,0 +1,498 @@
+// 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 (stored with the node in SQL) 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 { envProfileId } from '../../shared/env.js';
+import { readMergedLaunchConfig } from '../config.js';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { personId, PersonUnresolvedError, PersonOutsideRequestError } from '../canvas/person-state.js';
+import { currentSnapshot, PersonSettingsNotLoadedError } from '../scoped-state/person-store.js';
+import { freshChildNodeExecPath, recheckChildNode } from './branded-host.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_TOOL_GUIDE_PATH, CANVAS_DOC_SUBSTRATE_PATH, CANVAS_STRUCTURED_OUTPUT_PATH, CANVAS_BASH_VALVE_PATH, } from './canvas-extensions.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];
+}
+const MODEL_STRENGTH_RANK = { light: 0, medium: 1, strong: 2, ultra: 3 };
+/** 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 (a ladder is free to serve `ultra` and `strong` off one model 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. */
+export function modelTokenStrength(model) {
+    const slash = model.lastIndexOf('/');
+    const provider = slash === -1 ? undefined : model.slice(0, slash);
+    const rest = slash === -1 ? model : model.slice(slash + 1);
+    const strength = STRENGTH_ALIASES[rest];
+    if (strength !== undefined)
+        return strength;
+    if (provider !== undefined && provider !== 'anthropic')
+        return null;
+    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('review/') || kind.includes('/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 `model` is a PORTABLE ladder token — a bare strength/alias
+ *  (`ultra`, `normal`, `opus`, …), a `<family>/<strength>` pair, or an
+ *  anthropic family alias — i.e. a logical preference rather than a concrete
+ *  provider/model id. Portable tokens are safe to PERSIST as defaults
+ *  (`persistDefaultKindModel`): they re-resolve against the declared routes or
+ *  ladder the running build ships, so they never freeze a stale concrete model
+ *  id to disk. */
+export function isPortableModelToken(model) {
+    if (model.includes('/')) {
+        const slash = model.lastIndexOf('/');
+        const family = model.slice(0, slash);
+        const rest = model.slice(slash + 1);
+        return family !== '' && (STRENGTH_ALIASES[rest] !== undefined
+            || (family === 'anthropic' && (rest === 'opus' || rest === 'sonnet' || rest === 'haiku')));
+    }
+    return STRENGTH_ALIASES[model] !== undefined || model === 'opus' || model === 'sonnet' || model === 'haiku';
+}
+export function logicalModelIntent(model, ladders = modelLadders()) {
+    const strength = modelTokenStrength(model);
+    if (strength === null)
+        return undefined;
+    if (model.includes('/'))
+        return { family: model.slice(0, model.lastIndexOf('/')), strength };
+    if (model === 'opus' || model === 'sonnet' || model === 'haiku')
+        return { family: 'anthropic', strength };
+    return { family: defaultProvider(ladders), strength };
+}
+/** The routing contract an explicit model choice asks for, decided from the RAW
+ *  token: a portable token (`anthropic/strong`, `strong`, `opus`) is an intent
+ *  that may rotate to another family at the same strength; any other token names
+ *  one model exactly (undefined). `node new --model`, `node config --model`, and
+ *  a viewer `/model` all apply this one rule. */
+export function explicitModelIntent(model, ladders = modelLadders()) {
+    return isPortableModelToken(model) ? logicalModelIntent(model, ladders) : undefined;
+}
+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];
+        }
+        if (provider === 'anthropic') {
+            if (rest === 'opus')
+                return ladders.anthropic.strong;
+            if (rest === 'sonnet')
+                return ladders.anthropic.medium;
+            if (rest === 'haiku')
+                return ladders.anthropic.light;
+        }
+        // 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];
+}
+function buildLaunchSpecFromMerged(kind, mode, opts, merged) {
+    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 exact = opts.modelExact === true
+        || (opts.modelOverride === true && opts.model !== undefined && !isPortableModelToken(opts.model));
+    const resolvedModel = opts.modelExact === true
+        ? chosenModel
+        : (chosenModel !== undefined ? normalizeModel(chosenModel, ladders) : undefined);
+    const intent = exact ? undefined : (opts.modelIntent ?? (chosenModel !== undefined ? logicalModelIntent(chosenModel, ladders) : undefined));
+    const launch = {
+        model: resolvedModel,
+        modelIntent: intent,
+        modelExact: exact ? true : undefined,
+        tools: kindConfig?.tools ?? [],
+        extensions: mergeCanvasExtensions([...CANVAS_EXTENSIONS, ...(kindConfig?.extensions ?? [])]),
+        systemPrompt: LAUNCH_SYSTEM_PROMPT,
+        env: { ...(opts.extraEnv ?? {}), ...(intent ? { CRTR_MODEL_INTENT: `${intent.family}/${intent.strength}` } : {}) },
+    };
+    return { launch, lifecycle: opts.lifecycle };
+}
+/** Build a launch recipe for callers that are not on crtrd's event loop. */
+export function buildLaunchSpec(kind, mode, opts) {
+    return buildLaunchSpecFromMerged(kind, mode, opts, readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (envProfileId() || null)));
+}
+/**
+ * Resolve launch config in a bounded subprocess before building a recipe.
+ * crtrd is single-threaded: project/profile roots can live on a network
+ * filesystem, so even an ordinary synchronous config read must never run on
+ * its event loop.
+ */
+export async function buildLaunchSpecAsync(kind, mode, opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const profileId = opts.profileId !== undefined ? opts.profileId : (envProfileId() || null);
+    const merged = await readMergedLaunchConfigAsync(cwd, profileId);
+    return buildLaunchSpecFromMerged(kind, mode, opts, merged);
+}
+const LAUNCH_CONFIG_TIMEOUT_MS = 15_000;
+/** Describe how a launch-config subprocess ended, with the cause an operator
+ *  needs: the exit code or fatal signal, and the tail of its stderr (a dyld
+ *  failure, an uncaught exception). Exported for tests. */
+export function describeLaunchConfigExit(code, signal, stderr) {
+    const how = signal !== null ? `was killed by ${signal}` : `exited with code ${code}`;
+    const tail = stderr.trim().split('\n').slice(-8).join('\n').slice(-1_500);
+    return `launch config subprocess ${how}${tail !== '' ? `: ${tail}` : ' (no stderr output)'}`;
+}
+/** The worker process died without answering (as opposed to answering with an error). */
+class LaunchConfigWorkerCrash extends Error {
+}
+export async function readMergedLaunchConfigAsync(cwd, profileId, 
+/** Test seam: the interpreter and worker script to fork with. */
+seam = {}) {
+    const execPath = seam.execPath ?? await freshChildNodeExecPath();
+    const workerPath = seam.workerPath ?? fileURLToPath(new URL('./launch-config-worker.js', import.meta.url));
+    try {
+        return await runLaunchConfigWorker(cwd, profileId, execPath, workerPath);
+    }
+    catch (error) {
+        if (!(error instanceof LaunchConfigWorkerCrash))
+            throw error;
+        // A branded host whose dependencies moved aborts every fresh process while
+        // the running one carries on. Re-probe now and retry once on a real node,
+        // so the first failed fork heals instead of failing until a cache expires.
+        const next = await recheckChildNode(execPath);
+        if (next === execPath)
+            throw error;
+        return runLaunchConfigWorker(cwd, profileId, next, workerPath);
+    }
+}
+/** The calling process's person and settings snapshot, when it holds them (a process with none reads defaults, as the worker will). */
+function heldPersonSettings() {
+    try {
+        return { person: personId(), snapshot: currentSnapshot() };
+    }
+    catch (error) {
+        if (error instanceof PersonUnresolvedError || error instanceof PersonOutsideRequestError || error instanceof PersonSettingsNotLoadedError)
+            return {};
+        throw error;
+    }
+}
+function runLaunchConfigWorker(cwd, profileId, execPath, workerPath) {
+    return new Promise((resolve, reject) => {
+        const child = fork(workerPath, [], {
+            execPath,
+            stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            serialization: 'advanced',
+        });
+        let stderr = '';
+        child.stderr?.setEncoding('utf8').on('data', (chunk) => { stderr = (stderr + chunk).slice(-8_192); });
+        child.send({ cwd, profileId, ...heldPersonSettings() });
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (child.connected)
+                child.disconnect();
+            if (!child.killed)
+                child.kill('SIGKILL');
+            fn();
+        };
+        const timeout = setTimeout(() => finish(() => reject(new Error(`timed out after ${LAUNCH_CONFIG_TIMEOUT_MS}ms reading launch config for ${cwd}`))), LAUNCH_CONFIG_TIMEOUT_MS);
+        child.once('message', (message) => {
+            if (message.error !== undefined)
+                finish(() => reject(new Error(message.error)));
+            else if (message.config !== undefined)
+                finish(() => resolve(message.config));
+            else
+                finish(() => reject(new Error('launch config subprocess returned no result')));
+        });
+        // An 'error' (e.g. EPIPE writing to a worker that already died) can arrive before
+        // 'close' has delivered the exit signal and the drained stderr. Settling on it would
+        // hide how the worker died, so remember it and let 'close' report: a process that
+        // fails to start, or loses its channel, still ends in 'close' (the timeout bounds the rest).
+        let channelError = null;
+        child.on('error', (error) => { channelError ??= error; });
+        // 'close', not 'exit': stderr must be fully drained to name the cause.
+        child.once('close', (code, signal) => {
+            // Our own SIGKILL (in finish) is expected; any other death before an answer is the cause.
+            if (settled)
+                return;
+            const detail = describeLaunchConfigExit(code, signal, stderr);
+            finish(() => reject(new LaunchConfigWorkerCrash(channelError === null ? detail : `${detail} (${channelError.message})`)));
+        });
+    });
+}
+/** 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>` asks pi to copy a source session. The daemon's normal
+    // node-fork path prepares the copy before launch and passes its own path as
+    // `--session`, so the broker never reads another node's conversation. Other
+    // callers may still select `--fork`; it takes precedence over `--session`.
+    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?.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 takes literal text; the text rides in the launch recipe (`launch_json`), not a file.
+        argv.push('--append-system-prompt', spec.systemPrompt);
+    }
+    if (opts.prompt !== undefined && opts.prompt !== '')
+        argv.push(opts.prompt);
+    return { argv, env: nodeEnv(meta), ...(spec?.worktree === undefined ? {} : { worktree: spec.worktree }) };
+}
+/** 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-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/ledger.d.ts

@@ -0,0 +1,10 @@
+/** End the node's context session: its ledger holds nothing. */
+export declare function clearNodeLedger(nodeId: string): Promise<void>;
+/** Seed a fork's ledger once with the transcript rows its source holds; no
+ *  source → empty. A fork already seeded (at spawn, or by an earlier birth
+ *  attempt) keeps its ledger, so a retry after the source is deleted loses nothing. */
+export declare function forkNodeLedger(forkId: string, sourceId: string | null): Promise<void>;
+/** Queue one inbox entry for a node revived from done listing the watched
+ *  documents that got a newer revision (by someone else) since `since`.
+ *  Returns whether a notice was queued. */
+export declare function noticeChangedWhileDone(nodeId: string, since: string): Promise<boolean>;

package/dist/core/runtime/ledger.js

@@ -0,0 +1,55 @@
+/** Node-id entry points to the exposure ledger (graph/exposures.ts) for the
+ *  launch paths: revive's context-session clears, and fork births (spawn,
+ *  review and feedback companions) seeding the fork from its source. */
+import { withCanvasWrite } from '../canvas/db.js';
+import { changedWhileDone } from '../substrate/delivery/deliver.js';
+import { queueNodeNotice } from '../feed/messages.js';
+import { clearLedger, forkLedger, hasLedger } from '../graph/exposures.js';
+import { getById, nodeObject } from '../graph/objects.js';
+import { mapAsync } from '../async-array.js';
+/** End the node's context session: its ledger holds nothing. */
+export async function clearNodeLedger(nodeId) {
+    await withCanvasWrite(async (db) => await clearLedger(db, (await nodeObject(db, nodeId)).id));
+}
+/** Seed a fork's ledger once with the transcript rows its source holds; no
+ *  source → empty. A fork already seeded (at spawn, or by an earlier birth
+ *  attempt) keeps its ledger, so a retry after the source is deleted loses nothing. */
+export async function forkNodeLedger(forkId, sourceId) {
+    await withCanvasWrite(async (db) => {
+        const fork = await nodeObject(db, forkId);
+        if (await hasLedger(db, fork.id))
+            return;
+        const source = sourceId === null ? null : await getById(db, sourceId);
+        if (source === null || source.type !== 'node')
+            await clearLedger(db, fork.id);
+        else
+            await forkLedger(db, source.id, fork.id);
+    });
+}
+function ownerHandle(owner) {
+    if (owner === null)
+        return '?';
+    return owner.type === 'node' ? owner.id : owner.name;
+}
+/** Queue one inbox entry for a node revived from done listing the watched
+ *  documents that got a newer revision (by someone else) since `since`.
+ *  Returns whether a notice was queued. */
+export async function noticeChangedWhileDone(nodeId, since) {
+    return await withCanvasWrite(async (db) => {
+        const changed = await changedWhileDone(db, await nodeObject(db, nodeId), since);
+        if (changed.length === 0)
+            return false;
+        const lines = (await mapAsync(changed, async ({ doc, from, to, authors }) => {
+            const owner = doc.owner === null ? null : await getById(db, doc.owner);
+            const by = authors.length === 0 ? '' : `, by ${(await mapAsync(authors, async (id) => ownerHandle(await getById(db, id)))).join(', ')}`;
+            return `- ${ownerHandle(owner)}/${doc.name} — revision ${from ?? 'none'} → ${to}${by}`;
+        }));
+        await queueNodeNotice(db, nodeId, {
+            body: `Documents you watch changed while you were done:\n${lines.join('\n')}`,
+            label: 'documents changed while you were done',
+            tier: 'normal',
+            wake: 0,
+        });
+        return true;
+    });
+}

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

@@ -0,0 +1,47 @@
+import type { NodeMeta, NodeOutcomeDetailV1, NodeStatus, ExitIntent, TerminalReason } 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' | 'park' | 'cancel' | 'crash' | 'yield' | 'release' | 'refresh-launch' | 'revive';
+export interface TerminalOutcomeInput {
+    /** Omit to derive: a lifecycle terminal transition is always a failure. */
+    detail?: NodeOutcomeDetailV1;
+}
+/** 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, opts?: {
+    reason?: TerminalReason;
+    outcome?: TerminalOutcomeInput;
+}): Promise<NodeMeta>;
+/** The last relay generation published when it bound. Missing means no replacement has bound yet. */
+export declare function brokerRelayGeneration(nodeId: string): string | null;
+/** The marker names the relay generation the committed disposition released. */
+export declare function recordBrokerRelease(nodeId: string, relay: string | null): void;
+/** Whether this row is a PARKED node — terminalized by the unattended clock
+ *  rather than by finishing its own work. The one read of the park marker:
+ *  `done` qualified by `intent='parked'`, both written in the same atomic
+ *  statement by the `park` event above. Revival clears it (`revive` writes
+ *  `intent: null`), so a reopened node is an ordinary node again. */
+export declare function isParked(node: {
+    status: NodeStatus;
+    intent?: ExitIntent;
+}): boolean;
+/** A parked node the runtime reopens for wake mail: resident, no final latch, not being deleted.
+ *  `PARKED_RESIDENT_SQL` (canvas/canvas.ts) is its SQL form and must change with it. */
+export declare function isParkedResident(node: {
+    status: NodeStatus;
+    intent?: ExitIntent;
+    lifecycle?: string;
+    final_report?: unknown;
+    deleting_at?: unknown;
+}): boolean;
+/** Whether the lifecycle table committed a deliberate idle release. `release`
+ * writes this intent with `status='idle'` atomically before its broker may exit,
+ * so an old busy marker cannot override the durable release decision. */
+export declare function hasIdleReleaseIntent(node: {
+    intent?: ExitIntent;
+} | null): boolean;