@north-light/crouter 0.3.233 → 0.3.234

package/dist/core/runtime/fault.js

@@ -1,3 +1,4 @@
+import { envNodeId } from '../../shared/env.js';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { jobDir } from '../canvas/paths.js';
@@ -140,7 +141,7 @@ export function recordFault(nodeId, input) {
     updateMarker(nodeId, fault);
 }
 export function recordFaultForCurrentNode(input) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return false;
     if (!existsSync(jobDir(nodeId)))
@@ -186,7 +187,7 @@ export function clearFault(nodeId, opts) {
     }
 }
 export function clearFaultForCurrentNode(opts) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return false;
     if (!existsSync(jobDir(nodeId)))

package/dist/core/runtime/headless-pi.js

@@ -3,6 +3,7 @@
 // Each call uses crouter's credential pool and route policy, an in-memory session,
 // and only the inline provider-rotation extension. No conversation resources or
 // canvas lifecycle hooks enter the helper session.
+import { envNodeCwd, envProfileId } from '../../shared/env.js';
 import { join } from 'node:path';
 import { PoolCredentialStore } from '../pool-credential-store.js';
 import { modelRequestFromConfig, selectInitialModelRoute } from '../model-routes.js';
@@ -55,8 +56,8 @@ async function runHeadless(request, fallback, collect) {
             ]);
             if (timedOut)
                 return fallback;
-            const nodeCwd = process.env['CRTR_NODE_CWD'] ?? process.cwd();
-            const profileId = process.env['CRTR_PROFILE_ID'];
+            const nodeCwd = envNodeCwd() ?? process.cwd();
+            const profileId = envProfileId();
             const agentDir = sdk.getAgentDir();
             const modelRuntime = await sdk.ModelRuntime.create({
                 credentials: new PoolCredentialStore(join(agentDir, 'auth.json')),

package/dist/core/runtime/host.js

@@ -25,12 +25,11 @@ import { assertMandatoryCanvasExtensions } from './canvas-extensions.js';
 import { boundFleet } from './fleet.js';
 import { emitEvent } from '../events/emit.js';
 import { bindBrokerEventSource, eventSource } from '../events/source.js';
-// ---------------------------------------------------------------------------
+import { envBrokerEngine } from '../../shared/env.js';
 // HeadlessBrokerHost (design §3.3): a detached broker PROCESS, no tmux pane. It
 // boots the dedicated broker-cli entry directly (NEVER src/cli.ts), supervises
 // via the broker pid recorded as pi_pid, and tears down over the node's unix
 // socket (graceful `shutdown` frame, SIGTERM fallback).
-// ---------------------------------------------------------------------------
 /** Resolve the broker entry beside this module. A broker must run from the
  *  same generation as the crtrd launching it, so module-relative resolution
  *  preserves that invariant. */
@@ -48,7 +47,7 @@ const DEFAULT_BROKER_ENGINE = '@earendil-works/pi-coding-agent';
  *  why: the default-deny allowlist in spawn-env.ts strips `CRTR_*` from
  *  ambient env, so the child can no longer re-derive this itself). */
 function resolveEngineSpec(inv) {
-    return inv.env['CRTR_BROKER_ENGINE'] ?? process.env['CRTR_BROKER_ENGINE'] ?? DEFAULT_BROKER_ENGINE;
+    return inv.env['CRTR_BROKER_ENGINE'] ?? envBrokerEngine();
 }
 function isPlainLaunchSessionPath(token) {
     return token.includes('/') || token.endsWith('.jsonl');

package/dist/core/runtime/kickoff.js

@@ -30,10 +30,8 @@ import { formatCard } from '../../shared/generated-context.js';
 /** The runtime-restart continuation exactly as delivered. `revive.ts` injects
  *  it as the prompt of a strict resume that follows a cleanly aborted turn. */
 export const RUNTIME_RESTART_CONTINUATION = formatCard('restart-continuation', {}, 'continue');
-// ---------------------------------------------------------------------------
 // Companion context files: the goal (the spawning mandate) and the one-shot
 // yield message (a note from the prior self to the revived self).
-// ---------------------------------------------------------------------------
 /** The goal file — the prompt/task a node was spawned with, persisted at birth
  *  so a fresh revive can re-read its mandate. */
 export function goalPath(nodeId) {
@@ -230,9 +228,7 @@ function backgroundJobsBlock(nodeId) {
     lines.push('', 'Read output so far: `tail -n 50 <log>` (or `crtr node bash list --tail 20`). Abandon one: `crtr node bash kill <job-id>`.');
     return `<background-jobs>\n${lines.join('\n')}\n</background-jobs>`;
 }
-// ---------------------------------------------------------------------------
 // buildReviveKickoff — assemble the full fresh-revive first message.
-// ---------------------------------------------------------------------------
 /** Assemble the auto-injected first message for a FRESH revive of `meta` from its
  *  already-drained `bearings` (see drainBearings) plus pure on-disk reads of the
  *  node's goal, roadmap, and context dir, framed so the revived node can rebuild

package/dist/core/runtime/launch-target.js

@@ -1,3 +1,4 @@
+import { envProfileId } from '../../shared/env.js';
 import { resolve } from 'node:path';
 import { getNode } from '../canvas/canvas.js';
 import { usage } from '../errors.js';
@@ -10,7 +11,7 @@ export function resolveCreateKind(kind, profile) {
 /** Validate a kind against the same cwd/profile configuration used to build its launch.
  *  Resolution is subprocess-isolated: crtrd is single-threaded and a config read can
  *  block indefinitely on a network filesystem. */
-export async function assertLaunchKind(kind, cwd = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+export async function assertLaunchKind(kind, cwd = process.cwd(), profileId = envProfileId() || null) {
     const kinds = Object.keys((await readMergedLaunchConfigAsync(cwd, profileId)).kinds);
     if (!kinds.includes(kind)) {
         throw usage(`unknown kind: ${kind}`, { received: kind, next: `Valid kinds: ${kinds.sort().join(', ')}.` });

package/dist/core/runtime/launch.js

@@ -8,6 +8,7 @@
 // fresh cycle as a new branch rather than starting a new file.
 // The spec is rewritten on every polymorph (base→orchestrator) so a node
 // always comes back as its *current* self.
+import { envProfileId } from '../../shared/env.js';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readMergedLaunchConfig } from '../config.js';
@@ -25,7 +26,6 @@ import { modelLadders, defaultProvider, STRENGTH_ALIASES, MODEL_PROVIDER_KEYS, M
 // file's openDb-reaching graph. Re-exported here so existing importers of these
 // launch.ts symbols keep working.
 export { OPENAI_PROVIDER_ENV, configuredLadderProviders, inferPortableModelSelection } from './model-selection.js';
-// ---------------------------------------------------------------------------
 // Two-axis model resolution: (provider × strength) → concrete `model:thinking`.
 //
 // A persona declares ONE `model:` field valued `provider/strength` (e.g.
@@ -36,7 +36,6 @@ export { OPENAI_PROVIDER_ENV, configuredLadderProviders, inferPortableModelSelec
 // pi accepts the `:thinking` suffix on `--model` (off,minimal,low,medium,high,
 // xhigh — confirmed via `pi --help`), so the resolved spec is exactly the
 // string buildPiArgv passes to `--model`; no extra launch plumbing.
-// ---------------------------------------------------------------------------
 /** Model-ladder resolution goes through `readMergedLaunchConfig` — the SAME
  *  project-stack > profile > user > builtin precedence `resolveKindConfig`
  *  already uses for `kinds` — so a project/profile override of `modelLadders`
@@ -258,7 +257,7 @@ function buildLaunchSpecFromMerged(kind, mode, opts, merged) {
 }
 /** Build a launch recipe for callers that are not on crtrd's event loop. */
 export function buildLaunchSpec(kind, mode, opts) {
-    return buildLaunchSpecFromMerged(kind, mode, opts, readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null)));
+    return buildLaunchSpecFromMerged(kind, mode, opts, readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (envProfileId() || null)));
 }
 /**
  * Resolve launch config in a bounded subprocess before building a recipe.
@@ -268,7 +267,7 @@ export function buildLaunchSpec(kind, mode, opts) {
  */
 export async function buildLaunchSpecAsync(kind, mode, opts) {
     const cwd = opts.cwd ?? process.cwd();
-    const profileId = opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null);
+    const profileId = opts.profileId !== undefined ? opts.profileId : (envProfileId() || null);
     const merged = await readMergedLaunchConfigAsync(cwd, profileId);
     return buildLaunchSpecFromMerged(kind, mode, opts, merged);
 }
@@ -308,9 +307,7 @@ export function readMergedLaunchConfigAsync(cwd, profileId) {
         });
     });
 }
-// ---------------------------------------------------------------------------
 // Build the pi argv to launch / revive a node
-// ---------------------------------------------------------------------------
 /** Persist a node's (possibly large) system prompt to a file in its node dir and
  *  return the absolute path, so callers can pass a short path to pi instead of
  *  the inline text. Returns null if the write fails — the caller then falls back

package/dist/core/runtime/lifecycle.js

@@ -25,11 +25,13 @@
 // `cancel`.
 //
 // Layering note: lifecycle.ts is runtime, but it is the canvas write surface's
-// `transition` verb (the only writer of status+intent), so it owns its atomic
-// row UPDATE directly via openDb — the one sanctioned exception to "only
-// canvas.ts touches the db" (see src/core/canvas/.crouter/memory/INDEX.md),
-// exactly as db.ts's backfill is the sanctioned exception for a data migration.
-import { openDb, getNode, cancelCronsOnWake } from '../canvas/index.js';
+// `transition` verb (the only writer of status+intent), so it drives the
+// atomic status+intent write through canvas.ts's `transitionStatusIntent`
+// (its own decision logic — the legality table below, and the
+// unknown-node/illegal-move/already-finalized-cancel branching — stays here;
+// only the raw conditional UPDATE lives in canvas.ts, keeping every `.prepare(`
+// inside `core/canvas/`).
+import { getNode, cancelCronsOnWake, transitionStatusIntent } from '../canvas/index.js';
 const ANY = '*';
 /** The supervised statuses — a live node the daemon watches. */
 const LIVE = ['active', 'idle'];
@@ -71,28 +73,17 @@ export function transition(nodeId, event) {
     const spec = TRANSITIONS[event];
     const writeStatus = Object.prototype.hasOwnProperty.call(spec, 'status');
     const writeIntent = Object.prototype.hasOwnProperty.call(spec, 'intent');
-    const assignments = [];
-    const values = [];
-    if (writeStatus) {
-        assignments.push('status = ?');
-        values.push(spec.status ?? null);
-    }
-    if (writeIntent) {
-        assignments.push('intent = ?');
-        values.push(spec.intent ?? null);
-    }
-    const predicates = ['node_id = ?'];
-    values.push(nodeId);
-    if (spec.from !== ANY) {
-        predicates.push(`status IN (${spec.from.map(() => '?').join(', ')})`);
-        values.push(...spec.from);
-    }
+    const fields = {};
+    if (writeStatus)
+        fields.status = spec.status;
+    if (writeIntent)
+        fields.intent = spec.intent ?? null;
     // A committed canonical result is protected from a concurrent close.
-    if (event === 'cancel')
-        predicates.push('final_report IS NULL');
-    const db = openDb();
-    const result = db.prepare(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`).run(...values);
-    if (result.changes === 0) {
+    const changes = transitionStatusIntent(nodeId, fields, {
+        fromStatuses: spec.from === ANY ? undefined : spec.from,
+        requireNoFinalReport: event === 'cancel',
+    });
+    if (changes === 0) {
         const cur = getNode(nodeId);
         if (cur === null)
             throw new Error(`transition: unknown node ${nodeId}`);

package/dist/core/runtime/managed-provider-cooling.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessageDiagnostic } from "@earendil-works/pi-ai";
+import type { AssistantMessageDiagnostic } from '@earendil-works/pi-ai';
 /** Diagnostic `type` tag carrying the cooling deadline; also the wire contract the
  *  stophook matches on. */
 export declare const MANAGED_PROVIDER_COOLING_DIAGNOSTIC = "crtr:managed-provider-cooling";

package/dist/core/runtime/naming.js

@@ -217,10 +217,8 @@ export async function headlessName(body, sourceCap = PROMPT_CAP) {
 export function headlessNameFromConversation(conversation) {
     return headlessName(conversation, 30_000);
 }
-// ---------------------------------------------------------------------------
 // Issue titles — turn a free-text todo/idea/bug note into a short, human-readable
 // GitHub-issue title (sentence case, NOT kebab). Used by `crtr canvas issue new`.
-// ---------------------------------------------------------------------------
 const TITLE_SYSTEM_PROMPT = 'You write GitHub issue titles. Given a free-text note (a todo, idea, or bug ' +
     'report), reply with ONLY a concise issue title: sentence case, 4-10 words, no ' +
     'trailing period, no quotes, no prefix like "Bug:" or "Idea:", no markdown. ' +

package/dist/core/runtime/nodes.js

@@ -12,6 +12,7 @@
 //             learns when the work finishes — this seeds the subscription
 //             graph to mirror the spawn structure. A `spawned_by` audit edge
 //             is also recorded.
+import { envHomeOverride } from '../../shared/env.js';
 import { randomBytes } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
 import { createNode, getNode, getRow, subscribe, recordSpawn, contextDir, } from '../canvas/index.js';
@@ -200,7 +201,7 @@ export function nodeEnv(meta) {
     if (meta.parent)
         env['CRTR_PARENT_NODE_ID'] = meta.parent;
     // Propagate an explicit canvas home so children share the same canvas.
-    const home = process.env['CRTR_HOME'];
+    const home = envHomeOverride();
     if (home !== undefined && home !== '')
         env['CRTR_HOME'] = home;
     // Propagate the subtree-root node id. The broker uses it to group a subtree;

package/dist/core/runtime/persona.js

@@ -4,9 +4,7 @@
 import { getNode, updateNode } from '../canvas/index.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
 import { orchestratorContextNote } from './bearings.js';
-// ---------------------------------------------------------------------------
 // Base → orchestrator guidance
-// ---------------------------------------------------------------------------
 /** Fresh-context framing for a base → orchestrator change. */
 function orchestrationGuidance(nodeId, kind) {
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
@@ -18,9 +16,7 @@ function orchestrationGuidance(nodeId, kind) {
     parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using your orchestration protocol. Current contents:`, '', roadmap, '', orchestratorContextNote(nodeId), '', 'Your three long-term memory scopes (user-global, project, node-local) already surface in your bearings at boot. What promotion changes is USE, not access: you now persist across refresh cycles, so node-local carries what THIS goal needs between your refreshes, and durable facts you commit to user-global or project outlive this node. Use `crtr memory write` to save a document; `crtr memory list` to browse; `crtr memory find` to search (see "Your long-term memory" above for the full substrate flow).', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
     return parts.join('\n');
 }
-// ---------------------------------------------------------------------------
 // Orchestrator → base guidance
-// ---------------------------------------------------------------------------
 /** orchestrator → base (demote): hands-on again, finish in-window. */
 function baseModeGuidance() {
     return ('You are HANDS-ON again — base mode. Do the work yourself in THIS window and finish it here; ' +
@@ -36,9 +32,7 @@ export function transitionGuidance(nodeId, from, to) {
     const node = getNode(nodeId);
     return orchestrationGuidance(nodeId, node?.kind ?? 'general');
 }
-// ---------------------------------------------------------------------------
 // Detector + ack commit.
-// ---------------------------------------------------------------------------
 /** Compare the live persona with the last acknowledged context delivery.
  * `guidance` contains only fresh-context framing; current snapshots supply its
  * documents. An absent or pre-kind acknowledgment cannot fabricate drift. */

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

@@ -15,19 +15,16 @@
 // §5.1 import-lint: placement-tmux.ts is an allowed direct importer of
 // tmux-driver.ts — it is the sanctioned pure-tmux seam, re-exporting the driver
 // verbs other modules need so they never import the driver directly.
+import { envHomeOverride } from '../../shared/env.js';
 import { paneLocation, ensureSession, openNodeWindow, splitWindow, selectLayout, } from './tmux-driver.js';
 import { BROKER_VIEW_SOCKET_WAIT_MS } from './view-socket.js';
 // Re-export the pure tmux driver verbs the CLI/viewer consumers need without
 // exposing the canvas focuses table or sending command modules to the raw driver.
 export { paneExists, paneLocation, paneOfNode, paneCurrentPath, paneSize, paneRunning, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, renameWindow, displayPopup, windowOfPane, respawnPaneSync, respawnPaneInBackground, respawnPaneInPlace, paneStartCommand, panePid, windowAlive, listLivePanes, VIEWER_STAMP_OPTION, stampViewerPaneAsync, liveViewerPanes, sendAttachControl, displayClientMessage, } from './tmux-driver.js';
 export { installTmuxBindings } from './tmux-bindings.js';
-// ---------------------------------------------------------------------------
 // view.sock readiness — the one shared broker-cold-start primitive
-// ---------------------------------------------------------------------------
 export { BROKER_VIEW_SOCKET_WAIT_MS, waitForBrokerViewSocket } from './view-socket.js';
-// ---------------------------------------------------------------------------
 // Viewer pane opener (tmux half, NO focus-row write)
-// ---------------------------------------------------------------------------
 /** Env for a `crtr surface attach` VIEWER pane (the focus split, the spawn viewer
  *  window, AND recycle's re-attach respawn): propagate CRTR_HOME so the viewer
  *  resolves the SAME canvas home — and thus the right view.sock — under a
@@ -35,7 +32,7 @@ export { BROKER_VIEW_SOCKET_WAIT_MS, waitForBrokerViewSocket } from './view-sock
  *  server env, like every other crtr chrome pane). One helper so the viewer-pane
  *  sites can't drift. */
 export function viewerSplitEnv() {
-    const crtrHome = process.env['CRTR_HOME'];
+    const crtrHome = envHomeOverride();
     return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
 }
 /** Open a `crtr surface attach` VIEWER pane for `nodeId` — the PURE tmux half of

package/dist/core/runtime/placement.js

@@ -22,8 +22,9 @@
 //   • The chrome/viewer tmux re-exports (§2.1): placement stays the sanctioned
 //     model-over-driver. Raw driver access is confined to placement, its pure
 //     tmux half, the bindings owner, and tmux chrome.
+import { envNodeId } from '../../shared/env.js';
 import { getNode, fullName, deleteNode, listNodes, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
-import { nodeHasAssistantMessage, isNodeStreaming } from '../canvas/render.js';
+import { nodeHasAssistantMessage, isStreaming } from '../canvas/render-source.js';
 import { headlessBrokerHost } from './host.js';
 import { paneExists, paneLocation, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, respawnPaneSync, windowOfPane, renameWindow, } from './tmux-driver.js';
 // The PURE tmux + broker-socket half now lives in placement-tmux.ts. placement
@@ -47,7 +48,6 @@ import { isPidAlive } from '../canvas/pid.js';
 // tmux-driver.ts directly.
 export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux-driver.js';
 export { installTmuxBindings } from './tmux-bindings.js';
-// ---------------------------------------------------------------------------
 // Viewer registry reads — COMPOSE over the canvas focuses table (§2.3/§4).
 //
 // placement is the front door for "which nodes have a viewer on screen"; the SQL
@@ -57,7 +57,6 @@ export { installTmuxBindings } from './tmux-bindings.js';
 // GC is lazy on read: a row whose viewer pane no longer exists (the user closed
 // the window, the attach client died) is pruned the next time it is read, so the
 // registry self-heals without a sweeper.
-// ---------------------------------------------------------------------------
 /** Prune a viewer row whose pane is gone; return it iff its pane is still live. */
 function liveOrPrune(f) {
     if (f === null)
@@ -131,9 +130,7 @@ export function openViewerWindow(nodeId, session, opts = {}) {
         return null;
     return registerViewerFocus(nodeId, opened.pane, opened.session, opened.window);
 }
-// ---------------------------------------------------------------------------
 // focus — the front door for `surface node focus` / `surface node cycle` / nav (§A.4)
-// ---------------------------------------------------------------------------
 /** Bring a node's ONE viewer pane forefront (§A.4). Every node is a detached
  *  broker, so there is no engine pane to swap into the caller's viewport — focus
  *  instead ensures the node's single surface-attach viewer is on screen beside (or
@@ -283,9 +280,7 @@ export async function focus(nodeId, opts) {
         surfaceNewPane(opened.pane);
     return { focused: true, session: opened.session, inPlace: false, revived };
 }
-// ---------------------------------------------------------------------------
 // Teardown / detach — close a node's viewer pane + row
-// ---------------------------------------------------------------------------
 /** Tear a node off its viewer (close/reset/cancel teardown). The broker engine
  *  is killed by its own host teardown over view.sock — this only closes the
  *  on-screen viewer: kill its pane (the window collapses once its last pane goes)
@@ -326,9 +321,7 @@ export function detachToBackground(nodeId, pane) {
     reapIfEmpty(nodeId);
     return closed;
 }
-// ---------------------------------------------------------------------------
 // Reaping empty nodes (no AI output) on close / detach
-// ---------------------------------------------------------------------------
 /** Is this node an EMPTY SHELL right now — a node whose engine never produced an
  *  assistant message? Such nodes are pure dead weight on the graph. A node
  *  actively generating its FIRST turn is NOT empty (its output just hasn't landed
@@ -337,7 +330,7 @@ function isEmptyNode(nodeId) {
     const m = getNode(nodeId);
     if (m === null)
         return false;
-    if (isNodeStreaming(nodeId))
+    if (isStreaming(nodeId, getNode(nodeId)?.pi_pid ?? null))
         return false;
     return !nodeHasAssistantMessage(m.pi_session_file);
 }
@@ -366,7 +359,7 @@ export function reapIfEmpty(nodeId, keepPane) {
  *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
 export function reapEmptyNodes(opts = {}) {
     const dryRun = opts.dryRun ?? false;
-    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const selfId = envNodeId() ?? '';
     const reaped = [];
     for (const row of listNodes()) {
         const id = row.node_id;

package/dist/core/runtime/recap.js

@@ -11,6 +11,7 @@
 // there is no local fallback, unlike naming, because a wrong recap is worse than
 // none.
 import { headlessText } from './headless-pi.js';
+import { envRecapModelOverride } from '../../shared/env.js';
 /** Wall-clock budget for the headless pi call before we give up (no recap). */
 const RECAP_TIMEOUT_MS = 25_000;
 /** Fallback model when the live session has not resolved one yet. Ordinarily the
@@ -59,9 +60,9 @@ function recapUserPrompt(conversation, roadmap) {
 /** Model precedence is explicit env override → the conversation's live
  *  working model → the small fallback. */
 function recapModel(liveModel) {
-    const override = process.env['CRTR_RECAP_MODEL'];
-    if (override !== undefined && override.trim() !== '')
-        return override.trim();
+    const override = envRecapModelOverride();
+    if (override !== undefined)
+        return override;
     if (liveModel !== undefined && liveModel.trim() !== '')
         return liveModel.trim();
     return DEFAULT_RECAP_MODEL;

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/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