@north-light/api 0.0.0-stage → 0.3.414

package/dist/daemon/pidfile.js

@@ -0,0 +1,37 @@
+// pidfile.ts — the lean crtrd pidfile + liveness helpers, split out of crtrd.ts
+// so the CLI's daemon front door (`daemon/manage.ts` → `ensureDaemon`) can
+// resolve "is the daemon up?" WITHOUT importing crtrd.ts, whose module graph
+// pulls the entire canvas state store (`core/canvas/index.js` → `openDb`). A
+// `crtr` CLI process asking whether crtrd is running must not, by that question
+// alone, open canvas.db — this module keeps that path fs/process-only.
+//
+// PURITY: Node built-ins + `core/canvas/paths.ts` (pure path builder) + the
+// db-free `core/canvas/pid.ts` liveness probe. Never `openDb` / crtrd.ts / any
+// canvas state accessor. crtrd.ts imports + re-exports these to preserve its
+// historical export surface (tests, `commands/sys/daemon.ts`).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { crtrHome } from '../core/canvas/paths.js';
+import { isPidAlive } from '../core/canvas/pid.js';
+import { envPidfileOverride } from '../shared/env.js';
+// Re-exported so `isPidAlive` stays reachable from the daemon layer's public
+// surface (crtrd.ts already re-exports it; callers may reach it either way).
+export { isPidAlive };
+/** Absolute path to crtrd's pidfile. `CRTR_PIDFILE` overrides for tests. */
+export function pidfilePath() {
+    return envPidfileOverride() ?? join(crtrHome(), 'crtrd.pid');
+}
+/** Read the pid stored in the pidfile, or null if absent / malformed. */
+export function readPidfile() {
+    const p = pidfilePath();
+    if (!existsSync(p))
+        return null;
+    const raw = readFileSync(p, 'utf8').trim();
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** True when a crtrd process is already running (pidfile exists + pid alive). */
+export function isDaemonRunning() {
+    const pid = readPidfile();
+    return pid !== null && isPidAlive(pid);
+}

package/dist/daemon/startup-policy.d.ts

@@ -0,0 +1 @@
+export declare const DAEMON_STARTUP_WINDOW_MS: number;

package/dist/daemon/startup-policy.js

@@ -0,0 +1 @@
+export const DAEMON_STARTUP_WINDOW_MS = 5 * 60 * 1_000;

package/dist/native/linux.d.ts

@@ -0,0 +1,29 @@
+import type { Socket } from 'node:net';
+export interface LinuxNative {
+    peerCred(fd: number): {
+        pid: number;
+        uid: number;
+        gid: number;
+    };
+    openat2(dirfd: number, path: string, flags: number, resolve: number): number;
+    fdPath(fd: number): string;
+    fstat(fd: number): {
+        uid: number;
+        gid: number;
+        mode: number;
+        nlink: number;
+        dev: bigint;
+        ino: bigint;
+    };
+    sendFds(socketFd: number, data: string, fds: number[]): void;
+    recvFds(socketFd: number): {
+        data: string;
+        fds: number[];
+    };
+}
+export declare const O_PATH = 2097152;
+export declare const O_CLOEXEC = 524288;
+export declare const RESOLVE_NO_SYMLINKS = 4;
+export declare const RESOLVE_BENEATH = 8;
+export declare function loadLinuxNative(): LinuxNative | undefined;
+export declare function peerUid(socket: Socket): number;

package/dist/native/linux.js

@@ -0,0 +1,20 @@
+import { createRequire } from 'node:module';
+export const O_PATH = 0x200000;
+export const O_CLOEXEC = 0x80000;
+export const RESOLVE_NO_SYMLINKS = 0x04;
+export const RESOLVE_BENEATH = 0x08;
+export function loadLinuxNative() {
+    if (process.platform !== 'linux')
+        return undefined;
+    // One prebuilt addon per architecture (see scripts/ensure-native-linux.mjs).
+    return createRequire(import.meta.url)(`./linux/${process.arch}/addon.node`);
+}
+export function peerUid(socket) {
+    const fd = socket._handle?.fd;
+    if (fd === undefined || fd < 0)
+        throw new Error('unix socket peer fd is unavailable');
+    const native = loadLinuxNative();
+    if (!native)
+        throw new Error('Linux peer credentials are unavailable');
+    return native.peerCred(fd).uid;
+}

package/dist/shared/env.d.ts

@@ -0,0 +1,116 @@
+/** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
+export declare function envNodeId(): string | undefined;
+/** Find the single launch snapshot mounted by the launcher into this process's
+ * Linux namespace. Cron bash has no CRTR_NODE_ID, but its creator's mounted
+ * launch snapshot supplies config and granted-command projection without
+ * claiming the cron is a node. Its broker relay may already have closed when
+ * the cron fires; still classify the sandbox so CLI bootstrap never falls back
+ * to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
+ * the caller-editable CRTR_API_SOCKET selects the launch identity. */
+export declare function sandboxCliNodeId(): string | undefined;
+/** A Linux app command uses its mounted launch snapshot, not host user stores. */
+export declare function isSandboxedNode(): boolean;
+/** The app that owns the current node, supplied in its broker launch identity. */
+export declare function envGrantee(): string | undefined;
+/** Set to '1' by `nodeEnv` for an app-started run's brokers, which admit inbox
+ *  mail only between agent runs. Terminal nodes also carry `CRTR_RUN_ID`, so
+ *  that variable is not this signal. */
+export declare const INBOX_BETWEEN_TURNS_ENV = "CRTR_INBOX_BETWEEN_TURNS";
+export declare function envInboxBetweenTurns(): boolean;
+/** The current run's scope allow-list; null means the row inherits everything. */
+export declare function envScopes(): readonly string[] | null;
+/** Whether a launched scope list covers a capability. Null means not narrowed. */
+export declare function scopeAllowed(scopes: readonly string[] | null | undefined, scope: string): boolean;
+export declare function envExecutionId(): string | undefined;
+/** The current node's target profile id (`CRTR_PROFILE_ID`), or undefined. */
+export declare function envProfileId(): string | undefined;
+/** The current node's working directory (`CRTR_NODE_CWD`), or undefined. */
+export declare function envNodeCwd(): string | undefined;
+/** An explicit model-routing override for this turn (`CRTR_MODEL_INTENT`), or
+ *  undefined. Cleared (not read) via `delete process.env['CRTR_MODEL_INTENT']`
+ *  in `runtime/broker.ts` — a mutation, not a read, so it stays there. */
+export declare function envModelIntent(): string | undefined;
+/** Whether the launch recipe requires this broker to keep its exact provider/model. */
+export declare function envModelExact(): boolean;
+/** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
+ *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
+ *  only when a caller needs the override itself — to check whether one is
+ *  set, or to propagate it verbatim into a child process's env. */
+export declare function envHomeOverride(): string | undefined;
+/** The raw installed-runtime directory override, unresolved. */
+export declare function envRuntimeHomeOverride(): string | undefined;
+/** Dead-provider watchdog timeout (`CRTR_STREAM_WATCHDOG_MS`), 5 minutes by
+ *  default. See `runtime/stream-watchdog.ts` for what it guards. */
+export declare function envStreamWatchdogMs(): number;
+/** The canvas inbox watcher's poll tick (`CRTR_WATCHER_TICK_MS`). */
+export declare function envWatcherTickMs(): number;
+/** Claim backstop while broker signals are connected (`CRTR_WATCHER_BACKSTOP_MS`). */
+export declare function envWatcherBackstopMs(): number;
+/** The canvas inbox watcher's debounce window (`CRTR_WATCHER_DEBOUNCE_MS`). */
+export declare function envWatcherDebounceMs(): number;
+/** No-new-message window before a recap is shown (`CRTR_RECAP_IDLE_MS`), 60s
+ *  by default. */
+export declare function envRecapIdleMs(): number;
+/** Explicit recap-model override (`CRTR_RECAP_MODEL`), trimmed; undefined if
+ *  unset or blank. */
+export declare function envRecapModelOverride(): string | undefined;
+/** The bash safety-valve deadline (`CRTR_BASH_VALVE_MS`), 5 minutes by
+ *  default; undocumented test-only override so the E2E valve check doesn't
+ *  sleep 5 minutes. */
+export declare function envBashValveMs(): number;
+/** How long an AUTO-backgrounded bash job may run before the daemon cancels it
+ *  unless the agent claims it (`CRTR_BASH_AUTO_BG_DEADLINE_MS`), 60s by default;
+ *  undocumented test-only override so the deadline check doesn't wait a minute. */
+export declare function envBashAutoBgDeadlineMs(): number;
+/** Explicit pidfile path override (`CRTR_PIDFILE`, tests only); undefined if
+ *  unset or blank. */
+export declare function envPidfileOverride(): string | undefined;
+/** The broker engine module spec (`CRTR_BROKER_ENGINE`, the T11 test seam),
+ *  defaulting to the real SDK. `runtime/host.ts` layers `inv.env` ahead of
+ *  this (a launch-time override mirrored into the child's env, since
+ *  spawn-env.ts's default-deny allowlist strips `CRTR_*` from ambient env). */
+export declare function envBrokerEngine(): string;
+/** Test-only pi-binary substitution (`CRTR_PI_BINARY`) so the integration
+ *  harness can point a real `crtr node new` at a deterministic fake-pi
+ *  vehicle. Undefined in production. */
+export declare function envPiBinaryOverride(): string | undefined;
+/** Whether implicit daemon autostart is suppressed for this invocation
+ *  (`CRTR_NO_DAEMON_AUTOSTART=1`). */
+export declare function envNoDaemonAutostart(): boolean;
+/** The `--tcp` fallback for crtrd's opt-in TCP listener (`CRTRD_TCP`), raw
+ *  (`host:port` or undefined — absent means unix socket only). */
+export declare function envCrtrdTcp(): string | undefined;
+/** The opt-in bearer token guarding crtrd's TCP listener (`CRTRD_TOKEN`).
+ *  Unset (or blank) → undefined, and the TCP listener performs NO auth check
+ *  at all — exactly today's behavior. The unix socket never checks this,
+ *  set or not. */
+export declare function envCrtrdToken(): string | undefined;
+/** Kill switch for the host-exports writer/pruner (`CRTR_NO_EXPORTS=1`). */
+export declare function envNoExports(): boolean;
+/** Verbose-diagnostics gate for otherwise-silent best-effort catches
+ *  (`CRTR_DEBUG=1`). Distinct from `CRTR_DEBUG_PID_LIVENESS`
+ *  (`core/canvas/pid.ts`), a different, unrelated var. */
+export declare function envDebug(): boolean;
+/** Live-broker automatic-revive cap override (`CRTR_MAX_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.automaticReviveCap` when set. */
+export declare function envMaxLiveBrokers(): number | undefined;
+/** Live-broker warning threshold override (`CRTR_WARN_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.warning` when set. */
+export declare function envWarnLiveBrokers(): number | undefined;
+/** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
+ *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
+export declare function envTestUnattendedParkMs(): number | undefined;
+/** Production unattended-park interval override (`CRTR_UNATTENDED_PARK_MS`), in
+ *  milliseconds; wins over the user-scope config value
+ *  (`readConfig('user').lifecycle.unattendedParkMs`, itself defaulting to 15
+ *  min) whenever set, autostart or not. Unlike `CRTR_TEST_UNATTENDED_PARK_MS`
+ *  this is not gated on `envNoDaemonAutostart()`: it is the env escape hatch
+ *  above the configured knob a deployment sets to tune how long an eligible
+ *  resident idles before its parking turn. */
+export declare function envUnattendedParkMs(): number | undefined;
+/** Test-only park-summary grace-period override
+ *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
+export declare function envTestParkSummaryGraceMs(): number | undefined;
+/** The bounded lifetime shared by the daemon's pending-park sweep and its
+ * in-broker isolated turn. */
+export declare function parkSummaryGraceMs(): number;

package/dist/shared/env.js

@@ -0,0 +1,271 @@
+// The reader-side surface for every environment variable crouter reads back
+// out of `process.env`, outside `core/runtime/spawn-env.ts`'s writer
+// allowlist. That module documents what a broker child is ADMITTED to see;
+// this one documents what crouter itself reads. Two families:
+//
+//   - Identity: raw passthrough (`string | undefined`, exactly what
+//     `process.env[name]` returns). Every existing call site keeps its own
+//     established fallback (`?? ''`, `|| null`, `?? cfg.cwd`, a presence
+//     check, ...) — the fallback has always been call-site-owned, not
+//     var-owned, so centralizing it here would be a behavior change, not a
+//     dedup. `CRTR_HOME` also has a resolved-path accessor, `crtrHome()` in
+//     `core/canvas/paths.ts`; that stays the canonical way to get the
+//     resolved canvas home; `envHomeOverride()` here is for the handful of
+//     sites that want the raw override value itself (to check presence or
+//     propagate it verbatim to a child env).
+//
+//   - Tuning: parsed, with the default baked into the accessor. Each of
+//     these had exactly one parse site before this module existed; the
+//     parse logic moved here unchanged so a second site, if one appears,
+//     reads the single implementation instead of re-deriving it.
+//
+// `CRTR_DIR_NAME` is NOT here — it is a plain exported string constant
+// (`types.ts`), never read off `process.env`.
+import { lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { covers } from '@north-light/identity';
+// Identity
+/** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
+export function envNodeId() {
+    return process.env['CRTR_NODE_ID'];
+}
+/** Find the single launch snapshot mounted by the launcher into this process's
+ * Linux namespace. Cron bash has no CRTR_NODE_ID, but its creator's mounted
+ * launch snapshot supplies config and granted-command projection without
+ * claiming the cron is a node. Its broker relay may already have closed when
+ * the cron fires; still classify the sandbox so CLI bootstrap never falls back
+ * to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
+ * the caller-editable CRTR_API_SOCKET selects the launch identity. */
+export function sandboxCliNodeId() {
+    if (process.platform !== 'linux')
+        return undefined;
+    try {
+        const root = '/run/crtr/nodes';
+        const mounted = new Set(readFileSync('/proc/self/mountinfo', 'utf8').split('\n').map((line) => line.split(' ')[4]));
+        const ids = readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() &&
+            /^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$/.test(entry.name) &&
+            mounted.has(join(root, entry.name)) &&
+            lstatSync(join(root, entry.name, 'broker-launch.json'), { throwIfNoEntry: false })?.isFile());
+        return ids.length === 1 ? ids[0].name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A Linux app command uses its mounted launch snapshot, not host user stores. */
+export function isSandboxedNode() {
+    return sandboxCliNodeId() !== undefined;
+}
+/** The app that owns the current node, supplied in its broker launch identity. */
+export function envGrantee() {
+    return process.env['CRTR_GRANTEE'];
+}
+/** Set to '1' by `nodeEnv` for an app-started run's brokers, which admit inbox
+ *  mail only between agent runs. Terminal nodes also carry `CRTR_RUN_ID`, so
+ *  that variable is not this signal. */
+export const INBOX_BETWEEN_TURNS_ENV = 'CRTR_INBOX_BETWEEN_TURNS';
+export function envInboxBetweenTurns() {
+    return process.env[INBOX_BETWEEN_TURNS_ENV] === '1';
+}
+/** The current run's scope allow-list; null means the row inherits everything. */
+export function envScopes() {
+    const raw = process.env['CRTR_SCOPES'];
+    return raw === undefined ? null : raw === '' ? [] : raw.split(',');
+}
+/** Whether a launched scope list covers a capability. Null means not narrowed. */
+export function scopeAllowed(scopes, scope) {
+    if (scopes === null || scopes === undefined)
+        return true;
+    return scopes.some((held) => covers(held, scope));
+}
+export function envExecutionId() {
+    return process.env['CRTR_EXECUTION_ID'];
+}
+/** The current node's target profile id (`CRTR_PROFILE_ID`), or undefined. */
+export function envProfileId() {
+    return process.env['CRTR_PROFILE_ID'];
+}
+/** The current node's working directory (`CRTR_NODE_CWD`), or undefined. */
+export function envNodeCwd() {
+    return process.env['CRTR_NODE_CWD'];
+}
+/** An explicit model-routing override for this turn (`CRTR_MODEL_INTENT`), or
+ *  undefined. Cleared (not read) via `delete process.env['CRTR_MODEL_INTENT']`
+ *  in `runtime/broker.ts` — a mutation, not a read, so it stays there. */
+export function envModelIntent() {
+    return process.env['CRTR_MODEL_INTENT'];
+}
+/** Whether the launch recipe requires this broker to keep its exact provider/model. */
+export function envModelExact() {
+    return process.env['CRTR_MODEL_EXACT'] === '1';
+}
+/** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
+ *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
+ *  only when a caller needs the override itself — to check whether one is
+ *  set, or to propagate it verbatim into a child process's env. */
+export function envHomeOverride() {
+    return process.env['CRTR_HOME'];
+}
+/** The raw installed-runtime directory override, unresolved. */
+export function envRuntimeHomeOverride() {
+    return process.env['CRTR_RUNTIME_HOME'];
+}
+// Tuning
+/** Generic `Number(raw)` parse with a positive-finite guard, shared by every
+ *  millisecond tuning var below (each previously reimplemented this locally,
+ *  identically). */
+function parsePositiveMs(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+const DEFAULT_STREAM_WATCHDOG_MS = 5 * 60_000; // 5 minutes.
+/** Dead-provider watchdog timeout (`CRTR_STREAM_WATCHDOG_MS`), 5 minutes by
+ *  default. See `runtime/stream-watchdog.ts` for what it guards. */
+export function envStreamWatchdogMs() {
+    return parsePositiveMs(process.env['CRTR_STREAM_WATCHDOG_MS'], DEFAULT_STREAM_WATCHDOG_MS);
+}
+const DEFAULT_WATCHER_TICK_MS = 800;
+/** The canvas inbox watcher's poll tick (`CRTR_WATCHER_TICK_MS`). */
+export function envWatcherTickMs() {
+    return parsePositiveMs(process.env['CRTR_WATCHER_TICK_MS'], DEFAULT_WATCHER_TICK_MS);
+}
+const DEFAULT_WATCHER_BACKSTOP_MS = 60_000;
+/** Claim backstop while broker signals are connected (`CRTR_WATCHER_BACKSTOP_MS`). */
+export function envWatcherBackstopMs() {
+    return parsePositiveMs(process.env['CRTR_WATCHER_BACKSTOP_MS'], DEFAULT_WATCHER_BACKSTOP_MS);
+}
+const DEFAULT_WATCHER_DEBOUNCE_MS = 1000;
+/** The canvas inbox watcher's debounce window (`CRTR_WATCHER_DEBOUNCE_MS`). */
+export function envWatcherDebounceMs() {
+    return parsePositiveMs(process.env['CRTR_WATCHER_DEBOUNCE_MS'], DEFAULT_WATCHER_DEBOUNCE_MS);
+}
+const DEFAULT_RECAP_IDLE_MS = 60_000;
+/** No-new-message window before a recap is shown (`CRTR_RECAP_IDLE_MS`), 60s
+ *  by default. */
+export function envRecapIdleMs() {
+    return parsePositiveMs(process.env['CRTR_RECAP_IDLE_MS'], DEFAULT_RECAP_IDLE_MS);
+}
+/** Explicit recap-model override (`CRTR_RECAP_MODEL`), trimmed; undefined if
+ *  unset or blank. */
+export function envRecapModelOverride() {
+    const raw = process.env['CRTR_RECAP_MODEL'];
+    return raw !== undefined && raw.trim() !== '' ? raw.trim() : undefined;
+}
+const DEFAULT_BASH_VALVE_MS = 5 * 60 * 1000;
+/** The bash safety-valve deadline (`CRTR_BASH_VALVE_MS`), 5 minutes by
+ *  default; undocumented test-only override so the E2E valve check doesn't
+ *  sleep 5 minutes. */
+export function envBashValveMs() {
+    return parsePositiveMs(process.env['CRTR_BASH_VALVE_MS'], DEFAULT_BASH_VALVE_MS);
+}
+const DEFAULT_BASH_AUTO_BG_DEADLINE_MS = 60 * 1000;
+/** How long an AUTO-backgrounded bash job may run before the daemon cancels it
+ *  unless the agent claims it (`CRTR_BASH_AUTO_BG_DEADLINE_MS`), 60s by default;
+ *  undocumented test-only override so the deadline check doesn't wait a minute. */
+export function envBashAutoBgDeadlineMs() {
+    return parsePositiveMs(process.env['CRTR_BASH_AUTO_BG_DEADLINE_MS'], DEFAULT_BASH_AUTO_BG_DEADLINE_MS);
+}
+/** Explicit pidfile path override (`CRTR_PIDFILE`, tests only); undefined if
+ *  unset or blank. */
+export function envPidfileOverride() {
+    const raw = process.env['CRTR_PIDFILE'];
+    return raw !== undefined && raw !== '' ? raw : undefined;
+}
+const DEFAULT_BROKER_ENGINE = '@earendil-works/pi-coding-agent';
+/** The broker engine module spec (`CRTR_BROKER_ENGINE`, the T11 test seam),
+ *  defaulting to the real SDK. `runtime/host.ts` layers `inv.env` ahead of
+ *  this (a launch-time override mirrored into the child's env, since
+ *  spawn-env.ts's default-deny allowlist strips `CRTR_*` from ambient env). */
+export function envBrokerEngine() {
+    return process.env['CRTR_BROKER_ENGINE'] ?? DEFAULT_BROKER_ENGINE;
+}
+/** Test-only pi-binary substitution (`CRTR_PI_BINARY`) so the integration
+ *  harness can point a real `crtr node new` at a deterministic fake-pi
+ *  vehicle. Undefined in production. */
+export function envPiBinaryOverride() {
+    return process.env['CRTR_PI_BINARY'];
+}
+/** Whether implicit daemon autostart is suppressed for this invocation
+ *  (`CRTR_NO_DAEMON_AUTOSTART=1`). */
+export function envNoDaemonAutostart() {
+    return process.env['CRTR_NO_DAEMON_AUTOSTART'] === '1';
+}
+/** The `--tcp` fallback for crtrd's opt-in TCP listener (`CRTRD_TCP`), raw
+ *  (`host:port` or undefined — absent means unix socket only). */
+export function envCrtrdTcp() {
+    return process.env['CRTRD_TCP'];
+}
+/** The opt-in bearer token guarding crtrd's TCP listener (`CRTRD_TOKEN`).
+ *  Unset (or blank) → undefined, and the TCP listener performs NO auth check
+ *  at all — exactly today's behavior. The unix socket never checks this,
+ *  set or not. */
+export function envCrtrdToken() {
+    const raw = process.env['CRTRD_TOKEN'];
+    return raw !== undefined && raw !== '' ? raw : undefined;
+}
+/** Kill switch for the host-exports writer/pruner (`CRTR_NO_EXPORTS=1`). */
+export function envNoExports() {
+    return process.env['CRTR_NO_EXPORTS'] === '1';
+}
+/** Verbose-diagnostics gate for otherwise-silent best-effort catches
+ *  (`CRTR_DEBUG=1`). Distinct from `CRTR_DEBUG_PID_LIVENESS`
+ *  (`core/canvas/pid.ts`), a different, unrelated var. */
+export function envDebug() {
+    return process.env['CRTR_DEBUG'] === '1';
+}
+// Precedence — broker-supervision.ts's threshold/interval overrides. Each
+// returns the raw parsed value with NO default: the caller supplies the
+// default (user config for the broker thresholds and the unattended-park
+// interval, a hardcoded constant for the test-only park-summary grace), and
+// env wins over it when set. Undefined, unparseable, or non-positive all mean
+// "no override" — the caller's own default applies.
+function parsePositiveInteger(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number(raw);
+    return Number.isSafeInteger(n) && n >= 1 ? n : undefined;
+}
+/** Live-broker automatic-revive cap override (`CRTR_MAX_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.automaticReviveCap` when set. */
+export function envMaxLiveBrokers() {
+    return parsePositiveInteger(process.env['CRTR_MAX_LIVE_BROKERS']);
+}
+/** Live-broker warning threshold override (`CRTR_WARN_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.warning` when set. */
+export function envWarnLiveBrokers() {
+    return parsePositiveInteger(process.env['CRTR_WARN_LIVE_BROKERS']);
+}
+function parsePositiveMsNoDefault(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
+ *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
+export function envTestUnattendedParkMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_TEST_UNATTENDED_PARK_MS']);
+}
+/** Production unattended-park interval override (`CRTR_UNATTENDED_PARK_MS`), in
+ *  milliseconds; wins over the user-scope config value
+ *  (`readConfig('user').lifecycle.unattendedParkMs`, itself defaulting to 15
+ *  min) whenever set, autostart or not. Unlike `CRTR_TEST_UNATTENDED_PARK_MS`
+ *  this is not gated on `envNoDaemonAutostart()`: it is the env escape hatch
+ *  above the configured knob a deployment sets to tune how long an eligible
+ *  resident idles before its parking turn. */
+export function envUnattendedParkMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_UNATTENDED_PARK_MS']);
+}
+/** Test-only park-summary grace-period override
+ *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
+export function envTestParkSummaryGraceMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS']);
+}
+const DEFAULT_PARK_SUMMARY_GRACE_MS = 5 * 60_000;
+/** The bounded lifetime shared by the daemon's pending-park sweep and its
+ * in-broker isolated turn. */
+export function parkSummaryGraceMs() {
+    return envTestParkSummaryGraceMs() ?? DEFAULT_PARK_SUMMARY_GRACE_MS;
+}

package/dist/shared/generated-context.d.ts

@@ -0,0 +1,83 @@
+/** Custom message carrying the node's session-start bearings. */
+export declare const CONTEXT_INTRO_CUSTOM_TYPE = "crtr-context";
+/** Custom message carrying an ambient situational-context update. */
+export declare const SITUATIONAL_CONTEXT_CUSTOM_TYPE = "crtr-situational-context";
+/** Custom message used when a context-size nudge waits for the next turn. */
+export declare const CONTEXT_NUDGE_CUSTOM_TYPE = "crtr-context-nudge";
+/** Custom message that opens a review companion's visible transcript. */
+export declare const REVIEW_BOUNDARY_CUSTOM_TYPE = "crtr-review-boundary";
+/** Generic completion mandate issued by the terminal-node stop guard. */
+export declare const STALL_REPROMPT: string;
+/** The daemon's parking mandate for an isolated turn. It leaves current truth,
+ * supporting material when needed, lasting lessons, and one deferred update;
+ * the main conversation remains untouched and resumes without a fresh cycle. */
+export declare const PARK_SUMMARY_PROMPT: string;
+/** Static recovery prompts shared by the broker producer and display classifier. */
+export declare const AUTH_FAULT_RECOVERY_BODY = "Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.";
+export declare const CONNECTION_FAULT_RECOVERY_BODY = "The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.";
+/** A run node's connection retry. Its broker never probes the network (its
+ *  model calls go through the daemon), so it cannot claim the network is back;
+ *  the attempt itself is the probe. */
+export declare const RUN_CONNECTION_FAULT_RETRY_BODY = "Your previous turn stopped on a connection error reaching the model provider. Retrying now: continue from where you left off and retry the work that failed.";
+export declare const PROVIDER_FAULT_RECOVERY_BODY = "Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.";
+export type ModelFallbackRecoveryReason = 'credential' | 'not-found';
+/** Format the stop guard's dynamic structured-output mandate. */
+export declare function formatStructuredOutputReprompt(schema: string, requestId: string): string;
+/** Keep model-fallback guidance editable without making it a reader contract. */
+export declare function formatModelFallbackRecovery(previousModel: string, nextModel: string, reason: ModelFallbackRecoveryReason): string;
+export interface GeneratedContextMessageLike {
+    role?: string;
+    customType?: string;
+    content?: unknown;
+}
+export type CardEntryDisposition = 'report' | 'human-answer' | 'human-canceled';
+export interface CardEntry {
+    disposition: CardEntryDisposition;
+    kind: string;
+    body: string;
+    ref?: string;
+}
+export interface CardSender {
+    id: string;
+    updates: number;
+    finished: boolean;
+    entries: CardEntry[];
+}
+/** An already-resolved inbox entry supplied to the pure digest formatter. */
+export interface InboxCardEntry {
+    kind: string;
+    body: string;
+    ref?: string;
+    disposition?: CardEntryDisposition;
+}
+/** An already-resolved sender section supplied to the pure digest formatter. */
+export interface InboxCardSection {
+    id: string;
+    entries: readonly InboxCardEntry[];
+}
+export interface GeneratedCard {
+    kind: string;
+    facts: Readonly<Record<string, string>>;
+    body: string;
+    senders: CardSender[];
+}
+/** Plain text from a generated message's string or text-block content. */
+export declare function generatedContextText(message: GeneratedContextMessageLike): string;
+/** Wrap a user-role runtime message in its whole-message card envelope. */
+export declare function formatCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
+/** Wrap a card whose body is DATA, not markup — the only escape on the API
+ *  path, so a caller can neither emit a malformed card nor smuggle markup into
+ *  one. `formatCard` keeps its raw body for the trusted crouter producers that
+ *  deliberately nest markup (bearings blocks, the inbox `<from>`/`<entry>`
+ *  grammar `parseInboxBody` depends on). */
+export declare function formatDataCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
+/** Parse a runtime envelope, with pre-envelope customType compatibility. */
+export declare function parseCard(message: GeneratedContextMessageLike): GeneratedCard | null;
+/** Whether an inbox entry is the person's own words. A `human-answer` entry
+ *  whose body is itself a runtime card is a runtime notice — review approvals
+ *  were delivered that way before they became plain prose — never speech. */
+export declare function isHumanWordsEntry(entry: CardEntry): boolean;
+/** Explain how an inbox entry's ref is read without guessing its filesystem location. */
+export declare function formatInboxRefInstruction(ref: string): string;
+/** Format a complete inbox card from report bodies resolved by the caller. */
+export declare function formatInboxCard(sections: readonly InboxCardSection[]): string;