@north-light/crouter 0.3.233 → 0.3.235

package/dist/core/runtime/reopen.js

@@ -38,11 +38,10 @@
 // mutating the live pointer — the explicit operation must not retract a
 // canonical final unless it can actually enact the requested re-task.
 import { join } from 'node:path';
-import { openDb, reportsDir, updateNode } from '../canvas/index.js';
+import { clearFinalReportIfMatches, getFinalReport, reportsDir, updateNode } from '../canvas/index.js';
 import { InputError } from '../io.js';
 function currentFinalReport(nodeId) {
-    const row = openDb().prepare('SELECT final_report FROM nodes WHERE node_id = ?').get(nodeId);
-    return row?.final_report ?? null;
+    return getFinalReport(nodeId);
 }
 function throwNodeFinalized(nodeId, finalReport) {
     const reportPath = join(reportsDir(nodeId), finalReport);
@@ -90,10 +89,8 @@ export function assertFinalizedForReopen(nodeId) {
  *  canonical result. Callers MUST NOT proceed to revive/deliver when this
  *  throws. */
 export function commitReopen(nodeId, expectedFinalReport) {
-    const result = openDb()
-        .prepare('UPDATE nodes SET final_report = NULL, finalized_at = NULL WHERE node_id = ? AND final_report = ?')
-        .run(nodeId, expectedFinalReport);
-    if (result.changes === 0) {
+    const cleared = clearFinalReportIfMatches(nodeId, expectedFinalReport);
+    if (!cleared) {
         throw new InputError({
             error: 'reopen_latch_changed',
             message: `${nodeId}'s finalization latch changed since it was last inspected — a concurrent --reopen (or a fresh push final) already moved it, so clearing it now would risk erasing a newer canonical result.`,

package/dist/core/runtime/reset.js

@@ -27,9 +27,7 @@ import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPa
 import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
-// ---------------------------------------------------------------------------
 // reapDescendants — tear down a root's descendant sub-DAG (shared helper)
-// ---------------------------------------------------------------------------
 /** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
  *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
  *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
@@ -175,9 +173,7 @@ export function handleNewSession(nodeId, newSessionId, newSessionFile) {
     resetRoot(nodeId, newSessionId, newSessionFile);
     return { path: 'reset-child' };
 }
-// ---------------------------------------------------------------------------
 // markCleanExitDone — the clean-exit→done termination guard
-// ---------------------------------------------------------------------------
 /** Resolve a cleanly-exiting node to `done`. Returns true iff it transitioned.
  *  Guard: only a real quit, and only a node still active|idle with no pending
  *  intent — so it never clobbers a node already routed by agent_end to done

package/dist/core/runtime/resume-root.js

@@ -113,9 +113,7 @@ async function attachInline(nodeId) {
     });
     process.exit(code);
 }
-// ---------------------------------------------------------------------------
 // `-r` picker — a minimal raw-mode keypress menu (pre-boot, we own the TTY).
-// ---------------------------------------------------------------------------
 const HILITE = accent('\u25b8');
 const cursorUp = (n) => (n > 0 ? `\u001b[${n}A\r` : '');
 const CLEAR_DOWN = '\u001b[0J';

package/dist/core/runtime/revive.js

@@ -17,7 +17,9 @@
 //
 // These are requests. Durable `intent=refresh` or `cycle_pending=true` always
 // vetoes strict resume so focus and daemon callers cannot reopen an old
-// context while a fresh cycle is still unconfirmed.
+// context while a fresh cycle is still unconfirmed. A parked node vetoes it
+// too, but only when the revival carries new input — unseen wake-worthy mail —
+// and there is goal/roadmap ground state to re-enter on.
 //
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
 import { existsSync } from 'node:fs';
@@ -30,6 +32,7 @@ import { InputError } from '../io.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings, readGoal, readYieldMessage, RUNTIME_RESTART_CONTINUATION } from './kickoff.js';
 import { readRoadmap } from './roadmap.js';
+import { hasUnseenWakeMail } from '../feed/inbox.js';
 import { headlessBrokerHost } from './host.js';
 import { boundFleet } from './fleet.js';
 import { clearFault, beginBootFaultAttempt } from './fault.js';
@@ -37,9 +40,7 @@ import { clearContextExposureState, initializeForkContextExposure, } from '../su
 import { rootOfSpine } from './nodes.js';
 import { isReviewCompanionBound } from '../review/companion.js';
 import { assertProfileActive } from '../profiles/manifest.js';
-// ---------------------------------------------------------------------------
 // resumeArgs — which session source a revive resumes from
-// ---------------------------------------------------------------------------
 /** Pick the `--session` source for a revive. Both resume=true (a true resume)
  *  and resume=false (a refresh-yield) resume by the absolute session-file path
  *  (immune to cwd; pi opens it directly) — but ONLY when that file actually
@@ -62,9 +63,7 @@ export function resumeArgs(meta, resume) {
         return {};
     return resume ? { resumeSessionPath: path } : { resumeSessionPath: path, newCycle: true };
 }
-// ---------------------------------------------------------------------------
 // Return type
-// ---------------------------------------------------------------------------
 /** A relaunch that has NO transcript to resume or branch from, and no durable
  *  work state on disk (no roadmap, no yield note), is not a revive at all — the
  *  node never got a conversation off the ground, so there is no "previous
@@ -91,9 +90,7 @@ export function hasFreshGroundState(nodeId) {
     const roadmap = readRoadmap(nodeId);
     return roadmap !== null && roadmap.trim() !== '';
 }
-// ---------------------------------------------------------------------------
 // reviveNode
-// ---------------------------------------------------------------------------
 /** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
  *  meta. Opens no viewer (engine-only).
  *
@@ -194,14 +191,21 @@ export function reviveNode(nodeId, opts) {
     // selects only an existing absolute session path: strict
     // resume continues its leaf, while fresh/cycle mode roots a new one.
     // A parked node re-enters on a FRESH cycle grounded in goal + roadmap rather
-    // than resuming the transcript its parking turn concluded — the second veto
-    // on strict resume, and a property of the node, so every revival doorway gets
-    // it without learning a predicate. Its one exception is a park with nothing
-    // on disk to ground a fresh window (reachable only on the degraded path,
-    // which writes no summary): resuming an old transcript beats waking amnesiac.
+    // than resuming the transcript its parking turn concluded — but ONLY when the
+    // revival carries new input. Mail that arrived after the park is what a fresh
+    // window is for: every doorway that wakes a parked node because something
+    // arrived appends the durable entry BEFORE calling in, so the unseen set IS
+    // that input. An input-less revival — a bare `node lifecycle revive`, a viewer
+    // attach, a focus — has nothing to answer, so a fresh cycle would only buy a
+    // nothing-to-do turn and a re-park 15 minutes later: it quietly resumes the
+    // old transcript instead, injects no kickoff, and generates nothing. The park
+    // clock re-parks it in due course.
+    // The second exception is unchanged: a park with nothing on disk to ground a
+    // fresh window (reachable only on the degraded path, which writes no summary)
+    // resumes rather than waking amnesiac.
     // The transition below clears the marker, and this snapshot precedes it.
     const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
-    const parkedReentry = isParked(meta) && hasFreshGroundState(nodeId);
+    const parkedReentry = isParked(meta) && hasFreshGroundState(nodeId) && hasUnseenWakeMail(nodeId);
     const effectiveResume = refreshPending || parkedReentry ? false : opts.resume;
     const resume = forkBirthPending ? {} : resumeArgs(meta, effectiveResume);
     // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether

package/dist/core/runtime/session-list-cache.js

@@ -77,7 +77,7 @@ function isValidEntry(e) {
     const c = e;
     return isFiniteNonNeg(c['mtimeMs']) && isFiniteNonNeg(c['size']) && isValidWireInfo(c['info']);
 }
-// ---- faithful mirror of pi's private buildSessionInfo -----------------------
+// faithful mirror of pi's private buildSessionInfo
 function parseLine(line) {
     if (!line.trim())
         return null;
@@ -187,7 +187,7 @@ async function buildWireSessionInfo(filePath) {
         return null;
     }
 }
-// ---- the cache ---------------------------------------------------------------
+// the cache
 /** In-memory + file-backed cache keyed by absolute `.jsonl` path. One instance
  *  per broker; the file is shared across brokers (last-writer-wins via atomic
  *  rename — a lost update just costs one file's rebuild next open, never

package/dist/core/runtime/shell-expansion.js

@@ -1,5 +1,4 @@
 import { execFile } from 'node:child_process';
-// ---------------------------------------------------------------------------
 // Shell expansion inside Markdown bodies: `!`cmd`` inline and ```! fenced
 // blocks are replaced by the command's output.
 //
@@ -13,7 +12,6 @@ import { execFile } from 'node:child_process';
 // Node built-ins ONLY. This module is reachable from `src/commands/**`, where a
 // `@earendil-works/pi-coding-agent` import would load the whole pi runtime just
 // to read a document.
-// ---------------------------------------------------------------------------
 // Built fresh per use, never shared. A module-level /g regex carries mutable
 // `lastIndex`, and both `.test()` and `matchAll` (which copies it into its
 // internal clone) would make one call silently skip matches another consumed.

package/dist/core/runtime/spawn.js

@@ -35,10 +35,8 @@ import { modelRequestFromConfig, unregisteredConcreteModel } from '../model-rout
 import { openModelRegistry } from './model-registry.js';
 import { MODEL_SPEC_NEXT } from './model-selection.js';
 import { initializeForkContextExposure } from '../substrate/injected-store.js';
-// ---------------------------------------------------------------------------
 // Shared broker-launch wrapper — catch launch/preflight failures at the call
 // site, mark the node crashed, then rethrow a clear error.
-// ---------------------------------------------------------------------------
 function launchBrokerOrCrash(nodeId, inv, opts) {
     try {
         return headlessBrokerHost.launch(nodeId, inv, opts);

package/dist/core/runtime/stop-guard.js

@@ -17,8 +17,10 @@
 //   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
 //                      Also fine.
 //   • structured     → a TERMINAL node has a pending structured-output request.
-//                      Valid requests reprompt with the schema; invalid requests
-//                      reprompt with an error and require manual cleanup.
+//                      A valid request reprompts with the schema unless the node
+//                      also holds a wake source, which it may sleep on first;
+//                      an invalid request reprompts with an error and requires
+//                      manual cleanup.
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
 import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode, contextDir } from '../canvas/index.js';
@@ -39,6 +41,19 @@ function formatInvalidStructuredOutputReprompt(error) {
         `After resolving the file, retry the submission. ` +
         `If this is unexpected, escalate to the user using \`crtr human send\`.`);
 }
+/** The wake sources that legitimize a terminal node's dormancy: a pending
+ * cancel-on-wake deadline, an active subscription to a live publisher, an
+ * explicit live controller wait, or a live background bash job whose completion
+ * sends an inbox message. Parentage alone is deliberately absent. */
+function wakeCapableWait(nodeId, backgroundJobsRunning) {
+    if (hasPendingCancelOnWakeCron(nodeId))
+        return 'scheduled';
+    if (hasActiveLiveSubscription(nodeId)
+        || hasLiveMessageWait(nodeId)
+        || backgroundJobsRunning)
+        return 'awaiting';
+    return null;
+}
 /** Decide what to do when a node stops. crtrd supplies every current-canvas
  * fact; the broker contributes only whether its Pi-owned background job registry
  * is still running work. */
@@ -49,9 +64,14 @@ export function evaluateStop(nodeId, signals, backgroundJobsRunning = activeBack
         return { action: 'allow', reason: 'escalated' };
     // A pending structured-output request overrides every stored-state dormancy
     // path: a post-final one-off follow-up still owes `submit` before it may stop.
-    // Invalid requests surface an explicit error and require manual cleanup.
+    // A wake source is the exception — the request outlives the sleep, so
+    // reprompting instead would busy-wait the node against its own child, deadline,
+    // or job. Invalid requests surface an explicit error and require manual cleanup.
     const outputState = readOutputRequest(nodeId);
     if (outputState.state === 'valid') {
+        const pendingWait = wakeCapableWait(nodeId, backgroundJobsRunning);
+        if (pendingWait !== null)
+            return { action: 'allow', reason: pendingWait };
         return {
             action: 'reprompt',
             reason: 'stalled',
@@ -82,19 +102,11 @@ export function evaluateStop(nodeId, signals, backgroundJobsRunning = activeBack
     if (node !== null && node.lifecycle === 'resident') {
         return { action: 'allow', reason: 'dormant' };
     }
-    // A terminal node with a pending cancel-on-wake deadline is legitimately
-    // waiting on the clock, so it should idle-release rather than busy-wait
-    // holding its broker.
-    if (hasPendingCancelOnWakeCron(nodeId))
-        return { action: 'allow', reason: 'scheduled' };
-    // A terminal node holding something live to wake it is legitimately awaiting.
-    // Parentage alone is deliberately absent: only an active subscription, an
-    // explicit controller wait, or a live background bash job whose completion
-    // sends an inbox message can suppress the stall guard.
-    if (hasActiveLiveSubscription(nodeId)
-        || hasLiveMessageWait(nodeId)
-        || backgroundJobsRunning)
-        return { action: 'allow', reason: 'awaiting' };
+    // A terminal node holding a wake source is legitimately waiting: it should
+    // idle-release rather than busy-wait holding its broker.
+    const pendingWait = wakeCapableWait(nodeId, backgroundJobsRunning);
+    if (pendingWait !== null)
+        return { action: 'allow', reason: pendingWait };
     // A terminal node with nothing live and no final pushed has stalled.
     return {
         action: 'reprompt',

package/dist/core/runtime/stream-watchdog.d.ts

@@ -1,4 +1,3 @@
-export declare function resolveStreamWatchdogMs(): number;
 /**
  * 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

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/frontmatter-validation.d.ts

@@ -1,4 +1,5 @@
 import { type SurfaceEntry } from './schema.js';
+export declare const SUPPRESSIBLE_RULES: readonly string[];
 /** Strict validation of one raw routing entry. Runtime parsing deliberately
  * tolerates malformed docs; this authoring/preflight contract does not. */
 export declare function lintSubstrateSurfaces(value: unknown): string | null;

package/dist/core/substrate/frontmatter-validation.js

@@ -1,7 +1,7 @@
 import { isDocKind, parseSubstrateFrontmatter, SURFACE_EVENTS, SURFACE_RUNGS } from './schema.js';
 const RETIRED_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
 const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'gate', 'at'];
-const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read'];
+export const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read'];
 /** Strict validation of one raw routing entry. Runtime parsing deliberately
  * tolerates malformed docs; this authoring/preflight contract does not. */
 export function lintSubstrateSurfaces(value) {