@crouter/api 0.3.386 → 0.3.388

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 '@crouter/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/inbox-entry-body.d.ts

@@ -0,0 +1,22 @@
+export declare const INLINE_REPORT_MAX_CHARS = 1000;
+/** The rendering fields both inbox projections share. */
+export interface InboxEntryFields {
+    ts: string;
+    from: string | null;
+    from_name?: string;
+    label: string;
+    ref?: string;
+    data?: Record<string, unknown>;
+}
+/** A report document's ref (`<node>/reports/<name>`), else undefined. */
+export declare function reportRefNodeId(ref: string | undefined): string | undefined;
+/** Clip a body to the bounded preview stored beside a spilled message body. */
+export declare function clipBody(body: string): {
+    text: string;
+    clipped: boolean;
+};
+export declare function inlineBody(entry: Pick<InboxEntryFields, 'data' | 'label'>): string;
+/** One entry's card body: an inlined short report, a bounded inline message body, an event
+ *  push rendered from its metadata, or the label. `report` is the report document's body when
+ *  the caller could read it. */
+export declare function renderEntryBody(entry: InboxEntryFields, report: string | null): string;

package/dist/shared/inbox-entry-body.js

@@ -0,0 +1,116 @@
+// One inbox entry's card body, shared by the daemon (kickoff digest) and broker (live inbox) renderers.
+import { formatInboxRefInstruction } from './generated-context.js';
+const BODY_MAX_LINES = 12;
+const BODY_MAX_CHARS = 1000;
+export const INLINE_REPORT_MAX_CHARS = 1000;
+/** A report document's ref (`<node>/reports/<name>`), else undefined. */
+export function reportRefNodeId(ref) {
+    const match = ref === undefined ? null : /^([a-z0-9-]+)\/reports\/[^/]+$/.exec(ref);
+    return match?.[1];
+}
+/** Clip a body to the bounded preview stored beside a spilled message body. */
+export function clipBody(body) {
+    let text = body;
+    let clipped = false;
+    const lines = text.split('\n');
+    if (lines.length > BODY_MAX_LINES) {
+        text = lines.slice(0, BODY_MAX_LINES).join('\n');
+        clipped = true;
+    }
+    if (text.length > BODY_MAX_CHARS) {
+        text = text.slice(0, BODY_MAX_CHARS);
+        clipped = true;
+    }
+    return { text: text.trimEnd(), clipped };
+}
+export function inlineBody(entry) {
+    const body = typeof entry.data?.['body'] === 'string' ? String(entry.data['body']).trim() : '';
+    return body === '' || body === entry.label ? '' : body;
+}
+function pushOf(entry) {
+    const push = entry.data?.['push'];
+    return typeof push === 'object' && push !== null && typeof push.event === 'string' ? push : null;
+}
+/** The name a reader resolves the object by: `<owner handle>/<name>`, or the owner's id on an older push. */
+function objectRef(o) {
+    const owner = o.owner_handle ?? o.owner;
+    return owner === null || owner === undefined ? o.name : `${owner}/${o.name}`;
+}
+function objectText(o) {
+    if (o.type === 'document')
+        return `[[${objectRef(o)}]]`;
+    if (o.type === 'job')
+        return `job ${o.id} (\`${o.name}\`)`;
+    if (o.type === 'node')
+        return `node ${o.name} (${o.id})`;
+    return `${o.type} ${o.name}`;
+}
+function actorText(entry, push) {
+    if (push.actor === null)
+        return 'the runtime';
+    return entry.from_name === undefined || entry.from_name === push.actor ? push.actor : `${entry.from_name} (${push.actor})`;
+}
+function list(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/** One sentence per event: the object, the actor and the pointer — never the act's content. */
+function renderPush(entry, push) {
+    const obj = objectText(push.object);
+    const actor = actorText(entry, push);
+    const a = push.attrs;
+    const readHint = push.object.type === 'document'
+        ? ` Read it with \`crtr canvas read ${objectRef(push.object)}\`.`
+        : '';
+    switch (push.event) {
+        case 'created':
+            return push.object.type === 'node'
+                ? `${actor} created ${obj}${typeof a['kind'] === 'string' ? `, kind ${a['kind']}` : ''}.`
+                : `${actor} created ${obj}.${readHint}`;
+        case 'read': return `${actor} read ${obj}.`;
+        case 'watched': return `${actor} started watching ${obj}.`;
+        case 'deleted': return `${actor} deleted ${obj}.`;
+        case 'edited': {
+            const authors = list(a['authors']);
+            const rationales = list(a['rationales']);
+            const range = typeof a['from_revision'] === 'number' && typeof a['revision'] === 'number' && a['revision'] - a['from_revision'] > 1
+                ? `revisions ${a['from_revision'] + 1}–${a['revision']}` : typeof a['revision'] === 'number' ? `revision ${a['revision']}` : 'a new revision';
+            const by = authors.length === 0 ? actor : authors.join(', ');
+            const why = rationales.length === 0 ? '' : ` Rationale: ${rationales.join('; ')}.`;
+            const merge = a['needs_merge'] === true ? ' Two edits were made from the same revision; read it and edit it to merge them.' : '';
+            const unwatchHint = ` You get this because you read or wrote it; if it no longer concerns your work, stop with \`crtr canvas unwatch ${objectRef(push.object)}\`.`;
+            return `${by} edited ${obj} (${range}).${why}${merge}${readHint}${unwatchHint}`;
+        }
+        case 'messaged': return `${actor} messaged ${obj}.`;
+        case 'sent': return `${actor} sent a message as ${obj}.`;
+        case 'configured': return `${actor} changed the settings of ${obj}${typeof a['changed'] === 'string' ? `: ${a['changed']}` : ''}.`;
+        case 'exited': return `${obj[0].toUpperCase()}${obj.slice(1)} exited with code ${String(a['exit-code'])}. Log: ${String(a['log-path'])}`;
+        case 'killed': {
+            const by = push.actor === null ? '' : ` by ${actor}`;
+            const why = typeof a['reason'] === 'string' ? ` (${a['reason']})` : '';
+            const claim = a['reason'] === 'deadline'
+                ? ` It was canceled at its deadline; claim it with \`crtr node bash extend ${push.object.id} --for <duration>\` next time.`
+                : '';
+            return `${obj[0].toUpperCase()}${obj.slice(1)} was killed${by}${why}.${claim} Log: ${String(a['log-path'])}`;
+        }
+        default: return entry.label;
+    }
+}
+/** One entry's card body: an inlined short report, a bounded inline message body, an event
+ *  push rendered from its metadata, or the label. `report` is the report document's body when
+ *  the caller could read it. */
+export function renderEntryBody(entry, report) {
+    if (report !== null && report.length < INLINE_REPORT_MAX_CHARS && entry.ref !== undefined) {
+        return `${report.trimEnd()}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    }
+    const body = inlineBody(entry);
+    if (body === '') {
+        const push = pushOf(entry);
+        if (push !== null && entry.ref === undefined)
+            return renderPush(entry, push);
+        return entry.ref === undefined ? entry.label : `${entry.label}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    }
+    const { text, clipped } = clipBody(body);
+    if (entry.ref !== undefined)
+        return `${text}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    return clipped ? `${text}\n… (body clipped)` : text;
+}

package/dist/shared/working-activity.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_WORKING_GERUND = "working";
+export declare const DEFAULT_WORKING_GERUNDS: readonly ["thinking", "planning", "checking", "working"];
+export declare const DEFAULT_WORKING_ACTIVITY = "Working...";
+/** Keep only usable configured labels; malformed or empty lists fall back to working. */
+export declare function normalizeWorkingGerunds(value: unknown): string[];
+/** Format one configured gerund as the activity label shown by every viewer. */
+export declare function formatWorkingActivity(gerund: unknown): string;
+/** Pick one configured gerund when the broker receives a user message. */
+export declare function randomWorkingActivity(value: unknown, random?: () => number): string;

package/dist/shared/working-activity.js

@@ -0,0 +1,27 @@
+export const DEFAULT_WORKING_GERUND = 'working';
+export const DEFAULT_WORKING_GERUNDS = ['thinking', 'planning', 'checking', DEFAULT_WORKING_GERUND];
+export const DEFAULT_WORKING_ACTIVITY = 'Working...';
+/** Keep only usable configured labels; malformed or empty lists fall back to working. */
+export function normalizeWorkingGerunds(value) {
+    if (!Array.isArray(value))
+        return [DEFAULT_WORKING_GERUND];
+    const gerunds = value
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return gerunds.length > 0 ? gerunds : [DEFAULT_WORKING_GERUND];
+}
+/** Format one configured gerund as the activity label shown by every viewer. */
+export function formatWorkingActivity(gerund) {
+    const normalized = normalizeWorkingGerunds([gerund])[0] ?? DEFAULT_WORKING_GERUND;
+    return `${normalized[0].toUpperCase()}${normalized.slice(1)}...`;
+}
+/** Pick one configured gerund when the broker receives a user message. */
+export function randomWorkingActivity(value, random = Math.random) {
+    const gerunds = normalizeWorkingGerunds(value);
+    const draw = random();
+    const index = Number.isFinite(draw)
+        ? Math.min(gerunds.length - 1, Math.max(0, Math.floor(draw * gerunds.length)))
+        : 0;
+    return formatWorkingActivity(gerunds[index]);
+}