@north-light/crouter 0.3.233 → 0.3.234

package/dist/pi-extensions/canvas-stophook.js

@@ -20,6 +20,7 @@
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
+import { envNodeId } from '../shared/env.js';
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { contextDir, jobDir } from '../core/canvas/paths.js';
@@ -79,9 +80,7 @@ function flushTelemetry(jobDirPath, tokensIn, tokensOut, model, contextTokens, a
         /* telemetry is best-effort; never surface */
     }
 }
-// ---------------------------------------------------------------------------
 // Message-extraction helpers
-// ---------------------------------------------------------------------------
 /** Walk backwards through the agent_end messages array to find the last
  *  assistant turn. */
 function lastAssistantMessage(messages) {
@@ -117,7 +116,6 @@ function currentReviewBoundaryIds(ctx) {
         return [];
     }
 }
-// ---------------------------------------------------------------------------
 // Context-size steering bands — a single shared schedule of thresholds that
 // ESCALATE in tone as input context grows. The first band is a gentle
 // "consider it"; a later band turns firm. The schedule TIGHTENS as it climbs:
@@ -150,7 +148,6 @@ function currentReviewBoundaryIds(ctx) {
 // worthwhile parallel work. Only a terminal node is ever told `push final` (a
 // resident finishes by yielding or being closed); only an orchestrator already
 // HAS a roadmap to checkpoint before it yields.
-// ---------------------------------------------------------------------------
 const STEER_STEP = 10_000;
 // Shared escalation schedule (both lifecycles). Tightens as it climbs:
 // 130k, 150k, 170k, 185k, 200k, then every 10k (210k, 220k, …).
@@ -233,9 +230,7 @@ export function steerNote(at, lifecycle, mode) {
     }
     return `Context ~${k}k — this is getting long. Wrap up now before this context overflows: \`crtr push final\` if you're close, otherwise \`crtr node yield\` immediately to continue in a fresh window against your goal and your note.`;
 }
-// ---------------------------------------------------------------------------
 // Extension
-// ---------------------------------------------------------------------------
 /**
  * Register the canvas turn and settlement handlers on `pi`.
  *
@@ -245,7 +240,7 @@ export function steerNote(at, lifecycle, mode) {
  * per node lifecycle, matching how pi loads extensions).
  */
 export function registerCanvasStophook(pi) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return; // not a canvas node
     const jobDirPath = jobDir(nodeId);
@@ -310,7 +305,6 @@ export function registerCanvasStophook(pi) {
         touchBusy(nodeId);
         clearFault(nodeId, { link: 'daemon→node' });
     };
-    // ---------------------------------------------------------------------------
     // session_start — capture pi's session id, and detect `/new`.
     //
     // pi tags each session_start with a `reason`: 'startup' on boot (a fresh
@@ -327,7 +321,6 @@ export function registerCanvasStophook(pi) {
     //
     // `/new` splits by who ran it: crtrd derives rootness from the node row and
     // either directs a root relaunch or resets a child's session coordinates.
-    // ---------------------------------------------------------------------------
     pi.on('session_start', async (event, ctx) => {
         try {
             const id = ctx?.sessionManager?.getSessionId?.();
@@ -390,11 +383,9 @@ export function registerCanvasStophook(pi) {
             });
         }
     });
-    // ---------------------------------------------------------------------------
     // agent_start — pi entered a turn. Mark the node mid-turn (busy) so a
     // focus-away while it is genuinely working backstages it (Invariant F2)
     // rather than reaping it. Cleared only after the whole run settles.
-    // ---------------------------------------------------------------------------
     pi.on('agent_start', () => {
         // A fresh turn started. Keep any active fault marker in place so the daemon's
         // retry accounting survives a failed retry cycle; just mark the turn busy.
@@ -403,7 +394,6 @@ export function registerCanvasStophook(pi) {
         }
         catch { /* best-effort */ }
     });
-    // ---------------------------------------------------------------------------
     // input — a new user-directed run is beginning. This is the ONLY place stop
     // signals are cleared: `agent_start` re-fires for pi's automatic retries and
     // post-compaction continuations within the SAME run, so clearing there would
@@ -413,18 +403,15 @@ export function registerCanvasStophook(pi) {
     // `agent_settled` consumes them; a leftover from an errored or interrupted run
     // of this same broker is discarded here, when the next prompt arrives (the pid
     // stamp only rules out a PRIOR broker's markers, not this broker's own).
-    // ---------------------------------------------------------------------------
     pi.on('input', () => {
         try {
             clearStopSignals(nodeId);
         }
         catch { /* best-effort */ }
     });
-    // ---------------------------------------------------------------------------
     // tool_execution_start — capture the live "what is it doing" cue. Writes the
     // one-line tool summary to telemetry.json so out-of-process readers (the nav
     // chrome) show it inline without a second file or any extra read on their side.
-    // ---------------------------------------------------------------------------
     pi.on('tool_execution_start', (event) => {
         try {
             lastActivity = summarizeActivity(String(event?.toolName ?? ''), event?.args);
@@ -434,7 +421,6 @@ export function registerCanvasStophook(pi) {
         }
         catch { /* best-effort */ }
     });
-    // ---------------------------------------------------------------------------
     // tool_execution_update — wedge heartbeat + fault clear only. Fired with
     // partial/streaming tool output (when a tool reports progress); throttled via
     // `heartbeat()` since it can arrive many times per second. Most tools (e.g.
@@ -442,27 +428,23 @@ export function registerCanvasStophook(pi) {
     // for them — it exists so any tool that DOES stream partial output (now or in
     // the future) counts as live progress instead of tripping the wedge detector,
     // AND clears any wedge notice that already fired before this progress resumed.
-    // ---------------------------------------------------------------------------
     pi.on('tool_execution_update', () => {
         try {
             heartbeat();
         }
         catch { /* best-effort */ }
     });
-    // ---------------------------------------------------------------------------
     // message_update — wedge heartbeat + fault clear only. Fired token-by-token
     // while the assistant is actively streaming a reply — genuine progress,
     // throttled the same way, and equally clears a stale wedge notice if streaming
     // resumes before a coarser boundary. A node stuck streaming forever without
     // ever firing this is exactly the daemon's busy+quiet wedge signature.
-    // ---------------------------------------------------------------------------
     pi.on('message_update', () => {
         try {
             heartbeat();
         }
         catch { /* best-effort */ }
     });
-    // ---------------------------------------------------------------------------
     // tool_execution_end — IMMEDIATE refresh-yield. When a tool this turn set
     // intent='refresh' (the node ran `crtr node yield`), shut the broker down NOW
     // instead of letting the model keep burning its bloated context to the turn's
@@ -494,11 +476,9 @@ export function registerCanvasStophook(pi) {
         }
         catch { /* best-effort */ }
     });
-    // ---------------------------------------------------------------------------
     // session_shutdown — Pi's clean /quit fact goes to crtrd, which owns the
     // finish transition, focus teardown, presence clear, and fault clear. Other
     // session swaps keep the same node and need no durable settlement.
-    // ---------------------------------------------------------------------------
     pi.on('session_shutdown', async (event, ctx) => {
         clearBusy(nodeId); // turn marker is meaningless once Pi is exiting
         if (event?.reason !== 'quit')
@@ -525,10 +505,8 @@ export function registerCanvasStophook(pi) {
         if (typeof msg.model === 'string' && msg.model !== '')
             model = msg.model;
     };
-    // ---------------------------------------------------------------------------
     // turn_end — live telemetry refresh.
     // event shape: { message: AssistantMessage, ... }
-    // ---------------------------------------------------------------------------
     pi.on('turn_end', async (event, ctx) => {
         accumulate(event?.message);
         // The CURRENT context size via ctx.getContextUsage() — the exact figure pi's
@@ -615,10 +593,8 @@ export function registerCanvasStophook(pi) {
         }
         catch { /* best-effort */ }
     });
-    // ---------------------------------------------------------------------------
     // agent_settled — Pi supplies stop facts; crtrd commits every canvas effect
     // and returns the one Pi-side consequence to enact.
-    // ---------------------------------------------------------------------------
     pi.on('agent_settled', async (_event, ctx) => {
         const event = stagedAgentEnd;
         stagedAgentEnd = null;

package/dist/pi-extensions/canvas-structured-output.js

@@ -3,6 +3,7 @@
 // Loaded into every canvas node. Inert unless nodes/<id>/output-schema.json exists
 // and is valid. If the request file is malformed, the tool is not registered — the
 // stop-guard will reprompt the node with an explicit error about the invalid file.
+import { envNodeId } from '../shared/env.js';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { validateToolArguments } from '@earendil-works/pi-ai';
@@ -168,7 +169,7 @@ function toolDescription(request) {
     return 'Submit the requested one-off structured result. Calling this records the result, pushes an update report automatically, frees you from the structured-output gate, and lets you continue working.';
 }
 export function registerCanvasStructuredOutput(pi) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return;
     let registeredKey = null;

package/dist/pi-extensions/canvas-tool-guide.js

@@ -3,6 +3,7 @@
 // Capturing `crtr -h` builds the full configured command tree, including commands
 // discovered from the node's cwd. It runs only at session start; before_agent_start
 // injects the last successful capture without starting work or waiting.
+import { envNodeId } from '../shared/env.js';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -25,7 +26,7 @@ function injectToolGuide(systemPrompt, helpText) {
 }
 /** Register the root crtr tool-guide injection for a canvas node. */
 export function registerCanvasToolGuide(pi) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return;
     let helpText = '';

package/dist/shared/__tests__/env-boundary.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/__tests__/env-boundary.test.js

@@ -0,0 +1,93 @@
+// `shared/env.ts` is the reader-side surface for the env vars listed below —
+// every one of them was migrated off a scattered `process.env` read onto a
+// named accessor there. This grep-enforces that boundary: outside the owner
+// module itself, a read of any migrated var may live only in an explicitly
+// documented exemption — a distinct, non-read use of the SAME var. Exemptions
+// are itemized below so a new stray read fails loud instead of silently
+// reintroducing the var outside its accessor.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve, relative } from 'node:path';
+const SRC_ROOT = resolve(process.cwd(), 'src');
+// Every var migrated onto an accessor in `shared/env.ts`. Complete: every
+// forbidden-file sweep has landed, so this is the full migrated set.
+const MIGRATED_VARS = [
+    'CRTR_NODE_ID',
+    'CRTR_PROFILE_ID',
+    'CRTR_NODE_CWD',
+    'CRTR_MODEL_INTENT',
+    'CRTR_HOME',
+    'CRTR_STREAM_WATCHDOG_MS',
+    'CRTR_WATCHER_TICK_MS',
+    'CRTR_WATCHER_DEBOUNCE_MS',
+    'CRTR_RECAP_IDLE_MS',
+    'CRTR_RECAP_MODEL',
+    'CRTR_BASH_VALVE_MS',
+    'CRTR_PIDFILE',
+    'CRTR_BROKER_ENGINE',
+    'CRTR_PI_BINARY',
+    'CRTR_NO_DAEMON_AUTOSTART',
+    'CRTRD_TCP',
+    'CRTR_NO_EXPORTS',
+    'CRTR_DEBUG',
+    'CRTR_MAX_LIVE_BROKERS',
+    'CRTR_WARN_LIVE_BROKERS',
+    'CRTR_TEST_UNATTENDED_PARK_MS',
+    'CRTR_TEST_PARK_SUMMARY_GRACE_MS',
+];
+// Matches `process.env['VAR']`, `process.env.VAR`, or `process.env[\`VAR\`]`
+// for exactly one of MIGRATED_VARS — not a longer name that merely starts
+// with it (e.g. `CRTR_DEBUG_PID_LIVENESS` must NOT match `CRTR_DEBUG`).
+const VAR_PATTERN = MIGRATED_VARS.join('|');
+const READ_RE = new RegExp(String.raw `process\.env(?:\.(?:${VAR_PATTERN})\b|\[['"\`](?:${VAR_PATTERN})['"\`]\])`);
+// Relative to src/, forward-slash form. Each entry is a genuinely distinct
+// use of the SAME var name that the migration deliberately leaves in place —
+// not an unmigrated read.
+const EXEMPTIONS = new Map([
+    [
+        'core/canvas/paths.ts',
+        'crtrHome() is the canonical resolved-path accessor for CRTR_HOME; ' +
+            'envHomeOverride() in shared/env.ts is for callers that want the raw ' +
+            'override itself (see the header comment there).',
+    ],
+    [
+        'core/runtime/broker.ts',
+        "clears CRTR_MODEL_INTENT via `delete process.env[...]` — a mutation, " +
+            'not a read, so it stays here per shared/env.ts\'s header comment.',
+    ],
+]);
+function tsFilesUnder(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const path = join(dir, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory()) {
+            if (entry === '__tests__')
+                continue;
+            out.push(...tsFilesUnder(path));
+        }
+        else if (entry.endsWith('.ts') && !entry.endsWith('.test.ts')) {
+            out.push(path);
+        }
+    }
+    return out;
+}
+test('every migrated env var is read only through shared/env.ts or an explicit exemption', () => {
+    const offenders = [];
+    for (const file of tsFilesUnder(SRC_ROOT)) {
+        const relPath = relative(SRC_ROOT, file).split('\\').join('/');
+        if (relPath === 'shared/env.ts')
+            continue;
+        if (EXEMPTIONS.has(relPath))
+            continue;
+        const source = readFileSync(file, 'utf8');
+        const lines = source.split('\n');
+        lines.forEach((line, index) => {
+            if (READ_RE.test(line)) {
+                offenders.push(`${relPath}:${index + 1}: ${line.trim()}`);
+            }
+        });
+    }
+    assert.deepEqual(offenders, [], `migrated env var read(s) outside shared/env.ts and its exemptions:\n${offenders.join('\n')}`);
+});

package/dist/shared/env.d.ts

@@ -0,0 +1,68 @@
+/** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
+export declare function envNodeId(): 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;
+/** 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;
+/** 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;
+/** 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;
+/** 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;
+/** 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;
+/** Test-only park-summary grace-period override
+ *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
+export declare function envTestParkSummaryGraceMs(): number | undefined;

package/dist/shared/env.js

@@ -0,0 +1,171 @@
+// 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`.
+// Identity
+/** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
+export function envNodeId() {
+    return process.env['CRTR_NODE_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'];
+}
+/** 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'];
+}
+// 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_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);
+}
+/** 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'];
+}
+/** 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 (config for the
+// thresholds, a hardcoded production constant for the intervals) supplies
+// the default, 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']);
+}
+/** 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']);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.233",
+  "version": "0.3.234",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -74,6 +74,8 @@
     "typecheck:pi-packages": "npx tsc -p src/builtin-pi-packages/pi-crtr-extensions/tsconfig.json",
     "test:build-output": "node scripts/build-concurrency-test.mjs",
     "check:cli-no-canvas": "node scripts/check-cli-no-canvas.mjs",
+    "check:daemon-no-barrel": "node scripts/check-daemon-no-barrel.mjs",
+    "check:quote-style": "node scripts/check-quote-style.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "install-runtime": "node scripts/install-runtime.mjs",
     "prepack": "node scripts/runtime-lock.mjs prepack",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.233",
+  "version": "0.3.234",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.233",
+      "version": "0.3.234",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/dist/core/canvas/render.d.ts

@@ -1,47 +0,0 @@
-import { type DashboardRow } from './render-source.js';
-export * from './render-source.js';
-/**
- * Render the subscription sub-DAG rooted at `rootId` as an ASCII tree.
- * The root is the first line (no connector prefix); children are indented.
- *
- * Each line: `<glyph> <name> [<kind>/<mode>] ctx <Nk>[ ⚑<asks>]`
- *
- * Returns a multi-line string (no trailing newline).
- */
-export declare function renderTree(rootId: string): string;
-/**
- * Render all canvas roots as a forest. A root is a node with no subscribers
- * (no one subscribes to it = it has no managers in the org chart).
- *
- * If there are no roots on the canvas, returns a placeholder string.
- */
-export declare function renderForest(): string;
-/** One row per node visible in the sub-DAG of `rootId` (including root). */
-export declare function dashboardRows(rootId: string): DashboardRow[];
-/**
- * CHEAP boot builder — one row per node across the entire canvas, with only the
- * fields that need no per-node meta/telemetry/session read. Two db queries total:
- * `listNodes()` + `listFocuses()` (the focus set replaces per-node getFocusByNode
- * calls). See {@link dashboardRowFromNodeRow} for the per-row projection, and
- * {@link enrichRow}/{@link enrichRows}/{@link loadPreview} for the lazy fields.
- */
-export declare function dashboardRowsAll(): DashboardRow[];
-/** Fold the cheap-boot row's deferred fields in for ONE row: the full label
- *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
- *  meta read + one telemetry read + one ticket scan. Idempotent (no-op once enriched).
- *  For a batch, prefer {@link enrichRows} — it scans each cwd's ticket inbox once. */
-export declare function enrichRow(row: DashboardRow): DashboardRow;
-/** Batch {@link enrichRow}: enrich every not-yet-enriched row, scanning each
- *  distinct cwd's ticket inbox exactly ONCE (via `ticketCountsForNodes`) instead
- *  of per row. Use this for a whole viewport / the full forest; mutates each row in place. */
-export declare function enrichRows(rows: DashboardRow[]): void;
-/** Load the SELECTED row's preview text: the spawn `goal` (initial-prompt.md) plus
- *  the whole-conversation `prompts` and the `lastAssistant` reply — the latter two
- *  folded into ONE session-file read (see {@link readSessionParts}). Mutates the row
- *  in place; idempotent. Call only for the cursor row (and lazily/in-background to
- *  warm the prompt super-search corpus), never on the boot path. */
-export declare function loadPreview(row: DashboardRow): DashboardRow;
-/** {@link isStreaming} keyed by node id alone — hydrates the broker pid off the
- *  db row. The exported "is this node actively generating right now?" guard so a
- *  reap never nukes a node mid-first-turn before its output lands on disk. */
-export declare function isNodeStreaming(nodeId: string): boolean;