@north-light/crouter 0.3.233 → 0.3.235

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.d.ts

@@ -31,6 +31,14 @@ export interface RemoteShowResponse {
         session_file?: string | null;
     };
     follow_up: string;
+    fault?: {
+        link: string;
+        kind: string;
+        retry: {
+            disposition: string;
+        };
+        since: string;
+    } | null;
 }
 export declare class RemoteCanvasSource implements CanvasSource {
     private readonly previewEndpoint;

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);
 }
@@ -49,6 +47,14 @@ function isValidShowResponse(x) {
         return false;
     if (typeof x['follow_up'] !== 'string')
         return false;
+    const fault = x['fault'];
+    if (fault !== undefined && fault !== null) {
+        if (!isPlainObject(fault) || typeof fault['link'] !== 'string' || typeof fault['kind'] !== 'string' || typeof fault['since'] !== 'string')
+            return false;
+        const retry = fault['retry'];
+        if (!isPlainObject(retry) || typeof retry['disposition'] !== 'string')
+            return false;
+    }
     return true;
 }
 /** A `reports`/`managers` entry (`RemoteShowResponse`) — validated per-element
@@ -123,7 +129,7 @@ export class RemoteCanvasSource {
         // node/inspect.ts's remote `show` passthrough render — see only well-formed
         // neighbor entries, never a malformed one they'd dereference unguarded.
         const res = isValidShowResponse(raw)
-            ? { ...raw, reports: raw.reports.filter(isValidNeighborEntry), managers: raw.managers.filter(isValidNeighborEntry) }
+            ? { ...raw, fault: raw.fault ?? null, reports: raw.reports.filter(isValidNeighborEntry), managers: raw.managers.filter(isValidNeighborEntry) }
             : null;
         this.nodeCache.set(id, { value: res, at: Date.now() });
         return res;

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

@@ -24,6 +24,8 @@ export type LeafAdapter = (leaf: DeclLeafBase, commandPath: readonly string[]) =
 export interface CommandContribution {
     contributor: CommandContributorRef;
     node: DeclBranch<DeclLeafBase>;
+    /** Root name from the manifest, before collision qualification. */
+    manifestName: string;
     adaptLeaf: LeafAdapter;
 }
 /** Per-contributor collision issue. */

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/compose.js

@@ -6,15 +6,17 @@ export function adaptPluginContributions(contributions) {
         contributions: contributions.map((contribution) => ({
             contributor: { name: contribution.plugin.name, scope: contribution.plugin.scope, sourceMarketplace: contribution.plugin.sourceMarketplace },
             node: contribution.node,
+            manifestName: contribution.manifestName,
             adaptLeaf: (leaf, commandPath) => {
                 const transport = contribution.transport;
+                const manifestCommandPath = [contribution.manifestName, ...commandPath.slice(1)];
                 if (transport.kind === 'exec') {
                     const executable = transport.executable;
                     if (executable === undefined)
                         throw new Error(`exec plugin "${contribution.plugin.name}" has an executable leaf without transport.executable`);
                     return {
                         outputKind: 'object',
-                        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable, commandPath: [...commandPath], output: leaf.output }, input),
+                        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable, commandPath: manifestCommandPath, output: leaf.output }, input),
                     };
                 }
                 const httpLeaf = leaf;
@@ -24,7 +26,7 @@ export function adaptPluginContributions(contributions) {
                         registration: { name: contribution.plugin.name, endpoint: transport.endpoint, ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}) },
                         ...(contribution.manifest?.baseUrl !== undefined ? { baseUrl: contribution.manifest.baseUrl } : {}),
                         ...(contribution.manifest?.timeouts !== undefined ? { timeouts: contribution.manifest.timeouts } : {}),
-                        params: httpLeaf.params, rest: httpLeaf.rest, output: httpLeaf.output, commandPath: [...commandPath],
+                        params: httpLeaf.params, rest: httpLeaf.rest, output: httpLeaf.output, commandPath: manifestCommandPath,
                     }, input, context),
                 };
             },

package/dist/core/command-plugins/discovery.d.ts

@@ -14,6 +14,7 @@ export interface ValidatedContribution {
     transport: PluginTransport;
     node: DeclBranchGeneric<DeclLeafGeneric>;
     manifest: ValidatedCommandManifest;
+    manifestName: string;
 }
 export interface PluginCommandValidation {
     plugin: InstalledPlugin;

package/dist/core/command-plugins/discovery.js

@@ -130,7 +130,7 @@ export function validatePluginCommands(plugin, reservedNames = new Set(), coreCo
         : transport;
     if (resolvedTransport === undefined)
         return { plugin, manifestPath, transport, contributions: [], issues };
-    return { plugin, manifestPath, transport: resolvedTransport, manifest: validation.manifest, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest })), issues };
+    return { plugin, manifestPath, transport: resolvedTransport, manifest: validation.manifest, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest, manifestName: node.name })), issues };
 }
 export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
     return effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin));

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;
@@ -140,9 +138,9 @@ export function defineRoot(opts) {
 /** Validate and return child names for an unknown-path error. */
 function childNames(node) {
     if (node.kind === 'root')
-        return node.subtrees.map((s) => s.name);
+        return node.subtrees.filter((s) => s.tier !== 'hidden').map((s) => s.name);
     if (node.kind === 'branch')
-        return node.children.map((c) => c.name);
+        return node.children.filter((c) => c.tier !== 'hidden').map((c) => c.name);
     return [];
 }
 /** Walk argv tokens to the deepest matched node.
@@ -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/fault-classifier.js

@@ -42,6 +42,10 @@ function classifyProviderText(message) {
         return 'context-overflow';
     if (/websocket.*(?:closed.*\b(?:1002|1003|1007|1008|1009|1010)\b|protocol error|policy violation|unsupported data|invalid (?:frame|payload)|message too big|mandatory extension)/i.test(m))
         return 'protocol';
+    // proper-lockfile contention on a credential file: another process holds the
+    // mutex right now, so the same request wins once it releases.
+    if (/lock file is already being held/i.test(m))
+        return 'overloaded';
     if (/overloaded|\b5\d\d\b|internal server error|api.?error|capacity|server.{0,3}busy|temporarily unavailable/i.test(m))
         return 'overloaded';
     if (/connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout|\bterminated\b|other side closed|premature close|websocket\s+(?:was\s+)?closed|websocket stream closed before response\.completed|websocket\s+error|websocket.*interrupt/i.test(m))
@@ -55,6 +59,10 @@ function classifyErrno(raw) {
     if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOENT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/i.test(code)) {
         return 'connection';
     }
+    // A held filesystem mutex, not a broken link: back off on time rather than
+    // behind the online probe a connection fault waits on.
+    if (/^ELOCKED$/i.test(code))
+        return 'overloaded';
     return null;
 }
 function classifyHttp(raw) {

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;