@north-light/crouter 0.3.232 → 0.3.234

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -11,6 +11,7 @@
 // trigger, so the agent cannot run on context alone before hearing the person.
 // A context-only batch keeps its wake by triggering on its LAST card while idle,
 // and rides the running turn while streaming.
+import { envNodeId, envProfileId, envWatcherDebounceMs, envWatcherTickMs } from '../shared/env.js';
 import { coalesceBrokerInbox, entryCards, readBrokerCanceledEntryIds, readBrokerCursor, readBrokerInboxSince, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
 import { advanceBrokerInboxCursor, brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { emitEvent } from '../core/events/emit.js';
@@ -18,8 +19,6 @@ import { errorClassFromError } from '../core/events/errors.js';
 import { operationIdContext } from '../core/events/operation-id.js';
 import { situationalContextEnvelope, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
 import { isProfilePaused } from '../core/profiles/manifest.js';
-const DEFAULT_TICK_MS = 800;
-const DEFAULT_DEBOUNCE_MS = 1000;
 const MAX_PENDING_HANDOFFS = 64;
 const MAX_SOURCE_OPERATION_IDS = 16;
 let currentWatcher;
@@ -31,26 +30,20 @@ class WatcherFatalError extends Error {
     }
 }
 function resolveCadence() {
-    const parse = (raw, fallback) => {
-        if (raw === undefined)
-            return fallback;
-        const value = Number(raw);
-        return Number.isFinite(value) && value > 0 ? value : fallback;
-    };
     return {
-        tickMs: parse(process.env['CRTR_WATCHER_TICK_MS'], DEFAULT_TICK_MS),
-        debounceMs: parse(process.env['CRTR_WATCHER_DEBOUNCE_MS'], DEFAULT_DEBOUNCE_MS),
+        tickMs: envWatcherTickMs(),
+        debounceMs: envWatcherDebounceMs(),
     };
 }
 function currentNodeId() {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     return nodeId === undefined || nodeId.trim() === '' ? undefined : nodeId;
 }
 /** The node's profile, read fresh each poll: `crtr profile pause` mutates the
  *  manifest file directly, so a live broker sees the flip on its next tick with
  *  no daemon round-trip. '' is the historical no-profile row. */
 function profilePaused() {
-    const profileId = process.env['CRTR_PROFILE_ID'];
+    const profileId = envProfileId();
     return profileId !== undefined && profileId !== '' && isProfilePaused(profileId);
 }
 function isFilesystemError(error) {

package/dist/pi-extensions/canvas-passive-context.js

@@ -18,6 +18,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 { existsSync, readFileSync } from 'node:fs';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { reportPathFromRef } from '../core/runtime/broker-extension-render.js';
@@ -26,9 +27,7 @@ import { parseCard } from '../shared/generated-context.js';
 // Per-entry body cap so a single fat report can't blow the context budget. The
 // full report stays on disk at `ref` if the agent needs more.
 const BODY_CAP = 4_000;
-// ---------------------------------------------------------------------------
 // Report dereference — turn a passive pointer into the message text it carries.
-// ---------------------------------------------------------------------------
 /** Strip the leading YAML frontmatter block a report is written with, returning
  *  just the body. Tolerant: no frontmatter → returns the input unchanged. */
 function stripFrontmatter(raw) {
@@ -126,9 +125,7 @@ export function placeBacklog(text, preText) {
     const bodyStart = text.length - card.body.length - CARD_CLOSE.length;
     return `${text.slice(0, bodyStart)}${preText}\n${text.slice(bodyStart)}`;
 }
-// ---------------------------------------------------------------------------
 // Extension
-// ---------------------------------------------------------------------------
 /**
  * Register the passive-context drain on `pi`.
  *
@@ -138,7 +135,7 @@ export function placeBacklog(text, preText) {
 export function registerCanvasPassiveContext(pi) {
     pi.on('input', async (event) => {
         try {
-            const nodeId = process.env['CRTR_NODE_ID'];
+            const nodeId = envNodeId();
             if (nodeId === undefined || nodeId.trim() === '')
                 return; // not a canvas node
             const drained = drainBrokerPassive(nodeId);

package/dist/pi-extensions/canvas-preview-result.js

@@ -6,6 +6,7 @@
 // mirrors its record there, and this hook attaches the record to Pi's
 // ToolResult.details. The attach viewer can render a structured preview
 // without parsing the agent-facing text.
+import { envNodeId } from '../shared/env.js';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { previewResultPath } from '../core/preview-result-path.js';
 function isPreviewRecord(value) {
@@ -19,7 +20,7 @@ function isPreviewRecord(value) {
 /** Loaded into every canvas broker. Plain Pi sessions have no node id and
  * deliberately receive no filesystem transport. */
 export function registerCanvasPreviewResult(pi) {
-    if (process.env['CRTR_NODE_ID'] === undefined || process.env['CRTR_NODE_ID'] === '')
+    if (envNodeId() === undefined || envNodeId() === '')
         return;
     pi.on('tool_result', (event) => {
         if (event.toolName !== 'bash')

package/dist/pi-extensions/canvas-prompt-scrub.js

@@ -23,6 +23,7 @@
 //
 // Every rule below is anchored to pi's exact wording and degrades to a no-op if
 // pi rewords, so a pi upgrade can never break a turn here.
+import { envNodeId } from '../shared/env.js';
 const PI_IDENTITY = 'You are an expert coding assistant operating inside pi, a coding agent harness.';
 const NEUTRAL_IDENTITY = 'You are an expert coding assistant.';
 const PI_DOCS_MARKER = 'Pi documentation (read only';
@@ -40,7 +41,7 @@ export function scrubPromptSelfReference(systemPrompt) {
 }
 /** Register the system-prompt scrub for a canvas node. */
 export function registerCanvasPromptScrub(pi) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return;
     pi.on('before_agent_start', (event) => {

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

@@ -38,20 +38,17 @@
 //
 // 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, envRecapIdleMs } from '../shared/env.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { generateRecap } from '../core/runtime/recap.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
 import { editorLabelForBrokerNode } from '../core/runtime/broker-extension-render.js';
 import { generateAndCommitRecapName, readRoadmap } from './broker-local.js';
-// ---------------------------------------------------------------------------
 // Tuning constants
-// ---------------------------------------------------------------------------
 /** No-new-message window before a recap is shown. 60s by default; override with
  *  CRTR_RECAP_IDLE_MS (for fast runtime verification). */
 function idleMs() {
-    const raw = process.env['CRTR_RECAP_IDLE_MS'];
-    const n = raw !== undefined ? parseInt(raw, 10) : NaN;
-    return Number.isFinite(n) && n > 0 ? n : 60_000;
+    return envRecapIdleMs();
 }
 /** How often the single low-rate timer checks elapsed-since-last-message. */
 const POLL_MS = 7_000;
@@ -62,14 +59,10 @@ const CONVO_EDGE_MESSAGES = 5;
  *  (10 messages × this ≈ the total budget the model needs for the gist). */
 const MESSAGE_CHAR_BUDGET = 1_200;
 const WIDGET_KEY = 'crtr-recap';
-// ---------------------------------------------------------------------------
 // Module-level state — persists across /reload so the timer doesn't stack.
-// ---------------------------------------------------------------------------
 /** The one live poll timer. Cleared and replaced on every re-registration. */
 let liveTimer;
-// ---------------------------------------------------------------------------
 // Conversation extraction — literal user+assistant text ONLY.
-// ---------------------------------------------------------------------------
 /** Pull the literal text out of a message's content (string or text blocks),
  *  dropping non-text blocks (thinking, toolCall, image). */
 function messageText(msg) {
@@ -162,9 +155,7 @@ function buildNamingConversation(sm, assistantPartial, reviewId) {
     });
     return sampled.join('\n\n');
 }
-// ---------------------------------------------------------------------------
 // Extension
-// ---------------------------------------------------------------------------
 /**
  * Register the inactivity-recap chrome on `pi`.
  *
@@ -172,7 +163,7 @@ function buildNamingConversation(sm, assistantPartial, reviewId) {
  * or legacy job agent loads it as a no-op.
  */
 export function registerCanvasRecap(pi, recapGenerator = generateRecap, nameRegenerator) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return; // not a canvas node
     // Captured on session_start; used by the timer and the message handlers.
@@ -344,9 +335,7 @@ export function registerCanvasRecap(pi, recapGenerator = generateRecap, nameRege
             requestRecap(true);
         },
     });
-    // -------------------------------------------------------------------------
     // Events
-    // -------------------------------------------------------------------------
     pi.on('session_start', (_event, ctx) => {
         ui = ctx.ui;
         sessionManager = ctx.sessionManager;
@@ -382,9 +371,7 @@ export function registerCanvasRecap(pi, recapGenerator = generateRecap, nameRege
         captureLiveModel(ctx);
         onMessage();
     });
-    // -------------------------------------------------------------------------
     // The single low-rate idle poll.
-    // -------------------------------------------------------------------------
     if (liveTimer !== undefined)
         clearInterval(liveTimer);
     const timer = setInterval(() => {

package/dist/pi-extensions/canvas-review-boundary.js

@@ -4,13 +4,12 @@
 // inherited fork context and before canvas-context-intro appends fork bearings.
 // The display projection starts at this marker while the model keeps the full
 // inherited context.
+import { envNodeId } from '../shared/env.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { isReviewBoundary, REVIEW_BOUNDARY_CUSTOM_TYPE } from '../core/runtime/session-visibility.js';
 import { formatCard, parseCard } from '../shared/generated-context.js';
 import { truncateToWidth } from './truncate.js';
-// ---------------------------------------------------------------------------
 // Collapsed-by-default rendering
-// ---------------------------------------------------------------------------
 /** Render the marker as a single compact divider; its full content remains in
  * the message list for the model and generated-context presenters. */
 export function renderReviewBoundary(message, options, theme) {
@@ -32,9 +31,7 @@ export function renderReviewBoundary(message, options, theme) {
         },
     };
 }
-// ---------------------------------------------------------------------------
 // Extension
-// ---------------------------------------------------------------------------
 /**
  * Register the review boundary marker. Companion nodes receive one boundary
  * marker on session_start that separates inherited context from the visible
@@ -43,7 +40,7 @@ export function renderReviewBoundary(message, options, theme) {
 export function registerCanvasReviewBoundary(pi) {
     pi.registerMessageRenderer(REVIEW_BOUNDARY_CUSTOM_TYPE, renderReviewBoundary);
     pi.on('session_start', async (_event, ctx) => {
-        const nodeId = process.env['CRTR_NODE_ID'];
+        const nodeId = envNodeId();
         if (!nodeId || nodeId.trim() === '')
             return;
         let node;

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;