@north-light/crouter 0.3.233 → 0.3.234

package/dist/core/runtime/stream-watchdog.js

@@ -13,23 +13,18 @@
 // generation so settlement records an automatic pi→provider connection fault;
 // the existing fault-retry machinery owns re-driving the turn. The broker
 // process — and its in-memory queues — survives instead of being killed.
-const DEFAULT_STREAM_WATCHDOG_MS = 5 * 60_000; // 5 minutes.
-// Comfortably under the daemon's 20-minute WEDGE_QUIET_MS hard kick (crtrd.ts),
-// so this is the common-case recovery path and the daemon kick becomes the rare
-// backstop. Generous enough that a live, healthy stream never trips it: a
-// single LLM turn's own network round-trips (message_update deltas,
-// tool_execution_start/update/end) land well inside 5 minutes. The watchdog
-// covers ONLY time awaiting the provider: the broker disarms it while a tool is
-// executing (a legitimately silent tool can run longer than the timeout — see
-// broker.ts relayEvent) and rearms it once the last in-flight tool ends, so a
-// slow-but-live turn is never mistaken for a dead one.
-export function resolveStreamWatchdogMs() {
-    const raw = process.env['CRTR_STREAM_WATCHDOG_MS'];
-    if (raw === undefined)
-        return DEFAULT_STREAM_WATCHDOG_MS;
-    const n = Number(raw);
-    return Number.isFinite(n) && n > 0 ? n : DEFAULT_STREAM_WATCHDOG_MS;
-}
+// The default is 5 minutes, comfortably under the daemon's 20-minute
+// WEDGE_QUIET_MS hard kick (crtrd.ts), so this is the common-case recovery
+// path and the daemon kick becomes the rare backstop. Generous enough that a
+// live, healthy stream never trips it: a single LLM turn's own network
+// round-trips (message_update deltas, tool_execution_start/update/end) land
+// well inside 5 minutes. The watchdog covers ONLY time awaiting the provider:
+// the broker disarms it while a tool is executing (a legitimately silent tool
+// can run longer than the timeout — see broker.ts relayEvent) and rearms it
+// once the last in-flight tool ends, so a slow-but-live turn is never mistaken
+// for a dead one. See `envStreamWatchdogMs()` (`shared/env.ts`) for the parsed
+// `CRTR_STREAM_WATCHDOG_MS` accessor and default value.
+import { envStreamWatchdogMs } from '../../shared/env.js';
 /**
  * A single-timer dead-man's switch: `poke(token)` (re)arms it, `clear()`
  * disarms it, and `onStall(token)` fires exactly once if `poke()` isn't called
@@ -50,7 +45,7 @@ export class StreamWatchdog {
     ms;
     constructor(onStall, ms) {
         this.onStall = onStall;
-        this.ms = ms ?? resolveStreamWatchdogMs();
+        this.ms = ms ?? envStreamWatchdogMs();
     }
     /** Proof of progress — (re)arm the timer for `token`, canceling any prior
      *  countdown. The fired `onStall` receives THIS arm's token. Inert while

package/dist/core/runtime/tmux-bindings.js

@@ -10,9 +10,7 @@ import { normalizeTmuxPassthrough } from '../config.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
 import { runTmux as tmux, shellQuote } from './tmux-driver.js';
-// ---------------------------------------------------------------------------
 // Crouter-owned tmux bindings
-// ---------------------------------------------------------------------------
 const TMUX_BINDING_MANIFEST = '@crtr_keybindings_manifest';
 const ROOT_TABLE = 'root';
 const LEAF_MENU_ACTIONS = {

package/dist/core/runtime/tmux-driver.d.ts

@@ -7,6 +7,18 @@ declare function tmux(args: string[]): {
     stderr: string;
 };
 export declare function inTmux(): boolean;
+/** Is any tmux SESSION currently up? `tmux list-sessions` exits 0 iff a server
+ *  is running with at least one session, non-zero otherwise (including "no
+ *  server"). This is the boot-time/bash-tooling probe — distinct from
+ *  `tmuxClientsReachable`, which asks whether a server is reachable at all
+ *  regardless of session count and is the human-surface gate. */
+export declare function tmuxSessionsReachable(): boolean;
+/** Is the tmux SERVER reachable at all? `tmux list-clients` exits 0 whenever a
+ *  server is up (even with zero attached clients), non-zero when no server is
+ *  running. This is the human-surface gate (core/spawn.ts's
+ *  `tmuxServerReachable`) — distinct from `tmuxSessionsReachable`, which
+ *  additionally requires a session to exist. */
+export declare function tmuxClientsReachable(): boolean;
 /** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
  *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
  *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of

package/dist/core/runtime/tmux-driver.js

@@ -7,9 +7,8 @@ import { execFile, spawnSync } from 'node:child_process';
 import { encodeAttachControlInput, } from '../keybindings/index.js';
 import { bundledPiCommandForShell } from './pi-cli.js';
 import { shellQuote } from '../../shared/shell-quote.js';
-// ---------------------------------------------------------------------------
+import { envPiBinaryOverride } from '../../shared/env.js';
 // tmux invocation
-// ---------------------------------------------------------------------------
 export { shellQuote };
 function tmux(args) {
     const r = spawnSync('tmux', args, { encoding: 'utf8' });
@@ -25,6 +24,22 @@ function tmuxOnSocket(socket, args) {
 export function inTmux() {
     return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
 }
+/** Is any tmux SESSION currently up? `tmux list-sessions` exits 0 iff a server
+ *  is running with at least one session, non-zero otherwise (including "no
+ *  server"). This is the boot-time/bash-tooling probe — distinct from
+ *  `tmuxClientsReachable`, which asks whether a server is reachable at all
+ *  regardless of session count and is the human-surface gate. */
+export function tmuxSessionsReachable() {
+    return spawnSync('tmux', ['list-sessions'], { encoding: 'utf8', stdio: 'ignore' }).status === 0;
+}
+/** Is the tmux SERVER reachable at all? `tmux list-clients` exits 0 whenever a
+ *  server is up (even with zero attached clients), non-zero when no server is
+ *  running. This is the human-surface gate (core/spawn.ts's
+ *  `tmuxServerReachable`) — distinct from `tmuxSessionsReachable`, which
+ *  additionally requires a session to exist. */
+export function tmuxClientsReachable() {
+    return spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8' }).status === 0;
+}
 /** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
  *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
  *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of
@@ -63,9 +78,7 @@ export function currentTmux() {
     const [session, window, pane] = r.stdout.split('\t');
     return { session, window, pane };
 }
-// ---------------------------------------------------------------------------
 // Sessions + windows
-// ---------------------------------------------------------------------------
 export function sessionExists(name) {
     return tmux(['has-session', '-t', name]).ok;
 }
@@ -517,9 +530,7 @@ export function panePid(pane) {
 export function respawnPaneInPlace(pane) {
     return tmux(['respawn-pane', '-k', '-t', pane]).ok;
 }
-// ---------------------------------------------------------------------------
 // pi command assembly
-// ---------------------------------------------------------------------------
 /** Turn a pi argv array into a single shell command string.
  *
  *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
@@ -530,12 +541,10 @@ export function respawnPaneInPlace(pane) {
  *  explicit `binary` arg still overrides the env. The value may be a multi-word
  *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
  *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
-export function piCommand(argv, binary = process.env['CRTR_PI_BINARY'] ?? bundledPiCommandForShell(shellQuote)) {
+export function piCommand(argv, binary = envPiBinaryOverride() ?? bundledPiCommandForShell(shellQuote)) {
     return [binary, ...argv.map(shellQuote)].join(' ');
 }
-// ---------------------------------------------------------------------------
 // Window liveness helpers (used by the supervisor daemon)
-// ---------------------------------------------------------------------------
 /** List all window ids present in `session`. Returns [] if the session does
  *  not exist or tmux fails for any reason. Each entry is the raw window id
  *  string reported by tmux (e.g. `@1`, `@2`, …). */
@@ -553,9 +562,7 @@ export function windowAlive(session, window) {
         return false;
     return listWindowIds(session).includes(window);
 }
-// ---------------------------------------------------------------------------
 // Focus helpers (used by the placement layer)
-// ---------------------------------------------------------------------------
 /** Activate a window within its session (same-session navigation). Equivalent
  *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
 export function selectWindow(session, window) {
@@ -582,9 +589,7 @@ export function selectPane(pane) {
 export function switchClient(session) {
     return tmux(['switch-client', '-t', session]).ok;
 }
-// ---------------------------------------------------------------------------
 // send-keys (chrome — used by the prefix menu + nav bindings)
-// ---------------------------------------------------------------------------
 /** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
  *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
  *  empty, same limitation as the menu's `/promote` item. Best-effort. */

package/dist/core/runtime/warm-pool.js

@@ -182,9 +182,7 @@ function abandonSpare(nodeId, what, err) {
     catch { /* best-effort */ }
     return null;
 }
-// ---------------------------------------------------------------------------
 // Reaping
-// ---------------------------------------------------------------------------
 /** How long an UNCLAIMED spare is worth its resident broker (~150-300 MB).
  *  A spare exists to make the NEXT create instant; one nobody has claimed in
  *  this long is memory rented for nothing, so it is returned. Over-reaping
@@ -308,9 +306,7 @@ function mint(recipe) {
         }
     })();
 }
-// ---------------------------------------------------------------------------
 // Daemon-start pre-warm
-// ---------------------------------------------------------------------------
 /** How many profiles get a spare at daemon start. Each spare is a resident
  *  broker at ~150-300 MB, so this is deliberately tiny. */
 const PREWARM_PROFILES = 2;

package/dist/core/scope.js

@@ -1,3 +1,4 @@
+import { envProfileId } from '../shared/env.js';
 import { homedir } from 'node:os';
 import { existsSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
@@ -105,7 +106,7 @@ function collectAncestorScopeRoots(startDir, userRoot) {
  *  (`findProjectScopeRootsWithMemory`), a projection layered onto this order
  *  rather than part of it: discovery provenance decides precedence, the
  *  relationship decides the ceiling, and the two never influence each other. */
-export function findProjectScopeRoots(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+export function findProjectScopeRoots(startDir = process.cwd(), profileId = envProfileId() || null) {
     return resolveProjectScopeRoots(startDir, profileId).roots;
 }
 /** `findProjectScopeRoots` with each root's profile memory ceiling attached —
@@ -113,7 +114,7 @@ export function findProjectScopeRoots(startDir = process.cwd(), profileId = proc
  *  walk takes that entry's `memory` (first entry in manifest order wins, even
  *  when cwd also reaches the root); every other root takes the neutral
  *  `content` ceiling. */
-export function findProjectScopeRootsWithMemory(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+export function findProjectScopeRootsWithMemory(startDir = process.cwd(), profileId = envProfileId() || null) {
     return resolveProjectScopeRoots(startDir, profileId).annotated;
 }
 function resolveProjectScopeRoots(startDir, profileId) {
@@ -195,7 +196,7 @@ export function ensureProjectScopeRoot(startDir = process.cwd()) {
     // cache hit.
     const resolvedStart = resolve(startDir);
     const root = join(resolvedStart, CRTR_DIR_NAME);
-    const profileId = process.env['CRTR_PROFILE_ID'] || null;
+    const profileId = envProfileId() || null;
     // Neutral ceiling: the empty cached stack proves no profile entry's ancestor
     // walk reached this root, since it did not exist to be walked into.
     scopeRootsCache.set(scopeRootsCacheKey(resolvedStart, profileId), {

package/dist/core/spawn.js

@@ -4,7 +4,7 @@
 // (tmuxServerReachable) so it can decide whether to surface a prompt or degrade
 // to the inbox-drain follow-up. The canvas runtime has its own
 // one-window-per-node machinery in core/runtime/placement-tmux.ts.
-import { spawnSync } from 'node:child_process';
+import { tmuxClientsReachable } from './runtime/tmux-driver.js';
 /** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
  *  gate for the human surface — see tmuxServerReachable. A headless-broker child
  *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
@@ -22,6 +22,5 @@ export function isInTmux() {
  *  no server is running — the true "no tmux to surface into" case that should
  *  degrade to the inbox-drain follow-up. */
 export function tmuxServerReachable() {
-    const r = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8' });
-    return r.status === 0;
+    return tmuxClientsReachable();
 }

package/dist/core/subscription-state.js

@@ -1,8 +1,9 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { LockedJsonFile } from "./locked-file.js";
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWriteJson } from './fs-utils.js';
+import { LockedJsonFile } from './locked-file.js';
 export const ANTHROPIC_PROVIDER_ID = "anthropic";
 export const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
 export const INVALID_REFRESH_TOKEN_BACKOFF_MS = 30 * 24 * 60 * 60 * 1000;
@@ -123,14 +124,6 @@ function parsePoolUnderLock(path, current) {
         throw new Error(`Subscription pool ${path} is corrupt: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function writeJsonFile(path, value, mode) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, mode === undefined ? "utf8" : { encoding: "utf8", mode });
-    if (mode !== undefined)
-        chmodSync(tmp, mode);
-    renameSync(tmp, path);
-}
 function normalizeStrength(value) {
     return value === "ultra" || value === "strong" || value === "medium" || value === "light" ? value : undefined;
 }
@@ -212,13 +205,13 @@ function assertCandidateRowsStorable(providerId, candidate) {
 // The ONE door every write to a pool file goes through. Both pool invariants -- one account
 // identity per pool, and every candidate row carrying a storable credential -- are properties
 // of the FILE, not of whichever code path happens to be writing, so they are asserted here
-// against the state this write replaces, under the caller's already-held lock. `writeJsonFile`
-// is reached for the pool NOWHERE ELSE: that makes the invariants unbypassable.
+// against the state this write replaces, under the caller's already-held lock. `atomicWriteJson`
+// is reached for the pool NOWHERE ELSE in this file: that makes the invariants unbypassable.
 function persistPool(providerId, poolFile, base, candidate) {
     assertCandidateRowsStorable(providerId, candidate);
     const next = normalizeCredentials(candidate);
     logCredentialSetChange(providerId, base, next);
-    writeJsonFile(poolFile, next, 0o600);
+    atomicWriteJson(poolFile, next, { mode: 0o600 });
     return next;
 }
 // Accounts vanishing from a pool is the failure users actually feel ("I keep having to log in
@@ -721,7 +714,7 @@ export function writeRotationConfig(next) {
         defaultFallbackStrength: normalizeStrength(next.defaultFallbackStrength) ?? current.defaultFallbackStrength ?? DEFAULT_FALLBACK_STRENGTH,
         revertWhenAvailable: next.revertWhenAvailable ?? current.revertWhenAvailable ?? true,
     };
-    writeJsonFile(rotationConfigFile(), merged);
+    atomicWriteJson(rotationConfigFile(), merged);
     return merged;
 }
 export function formatStatusLine(providerId, now = Date.now()) {

package/dist/core/substrate/__tests__/surface-match-pre-command.test.js

@@ -28,7 +28,7 @@ const SUBJECT = {
 function entry(match, gate) {
     return { on: 'pre-command', at: 'content', match, ...(gate !== undefined ? { gate } : {}) };
 }
-// --- the behaviour this event adds -----------------------------------------
+// the behaviour this event adds
 test('a matched invocation inside a heredoc BODY does not hold the command', () => {
     const command = [
         "crtr memory write approvals --body <<'EOF'",
@@ -60,7 +60,7 @@ test('a `command` entry is never consumed by the pre-command matcher, nor the re
     assert.equal(matchesPreCommandEntry(post, SUBJECT, 'crtr integration run --action send'), false);
     assert.equal(matchesCommandEntry(entry(['crtr integration run*']), SUBJECT, 'crtr integration run --action send'), false);
 });
-// --- the rung fold ---------------------------------------------------------
+// the rung fold
 test('the rung fold returns the highest `at` across matching entries, and none when nothing matches', () => {
     const doc = {
         surfaces: [
@@ -72,7 +72,7 @@ test('the rung fold returns the highest `at` across matching entries, and none w
     assert.equal(preCommandDeliveryRung(doc, SUBJECT, 'crtr integration run --action send'), 'content');
     assert.equal(preCommandDeliveryRung(doc, SUBJECT, 'ls -la'), 'none');
 });
-// --- shared routing: one command-glob semantics, not two --------------------
+// shared routing: one command-glob semantics, not two
 test('outside a heredoc, pre-command matching is exactly the `command` matcher', () => {
     // The guard against a second command tokenizer drifting away from the first.
     // Whatever `command` globs mean today, `pre-command` means the same thing —

package/dist/core/substrate/render.js

@@ -140,9 +140,7 @@ function bootCorpus() {
     }
     return { docs, sources };
 }
-// ---------------------------------------------------------------------------
 // Exposure registration
-// ---------------------------------------------------------------------------
 function rendersAtBoot(doc) {
     return isVisible(doc.bootRung) && (doc.bootRung !== 'content' || doc.body.trim() !== '');
 }
@@ -156,9 +154,7 @@ function recordRendered(target, docs) {
         registerDocumentExposure(target, d.path, d.body, d.bootRung);
     }
 }
-// ---------------------------------------------------------------------------
 // Step 2 — display ordering + grouped render.
-// ---------------------------------------------------------------------------
 /** Content-prose ordering rank: general → specific. builtin=0, user=1,
  *  profile=2, project ranks start at 3 and climb by root nearness — the
  *  OUTERMOST ancestor `.crouter/` root ranks lowest (renders first), the
@@ -412,9 +408,7 @@ function buildTree(docs, rootLabel) {
     renderChildren(root, '', lines);
     return lines.join('\n');
 }
-// ---------------------------------------------------------------------------
 // Block prose — the intro legend + the update directive for each kind.
-// ---------------------------------------------------------------------------
 const READ_LEGEND = 'Each %s below shows either its full content (indented beneath its name), a ' +
     '`# read when:` line telling you when to read the full document, or simply its name.';
 const PREFERENCES_INTRO = 'Preferences are how the user wants you to behave — standing directives and corrections. ' +
@@ -487,9 +481,7 @@ export function buildSubPersonaMenu(kind) {
         'dragging unrelated context into it.\n\n' +
         lines.join('\n'));
 }
-// ---------------------------------------------------------------------------
 // 1. Preferences — protocol prose + `<memory kind="preference">` (system prompt).
-// ---------------------------------------------------------------------------
 /** The system-prompt substrate splice, TWO parts in one string.
  *
  *  1. The operating protocol: shipped (builtin/plugin) content-rung bodies as
@@ -548,9 +540,7 @@ function buildPreferencesBlock(subject, target) {
 export function renderPreferencesForSubject(subject, target) {
     return buildPreferencesBlock(subject, target);
 }
-// ---------------------------------------------------------------------------
 // 2. Knowledge — `<memory kind="knowledge">` (the first-message bearings).
-// ---------------------------------------------------------------------------
 /** STEP 1 for the knowledge block, shared by the boot render and the
  *  config-change delta: the resolver's knowledge winners ∪ the node's own store
  *  (any kind), first-wins deduped resolver-first so a same-named node doc
@@ -589,9 +579,7 @@ export function renderKnowledgeForSubject(subject, nodeId, target) {
     // Surfaced INTO this node: swap literal `$CRTR_CONTEXT_DIR` for the real path.
     return interpolateNodePaths(`<memory kind="knowledge">\n${out}\n</memory>`, nodeId);
 }
-// ---------------------------------------------------------------------------
 // 3. The config-change delta — the memory a node's NEW configuration exposes.
-// ---------------------------------------------------------------------------
 const DELTA_PROTOCOL_INTRO = 'Your node configuration changed. This operating protocol is in force for you now:';
 const DELTA_PREFERENCES_INTRO = 'Your new configuration puts these preferences in force — standing directives and corrections ' +
     'from the user. To read one, run `crtr memory read <name>`. ' +

package/dist/core/substrate/schema.js

@@ -9,21 +9,17 @@
 // render, and `crtr memory lint` owns strict authoring-time enforcement.
 import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
 import { surfaceEntryGatePasses } from './gate.js';
-// ---------------------------------------------------------------------------
 // Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
 // playbooks + factual references merged) vs `preference` (behave — standing
 // directives). `kind` is a load-bearing binary, not a content taxonomy.
-// ---------------------------------------------------------------------------
 export const KINDS = ['knowledge', 'preference'];
 /** Is `v` one of the two valid document kinds? */
 export function isDocKind(v) {
     return typeof v === 'string' && KINDS.includes(v);
 }
-// ---------------------------------------------------------------------------
 // The 4-rung visibility ladder (design §4). A strict, monotone ordering where
 // each rung is a superset of disclosure over the one before:
 //   none < name < preview < content
-// ---------------------------------------------------------------------------
 // The ladder is ONE union, owned by the public API DTO (`ProfileProjectMemory`)
 // so a profile relationship's cap and a doc's authored rung are the same values
 // and clamp against each other without a conversion.
@@ -41,21 +37,17 @@ export function rungAtLeast(r, min) {
 export function minRung(a, b) {
     return rungRank(a) <= rungRank(b) ? a : b;
 }
-// ---------------------------------------------------------------------------
 // Identity — owned entirely by core/memory/identity.ts (ordering-prefix
 // normalization, INDEX collapse, explicit-name-then-path local identity,
 // namespace composition). Re-exported here so document parsing and identity
 // derivation stay one rule with one implementation.
-// ---------------------------------------------------------------------------
 export { normalizeNameSegment, normalizeDocName, resolveLocalName as resolveDocName } from '../memory/identity.js';
-// ---------------------------------------------------------------------------
 // Surfaces — explicit event routing (design: surfaces-design.md). A doc
 // declares WHEN it delivers as (event, match, rung) entries; matches are
 // always globs, always absolute in the event's namespace, with `./` as the
 // one relative spelling (anchoring to the doc's own container). A doc with
 // no `surfaces` at all does exactly one thing: appears in its directory's
 // listing.
-// ---------------------------------------------------------------------------
 export const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read', 'command', 'pre-command'];
 /** The rungs an entry may deliver at. There is no `none` — silence is the
  *  absence of an entry. (`Rung`'s `none` survives only as the internal
@@ -74,9 +66,7 @@ export function bootRung(doc, subject) {
     }
     return r;
 }
-// ---------------------------------------------------------------------------
 // Parse / validate.
-// ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
@@ -135,9 +125,7 @@ export function previewLine(doc) {
     const line = doc.whenAndWhyToRead.trim().replace(/\.+$/, '');
     return line === '' ? '' : `${line}.`;
 }
-// ---------------------------------------------------------------------------
 // Field coercion helpers (private).
-// ---------------------------------------------------------------------------
 function strField(v) {
     return typeof v === 'string' ? v : '';
 }

package/dist/core/substrate/surface-match.js

@@ -323,12 +323,10 @@ export function matchesPreCommandEntry(entry, subject, command) {
     const stripped = stripHeredocs(command);
     return entry.match.some((g) => commandGlobMatches(g, stripped));
 }
-// ---------------------------------------------------------------------------
 // Per-doc rung folds — a doc's delivery rung for one event occurrence is the
 // highest `at` over its matching entries of that event, `none` when none
 // match (entries OR together; `none` is the internal "does not deliver"
 // floor, never an authored rung).
-// ---------------------------------------------------------------------------
 /** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
 export function readDeliveryRung(doc, subject, absReadFile, readFrontmatter) {
     let r = 'none';

package/dist/core/termrender/display.js

@@ -1,3 +1,4 @@
+import { envNodeId } from '../../shared/env.js';
 import { spawnSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { breakPane, closePane, currentTmux, paneOfNode, splitWindow, } from '../runtime/placement-tmux.js';
@@ -6,7 +7,7 @@ function targetPane() {
     const callerPane = process.env['TMUX_PANE'];
     if (callerPane !== undefined && callerPane !== '')
         return callerPane;
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId !== undefined && nodeId !== '') {
         const viewerPane = paneOfNode(nodeId);
         if (viewerPane !== null)

package/dist/core/tui/page-host.d.ts

@@ -1,6 +1,6 @@
-import { ProcessTerminal, type Component, type Focusable, type TUI } from "@earendil-works/pi-tui";
-import { readRawScopeConfig } from "../config.js";
-import { type BindingId, type BindingResolution } from "../keybindings/index.js";
+import { ProcessTerminal, type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+import { readRawScopeConfig } from '../config.js';
+import { type BindingId, type BindingResolution } from '../keybindings/index.js';
 /** A full-screen page: a focusable TUI component that cleans up after itself. */
 export type TuiPageSurface = Component & Focusable & {
     dispose(): void;

package/dist/core/tui/page-host.js

@@ -6,10 +6,10 @@
 // restore path that survives an exception, a signal, and process exit. Anything
 // a single page needs beyond that — pi's model runtime, a canvas client — the
 // page's own runner builds and closes over before calling in here.
-import { ProcessTerminal, TuiMainScreen, } from "@earendil-works/pi-tui";
-import { applyTheme } from "../../clients/attach/config.js";
-import { readRawScopeConfig } from "../config.js";
-import { resolveKeybindings, } from "../keybindings/index.js";
+import { ProcessTerminal, TuiMainScreen, } from '@earendil-works/pi-tui';
+import { applyTheme } from '../../clients/attach/config.js';
+import { readRawScopeConfig } from '../config.js';
+import { resolveKeybindings, } from '../keybindings/index.js';
 /** Mount one page as the TUI's only child and resolve when it closes.
  *
  *  `interceptCancel` is a process-level escape hatch for surfaces that must be

package/dist/core/tui/panel.js

@@ -1,5 +1,5 @@
-import { getMarkdownTheme, getSelectListTheme, getSettingsListTheme, } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, getSelectListTheme, getSettingsListTheme, } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
 const ansiGreen = (text) => `\x1b[32m${text}\x1b[39m`;
 const ansiYellow = (text) => `\x1b[33m${text}\x1b[39m`;
 export const theme = {
@@ -95,7 +95,7 @@ export function framed(lines, width) {
 export function fitTail(lines, budget) {
     return budget >= lines.length ? lines : lines.slice(lines.length - budget);
 }
-// --- Page chrome shared by the settings shell and the setup wizard ----------
+// Page chrome shared by the settings shell and the setup wizard
 /** Rows the page frame spends on its own title, rules and footer. */
 export const PAGE_CHROME_ROWS = 4;
 /** Title row with right-aligned scope metadata, a rule under it, the body

package/dist/core/wake.js

@@ -10,9 +10,7 @@
 // design §5.3 + D7 (engine evaluates UTC; the surface bakes the IANA zone
 // into a calendar `recur`). Tick-scale only — no sub-second precision.
 import { CronExpressionParser } from 'cron-parser';
-// ---------------------------------------------------------------------------
 // Constants
-// ---------------------------------------------------------------------------
 /** Cadence floor: reject any interval / cron min-spacing below this (AC-N4). */
 export const CADENCE_FLOOR_MS = 60_000;
 const DURATION_UNIT_MS = {
@@ -38,9 +36,7 @@ const CRON_ALIASES = {
     '@midnight': '0 0 * * *',
     '@hourly': '0 * * * *',
 };
-// ---------------------------------------------------------------------------
 // Internal helpers
-// ---------------------------------------------------------------------------
 function whenError(code, message, received) {
     return { error: { code, message, received } };
 }
@@ -127,9 +123,7 @@ function classifyIso(s) {
         return { zoned: true };
     return null; // trailing garbage -> not a valid ISO instant
 }
-// ---------------------------------------------------------------------------
 // parseWhen — resolve a one-shot <when> to an absolute UTC instant
-// ---------------------------------------------------------------------------
 /**
  * Resolve a `<when>` to a single UTC `fireAt`:
  *   - relative duration (`90s`, `1h30m`)        -> now + Σ
@@ -182,9 +176,7 @@ export function parseWhen(when, opts) {
     }
     return whenError('bad_when', `Could not parse "${received}". Use a duration ("5m", "1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").`, received);
 }
-// ---------------------------------------------------------------------------
 // parseCadence — resolve --every to a stored recur + first fire
-// ---------------------------------------------------------------------------
 /**
  * Resolve a `<cadence>` (the `--every` value) to a stored `recur` JSON string
  * plus the first `fireAt`:
@@ -240,9 +232,7 @@ export function parseCadence(every, opts) {
         firstFireAt,
     };
 }
-// ---------------------------------------------------------------------------
 // cadenceDisplay — a recur JSON rendered for humans + agents
-// ---------------------------------------------------------------------------
 /**
  * Render a stored `recur` JSON as a compact, human-readable cadence:
  *   - {"every":"6h"}                         -> `every 6h`
@@ -270,9 +260,7 @@ export function cadenceDisplay(recur) {
     }
     return 'none';
 }
-// ---------------------------------------------------------------------------
 // nextSlotAfter — the coalescing primitive (daemon advance)
-// ---------------------------------------------------------------------------
 /**
  * Earliest occurrence of `recur` strictly greater than `now`, as a UTC ISO
  * string. Anchors on `now` (not the stored `fire_at`), so it structurally

package/dist/core/worktree.js

@@ -357,9 +357,7 @@ export function closeManagedWorktree(nodeId) {
         return closeManagedWorktreeLocked(nodeId);
     return withRepositoryWorktreeLock(wt.repo_root, () => closeManagedWorktreeLocked(nodeId));
 }
-// ---------------------------------------------------------------------------
 // Push-final auto-drop of a clean, zero-commit managed worktree
-// ---------------------------------------------------------------------------
 /** Delete a source branch only while the ref that proved it already delivered
  *  is still at the exact inspected SHA. `containingRef` can be the recorded
  *  local base or that base's remote-tracking upstream. */

package/dist/daemon/__tests__/reconciler-signature.test.d.ts

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

package/dist/daemon/__tests__/reconciler-signature.test.js

@@ -0,0 +1,36 @@
+// Every reconciler in crtrd's tick loop conforms to one shape:
+// `run(now: number, ctx: TCtx): void | Promise<unknown>`. The call loop treats
+// every reconciler identically — a 1-arg or discard-shaped signature is exactly
+// the drift this test catches (a runtime arity check; a compile-time
+// `satisfies` pass over the same five/seven classes would need a shared
+// Reconciler<TCtx> interface that adds no real safety this doesn't already
+// give, since `tsc --noEmit` already fails hard on a wrong-shaped ctx object
+// at each call site in crtrd.ts).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { BrokerSupervisionReconciler } from '../reconcilers/broker-supervision.js';
+import { ControllerDeathReconciler, DormantInboxReconciler } from '../reconcilers/dormant-inbox.js';
+import { CronLaneReconciler } from '../reconcilers/cron-lane.js';
+import { HumanDeliveryLaneReconciler } from '../reconcilers/human-delivery-lane.js';
+import { PendingReviewSubmitReconciler } from '../reconcilers/pending-review-submit.js';
+import { StorageMaintenanceReconciler } from '../reconcilers/storage-maintenance.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const RECONCILERS = [
+    ['BrokerSupervisionReconciler', BrokerSupervisionReconciler],
+    ['ControllerDeathReconciler', ControllerDeathReconciler],
+    ['DormantInboxReconciler', DormantInboxReconciler],
+    ['CronLaneReconciler', CronLaneReconciler],
+    ['HumanDeliveryLaneReconciler', HumanDeliveryLaneReconciler],
+    ['PendingReviewSubmitReconciler', PendingReviewSubmitReconciler],
+    ['StorageMaintenanceReconciler', StorageMaintenanceReconciler],
+];
+test('every crtrd reconciler declares run(now, ctx) — arity 2', () => {
+    const offenders = [];
+    for (const [name, Ctor] of RECONCILERS) {
+        const instance = new Ctor();
+        if (instance.run.length !== 2) {
+            offenders.push(`${name}.run has arity ${instance.run.length}, expected 2`);
+        }
+    }
+    assert.deepEqual(offenders, [], `reconciler(s) not shaped run(now, ctx):\n${offenders.join('\n')}`);
+});