@north-light/api 0.3.580 → 0.3.588

package/dist/core/runtime/lifecycle.js

@@ -0,0 +1,283 @@
+// lifecycle.ts — the node status×intent state machine.
+//
+// ONE place defines which (status, intent) moves are legal and enacts them.
+// The legal transition TABLE is the definition, and `transition(id, event)` is
+// the single writer of status+intent for every caller (reset, close, revive,
+// feed, daemon, stophook, queue, promote): it validates the from-status, then
+// writes both fields in ONE atomic statement (on the WAL'd row setters) so the
+// two can never disagree.
+//
+// Persona modules own context framing; this file owns which status/intent move
+// is legal. The two state machines stay independent.
+//
+// Crash-safety invariant: 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 the DEFINITION of the
+// `cancel` event: callers flip via transition() and only THEN tear the host down.
+//
+// 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. There is no separate reap event: it would be identical to `cancel`
+// in every field and side effect, so 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 drives the
+// atomic status+intent write through canvas.ts's `transitionStatusIntent`
+// (its own decision logic — the legality table below, and the
+// unknown-node/illegal-move/already-finalized-cancel branching — stays here;
+// only the raw conditional UPDATE lives in canvas.ts, keeping every `.prepare(`
+// inside `core/canvas/`).
+import { getNode, cancelCronsOnWake, transitionStatusIntent } from '../canvas/index.js';
+import { closeSync, constants, existsSync, fstatSync, readSync } from 'node:fs';
+import { join } from 'node:path';
+import { BROKER_RELEASED_MARKER, BROKER_RELAY_GENERATION, nodeRunDir } from '../canvas/paths.js';
+import { openBeneath, writeFileBeneath, isAbsentOrRefused } from '../spaces/open-beneath.js';
+import { emitEvent } from '../events/emit.js';
+import { composeNodeOutcomeDocument } from './outcome-document.js';
+import { afterCommit, withCanvasWrite } from '../canvas/db.js';
+import { nodeObject } from '../graph/objects.js';
+import { endMessageSubscriptions } from '../graph/watches.js';
+import { settleNodeObjectWaits } from '../canvas/waits.js';
+import { runStructuredRequestEffects, settlePendingStructuredRequestForNodeIn } from '../canvas/structured-requests.js';
+const ANY = '*';
+const TERMINAL_REASONS = {
+    finish: 'finished',
+    park: 'parked',
+    cancel: 'stranded',
+    crash: 'crashed',
+    'refresh-launch': null,
+    revive: null,
+};
+/** 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 },
+    // The unattended park: a node whose conversation went idle with nothing left
+    // to wake it. `intent='parked'` IS the durable park marker — it qualifies the
+    // `done` it is written with, and `revive` clears it. Read it through
+    // `isParked` below, never by comparing the string at a call site.
+    park: { status: 'done', intent: 'parked', 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 },
+    // Free the host, stay woken by the inbox. A parked resident can also drain
+    // here after a capacity freeze without spending a slot.
+    release: { status: 'idle', intent: 'idle-release', from: [...LIVE, 'done'] },
+    // 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 },
+};
+function firstLineAtMost(value, maxBytes) {
+    const line = value.split('\n')[0] ?? '';
+    let bytes = 0;
+    let result = '';
+    for (const character of line) {
+        const next = Buffer.byteLength(character, 'utf8');
+        if (bytes + next > maxBytes)
+            break;
+        bytes += next;
+        result += character;
+    }
+    return result;
+}
+function detailJson(detail) {
+    if (detail === undefined)
+        return null;
+    const message = detail.message === undefined ? undefined : firstLineAtMost(detail.message, 500);
+    const bounded = { ...detail, ...(message === undefined ? {} : { message }) };
+    const serialized = JSON.stringify(bounded);
+    if (Buffer.byteLength(serialized, 'utf8') <= 4 * 1024)
+        return serialized;
+    return JSON.stringify({ schema: 'crtr.node-outcome-detail/v1', truncated: true, ...(message === undefined ? {} : { message }) });
+}
+function nodeAtOutcome(node, reason) {
+    let status;
+    let intent;
+    if (reason === 'finished' || reason === 'declined') {
+        status = 'done';
+        intent = 'done';
+    }
+    else if (reason === 'parked') {
+        status = 'done';
+        intent = 'parked';
+    }
+    else if (reason === 'closed' || reason === 'retired' || reason === 'stranded' || reason === 'deadline_exceeded') {
+        status = 'canceled';
+        intent = null;
+    }
+    else {
+        status = 'dead';
+        intent = null;
+    }
+    return { ...node, status, intent, terminal_reason: reason };
+}
+/** 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 async function transition(nodeId, event, opts) {
+    const spec = TRANSITIONS[event];
+    const writeStatus = Object.prototype.hasOwnProperty.call(spec, 'status');
+    const writeIntent = Object.prototype.hasOwnProperty.call(spec, 'intent');
+    const reason = opts?.reason ?? TERMINAL_REASONS[event];
+    const fields = {};
+    if (writeStatus)
+        fields.status = spec.status;
+    if (writeIntent)
+        fields.intent = spec.intent ?? null;
+    if (reason !== undefined)
+        fields.terminal_reason = reason;
+    const terminal = event === 'finish' || event === 'park' || event === 'cancel' || event === 'crash';
+    const outcomeAt = terminal ? new Date().toISOString() : null;
+    const outcomeReason = reason;
+    const outcomeDetailJson = detailJson(opts?.outcome?.detail);
+    const settlementInput = !terminal ? null : reason === 'deadline_exceeded'
+        ? { intended: 'expired', failureReason: 'node_deadline_exceeded', failureDetail: opts?.outcome?.detail ?? null }
+        : { intended: 'failed', failureReason: reason, failureDetail: opts?.outcome?.detail ?? null };
+    // A committed canonical result is protected from a concurrent close. A node that ends
+    // ends every message subscription on it, and settles its pending structured request,
+    // in the same write.
+    const transitionResult = await withCanvasWrite(async (db) => {
+        // The decision read lives in the write transaction: the outcome revision and the supersede
+        // choice come from the row this same transaction then updates, not from an earlier read.
+        const current = terminal ? await getNode(nodeId) : null;
+        const recordsOutcome = terminal && current?.kind !== 'human';
+        // An already-settled child can be closed with its run; only a reopened
+        // node or a parked run can replace the previous outcome.
+        const supersedeRunOutcome = recordsOutcome && current?.run_id != null && reason !== 'parked' && current.outcome_at !== null
+            && (LIVE.includes(current.status) || current.outcome_reason === 'parked');
+        let documentJson;
+        if (recordsOutcome && current !== null && (current.outcome_at === null || supersedeRunOutcome)) {
+            documentJson = JSON.stringify(await composeNodeOutcomeDocument({
+                node: nodeAtOutcome(current, outcomeReason),
+                outcome: { kind: 'failure', reason: outcomeReason, at: outcomeAt, revision: (current.outcome_revision ?? 0) + 1, detailJson: outcomeDetailJson },
+            }));
+        }
+        const written = await transitionStatusIntent(nodeId, fields, {
+            fromStatuses: spec.from === ANY ? undefined : spec.from,
+            requireNoFinalReport: event === 'cancel',
+            ...(recordsOutcome ? {
+                outcome: {
+                    kind: 'failure',
+                    reason: outcomeReason,
+                    detailJson: outcomeDetailJson,
+                    at: outcomeAt,
+                    ...(supersedeRunOutcome ? { supersede: true } : {}),
+                    ...(documentJson === undefined ? {} : { documentJson }),
+                },
+            } : {}),
+        });
+        if (terminal && written > 0) {
+            await endMessageSubscriptions(db, await nodeObject(db, nodeId), 'done');
+            await settleNodeObjectWaits(db, nodeId);
+        }
+        const settlement = written === 1 && settlementInput !== null
+            ? await settlePendingStructuredRequestForNodeIn(db, nodeId, settlementInput)
+            : null;
+        if (written === 1 && (event === 'release' || event === 'park' || event === 'finish' || event === 'cancel')) {
+            const relay = brokerRelayGeneration(nodeId);
+            afterCommit(() => recordBrokerRelease(nodeId, relay));
+        }
+        return { changes: written, settlement };
+    });
+    if (transitionResult.changes === 0) {
+        const cur = await 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 · park · 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 (transitionResult.settlement?.changed)
+        runStructuredRequestEffects(transitionResult.settlement.row);
+    if (event === 'finish' || event === 'park' || event === 'cancel')
+        await cancelCronsOnWake(nodeId);
+    return await getNode(nodeId);
+}
+/** The last relay generation published when it bound. Missing means no replacement has bound yet. */
+export function brokerRelayGeneration(nodeId) {
+    const dir = nodeRunDir(nodeId);
+    let fd;
+    try {
+        fd = openBeneath(dir, join(dir, BROKER_RELAY_GENERATION), constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isAbsentOrRefused(error))
+            return null;
+        throw error;
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return null;
+        const bytes = Buffer.alloc(37);
+        const length = readSync(fd, bytes, 0, bytes.length, 0);
+        const value = bytes.toString('utf8', 0, length);
+        return length === 36 && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value) ? value : null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** The marker names the relay generation the committed disposition released. */
+export function recordBrokerRelease(nodeId, relay) {
+    const dir = nodeRunDir(nodeId);
+    if (relay === null || !existsSync(dir))
+        return;
+    try {
+        writeFileBeneath(dir, join(dir, BROKER_RELEASED_MARKER), relay, { atomic: true });
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'node.lifecycle.release_marker_failed', node_id: nodeId, error });
+    }
+}
+/** 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 function isParked(node) {
+    return node.status === 'done' && node.intent === 'parked';
+}
+/** 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 function isParkedResident(node) {
+    return isParked(node) && node.lifecycle === 'resident' && node.final_report == null && node.deleting_at == null;
+}
+/** 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 function hasIdleReleaseIntent(node) {
+    return node?.intent === 'idle-release';
+}

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

@@ -0,0 +1,24 @@
+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";
+/** 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;

package/dist/core/runtime/managed-provider-cooling.js

@@ -0,0 +1,62 @@
+// managed-provider-cooling.ts — the typed carrier for "every managed provider
+// pool tried this turn is temporarily cooling down".
+//
+// runManagedProvider (provider-rotation.ts) raises this once every attempted
+// managed-pool credential is rate-limited with at least one finite future
+// deadline. The error converts to an AssistantMessageDiagnostic that survives
+// verbatim into the terminal error message and therefore into agent_end.messages
+// (pi-ai's AssistantMessageEventStream.result() returns the exact error message
+// object). The canvas-stophook reads the earliest deadline back off that message
+// and stamps it onto the pi→provider fault's retry.nextAt, so the broker's
+// existing auto-retry re-drives the pre-content turn exactly when the soonest
+// pool frees up — turning a transient pool cooldown into an auto (not fatal)
+// fault instead of a permanent one.
+/** Diagnostic `type` tag carrying the cooling deadline; also the wire contract the
+ *  stophook matches on. */
+export const MANAGED_PROVIDER_COOLING_DIAGNOSTIC = "crtr:managed-provider-cooling";
+/** Stable error code so a caller can recognize the typed error without message parsing. */
+export const MANAGED_PROVIDER_COOLING_CODE = "managed_provider_cooling";
+/** Every managed provider pool tried this turn is cooling; `rateLimitedUntil` is
+ *  the earliest future deadline (epoch ms) across those pools. */
+export class ManagedProviderCoolingError extends Error {
+    code = MANAGED_PROVIDER_COOLING_CODE;
+    rateLimitedUntil;
+    constructor(message, rateLimitedUntil) {
+        super(message);
+        this.name = "ManagedProviderCoolingError";
+        this.rateLimitedUntil = rateLimitedUntil;
+    }
+    /** 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() {
+        return {
+            type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
+            timestamp: Date.now(),
+            details: { rateLimitedUntil: this.rateLimitedUntil },
+        };
+    }
+}
+/** 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 function hasManagedProviderCoolingDiagnostic(message) {
+    const diagnostics = message?.diagnostics;
+    return Array.isArray(diagnostics) && diagnostics.some((diagnostic) => diagnostic?.type === MANAGED_PROVIDER_COOLING_DIAGNOSTIC);
+}
+export function extractCoolingDeadline(message) {
+    const diagnostics = message?.diagnostics;
+    if (!Array.isArray(diagnostics))
+        return undefined;
+    for (const diagnostic of diagnostics) {
+        if (diagnostic?.type !== MANAGED_PROVIDER_COOLING_DIAGNOSTIC)
+            continue;
+        const raw = diagnostic?.details?.rateLimitedUntil;
+        const value = typeof raw === "number" ? raw : Number(raw);
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    return undefined;
+}

package/dist/core/runtime/memory-admission.d.ts

@@ -0,0 +1,38 @@
+import { type LauncherReply } from '../../launcher/spec.js';
+/** The launcher's verdict, or a denial replayed from the memo. */
+export type BrokerMemoryVerdict = {
+    verdict: 'admitted';
+} | {
+    verdict: 'denied';
+    app: string;
+    level: 'app' | 'apps';
+    free_bytes: number;
+    needed_bytes: number;
+} | {
+    verdict: 'too_small';
+    app: string;
+    max_bytes: number;
+    needed_bytes: number;
+};
+/** How long a denial answers further admissions of the same app without asking the launcher. */
+export declare const DENIAL_MEMO_MS = 1000;
+/** How long after a denial broker supervision treats the app as short of memory. */
+export declare const MEMORY_PRESSURE_MS = 10000;
+interface Deps {
+    available: () => boolean;
+    request: (app: string, nodeId: string) => Promise<LauncherReply>;
+}
+/** Tests replace the launcher; `undefined` restores it. Either way the denial memo is cleared. */
+export declare function stubMemoryAdmissionForTests(stub?: Deps): void;
+/**
+ * Whether the node's app has memory for one more broker. Admits with no I/O where no root launcher runs (macOS,
+ * Linux without one). A launcher error admits: the kernel cap stays the hard limit. `useMemo: false` is the host's
+ * backstop, which must reach the launcher because the caller's admission left a ticket there that a memo would hide.
+ */
+export declare function admitBrokerMemory(nodeId: string, opts?: {
+    useMemo?: boolean;
+    now?: number;
+}): Promise<BrokerMemoryVerdict>;
+/** Whether the app (or the shared `apps/` level) was denied memory in the last `MEMORY_PRESSURE_MS`. */
+export declare function memoryDeniedRecently(app: string, now: number): boolean;
+export {};

package/dist/core/runtime/memory-admission.js

@@ -0,0 +1,68 @@
+// The daemon side of per-app memory admission. The root launcher measures the app's cgroup and holds the ledger
+// (crtrd cannot read those files); this module asks it, remembers a denial briefly so a burst of frozen candidates
+// costs one round-trip, and lets broker supervision see that an app is short of memory.
+import { existsSync } from 'node:fs';
+import { launcherRequest } from '../../launcher/client.js';
+import { LAUNCHER_SOCKET } from '../../launcher/spec.js';
+import { getNode } from '../canvas/index.js';
+import { emitEvent } from '../events/emit.js';
+import { isSafeNodeId } from '../canvas/paths.js';
+/** How long a denial answers further admissions of the same app without asking the launcher. */
+export const DENIAL_MEMO_MS = 1_000;
+/** How long after a denial broker supervision treats the app as short of memory. */
+export const MEMORY_PRESSURE_MS = 10_000;
+const ALL_APPS = '*';
+const realDeps = {
+    available: () => process.platform === 'linux' && existsSync(LAUNCHER_SOCKET),
+    request: (app, nodeId) => launcherRequest({ operation: 'memory.admit', app, nodeId }),
+};
+let deps = realDeps;
+const deniedAt = new Map();
+/** Tests replace the launcher; `undefined` restores it. Either way the denial memo is cleared. */
+export function stubMemoryAdmissionForTests(stub) {
+    deps = stub ?? realDeps;
+    deniedAt.clear();
+}
+/**
+ * Whether the node's app has memory for one more broker. Admits with no I/O where no root launcher runs (macOS,
+ * Linux without one). A launcher error admits: the kernel cap stays the hard limit. `useMemo: false` is the host's
+ * backstop, which must reach the launcher because the caller's admission left a ticket there that a memo would hide.
+ */
+export async function admitBrokerMemory(nodeId, opts = {}) {
+    if (!deps.available())
+        return { verdict: 'admitted' };
+    const app = (await getNode(nodeId))?.grantee ?? 'app:terminal';
+    const now = opts.now ?? Date.now();
+    if (opts.useMemo !== false) {
+        for (const key of [app, ALL_APPS]) {
+            const memo = deniedAt.get(key);
+            if (memo !== undefined && now - memo.at < DENIAL_MEMO_MS)
+                return memo.verdict;
+        }
+    }
+    let reply;
+    try {
+        reply = await deps.request(app, nodeId);
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'broker.memory_admission.failed', ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : {}), error });
+        return { verdict: 'admitted' };
+    }
+    if (!('verdict' in reply))
+        return { verdict: 'admitted' };
+    if (reply.verdict === 'denied') {
+        const verdict = { verdict: 'denied', app, level: reply.level, free_bytes: reply.free_bytes, needed_bytes: reply.needed_bytes };
+        deniedAt.set(reply.level === 'app' ? app : ALL_APPS, { at: now, verdict });
+        return verdict;
+    }
+    if (reply.verdict === 'too_small')
+        return { verdict: 'too_small', app, max_bytes: reply.max_bytes, needed_bytes: reply.needed_bytes };
+    return { verdict: 'admitted' };
+}
+/** Whether the app (or the shared `apps/` level) was denied memory in the last `MEMORY_PRESSURE_MS`. */
+export function memoryDeniedRecently(app, now) {
+    return [app, ALL_APPS].some(key => {
+        const memo = deniedAt.get(key);
+        return memo !== undefined && now - memo.at < MEMORY_PRESSURE_MS;
+    });
+}

package/dist/core/runtime/model-registry.d.ts

@@ -0,0 +1,3 @@
+import { ModelRegistry } from '@earendil-works/pi-coding-agent';
+/** Open pi's credential-backed model registry for runtime model resolution. */
+export declare function openModelRegistry(): Promise<ModelRegistry>;

package/dist/core/runtime/model-registry.js

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+import { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
+import { PoolCredentialStore } from '../pool-credential-store.js';
+import { piAgentDir } from './package-health.js';
+/** Open pi's credential-backed model registry for runtime model resolution. */
+export async function openModelRegistry() {
+    const agentDir = piAgentDir();
+    const runtime = await ModelRuntime.create({
+        credentials: new PoolCredentialStore(),
+        modelsPath: join(agentDir, 'models.json'),
+    });
+    return new ModelRegistry(runtime);
+}

package/dist/core/runtime/model-selection.d.ts

@@ -0,0 +1,54 @@
+import type { ModelProvider, ModelStrength, ScopeConfig } from '../../types.js';
+/** 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. */
+export declare function modelLadders(): ScopeConfig['modelLadders'];
+/** Env var naming the DEFAULT provider for an UNqualified bare strength only.
+ *  `CRTR_MODEL_PROVIDER=openai` (case-insensitive) makes a bare `strong` resolve
+ *  on the OpenAI ladder; anything else defaults to Anthropic. A configured
+ *  defaultProvider in config.json wins over this env. */
+export declare const OPENAI_PROVIDER_ENV = "CRTR_MODEL_PROVIDER";
+export declare function defaultProvider(ladders?: ScopeConfig['modelLadders']): ModelProvider;
+/** Strength synonyms accepted from personas/callers. */
+export declare const STRENGTH_ALIASES: Record<string, ModelStrength>;
+export declare const MODEL_PROVIDER_KEYS: ModelProvider[];
+export declare const MODEL_STRENGTHS: ModelStrength[];
+/** Canonical user-facing grammar for a durable model override. Help and
+ *  recovery paths compose from this one phrase so accepted forms cannot drift. */
+export declare const MODEL_SPEC_FORMS: string;
+export declare const MODEL_SPEC_NEXT: string;
+/** The ladder providers a picker/cycle should OFFER: a provider column is kept
+ *  only when at least one of its ladder cells names a runtime provider the
+ *  caller reports as signed in (`isConfigured` — e.g. pool occupancy or
+ *  `registry.getProviderAuthStatus(id).configured`). A user who never logged
+ *  into Codex sees no openai column in settings and no openai rungs on Alt+M.
+ *  When NO column qualifies (a fresh install before any login), every provider
+ *  is returned: the model surfaces must stay reachable so the user can still
+ *  inspect config and go sign in. Resolution (`normalizeModel` etc.) is
+ *  deliberately NOT gated — an explicit `openai/strong` request still resolves
+ *  and then fails/falls back through the normal auth-aware launch policy. */
+export declare function configuredLadderProviders(isConfigured: (runtimeProviderId: string) => boolean, ladders?: ScopeConfig['modelLadders']): ModelProvider[];
+export declare const THINKING_SUFFIXES: Set<string>;
+export declare function parseModelSpec<T extends string = string>(spec: string): {
+    modelSpec: string;
+    thinkingLevel?: T;
+};
+export declare function isUnknownModel(model: {
+    provider?: string;
+    id?: string;
+    api?: string;
+} | null | undefined): boolean;
+export declare function stripThinkingSuffix(spec: string): string;
+export interface PortableModelSelection {
+    provider: ModelProvider;
+    strength: ModelStrength;
+}
+/** Choose the provider×strength option an editor should highlight for an
+ * existing model value. Portable tokens follow the exact provider rules used
+ * by `normalizeModel`; concrete ladder refs map back to their configured cell,
+ * ignoring a thinking suffix only after an exact match. An off-ladder concrete
+ * ref retains a recognizable provider and starts at `ultra`; an unrecognized
+ * value starts at `ultra` on the effective default provider. */
+export declare function inferPortableModelSelection(model: string | undefined, ladders?: ScopeConfig['modelLadders']): PortableModelSelection;