@north-light/crouter 0.3.233 → 0.3.234

package/dist/core/canvas/nav-model.js

@@ -11,7 +11,7 @@
 // `FoldState`) so this layer owns no singletons and each consumer keeps its own
 // state.
 import { getNode, subscribersOf, subscriptionsOf } from './index.js';
-import { activeFaultForDisplay } from './render.js';
+import { activeFaultForDisplay } from './render-source.js';
 import { readFault } from '../runtime/fault.js';
 import { faultSummary } from './status-glyph.js';
 import { statusRank } from './node-order.js';
@@ -19,7 +19,6 @@ import { nodeGlyph, navLabel, shortId, tokensCell, activityCell, cycleBadge, ask
 // Re-export the pure render/telemetry half so existing nav-model importers
 // (chrome/canvas-panels, overlays/graph, resume) keep resolving these here.
 export { PI_MAX_WIDGET_LINES, VIEWPORT_FALLBACK_ROWS, ESC, RESET, BOLD, DIM, REVERSE, BG_ATTACHED, GREEN, RED, YELLOW, CYAN, GRAY, nodeGlyph, visibleWidth, truncate, fillWidth, fillBar, readTelemetry, fmtTokens, tokensCell, activityCell, cycleBadge, navLabel, shortId, askBadge, liveBelowBadge, isAttached, hasBrokerViewers, fetchAsksMap, graphWidgetBudget, GRAPH_HINT, } from './nav-render.js';
-// ---------------------------------------------------------------------------
 // Read primitives — UNCACHED, deliberately
 //
 // These once memoized into module-global Maps that a `beginFrame()` cleared at
@@ -36,7 +35,6 @@ export { PI_MAX_WIDGET_LINES, VIEWPORT_FALLBACK_ROWS, ESC, RESET, BOLD, DIM, REV
 // goes straight to the canvas db. The only frame cache still in play is
 // nav-render's telemetry memo, whose TUI callers clear it themselves via
 // `beginFrameTelem()`.
-// ---------------------------------------------------------------------------
 /** subscriptionsOf (a node's reports); an unreadable row reads as no edges. */
 function subsOf(id) {
     try {
@@ -55,7 +53,6 @@ function mgrsOf(id) {
         return [];
     }
 }
-// ---------------------------------------------------------------------------
 // Attachment — is a human currently WATCHING a node? A separate axis from
 // running (status 'active' = the engine is live on its detached broker, watched
 // or not). Two signals:
@@ -65,10 +62,7 @@ function mgrsOf(id) {
 //                 web tabs) to job/attach.json on every viewer change
 //                 (src/core/runtime/broker.ts). Trusted only while the node is
 //                 'active': a broker crash can leave a stale file.
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
 // Graph queries (dependency-free, straight off the canvas db)
-// ---------------------------------------------------------------------------
 /** First manager (by created) — the UP step for the ancestry spine. */
 export function managerOf(id) {
     return mgrsOf(id)[0]?.node_id;
@@ -130,9 +124,7 @@ export function subtreeIds(root) {
     }
     return out;
 }
-// ---------------------------------------------------------------------------
 // Shared cell builders
-// ---------------------------------------------------------------------------
 /** ⤳M direct-children badge — the single child-count signal, shown on any row
  *  with navigable children (folded or not). In GRAPH the ▸ caret separately marks
  *  a collapsed row, so this stays a pure count and never doubles as a fold badge. */
@@ -148,11 +140,9 @@ export function childBadge(node) {
 export function sortedChildIds(id) {
     return convoChildIds(id).sort((a, b) => statusRank(getNode(a)?.status) - statusRank(getNode(b)?.status));
 }
-// ---------------------------------------------------------------------------
 // GRAPH model — flatten the local graph fold-aware. Rebuilt every render (cheap
 // sqlite reads) so a finished child / new spawn shows live; the manual fold
 // overrides and the cursor id are the only persisted state.
-// ---------------------------------------------------------------------------
 export function computeSubtreeActivity(root, self) {
     const expand = new Set();
     const activeBelow = new Map();

package/dist/core/canvas/nav-render.js

@@ -15,22 +15,18 @@ import { isBusy } from '../runtime/busy.js';
 import { readFault } from '../runtime/fault.js';
 import { activeFaultForDisplay } from './render-source.js';
 import { resolveNodeVisual } from './status-glyph.js';
-// ---------------------------------------------------------------------------
 // Tuning constants
-// ---------------------------------------------------------------------------
 /** pi's InteractiveMode.MAX_WIDGET_LINES — the hard cap on lines in a string
  *  array widget; anything beyond it pi truncates with its own "... (widget
  *  truncated)". Our GRAPH viewport stays at/under this and scrolls internally. */
 export const PI_MAX_WIDGET_LINES = 10;
 export const VIEWPORT_FALLBACK_ROWS = 30;
-// ---------------------------------------------------------------------------
 // ANSI styling. pi renders embedded escapes in widget lines and measures width
 // ANSI-aware, so raw escapes are safe and need no pi-tui dependency. The cursor
 // (selected row) uses a theme-agnostic ATTRIBUTE (reverse), so it reads under
 // NO_COLOR; the attached-row tint is a background COLOUR, while the overlay-
 // aware glyph (●/○/✓/✗/⟳/⚠) carries the live signal independently, even where
 // colour is stripped.
-// ---------------------------------------------------------------------------
 export const ESC = '\x1b[';
 export const RESET = `${ESC}0m`;
 export const BOLD = `${ESC}1m`;
@@ -129,14 +125,12 @@ export function fillBar(content, width, open) {
     const pad = Math.max(0, width - visibleWidth(clipped));
     return `${open}${reasserted}${' '.repeat(pad)}${RESET}`;
 }
-// ---------------------------------------------------------------------------
 // Per-frame telemetry cache. Its callers are TUI render passes ONLY (the GRAPH
 // overlay and the canvas panels), each of which calls beginFrameTelem() at the
 // top of the pass, so token/activity cells read fresh once per frame instead of
 // once per row and a stale entry can at worst be one frame old. Never memoize a
 // canvas read for a caller that is not a render pass: crtrd lives for hours, and
 // a memo it never clears is permanent, not per-frame.
-// ---------------------------------------------------------------------------
 const frameTelem = new Map();
 /** Clear the per-frame telemetry cache. Every render pass calls this first, so
  *  one keystroke re-reads each node's telemetry exactly once. */
@@ -246,12 +240,10 @@ export function liveBelowBadge(node, activeBelow) {
     const n = activeBelow.get(node.node_id) ?? 0;
     return n > 0 ? ` ${GREEN}⇣${n}${RESET}` : '';
 }
-// ---------------------------------------------------------------------------
 // Per-node ask counts — ONE shell-out per poll. `crtr canvas attention map`
 // buckets a whole sub-DAG's pending asks by node in a single process, so the
 // timer stays cheap (< 2 s) regardless of how many nodes are visible. --json
 // gives a parseable {counts} blob (the default render is XML chrome).
-// ---------------------------------------------------------------------------
 export function fetchAsksMap(rootId) {
     try {
         const raw = execFileSync('crtr', ['canvas', 'attention', 'map', '--view', rootId, '--json'], {

package/dist/core/canvas/remote-canvas-source.js

@@ -12,7 +12,6 @@
 // "every process is a /v1 client" architecture (which governs LOCAL access).
 import { createRemoteExec } from './remote-transport.js';
 const CACHE_TTL_MS = 1000;
-// ---------------------------------------------------------------------------
 // Remote JSON shape validation.
 //
 // `execJson<T>` parses stdout and casts it to T with NO structural check — a
@@ -21,7 +20,6 @@ const CACHE_TTL_MS = 1000;
 // `ticketCountsForView` validate before caching/returning; on a shape mismatch
 // they degrade exactly like the existing network-failure path (null/[]/{}),
 // never a malformed object a caller might dereference.
-// ---------------------------------------------------------------------------
 function isPlainObject(x) {
     return typeof x === 'object' && x !== null && !Array.isArray(x);
 }

package/dist/core/canvas/render-source.js

@@ -3,10 +3,10 @@
 // Every `*FromSource` variant + the pure/disk helpers they share live here so a
 // CLI process rendering the canvas through a `CanvasSource` (the API-backed
 // `ApiCanvasSource`, or a `RemoteCanvasSource`) NEVER drags in `core/canvas/db.ts`
-// (`openDb`) or the `core/canvas/canvas.ts` accessors. The sync, db-backed
-// renderers (`renderTree`/`dashboardRows`/…) stay in `render.ts`, which imports the
-// shared helpers FROM here and re-exports this whole module (`export *`) so its
-// existing importers are unaffected.
+// (`openDb`) or the `core/canvas/canvas.ts` accessors. This is the whole module now
+// — the sync, db-backed renderers (`renderTree`/`dashboardRows`/…) that used to live
+// in a separate `render.ts` re-export shim have been retired; their few real callers
+// migrated onto these `*FromSource` variants directly.
 //
 // ALLOWED imports (verified openDb-free): node:fs/path, ./pid.js, ./labels.js,
 // ./status-glyph.js, ../runtime/fault.js, ./paths.js, ./remote-canvas-source.js,
@@ -21,10 +21,8 @@ import { isPidAlive } from './pid.js';
 import { resolveNodeVisual, faultSummary } from './status-glyph.js';
 import { readFault } from '../runtime/fault.js';
 import { parseCard } from '../../shared/generated-context.js';
-// ---------------------------------------------------------------------------
 // Active-fault overlay: stale daemon-owned provider faults are hidden once the
 // broker pid is gone; manual/client faults stay visible until cleared.
-// ---------------------------------------------------------------------------
 export function activeFaultForDisplay(node, fault) {
     if (fault === null)
         return null;
@@ -52,7 +50,6 @@ export function fmtCtx(tokensIn) {
         return '0k';
     return `${Math.floor(tokensIn / 1000)}k`;
 }
-// ---------------------------------------------------------------------------
 // Source-driven tree builder (openDb-free)
 //
 // Ticket counts are threaded in as a `Record<node_id, count>` fetched ONCE per
@@ -61,7 +58,6 @@ export function fmtCtx(tokensIn) {
 // LOCAL disk reads (telemetry.json / fault.json), valid for a same-host source
 // but meaningless for a truly remote canvas, so both are suppressed when the
 // source is a `RemoteCanvasSource`.
-// ---------------------------------------------------------------------------
 async function nodeLineFromSource(source, nodeId, indent, connector, remote, tickets) {
     const node = await source.getNode(nodeId);
     if (node === null)
@@ -80,8 +76,15 @@ async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out,
     visited.add(nodeId);
     const connector = isLast ? '└─ ' : '├─ ';
     out.push(await nodeLineFromSource(source, nodeId, indent, connector, remote, tickets));
-    const children = await source.subscriptionsOf(nodeId).catch(() => []);
     const childIndent = indent + (isLast ? '   ' : '│  ');
+    let children;
+    try {
+        children = await source.subscriptionsOf(nodeId);
+    }
+    catch (err) {
+        out.push(`${childIndent}⚠ children unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
     for (let i = 0; i < children.length; i++) {
         const child = children[i];
         const childIsLast = i === children.length - 1;
@@ -98,7 +101,15 @@ export async function renderTreeFromSource(source, rootId) {
     const node = await source.getNode(rootId);
     if (node === null)
         return `? <missing node: ${rootId}>`;
-    const tickets = await source.ticketCountsForView(rootId).catch(() => ({}));
+    let tickets;
+    let ticketsUnavailable = null;
+    try {
+        tickets = await source.ticketCountsForView(rootId);
+    }
+    catch (err) {
+        tickets = {};
+        ticketsUnavailable = err instanceof Error ? err.message : String(err);
+    }
     const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(rootId).tokens_in);
     const asks = tickets[rootId] ?? 0;
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
@@ -108,12 +119,21 @@ export async function renderTreeFromSource(source, rootId) {
     const out = [];
     out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`);
     const visited = new Set([rootId]);
-    const children = await source.subscriptionsOf(rootId).catch(() => []);
+    let children;
+    try {
+        children = await source.subscriptionsOf(rootId);
+    }
+    catch (err) {
+        out.push(`⚠ children unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        children = [];
+    }
     for (let i = 0; i < children.length; i++) {
         const child = children[i];
         const isLast = i === children.length - 1;
         await walkTreeFromSource(source, child.node_id, '', isLast, visited, out, remote, tickets);
     }
+    if (ticketsUnavailable !== null)
+        out.push(`Tickets: unavailable (${ticketsUnavailable}).`);
     return out.join('\n');
 }
 export async function renderForestFromSource(source) {
@@ -424,13 +444,11 @@ export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = n
     const focusedNodeIds = remote ? new Set() : localFocusedNodeIds;
     return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
 }
-// ---------------------------------------------------------------------------
 // Lazy enrichment (source-driven) — fold expensive per-node reads into rows on
 // demand. Ask counts are supplied by the caller (`asks` — a pre-fetched
 // `ticketCountsForView` map merged across the visible roots), NOT scanned here
 // (`ticketCountsForNodes` reaches openDb). Telemetry (ctx tokens) + goal/session
 // are LOCAL disk reads, suppressed for a `RemoteCanvasSource`.
-// ---------------------------------------------------------------------------
 export async function enrichRowsFromSource(source, rows, asks) {
     const todo = rows.filter((r) => r.enriched !== true);
     if (todo.length === 0)

package/dist/core/command-manifests/manifest.js

@@ -9,9 +9,7 @@
 // the raw manifest bytes passed in.
 import { validateCommandNode } from './schema.js';
 import { isRecord } from '../../shared/predicates.js';
-// ---------------------------------------------------------------------------
 // Validation helpers
-// ---------------------------------------------------------------------------
 const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const REST_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 function typeName(v) {
@@ -21,9 +19,7 @@ function typeName(v) {
         return 'array';
     return typeof v;
 }
-// ---------------------------------------------------------------------------
 // Top-level manifest validation
-// ---------------------------------------------------------------------------
 /**
  * Validates a HTTP-transport plugin manifest exactly per §4, performing strict atomic
  * validation and order-independent forest materialization. Returns either a
@@ -130,9 +126,7 @@ export function validateCommandManifest(raw, options) {
     // Any issue found -> zero contributions
     return { issues };
 }
-// ---------------------------------------------------------------------------
 // Timeouts validation
-// ---------------------------------------------------------------------------
 function validateTimeouts(raw, issue) {
     if (!isRecord(raw)) {
         issue('command_manifest_invalid', 'timeouts must be an object', typeName(raw), '{ connectMs?, requestMs?, streamIdleMs? }', 'Fix timeouts.', 'timeouts');
@@ -156,9 +150,7 @@ function validateTimeouts(raw, issue) {
     }
     return out;
 }
-// ---------------------------------------------------------------------------
 // Help addenda validation
-// ---------------------------------------------------------------------------
 /** Validate the optional top-level `helpAddenda` map: core command path →
  *  addendum text rendered as an attributed block beneath that core command's
  *  help. When the caller supplies the core command path set, a key naming no
@@ -228,9 +220,7 @@ function validateMount(raw, index, transport, issue) {
     const typedNode = node;
     return { parent, node: typedNode };
 }
-// ---------------------------------------------------------------------------
 // Forest materialization (order-independent)
-// ---------------------------------------------------------------------------
 /**
  * Materializes a flat list of mounts into a forest of top-level branches,
  * resolving nested mounts whose parent exists in a top-level inline tree regardless of order. Nested mounts that provide another nested mount's parent must appear first. Validates self-containment and no duplicates.

package/dist/core/command-manifests/schema.js

@@ -1,8 +1,6 @@
 // Unified command-manifest schema. Transport is the sole leaf-dialect discriminator.
 import { isRecord } from '../../shared/predicates.js';
-// ---------------------------------------------------------------------------
 // Validation helpers
-// ---------------------------------------------------------------------------
 const TIERS = new Set(['normal', 'common', 'important']);
 const FLAG_TYPES = new Set(['string', 'int', 'bool', 'path', 'enum']);
 const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -471,9 +469,7 @@ function validateLeaf(raw, path, transport, issue) {
     const rest = validateRestMapping(raw['rest'], path, params, issue);
     return rest === null ? null : { ...base, rest };
 }
-// ---------------------------------------------------------------------------
 // REST mapping validation (§4.4)
-// ---------------------------------------------------------------------------
 const REST_METHODS_SET = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 // RFC 7230 `token` grammar — the legal charset for an HTTP header field name.
 const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;

package/dist/core/command-plugins/transport/http-invoke.js

@@ -20,9 +20,7 @@ import { CrtrError } from '../../errors.js';
 import { diag, recordPreviewError, recordPreviewJsonLine, writeStdout } from '../../io.js';
 import { ExitCode } from '../../../types.js';
 import { isRecord } from '../../../shared/predicates.js';
-// ---------------------------------------------------------------------------
 // Constants
-// ---------------------------------------------------------------------------
 const DEFAULT_CONNECT_MS = 10_000;
 const DEFAULT_REQUEST_MS = 30_000;
 const DEFAULT_STREAM_IDLE_MS = 60_000;
@@ -33,9 +31,7 @@ const RESERVED_CODES = new Set(['internal', 'unknown_path', 'command_collision',
 /** Marker for the idle-timeout abort so the relay loop can distinguish it. */
 class StreamIdleError extends Error {
 }
-// ---------------------------------------------------------------------------
 // Public entry
-// ---------------------------------------------------------------------------
 /**
  * Execute one HTTP-transport plugin leaf. Unary leaves return the validated response
  * object (crtr's ordinary dispatcher renders it, or mirrors it under --json).
@@ -59,9 +55,7 @@ export async function invokeHttpLeaf(spec, input, context) {
         return mapUnary2xx(spec, body);
     throwNon2xx(spec, status, body); // always throws
 }
-// ---------------------------------------------------------------------------
 // Request construction (§6.1) — pure, no network I/O
-// ---------------------------------------------------------------------------
 function buildRequestPlan(spec, input, context) {
     const paramsByName = new Map();
     for (const p of spec.params)
@@ -245,9 +239,7 @@ function encodePathSegmentValue(value) {
 function paramKey(name) {
     return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
-// ---------------------------------------------------------------------------
 // Unary lifecycle (§6.4) — connect + total clocks, buffered body
-// ---------------------------------------------------------------------------
 function requestUnary(spec, plan) {
     const connectMs = spec.timeouts?.connectMs ?? DEFAULT_CONNECT_MS;
     const requestMs = spec.timeouts?.requestMs ?? DEFAULT_REQUEST_MS;
@@ -335,9 +327,7 @@ function mapUnary2xx(spec, body) {
     }
     return parsed;
 }
-// ---------------------------------------------------------------------------
 // Streaming lifecycle (§6.3) — connect + idle clocks, verbatim frame relay
-// ---------------------------------------------------------------------------
 async function requestStreaming(spec, plan) {
     const connectMs = spec.timeouts?.connectMs ?? DEFAULT_CONNECT_MS;
     const idleMs = spec.timeouts?.streamIdleMs ?? DEFAULT_STREAM_IDLE_MS;
@@ -461,9 +451,7 @@ async function requestStreaming(spec, plan) {
         throw unreachable(spec, plan, detail);
     }
 }
-// ---------------------------------------------------------------------------
 // Error mapping (§6.5)
-// ---------------------------------------------------------------------------
 /** Extract a non-2xx error. A conforming nested `{ error: { code, message,
  *  field?, next? } }` with an acceptable snake_case, non-reserved code becomes a
  *  CrtrError carrying that code; a reserved/ill-formed code demotes to
@@ -526,9 +514,7 @@ function unreachable(spec, plan, detail) {
         next: `Check connectivity to ${plan.url.host} and retry; run \`crtr pkg plugin update ${spec.registration.name}\` if the command surface changed.`,
     });
 }
-// ---------------------------------------------------------------------------
 // Small helpers
-// ---------------------------------------------------------------------------
 function label(spec) {
     return `HTTP-transport plugin "${spec.registration.name}" command \`${spec.commandPath.join(' ')}\``;
 }

package/dist/core/command.js

@@ -15,9 +15,7 @@ import { spawnSync } from 'node:child_process';
 import { constants as osConstants } from 'node:os';
 import { isatty } from 'node:tty';
 import { resolve } from 'node:path';
-// ---------------------------------------------------------------------------
 // Factory functions
-// ---------------------------------------------------------------------------
 function freezeCommandMetadata(value) {
     if (value === null || typeof value !== 'object' || Object.isFrozen(value))
         return value;
@@ -301,9 +299,7 @@ export function unknownPathError(node, path, bad) {
         next: `Valid children: ${validStr}. Run \`${entryCmd}\` for the full list.`,
     });
 }
-// ---------------------------------------------------------------------------
 // Argv parser
-// ---------------------------------------------------------------------------
 function parseArgvError(code, message, received, field, next) {
     return new CrtrError(code, message, ExitCode.USAGE, {
         received,

package/dist/core/config.js

@@ -1,3 +1,4 @@
+import { envProfileId } from '../shared/env.js';
 import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
@@ -762,7 +763,7 @@ function readRawProjectScopeConfigs(targetCwd, targetProfileId) {
  *  the target node's) MUST pass the target's own cwd/profile explicitly, or
  *  `spawnEnv.allow` resolves from the wrong scope entirely (the C-1
  *  follow-up fix this parameterization exists for). */
-export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileId = process.env['CRTR_PROFILE_ID'] || null) {
+export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileId = envProfileId() || null) {
     const defaults = defaultScopeConfig();
     const userRaw = readRawScopeConfig('user');
     const profileRaw = readRawProfileConfig(targetProfileId);

package/dist/core/feed/inbox.d.ts

@@ -76,6 +76,16 @@ export declare function cancelPendingEntries(nodeId: string, select: (entry: Inb
 export declare function readCursor(nodeId: string): InboxEntryId | undefined;
 /** Persist one validated exact cursor identity (atomic tmp+rename). */
 export declare function writeCursor(nodeId: string, entryId: string): void;
+/** Is there mail this node has not seen that would drive a turn? The one
+ *  authority for "wake-worthy inbox state", read by the park clock, the
+ *  settlement policy, the review-companion guard, and reviveNode's parked
+ *  re-entry rule. Deferred entries are excluded everywhere for the same
+ *  reason: a deferred entry rides the next natural cycle and never starts one.
+ *  A cursor that no longer resolves against the physical inbox is a fault, not
+ *  an answer — every caller's conservative reading of this predicate is `true`
+ *  (do not park, do not shut down, do not resume quietly), so report it and
+ *  return that. */
+export declare function hasUnseenWakeMail(nodeId: string): boolean;
 /** Clip a body to a bounded preview, reporting whether anything was dropped. */
 export declare function clipBody(body: string): {
     text: string;

package/dist/core/feed/inbox.js

@@ -44,15 +44,11 @@ export function finalizeInboxEntry(input) {
         ts: new Date().toISOString(),
     };
 }
-// ---------------------------------------------------------------------------
 // Cursor sidecar path
-// ---------------------------------------------------------------------------
 function cursorPath(nodeId) {
     return `${inboxPath(nodeId)}.cursor`;
 }
-// ---------------------------------------------------------------------------
 // Append
-// ---------------------------------------------------------------------------
 /** Spill an oversized inline body to a durable file — the SAME atomic
  *  tmp+rename pattern a push report uses — and return its absolute path.
  *  Called only when the body would clip in the digest; short bodies never
@@ -151,9 +147,7 @@ export function appendControllerDeathNotice(nodeId, controller) {
         throw error;
     }
 }
-// ---------------------------------------------------------------------------
 // Read
-// ---------------------------------------------------------------------------
 function readPhysicalInbox(nodeId) {
     const p = inboxPath(nodeId);
     if (!existsSync(p))
@@ -212,9 +206,7 @@ export function readInboxRange(nodeId, afterEntryId, throughEntryId) {
         throw new Error(`inbox range is reversed: ${after} through ${through}`);
     return entries.slice(afterIndex + 1, throughIndex + 1);
 }
-// ---------------------------------------------------------------------------
 // Cancel set (interrupt-canceled entries)
-// ---------------------------------------------------------------------------
 function canceledPath(nodeId) {
     return `${inboxPath(nodeId)}.canceled`;
 }
@@ -267,9 +259,7 @@ export function cancelPendingEntries(nodeId, select) {
     appendFileSync(canceledPath(nodeId), targets.join('\n') + '\n', { encoding: 'utf8', flag: 'a' });
     return targets;
 }
-// ---------------------------------------------------------------------------
 // Cursor persistence
-// ---------------------------------------------------------------------------
 /** Read and validate the persisted exact cursor identity. */
 export function readCursor(nodeId) {
     const p = cursorPath(nodeId);
@@ -291,9 +281,25 @@ export function writeCursor(nodeId, entryId) {
     writeFileSync(tmp, value, 'utf8');
     renameSync(tmp, p);
 }
-// ---------------------------------------------------------------------------
+/** Is there mail this node has not seen that would drive a turn? The one
+ *  authority for "wake-worthy inbox state", read by the park clock, the
+ *  settlement policy, the review-companion guard, and reviveNode's parked
+ *  re-entry rule. Deferred entries are excluded everywhere for the same
+ *  reason: a deferred entry rides the next natural cycle and never starts one.
+ *  A cursor that no longer resolves against the physical inbox is a fault, not
+ *  an answer — every caller's conservative reading of this predicate is `true`
+ *  (do not park, do not shut down, do not resume quietly), so report it and
+ *  return that. */
+export function hasUnseenWakeMail(nodeId) {
+    try {
+        return readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred');
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'inbox.wake_scan.failed', node_id: nodeId, error });
+        return true;
+    }
+}
 // Coalesce
-// ---------------------------------------------------------------------------
 /** Bounds for inlining a message body's preview in the digest. */
 const BODY_MAX_LINES = 12;
 const BODY_MAX_CHARS = 1000;

package/dist/core/fs-utils.d.ts

@@ -5,8 +5,15 @@ export declare function realpathOrSelf(p: string): string;
 export declare function expandTilde(p: string, homeDir?: string): string;
 export declare function ensureDir(dir: string): void;
 export declare function writeJson(path: string, data: unknown): void;
-export declare function atomicWriteJson(path: string, data: unknown): void;
-export declare function atomicWriteText(path: string, content: string | Uint8Array): void;
+export interface AtomicWriteOptions {
+    /** Force this mode regardless of any existing file's mode. Omitted: preserve the existing file's mode, or default a new file to `0o600`. */
+    mode?: number;
+}
+export declare function atomicWriteJson(path: string, data: unknown, opts?: AtomicWriteOptions): void;
+/** Replace one file's contents in a single rename, so a concurrent reader — the
+ *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export declare function atomicWriteText(path: string, content: string | Uint8Array, opts?: AtomicWriteOptions): void;
 export declare function readJson<T = unknown>(path: string): T;
 export declare function readJsonIfExists<T = unknown>(path: string): T | null;
 /** Missing or corrupt reads as absent, so a crash artifact never throws. */

package/dist/core/fs-utils.js

@@ -26,24 +26,16 @@ export function writeJson(path, data) {
     ensureDir(dirname(path));
     writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
 }
-export function atomicWriteJson(path, data) {
-    ensureDir(dirname(path));
-    const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
-    try {
-        writeFileSync(temp, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode });
-        chmodSync(temp, mode);
-        renameSync(temp, path);
-    }
-    finally {
-        if (existsSync(temp))
-            rmSync(temp, { force: true });
-    }
+export function atomicWriteJson(path, data, opts) {
+    atomicWriteText(path, JSON.stringify(data, null, 2) + '\n', opts);
 }
-export function atomicWriteText(path, content) {
+/** Replace one file's contents in a single rename, so a concurrent reader — the
+ *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export function atomicWriteText(path, content, opts) {
     ensureDir(dirname(path));
     const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+    const mode = opts?.mode ?? (existsSync(path) ? statSync(path).mode & 0o777 : 0o600);
     try {
         writeFileSync(temp, content, { mode });
         chmodSync(temp, mode);

package/dist/core/help.js

@@ -2,9 +2,7 @@
 // Pure functions — no side effects, no commander, no process.exit.
 // Rendering matches reference.md shapes exactly:
 //   root L11-32, branch L43-58, leaf L65-189.
-// ---------------------------------------------------------------------------
 // Internal helpers
-// ---------------------------------------------------------------------------
 /** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
  *  subtree that owns the state authors it through this, so the tag name and any
  *  scalar metadata (e.g. a count) travel with the data and render identically
@@ -42,9 +40,7 @@ function maxLen(names) {
 function pad(s, width) {
     return s + ' '.repeat(Math.max(0, width - s.length));
 }
-// ---------------------------------------------------------------------------
 // renderRoot
-// ---------------------------------------------------------------------------
 const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is agent-ready markdown/XML you\n' +
     'act on directly — read it as a continuation of your prompt, don\'t parse it as data.\n' +
     'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h; a leaf may route an uncommon flag to focused --flag -h guidance.';
@@ -132,9 +128,7 @@ export function renderRoot(h) {
     lines.push(CAPABILITY_DISCOVERY);
     return lines.join('\n');
 }
-// ---------------------------------------------------------------------------
 // renderBranch
-// ---------------------------------------------------------------------------
 /** Escape a value for a rendered XML attribute. Output is light XML around
  *  markdown read as prose by a model, not parsed — so we only guard the
  *  double-quote that would visually break the attribute, swapping it for a
@@ -170,9 +164,7 @@ export function renderBranch(h) {
     lines.push('</command>');
     return lines.join('\n');
 }
-// ---------------------------------------------------------------------------
 // renderLeafArgv
-// ---------------------------------------------------------------------------
 /** Build the display label for a param entry (left column). */
 function paramLabel(p) {
     if (p.kind === 'positional')

package/dist/core/host-exports/export.d.ts

@@ -20,8 +20,8 @@ import type { RootDef } from '../command.js';
 export declare function writeIfOurs(path: string, content: string, markerPrefix: string): void;
 /** Render and write every built-in export artifact to every present host, while
  *  pruning legacy generated artifacts that should no longer be surfaced.
- *  Best-effort: swallows errors (debug-logged) so a provisioning fault never
- *  breaks an unrelated `crtr` command. Kill switch: `CRTR_NO_EXPORTS=1`. */
+ *  Best-effort: reports errors without breaking an unrelated `crtr` command.
+ *  Kill switch: `CRTR_NO_EXPORTS=1`. */
 export declare function pruneLegacyExports(argv?: string[]): void;
 /** Write every built-in export artifact to every present host. Split from the
  *  prune above because the prune must run BEFORE the front door boots (stale