@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/crtr-theme.js

@@ -0,0 +1,146 @@
+// crtr-theme.ts — the theme every crtr surface paints with.
+//
+// crtr owns its default instead of inheriting pi's: pi 0.99 made a terminal-
+// palette `system` theme the default and repainted its built-in `dark`, which
+// silently changed every crtr surface. `classic-dark` is pi 0.87.1's `dark`
+// verbatim — the teal-accented palette crtr was designed against.
+//
+// Theme lookup also has to agree with where the name came from. The attach
+// viewer reads the theme NAME from crtr's pi agent dir (`piAgentDir()`), but
+// pi's `initTheme(name)` resolves a custom theme FILE against its own
+// `getAgentDir()` — `$HOME/.pi/agent` for a viewer, a different directory — so
+// a name set in crtr's settings missed its file and pi fell back silently.
+// `initCrtrTheme` pins pi's agent dir to the one the name was read from.
+import { initTheme, Theme } from '@earendil-works/pi-coding-agent';
+import { getTerminalColorMode } from '@earendil-works/pi-tui';
+/** crtr's default theme name, used when no settings file names one. */
+export const CRTR_DEFAULT_THEME = 'classic-dark';
+const CLASSIC_DARK_VARS = {
+    cyan: '#00d7ff',
+    blue: '#5f87ff',
+    green: '#b5bd68',
+    red: '#cc6666',
+    yellow: '#ffff00',
+    text: '#d4d4d4',
+    gray: '#808080',
+    dimGray: '#666666',
+    darkGray: '#505050',
+    accent: '#8abeb7',
+    selectedBg: '#3a3a4a',
+    userMsgBg: '#343541',
+    toolPendingBg: '#282832',
+    toolSuccessBg: '#283228',
+    toolErrorBg: '#3c2828',
+    customMsgBg: '#2d2838',
+};
+const CLASSIC_DARK_COLORS = {
+    accent: 'accent',
+    border: 'blue',
+    borderAccent: 'cyan',
+    borderMuted: 'darkGray',
+    success: 'green',
+    error: 'red',
+    warning: 'yellow',
+    muted: 'gray',
+    dim: 'dimGray',
+    text: 'text',
+    thinkingText: 'gray',
+    selectedBg: 'selectedBg',
+    scrollbarTrack: 'darkGray',
+    scrollbarThumb: 'text',
+    searchMatchBg: 'selectedBg',
+    searchMatchText: 'text',
+    userMessageBg: 'userMsgBg',
+    userMessageText: 'text',
+    customMessageBg: 'customMsgBg',
+    customMessageText: 'text',
+    customMessageLabel: '#9575cd',
+    toolPendingBg: 'toolPendingBg',
+    toolSuccessBg: 'toolSuccessBg',
+    toolErrorBg: 'toolErrorBg',
+    toolTitle: 'text',
+    toolOutput: 'gray',
+    mdHeading: '#f0c674',
+    mdLink: '#81a2be',
+    mdLinkUrl: 'dimGray',
+    mdCode: 'accent',
+    mdCodeBlock: 'green',
+    mdCodeBlockBorder: 'gray',
+    mdQuote: 'gray',
+    mdQuoteBorder: 'gray',
+    mdHr: 'gray',
+    mdListBullet: 'accent',
+    toolDiffAdded: 'green',
+    toolDiffRemoved: 'red',
+    toolDiffContext: 'gray',
+    syntaxComment: '#6A9955',
+    syntaxKeyword: '#569CD6',
+    syntaxFunction: '#DCDCAA',
+    syntaxVariable: '#9CDCFE',
+    syntaxString: '#CE9178',
+    syntaxNumber: '#B5CEA8',
+    syntaxType: '#4EC9B0',
+    syntaxOperator: '#D4D4D4',
+    syntaxPunctuation: '#D4D4D4',
+    thinkingOff: 'darkGray',
+    thinkingMinimal: '#6e6e6e',
+    thinkingLow: '#5f87af',
+    thinkingMedium: '#81a2be',
+    thinkingHigh: '#b294bb',
+    thinkingXhigh: '#d183e8',
+    thinkingMax: '#ff5fff',
+    bashMode: 'green',
+};
+/** pi's background tokens (theme.js `BACKGROUND_TOKENS`); every other token is a foreground. */
+const BACKGROUND_TOKENS = new Set([
+    'selectedBg',
+    'searchMatchBg',
+    'userMessageBg',
+    'customMessageBg',
+    'toolPendingBg',
+    'toolSuccessBg',
+    'toolErrorBg',
+]);
+function classicDarkTheme() {
+    const fg = {};
+    const bg = {};
+    for (const [token, ref] of Object.entries(CLASSIC_DARK_COLORS)) {
+        const value = CLASSIC_DARK_VARS[ref] ?? ref;
+        (BACKGROUND_TOKENS.has(token) ? bg : fg)[token] = value;
+    }
+    return new Theme(fg, bg, getTerminalColorMode(), {
+        name: CRTR_DEFAULT_THEME,
+        appearance: 'dark',
+    });
+}
+const THEME_SYMBOL = Symbol.for('@earendil-works/pi-coding-agent:theme');
+const THEME_SYMBOL_OLD = Symbol.for('@mariozechner/pi-coding-agent:theme');
+/** Initialize pi's process-global theme for a crtr surface.
+ *
+ *  - No configured name → crtr's `classic-dark`.
+ *  - A configured name → pi resolves it, with `PI_CODING_AGENT_DIR` pinned to
+ *    `agentDir` for the call so a custom theme file is found in the same agent
+ *    dir its name was read from. pi reads that variable on every lookup.
+ *
+ *  `classic-dark` is published on pi's global theme slot, the one every pi
+ *  module copy (including a bundled viewer's inlined copy) reads through. */
+export function initCrtrTheme(themeName, agentDir, enableWatcher = false) {
+    const prior = process.env['PI_CODING_AGENT_DIR'];
+    process.env['PI_CODING_AGENT_DIR'] = agentDir;
+    try {
+        const name = themeName === CRTR_DEFAULT_THEME ? undefined : themeName;
+        initTheme(name ?? 'dark', name !== undefined && enableWatcher);
+        if (name === undefined) {
+            const theme = classicDarkTheme();
+            const slots = globalThis;
+            slots[THEME_SYMBOL] = theme;
+            slots[THEME_SYMBOL_OLD] = theme;
+        }
+    }
+    finally {
+        if (prior === undefined)
+            delete process.env['PI_CODING_AGENT_DIR'];
+        else
+            process.env['PI_CODING_AGENT_DIR'] = prior;
+    }
+}

package/dist/core/runtime/deliver-live.d.ts

@@ -0,0 +1,38 @@
+export interface LiveCustomMessage {
+    customType: string;
+    content: string;
+    /** Omitted → pushed straight onto the message list (lands first in an empty
+     *  session). `nextTurn` → folded into whatever turn comes next. */
+    deliverAs?: 'nextTurn';
+    /** Extension-only metadata, never sent to the LLM. */
+    details?: {
+        nodeId: string;
+    };
+}
+/** Deliver `message` into `nodeId`'s live session. Resolves without doing
+ *  anything when the node has no live broker. Rejects when a live broker cannot
+ *  be reached or refuses the frame — the caller decides what that means (for a
+ *  warm claim it is fatal: a node wearing the wrong bearings is worse than a
+ *  slow one, so the spare is abandoned and the create goes cold). */
+export declare function deliverCustomMessageLive(nodeId: string, message: LiveCustomMessage): Promise<void>;
+/** Build and deliver `nodeId`'s bearings into its live session, and freeze the
+ *  preference snapshot that goes with them. Called by the warm-pool claim once
+ *  the row already wears the claimant's kind/mode/name, so the identity
+ *  assertion, the knowledge catalog, the `<project_context>` environment
+ *  snapshot, and the preference block are all built for the node being handed
+ *  out.
+ *
+ *  The snapshot is frozen HERE for the same reason bearings are built here: a
+ *  spare boots with no claimant, so `canvas-context-intro` skips warm spares
+ *  and the block would otherwise assert the SPARE's preferences. Claim is the
+ *  first moment the real persona, profile, and cwd exist, and it is the last
+ *  moment before the claimant's first turn — which reaches the provider through
+ *  the persona gate, and which need not be a typed prompt. A slash command
+ *  opens its turn through `sendMessage({ triggerTurn: true })`, and Pi emits
+ *  `before_agent_start` only on the typed-prompt path, so the broker's own
+ *  freeze in `canvas-doc-substrate` never runs for it.
+ *
+ *  The `details.nodeId` stamp is what the context-intro extension's idempotency
+ *  guard matches on, so a LATER revive of this node sees its own bearings
+ *  already on the branch and does not inject a second copy. */
+export declare function deliverBearingsLive(nodeId: string): Promise<void>;

package/dist/core/runtime/deliver-live.js

@@ -0,0 +1,87 @@
+// deliver-live.ts — push a custom message into a node's ALREADY-BOOTED session
+// without waking it. The answer to "what can a live engine still be told?" for
+// everything that is a CLAIM-time property of a warm spare rather than a
+// mint-time one.
+//
+// Two callers today, both on the warm-pool claim path:
+//   • bearings (`deliverBearingsLive`) — a spare mints with NO bearings, because
+//     a block built at mint would assert the SPARE's persona (always
+//     `general`/`base`) and a snapshot of the repo as it looked whenever the
+//     spare happened to boot. Built and delivered here instead, it is exact for
+//     the node actually handed out. Pushed with no delivery option, so at the
+//     idle start of a still-empty session it lands as the FIRST entry, exactly
+//     where the context-intro extension's session_start injection would have put
+//     it — ahead of the claimant's kickoff prompt.
+//   • situational context (`situational-live.ts`, which layers the durable
+//     sidecar write over this) — `nextTurn`, so it rides the claimant's first
+//     real turn instead of starting one nobody asked for.
+//
+// A DORMANT node needs neither: its next revive renders both into the kickoff.
+import { getNode } from '../canvas/index.js';
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { readerForNode, warmNodeRepos } from '../graph/reader.js';
+import { noteNodeBooting } from '../graph/repo-sync/index.js';
+import { checkoutsForCwd } from '../graph/repo-sync/repos.js';
+import { deliver } from '../substrate/delivery/deliver.js';
+import { oneShotControllerRequest } from './broker-request.js';
+import { isBrokerLive } from './model-swap.js';
+import { CONTEXT_INTRO_CUSTOM_TYPE } from './bearings.js';
+import { formatCard } from '../../shared/generated-context.js';
+/** Deliver `message` into `nodeId`'s live session. Resolves without doing
+ *  anything when the node has no live broker. Rejects when a live broker cannot
+ *  be reached or refuses the frame — the caller decides what that means (for a
+ *  warm claim it is fatal: a node wearing the wrong bearings is worse than a
+ *  slow one, so the spare is abandoned and the create goes cold). */
+export async function deliverCustomMessageLive(nodeId, message) {
+    const meta = await getNode(nodeId);
+    if (meta === null)
+        throw new Error(`deliverCustomMessageLive: unknown node ${nodeId}`);
+    if (!isBrokerLive(meta))
+        return;
+    await oneShotControllerRequest({
+        nodeId,
+        what: `the ${message.customType} delivery`,
+        ackFor: 'deliver_custom_message',
+        frame: () => ({
+            type: 'deliver_custom_message',
+            customType: message.customType,
+            content: message.content,
+            ...(message.deliverAs !== undefined ? { deliverAs: message.deliverAs } : {}),
+            ...(message.details !== undefined ? { details: message.details } : {}),
+        }),
+        result: () => undefined,
+    });
+}
+/** Build and deliver `nodeId`'s bearings into its live session, and freeze the
+ *  preference snapshot that goes with them. Called by the warm-pool claim once
+ *  the row already wears the claimant's kind/mode/name, so the identity
+ *  assertion, the knowledge catalog, the `<project_context>` environment
+ *  snapshot, and the preference block are all built for the node being handed
+ *  out.
+ *
+ *  The snapshot is frozen HERE for the same reason bearings are built here: a
+ *  spare boots with no claimant, so `canvas-context-intro` skips warm spares
+ *  and the block would otherwise assert the SPARE's preferences. Claim is the
+ *  first moment the real persona, profile, and cwd exist, and it is the last
+ *  moment before the claimant's first turn — which reaches the provider through
+ *  the persona gate, and which need not be a typed prompt. A slash command
+ *  opens its turn through `sendMessage({ triggerTurn: true })`, and Pi emits
+ *  `before_agent_start` only on the typed-prompt path, so the broker's own
+ *  freeze in `canvas-doc-substrate` never runs for it.
+ *
+ *  The `details.nodeId` stamp is what the context-intro extension's idempotency
+ *  guard matches on, so a LATER revive of this node sees its own bearings
+ *  already on the branch and does not inject a second copy. */
+export async function deliverBearingsLive(nodeId) {
+    // A claimed spare boots here, not through the broker's boot delivery: sync its repos first.
+    await noteNodeBooting(nodeId);
+    // The boot delivery clears and rewrites the ledger and freezes preferences in
+    // one transaction before Pi receives the bearings.
+    await warmNodeRepos(await openDb(), nodeId);
+    const { content } = await withCanvasWrite(async (db) => await deliver(db, await readerForNode(db, nodeId, async (cwd) => await checkoutsForCwd(db, cwd)), { activity: 'boot' }));
+    await deliverCustomMessageLive(nodeId, {
+        customType: CONTEXT_INTRO_CUSTOM_TYPE,
+        content: formatCard('bearings', {}, content),
+        details: { nodeId },
+    });
+}

package/dist/core/runtime/fault-recovery.d.ts

@@ -0,0 +1,23 @@
+import type { Fault, FaultKind } from '../fault-classifier.js';
+export type FaultRecoveryGate = 'online' | 'time' | 'none';
+export interface FaultRecoveryPolicy {
+    kind: FaultKind;
+    gate: FaultRecoveryGate;
+    max: number;
+    baseDelayMs: number;
+    capDelayMs: number;
+    fatal: boolean;
+}
+export interface FaultRetryPlan {
+    fault: Fault;
+    attempt: number;
+    max: number;
+    nextAt: string;
+    delayMs: number;
+}
+export declare function policyFor(kind: FaultKind): FaultRecoveryPolicy;
+export declare function nextFaultRetry(fault: Fault, now: number, opts?: {
+    retryAfterMs?: number | null;
+    jitterMs?: (fault: Fault, attempt: number) => number;
+}): FaultRetryPlan | null;
+export declare function markFatalOnExhaust(fault: Fault): Fault;

package/dist/core/runtime/fault-recovery.js

@@ -0,0 +1,83 @@
+const POLICIES = {
+    connection: { kind: 'connection', gate: 'online', max: 8, baseDelayMs: 5_000, capDelayMs: 60_000, fatal: false },
+    'rate-limit': { kind: 'rate-limit', gate: 'time', max: 6, baseDelayMs: 30_000, capDelayMs: 5 * 60_000, fatal: false },
+    overloaded: { kind: 'overloaded', gate: 'time', max: 6, baseDelayMs: 10_000, capDelayMs: 2 * 60_000, fatal: false },
+    auth: { kind: 'auth', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    protocol: { kind: 'protocol', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    'context-overflow': { kind: 'context-overflow', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    other: { kind: 'other', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    // A wedge is a daemon-detected stall, never auto-retried — recovery is a
+    // deliberate agent/operator decision (kill the runaway subprocess), not a
+    // provider back-off.
+    wedged: { kind: 'wedged', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+    // A launch-time model resolution failure (unregistered/unauthenticated spec) —
+    // never auto-retried, since retrying with the same unresolved model would just
+    // fail again identically. Fixing it requires a new --model or new credentials.
+    'model-not-found': { kind: 'model-not-found', gate: 'none', max: 0, baseDelayMs: 0, capDelayMs: 0, fatal: true },
+};
+export function policyFor(kind) {
+    return POLICIES[kind];
+}
+function clampDelay(delayMs, capMs) {
+    if (!Number.isFinite(delayMs) || delayMs <= 0)
+        return 0;
+    return Math.min(Math.max(1, Math.round(delayMs)), capMs);
+}
+function defaultOverloadedJitterMs(fault, attempt) {
+    const seed = `${fault.link}|${fault.kind}|${fault.message}|${fault.since}|${attempt}`;
+    let hash = 0;
+    for (let i = 0; i < seed.length; i++) {
+        hash = (hash * 33 + seed.charCodeAt(i)) >>> 0;
+    }
+    return hash % 1_000;
+}
+function retryDelayMs(fault, attempt, opts) {
+    const policy = policyFor(fault.kind);
+    if (policy.fatal)
+        return 0;
+    if (fault.kind === 'rate-limit' && typeof opts?.retryAfterMs === 'number' && Number.isFinite(opts.retryAfterMs)) {
+        return clampDelay(opts.retryAfterMs, policy.capDelayMs);
+    }
+    const delay = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
+    const jitter = fault.kind === 'overloaded'
+        ? Math.max(0, Math.round(opts?.jitterMs?.(fault, attempt) ?? defaultOverloadedJitterMs(fault, attempt)))
+        : 0;
+    return clampDelay(delay + jitter, policy.capDelayMs);
+}
+export function nextFaultRetry(fault, now, opts) {
+    const policy = policyFor(fault.kind);
+    if (policy.fatal)
+        return null;
+    const attempt = (fault.retry.attempt ?? 0) + 1;
+    if (attempt > policy.max)
+        return null;
+    const delayMs = retryDelayMs(fault, attempt, opts);
+    return {
+        fault: {
+            ...fault,
+            retry: {
+                ...fault.retry,
+                disposition: 'auto',
+                by: fault.retry.by ?? 'daemon',
+                attempt,
+                max: policy.max,
+                nextAt: new Date(now + delayMs).toISOString(),
+            },
+        },
+        attempt,
+        max: policy.max,
+        nextAt: new Date(now + delayMs).toISOString(),
+        delayMs,
+    };
+}
+export function markFatalOnExhaust(fault) {
+    const retry = {
+        ...fault.retry,
+        disposition: 'fatal',
+        by: fault.retry.by ?? 'daemon',
+        max: policyFor(fault.kind).max,
+        attempt: fault.retry.attempt ?? 0,
+    };
+    delete retry.nextAt;
+    return { ...fault, retry };
+}

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

@@ -0,0 +1,6 @@
+export type { Fault, FaultKind, FaultLink, FaultProviderError, FaultRetry, FaultRetryDisposition, FaultRetryOwner, } from '../fault-classifier.js';
+export declare const FAULT_QUIET_MS: number;
+/** True when Pi could not resolve credentials for a provider. */
+export declare function isProviderUnconfiguredError(message: string): boolean;
+/** True when a provider reports that a requested model is unavailable. */
+export declare function isModelNotFoundError(message: string): boolean;

package/dist/core/runtime/fault.js

@@ -0,0 +1,17 @@
+export const FAULT_QUIET_MS = 5 * 60_000;
+/** True when Pi could not resolve credentials for a provider. */
+export function isProviderUnconfiguredError(message) {
+    const value = message ?? '';
+    if (/provider is not configured\b/i.test(value))
+        return true;
+    return /credential store (?:read|modify) failed\b/i.test(value);
+}
+/** True when a provider reports that a requested model is unavailable. */
+export function isModelNotFoundError(message) {
+    const value = message ?? '';
+    if (/not_found_error/i.test(value))
+        return true;
+    if (/model[^.]{0,40}(not\s*found|does not exist|is not available|unavailable)|(no such|unknown) model/i.test(value))
+        return true;
+    return /\b404\b/.test(value) && /not\s*found|not available|does not exist/i.test(value);
+}

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

@@ -0,0 +1,106 @@
+import { InputError } from '../io.js';
+import type { HostHandle } from './host.js';
+/** The daemon's live-broker thresholds. The hard cap is the ledger's admission
+ *  bound; `warning` is the saturation notice supervision fires below it. Lives
+ *  here — beside the ledger that enforces it — so the ledger, a refusal
+ *  message, and supervision's warning all read ONE definition. */
+export declare function brokerThresholdsForDaemon(): {
+    warning: number;
+    automaticReviveCap: number;
+};
+/** The typed refusal a caller that cannot wait gets when the ledger is full.
+ *  An InputError so its details round-trip through crtrd's error body and reach
+ *  a CLI caller as the real cap text instead of an opaque 5xx. */
+export declare function brokerCapReached(cap: number, live: number): InputError;
+/** The typed refusal a caller that cannot wait gets when the app's memory cannot take another broker. */
+export declare function appMemoryFull(detail: {
+    app: string;
+    free_bytes: number;
+    needed_bytes: number;
+}): InputError;
+/** The typed refusal when the app's memory cap is below what one broker needs to boot; waiting will not change it. */
+export declare function appMemoryTooSmall(detail: {
+    app: string;
+    max_bytes: number;
+    needed_bytes: number;
+}): InputError;
+/** Real child-exit status, exactly as Node reports it. Codes/signals are
+ *  diagnostics only — never policy inputs (design D-4). */
+export interface FleetExitStatus {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    /** The kernel's OOM killer ended the run's cgroup (hosted runtimes only). */
+    oomKilled?: boolean;
+}
+export interface FleetEntry {
+    /** The broker's supervised pid (never null — a launch with no pid is not
+     *  registered). */
+    pid: number;
+    /** The ChildProcess-backed handle (host.ts) whose `exited` promise is the
+     *  liveness authority. */
+    handle: HostHandle;
+}
+export interface FleetRegistry {
+    /** This daemon's epoch id — minted at boot, stamped into every broker's argv
+     *  (`--epoch <id>`) so the next daemon's startup census can reap every
+     *  prior-epoch broker without adoption. */
+    epoch(): string;
+    /** Record a just-spawned broker. Sync; THROWS if an entry already exists —
+     *  a second launch for a live node is a programming error, never silently
+     *  tolerated. */
+    register(nodeId: string, handle: HostHandle): void;
+    /** The reviveNode double-launch guard: a handle this process holds for a broker it spawned, or a `running`
+     *  execution row on a runner whose children this process cannot hold (Blaxel). */
+    has(nodeId: string): Promise<boolean>;
+    /** True while ANY launch claim exists for this node — a registered broker OR
+     *  an in-flight reservation. `has` alone reads false during the window
+     *  between `reserveSlot` and registration, so a caller asking "could this
+     *  node come back to life right now?" (the managed-worktree sweep, before it
+     *  destroys a checkout) must ask this instead. */
+    isClaimed(nodeId: string): Promise<boolean>;
+    /** Live-fleet checks pass (yield-stall, wedge, fatal-fault). */
+    get(nodeId: string): FleetEntry | undefined;
+    /** The capacity count: registered brokers only, excluding reservations. */
+    size(): number;
+    /** Every slot the cap accounts for — nodes with a live execution row (any process), plus this process's
+     *  brokers and launch reservations that have no row yet. */
+    occupancy(): Promise<number>;
+    /** Claim a slot for `nodeId`. True means the caller may launch; false means
+     *  the cap is reached and the caller must freeze or refuse. Idempotent — a
+     *  node that already holds a slot (reserved or registered) gets true without
+     *  consuming a second one. */
+    reserveSlot(nodeId: string): Promise<boolean>;
+    /** Give back a slot claimed by `reserveSlot` and not consumed by a launch. */
+    releaseReservation(nodeId: string): void;
+    entries(): Iterable<[string, FleetEntry]>;
+    /** Mark this exact broker's pause interruption before directly sending it
+     * SIGTERM. An explicit pid is the identity-checked fallback when the daemon
+     * has not registered a handle yet. */
+    interruptForProfilePause(nodeId: string, pid?: number): Promise<void>;
+    /** Whether the next dead-row policy pass must absorb this pause interruption
+     * before a later pass may recover the row normally (`executions.stop_reason`). */
+    hasProfilePauseInterruption(nodeId: string): Promise<boolean>;
+    /** Drop an entry without policy (terminal exits + close paths). */
+    forget(nodeId: string): void;
+    /** Wired by `headlessBrokerHost.launch` to the handle's `exited` promise.
+     *  Removes the entry (freeing the capacity slot), records the exit status on the
+     *  execution row (`exit_reason`), then enqueues its observation on the daemon's serial work lane — it never runs inline on
+     *  the Node event callback (design D-3). */
+    onChildExit(nodeId: string, status: FleetExitStatus, executionId?: string): Promise<void>;
+    /** Test seam — delivers a synthetic exit through the SAME path as
+     *  onChildExit, so fabricated-row tests drive policy without a process. */
+    deliverExit(nodeId: string, status: FleetExitStatus): Promise<void>;
+    /** The node-lifecycle tick's enactment entry: classify a row known to have no
+     *  live engine and enact through the SAME policy table exit events use, so
+     *  tick recovery and exit recovery can never diverge. */
+    applyDeadRowPolicy(nodeId: string): Promise<void>;
+}
+/** Inject the daemon's fleet registry. Idempotent for the same instance;
+ *  throws on a conflicting rebind (one registry per process, ever). */
+export declare function bindFleet(registry: FleetRegistry): void;
+/** The bound registry. Throws when unbound: broker launches happen only inside
+ *  crtrd (or a test harness that explicitly bound an in-process fleet). */
+export declare function boundFleet(): FleetRegistry;
+/** Test-only: clear the process-global binding, mirroring
+ *  resetEventSourceForTests. Production processes bind exactly once. */
+export declare function resetFleetForTests(): void;

package/dist/core/runtime/fleet.js

@@ -0,0 +1,75 @@
+// src/core/runtime/fleet.ts — the fleet-registry SEAM (daemon-epoch broker
+// ownership). Core defines the interface and a process-global binding holder;
+// the daemon (src/daemon/fleet.ts) constructs the one real implementation at
+// boot and injects it via `bindFleet` — the same core-seam/daemon-impl split as
+// `bindDaemonEventSource` (events/source.ts). No core→daemon import exists.
+//
+// The registry is the daemon's normal liveness authority: every broker launch
+// (`headlessBrokerHost.launch`) synchronously registers the ChildProcess-backed
+// handle here, and the handle's real `exit` event — not any pid probe — drives
+// dead-node policy. `boundFleet()` THROWS when no registry is bound, which is
+// the structural enforcement that broker launches happen only inside crtrd
+// (design D-2): a CLI or library process has no fleet and cannot launch an
+// unowned broker.
+import { readConfig } from '../config.js';
+import { InputError } from '../io.js';
+import { envMaxLiveBrokers, envWarnLiveBrokers } from '../../shared/env.js';
+/** The daemon's live-broker thresholds. The hard cap is the ledger's admission
+ *  bound; `warning` is the saturation notice supervision fires below it. Lives
+ *  here — beside the ledger that enforces it — so the ledger, a refusal
+ *  message, and supervision's warning all read ONE definition. */
+export function brokerThresholdsForDaemon() {
+    const configured = readConfig('user').brokerThresholds;
+    const automaticReviveCap = envMaxLiveBrokers() ?? configured.automaticReviveCap;
+    const warning = envWarnLiveBrokers() ?? configured.warning;
+    return { warning: Math.min(warning, automaticReviveCap), automaticReviveCap };
+}
+/** The typed refusal a caller that cannot wait gets when the ledger is full.
+ *  An InputError so its details round-trip through crtrd's error body and reach
+ *  a CLI caller as the real cap text instead of an opaque 5xx. */
+export function brokerCapReached(cap, live) {
+    return new InputError({
+        error: 'broker_cap_reached',
+        message: `no broker slot is free — ${live} live brokers at the cap of ${cap}.`,
+        next: `Finish or close a live node (\`crtr canvas dashboard\` shows them), or raise the cap with CRTR_MAX_LIVE_BROKERS, then retry.`,
+    });
+}
+const mib = (bytes) => Math.round(bytes / 1024 ** 2);
+/** The typed refusal a caller that cannot wait gets when the app's memory cannot take another broker. */
+export function appMemoryFull(detail) {
+    return new InputError({
+        error: 'app_memory_full',
+        message: `${detail.app} has ${mib(detail.free_bytes)} MiB of memory free and one more broker needs ${mib(detail.needed_bytes)} MiB.`,
+        next: `Retry once ${detail.app}'s running nodes finish.`,
+    });
+}
+/** The typed refusal when the app's memory cap is below what one broker needs to boot; waiting will not change it. */
+export function appMemoryTooSmall(detail) {
+    return new InputError({
+        error: 'app_memory_too_small',
+        message: `${detail.app} has a memory limit of ${mib(detail.max_bytes)} MiB, below the ${mib(detail.needed_bytes)} MiB one broker needs to start.`,
+        next: `Raise the limit with \`crtr sys limits set --app ${detail.app} --memory <size>\`, then retry.`,
+    });
+}
+let bound;
+/** Inject the daemon's fleet registry. Idempotent for the same instance;
+ *  throws on a conflicting rebind (one registry per process, ever). */
+export function bindFleet(registry) {
+    if (bound !== undefined && bound !== registry) {
+        throw new Error('a fleet registry is already bound for this process');
+    }
+    bound = registry;
+}
+/** The bound registry. Throws when unbound: broker launches happen only inside
+ *  crtrd (or a test harness that explicitly bound an in-process fleet). */
+export function boundFleet() {
+    if (bound === undefined) {
+        throw new Error('no fleet registry is bound in this process — broker launches happen only inside crtrd (route launch verbs through the /v1 API)');
+    }
+    return bound;
+}
+/** Test-only: clear the process-global binding, mirroring
+ *  resetEventSourceForTests. Production processes bind exactly once. */
+export function resetFleetForTests() {
+    bound = undefined;
+}

package/dist/core/runtime/focus-viewer.d.ts

@@ -0,0 +1,45 @@
+import type { CrtrClient } from '../../api/index.js';
+import type { NodeDetailDTO } from '../../api/dto/nodes.js';
+export declare function viewerEnv(): Record<string, string>;
+/** The live viewer pane for `nodeId` (the pane a surface-attach viewer tagged
+ *  `@crtr_node`), or undefined. Pure tag scan over live panes. */
+export declare function viewerPaneOf(nodeId: string): string | undefined;
+export interface FocusViewerOpts {
+    cwd: string;
+    name: string;
+    pane?: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+    /** With `inPlace`: leave this node's viewer in another pane open instead of closing it. */
+    keepOtherViewers?: boolean;
+    /** With `inPlace`: the inbox ticket the new viewer opens before showing the conversation. */
+    openTicket?: string;
+}
+export interface FocusViewerResult {
+    focused: boolean;
+    session: string | null;
+    inPlace: boolean;
+    revived: boolean;
+}
+/** Bring a node's ONE viewer forefront beside (or navigated to) the caller.
+ *  The server (`ensureAttach`) owns the broker revive + the view.sock
+ *  accept-wait; the `@crtr_node` pane tag is the viewer registry. crtr is
+ *  tmux-only: no caller pane ⇒ not focused. */
+export declare function focusViewer(client: CrtrClient, nodeId: string, opts: FocusViewerOpts): Promise<FocusViewerResult>;
+export interface FocusNodeResult {
+    focused: boolean;
+    session: string | null;
+    revived: boolean;
+    inPlace: boolean;
+}
+/** The whole `surface node focus` decision for one fetched node, placed into
+ *  `pane`: refuse a human-ask, open FINISHED work as a read-only saved
+ *  transcript popup, otherwise bring its conversation viewer into view.
+ *  Throws `InputError` for a human-ask; daemon failures propagate as `ApiError`. */
+export declare function focusNode(client: CrtrClient, node: Pick<NodeDetailDTO, 'node_id' | 'kind' | 'status' | 'lifecycle' | 'final_report' | 'cwd' | 'name'>, opts: {
+    pane: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+    keepOtherViewers?: boolean;
+    openTicket?: string;
+}): Promise<FocusNodeResult>;