@north-light/crouter 0.3.176 → 0.3.177

package/dist/core/canvas/pid.d.ts

@@ -8,8 +8,7 @@ export declare function isPidAlive(pid: number | null | undefined): boolean;
  *  `composeIdentity` fingerprints are compared (this module's own
  *  `recordedPidLiveness`, `captureTeardownSnapshot`'s reuse check, and
  *  `killProcessTreePids`'s reuse check) — centralized so no call site can
- *  drift from this rule (review Major #1, Round 2 of the pid-reuse-liveness
- *  fix).
+ *  drift from this rule.
  *
  *  Two hazards this closes, both in the false-DEAD direction (the dangerous
  *  one — a false DEAD lets `reviveNode`'s double-launch guard relaunch a
@@ -94,7 +93,7 @@ export declare function recordedPidLiveness(pid: number | null | undefined, expe
  *  swallowing ESRCH (already gone). Used by cron cancellation, timeout, and
  *  stale-lease recovery. Lives beside isPidAlive: canvas/ is
  *  the lowest shared layer every process-liveness/-teardown primitive sits at.
- *  Guards `pid` before signaling (review nit, crouter#98): never hit pid 0
+ *  Guards `pid` before signaling: never hit pid 0
  *  (which means "my own group") or a negative/non-integer value. */
 export declare function killProcessGroup(pid: number, signal?: NodeJS.Signals): void;
 /** The kernel `boot_id` (`/proc/sys/kernel/random/boot_id`) is stable for the
@@ -155,8 +154,8 @@ export interface PsLivenessSnapshot {
 }
 export declare function captureLivenessSnapshot(): PsLivenessSnapshot | null;
 /** Every transitive descendant of `rootPid`, discovered by walking `ps`'s
- *  pid/ppid table (BFS) — NOT process-GROUP membership. This is the fix for
- *  crouton-labs/crouter#98: the pi SDK's bash tool spawns its shell child with
+ *  pid/ppid table (BFS) — NOT process-GROUP membership. The pi SDK's bash tool
+ *  spawns its shell child with
  *  `detached: true` (verified in `@earendil-works/pi-agent-core`'s
  *  `harness/env/nodejs.js`), which calls `setsid()` and puts that child in a
  *  brand-new process GROUP of its own — so `kill(-rootPid)` never reaches it.
@@ -173,7 +172,7 @@ export declare function descendantPids(rootPid: number): number[];
  *  batched `ps -p <list>` call. `lstart` is a standard format keyword on BOTH
  *  BSD ps (macOS) and procps-ng (Linux), so this needs no `/proc` parsing or
  *  other Linux-only machinery. Used to guard against PID REUSE during the
- *  multi-second teardown escalation ladder (crouter#98 review finding 3): a
+ *  multi-second teardown escalation ladder: a
  *  captured pid can exit and the OS can recycle it for an unrelated process
  *  before the SIGKILL rung fires, and a bare `kill(pid, 0)` / `kill(pid, sig)`
  *  cannot tell the difference.
@@ -182,9 +181,9 @@ export declare function descendantPids(rootPid: number): number[];
  *  could not be spawned, or was killed by the timeout): a probe failure means
  *  we have NO information, which is a fundamentally different outcome from a
  *  probe that SUCCEEDED and simply found no row for a given pid (that pid is
- *  genuinely gone). Collapsing these two into the same empty map was the
- *  final-review bug (crouter#98 signal-safety finding): `killProcessTreePids`
- *  cannot tell "pid confirmed gone" from "we don't know" without this
+ *  genuinely gone). Collapsing these two into the same empty map is unsafe:
+ *  `killProcessTreePids` cannot tell "pid confirmed gone" from "we don't know"
+ *  without this
  *  distinction, and misreading a failed probe as positive proof of
  *  absence/reuse either signals a reused stranger or — worse — silently skips
  *  reaping a real live orphan. A successful call may still return a map with
@@ -210,7 +209,7 @@ export declare function capturePidIdentities(pids: readonly number[]): Map<numbe
  *  signal. */
 export declare function capturePidCommand(pid: number): string | null;
 /** The full pre-signal snapshot `teardown()` needs, taken ONCE, from ONE `ps`
- *  table (crouter#98 final review, Fix 1): the process TREE rooted at `rootPid`
+ *  table: the process TREE rooted at `rootPid`
  *  (itself + every transitive descendant) alongside each member's identity
  *  fingerprint — PLUS, load-bearing, a launch-time-identity REUSE check on
  *  `rootPid` itself before the tree is even walked.
@@ -259,21 +258,20 @@ export declare function captureTeardownSnapshot(rootPid: number, expectedIdentit
  *  caller before sending any signal — see the doc on `isProcessTreeAlive` for
  *  why re-deriving via `ps` after signaling starts is unsafe). Signals EACH
  *  pid's OWN process group (a detached SDK-spawned descendant is its own
- *  group leader — the pi bash tool's shell child, crouton-labs/crouter#98)
+ *  group leader — the pi bash tool's shell child)
  *  PLUS a plain `kill(pid)` on each (belt-and-suspenders for a pid that is
  *  NOT its own group leader). Every signal is best-effort — `killProcessGroup`
  *  swallows ESRCH and the plain `kill` here does too — so firing this against
  *  an already-fully-dead snapshot is a harmless no-op.
  *
- *  `identities`, when supplied (crouter#98 review finding 3), is a
+ *  `identities`, when supplied, is a
  *  `capturePidIdentities` snapshot taken alongside the pid list at the SAME
  *  moment — `null` if that INITIAL capture's `ps` probe itself failed (see
  *  `capturePidIdentities`'s doc). Before signaling EITHER the group or the
  *  plain kill for a pid, this re-derives CURRENT identities in one fresh
  *  batched call and compares — but ONLY skips on POSITIVE proof of reuse; any
  *  failure or absence of evidence falls through to the normal signal path
- *  (fail-open, matching this module's pre-guard behavior — final review,
- *  crouter#98 signal-safety finding):
+ *  (fail-open, matching this module's unguarded behavior):
  *
  *    - baseline identity present AND the current probe SUCCEEDED AND the
  *      current identity for this pid is present AND DIFFERENT — the OS has

package/dist/core/canvas/pid.js

@@ -4,9 +4,8 @@
 // LOWEST shared layer — so canvas/, runtime/, AND daemon/ can all import it
 // "down" without a reverse-layer violation (runtime/ sits above canvas/, daemon/
 // above runtime/). It is a pure process-existence utility, NOT data-model access,
-// so it is exempt from the "only canvas.ts touches the db" rule. Collapses the
-// four near-identical copies that used to live in canvas.ts, revive.ts,
-// placement.ts, and crtrd.ts into one (Phase 3 review reuse MINOR-1).
+// so it is exempt from the "only canvas.ts touches the db" rule. canvas.ts,
+// revive.ts, placement.ts, and crtrd.ts all probe liveness through it.
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { readKernelBootId } from './boot-id.js';
@@ -62,8 +61,7 @@ const BOOT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12
  *  purely-numeric suffix counts as ticks (the shape `procStartTicks` and
  *  `composeIdentity` guarantee); a malformed or empty suffix (`A#`, `A#bad`,
  *  `A#1#2`) is treated as ABSENT ticks, so the base compare then applies — a
- *  garbage suffix must never be trusted as a fine discriminator (review
- *  Minor). */
+ *  garbage suffix must never be trusted as a fine discriminator. */
 function splitIdentity(identity) {
     const i = identity.indexOf('#');
     if (i === -1)
@@ -75,8 +73,7 @@ function splitIdentity(identity) {
  *  `composeIdentity` fingerprints are compared (this module's own
  *  `recordedPidLiveness`, `captureTeardownSnapshot`'s reuse check, and
  *  `killProcessTreePids`'s reuse check) — centralized so no call site can
- *  drift from this rule (review Major #1, Round 2 of the pid-reuse-liveness
- *  fix).
+ *  drift from this rule.
  *
  *  Two hazards this closes, both in the false-DEAD direction (the dangerous
  *  one — a false DEAD lets `reviveNode`'s double-launch guard relaunch a
@@ -208,7 +205,7 @@ function logPidLivenessDecision(pid, isPidAliveResult, expectedIdentity, probeOu
  *  swallowing ESRCH (already gone). Used by cron cancellation, timeout, and
  *  stale-lease recovery. Lives beside isPidAlive: canvas/ is
  *  the lowest shared layer every process-liveness/-teardown primitive sits at.
- *  Guards `pid` before signaling (review nit, crouter#98): never hit pid 0
+ *  Guards `pid` before signaling: never hit pid 0
  *  (which means "my own group") or a negative/non-integer value. */
 export function killProcessGroup(pid, signal = 'SIGTERM') {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -220,8 +217,8 @@ export function killProcessGroup(pid, signal = 'SIGTERM') {
         /* already gone */
     }
 }
-/** Linux-only higher-resolution discriminator layered onto `lstart` (crouter#98
- *  review finding, minor): `ps lstart` is only second-granular, so a PID reused
+/** Linux-only higher-resolution discriminator layered onto `lstart`:
+ *  `ps lstart` is only second-granular, so a PID reused
  *  within the same wall-clock second compares equal and slips past the reuse
  *  guard. `/proc/<pid>/stat`'s `starttime` field is the kernel's own jiffies-
  *  since-boot counter for that process — effectively unique per pid even for
@@ -395,8 +392,8 @@ function descendantPidsFrom(rootPid, childrenOf) {
     return out;
 }
 /** Every transitive descendant of `rootPid`, discovered by walking `ps`'s
- *  pid/ppid table (BFS) — NOT process-GROUP membership. This is the fix for
- *  crouton-labs/crouter#98: the pi SDK's bash tool spawns its shell child with
+ *  pid/ppid table (BFS) — NOT process-GROUP membership. The pi SDK's bash tool
+ *  spawns its shell child with
  *  `detached: true` (verified in `@earendil-works/pi-agent-core`'s
  *  `harness/env/nodejs.js`), which calls `setsid()` and puts that child in a
  *  brand-new process GROUP of its own — so `kill(-rootPid)` never reaches it.
@@ -420,7 +417,7 @@ export function descendantPids(rootPid) {
  *  batched `ps -p <list>` call. `lstart` is a standard format keyword on BOTH
  *  BSD ps (macOS) and procps-ng (Linux), so this needs no `/proc` parsing or
  *  other Linux-only machinery. Used to guard against PID REUSE during the
- *  multi-second teardown escalation ladder (crouter#98 review finding 3): a
+ *  multi-second teardown escalation ladder: a
  *  captured pid can exit and the OS can recycle it for an unrelated process
  *  before the SIGKILL rung fires, and a bare `kill(pid, 0)` / `kill(pid, sig)`
  *  cannot tell the difference.
@@ -429,9 +426,9 @@ export function descendantPids(rootPid) {
  *  could not be spawned, or was killed by the timeout): a probe failure means
  *  we have NO information, which is a fundamentally different outcome from a
  *  probe that SUCCEEDED and simply found no row for a given pid (that pid is
- *  genuinely gone). Collapsing these two into the same empty map was the
- *  final-review bug (crouter#98 signal-safety finding): `killProcessTreePids`
- *  cannot tell "pid confirmed gone" from "we don't know" without this
+ *  genuinely gone). Collapsing these two into the same empty map is unsafe:
+ *  `killProcessTreePids` cannot tell "pid confirmed gone" from "we don't know"
+ *  without this
  *  distinction, and misreading a failed probe as positive proof of
  *  absence/reuse either signals a reused stranger or — worse — silently skips
  *  reaping a real live orphan. A successful call may still return a map with
@@ -529,21 +526,20 @@ export function captureTeardownSnapshot(rootPid, expectedIdentity) {
  *  caller before sending any signal — see the doc on `isProcessTreeAlive` for
  *  why re-deriving via `ps` after signaling starts is unsafe). Signals EACH
  *  pid's OWN process group (a detached SDK-spawned descendant is its own
- *  group leader — the pi bash tool's shell child, crouton-labs/crouter#98)
+ *  group leader — the pi bash tool's shell child)
  *  PLUS a plain `kill(pid)` on each (belt-and-suspenders for a pid that is
  *  NOT its own group leader). Every signal is best-effort — `killProcessGroup`
  *  swallows ESRCH and the plain `kill` here does too — so firing this against
  *  an already-fully-dead snapshot is a harmless no-op.
  *
- *  `identities`, when supplied (crouter#98 review finding 3), is a
+ *  `identities`, when supplied, is a
  *  `capturePidIdentities` snapshot taken alongside the pid list at the SAME
  *  moment — `null` if that INITIAL capture's `ps` probe itself failed (see
  *  `capturePidIdentities`'s doc). Before signaling EITHER the group or the
  *  plain kill for a pid, this re-derives CURRENT identities in one fresh
  *  batched call and compares — but ONLY skips on POSITIVE proof of reuse; any
  *  failure or absence of evidence falls through to the normal signal path
- *  (fail-open, matching this module's pre-guard behavior — final review,
- *  crouter#98 signal-safety finding):
+ *  (fail-open, matching this module's unguarded behavior):
  *
  *    - baseline identity present AND the current probe SUCCEEDED AND the
  *      current identity for this pid is present AND DIFFERENT — the OS has

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

@@ -21,8 +21,8 @@ export function createRemoteExec(previewEndpoint, relayToken, timeoutMs = DEFAUL
     // A malformed stored token (control chars / non-Latin1 bytes) would throw
     // from the Headers constructor with the invalid value IN the thrown
     // message — validate up front so that never happens, and fail with a
-    // GENERIC message instead (Phase 3 review Minor 1: no token bytes may ever
-    // reach returned stderr). HTTP header values are ISO-8859-1; reject
+    // GENERIC message instead: no token bytes may ever reach returned stderr.
+    // HTTP header values are ISO-8859-1; reject
     // anything outside `/^[\x20-\x7e]+$/` (printable ASCII, no CR/LF/control).
     const tokenValid = /^[\x20-\x7e]+$/.test(relayToken);
     return async function exec(bin, args) {

package/dist/core/canvas/status-glyph.d.ts

@@ -28,7 +28,7 @@ export declare function resolveNodeVisual(status: NodeStatus, opts: {
  *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
  *  `node lifecycle revive --now`, src/commands/node-lifecycle-revive.ts) can gate on the SAME
  *  predicate the dashboard advertises instead of drifting out of sync with it
- *  (issue #115 — `--now` used to reject exactly the nodes shown as "needs you"). */
+ *  and rejecting exactly the nodes shown as "needs you". */
 export declare function faultNeedsYou(fault: Pick<Fault, 'retry'>): boolean;
 /** Human-friendly active-fault disposition text. `auto` faults show the current
  *  retry attempt plus the next scheduled retry; client-owned redials say

package/dist/core/canvas/status-glyph.js

@@ -69,7 +69,7 @@ function retryCountdown(iso, now) {
  *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
  *  `node lifecycle revive --now`, src/commands/node-lifecycle-revive.ts) can gate on the SAME
  *  predicate the dashboard advertises instead of drifting out of sync with it
- *  (issue #115 — `--now` used to reject exactly the nodes shown as "needs you"). */
+ *  and rejecting exactly the nodes shown as "needs you". */
 export function faultNeedsYou(fault) {
     return fault.retry.disposition !== 'auto';
 }

package/dist/core/canvas/types.d.ts

@@ -191,7 +191,7 @@ export interface NodeRuntime {
     /** Stable process-identity fingerprint (`pid.ts`'s `composeIdentity`) captured
      *  at the SAME moment `pi_pid` is recorded (`recordPid`) — the LAUNCH-time
      *  baseline `headlessBrokerHost.teardown()` compares `pi_pid`'s CURRENT
-     *  identity against before signaling anything (crouter#98 review finding 1):
+     *  identity against before signaling anything:
      *  a mismatch proves the OS has already recycled `pi_pid` for an unrelated
      *  process since this node launched it, and teardown must refuse to signal
      *  that stranger. `null` for a node booted before this field existed, or if

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

@@ -8,14 +8,12 @@
 // This is pure validation: no fetch, no registration lookup, no file I/O beyond
 // 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 isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 function typeName(v) {
     if (v === null)
         return 'null';
@@ -38,7 +36,7 @@ export function validateCommandManifest(raw, options) {
         issues.push({ code, message, received, expected, next, ...(path ? { path } : {}) });
     };
     // Top-level structure check
-    if (!isObject(raw)) {
+    if (!isRecord(raw)) {
         issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts }' : '{ schemaVersion, mounts }', 'Provide a valid JSON manifest object.');
         return { issues };
     }
@@ -126,7 +124,7 @@ export function validateCommandManifest(raw, options) {
 // Timeouts validation
 // ---------------------------------------------------------------------------
 function validateTimeouts(raw, issue) {
-    if (!isObject(raw)) {
+    if (!isRecord(raw)) {
         issue('command_manifest_invalid', 'timeouts must be an object', typeName(raw), '{ connectMs?, requestMs?, streamIdleMs? }', 'Fix timeouts.', 'timeouts');
         return null;
     }
@@ -150,7 +148,7 @@ function validateTimeouts(raw, issue) {
 }
 function validateMount(raw, index, transport, issue) {
     const path = `mounts[${index}]`;
-    if (!isObject(raw)) {
+    if (!isRecord(raw)) {
         issue('command_manifest_invalid', 'mount must be an object', typeName(raw), '{ parent, node }', 'Fix the mount.', path);
         return null;
     }

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

@@ -1,4 +1,5 @@
 // Unified command-manifest schema. Transport is the sole leaf-dialect discriminator.
+import { isRecord } from '../../shared/predicates.js';
 // ---------------------------------------------------------------------------
 // Validation helpers
 // ---------------------------------------------------------------------------
@@ -41,9 +42,6 @@ const OUTPUT_KEYS = new Set(['name', 'type', 'required', 'constraint']);
  *  may name, so a typo'd lowercase key fails at authoring time rather than
  *  silently never resolving. */
 const ENV_VAR_NAME = /^[A-Z][A-Z0-9_]*$/;
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 function typeName(v) {
     if (v === null)
         return 'null';
@@ -60,7 +58,7 @@ function checkKeys(raw, allowed, path, issue) {
     return true;
 }
 function validateRootEntry(raw, path, issue) {
-    if (!isObject(raw)) {
+    if (!isRecord(raw)) {
         issue('command_node_invalid', `rootEntry must be an object`, typeName(raw), 'a { concept, description, whenToUse } object', 'Fix rootEntry.', path);
         return null;
     }
@@ -91,7 +89,7 @@ function validateParams(raw, path, issue) {
     for (let i = 0; i < raw.length; i++) {
         const p = raw[i];
         const pp = `${path}[${i}]`;
-        if (!isObject(p)) {
+        if (!isRecord(p)) {
             issue('command_node_invalid', `param must be an object`, typeName(p), 'a param object', 'Fix the param.', pp);
             return null;
         }
@@ -289,7 +287,7 @@ function validateOutput(raw, path, issue) {
     for (let i = 0; i < raw.length; i++) {
         const f = raw[i];
         const fp = `${path}[${i}]`;
-        if (!isObject(f)) {
+        if (!isRecord(f)) {
             issue('command_node_invalid', `output field must be an object`, typeName(f), 'a { name, type, required, constraint } object', 'Fix the output field.', fp);
             return null;
         }
@@ -337,7 +335,7 @@ function checkCommon(raw, path, issue) {
 }
 export function validateCommandNode(raw, path, topLevel, transport, issue) {
     const pathString = path.join('.');
-    if (!isObject(raw)) {
+    if (!isRecord(raw)) {
         issue('command_node_invalid', 'node must be an object', typeName(raw), 'a branch or leaf node object', 'Fix the node.', pathString);
         return null;
     }
@@ -424,7 +422,7 @@ function validateBranch(raw, path, topLevel, transport, issue) {
 }
 /** `passthrough: { bin, installHint }` — both required non-empty strings. */
 function validatePassthrough(raw, path, issue) {
-    if (!isObject(raw)) {
+    if (!isRecord(raw)) {
         issue('command_node_invalid', 'passthrough must be an object', typeName(raw), 'an object { bin, installHint }', 'Fix or remove passthrough.', path);
         return null;
     }
@@ -482,7 +480,7 @@ const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const REST_PARAM_PLACEMENT_SET = new Set(['path', 'query', 'body', 'header']);
 function validateRestMapping(raw, basePath, params, issue) {
     const path = `${basePath}.rest`;
-    if (!isObject(raw)) {
+    if (!isRecord(raw)) {
         issue('command_rest_invalid', `rest must be an object`, typeName(raw), '{ method, path, streaming?, params }', 'Provide a valid rest mapping.', path);
         return null;
     }
@@ -523,7 +521,7 @@ function validateRestMapping(raw, basePath, params, issue) {
     }
     // Validate params mapping (required object)
     const restParams = raw['params'];
-    if (!isObject(restParams)) {
+    if (!isRecord(restParams)) {
         issue('command_rest_invalid', `params must be an object`, typeName(restParams), 'a mapping of param names to placement specs', 'Provide params.', `${path}.params`);
         return null;
     }
@@ -542,7 +540,7 @@ function validateRestMapping(raw, basePath, params, issue) {
             return null;
         }
         declaredNames.add(paramName);
-        if (!isObject(mapping)) {
+        if (!isRecord(mapping)) {
             issue('command_rest_invalid', `param mapping must be an object`, typeName(mapping), '{ in, as? }', 'Fix the param mapping.', `${path}.params.${paramName}`);
             return null;
         }
@@ -644,7 +642,7 @@ function validateRestMapping(raw, basePath, params, issue) {
             return null;
         }
         const rawBody = raw['body'];
-        if (!isObject(rawBody)) {
+        if (!isRecord(rawBody)) {
             issue('command_rest_invalid', `body must be an object`, typeName(rawBody), 'a map of constant literal body fields (string | number | boolean)', 'Fix body.', `${path}.body`);
             return null;
         }

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

@@ -11,6 +11,7 @@ import { spawnSync } from 'node:child_process';
 import { CrtrError } from '../../errors.js';
 import { diag } from '../../io.js';
 import { ExitCode } from '../../../types.js';
+import { isRecord } from '../../../shared/predicates.js';
 const MAX_STDOUT = 10 * 1024 * 1024; // 10 MiB hard cap on plugin stdout.
 const RESERVED_CODES = new Set(['internal', 'unknown_path', 'command_collision', 'plugin_protocol_error']);
 // Strict snake_case: no leading/trailing underscore, no consecutive underscores.
@@ -77,7 +78,7 @@ export function executeExternalLeaf(spec, input) {
     catch {
         throw protocolError(spec, `stdout was not a single JSON envelope`, 'exactly one JSON envelope on stdout');
     }
-    if (!isObject(envelope)) {
+    if (!isRecord(envelope)) {
         throw protocolError(spec, `stdout was not a JSON object`, 'a { protocolVersion: 1, ok: boolean, ... } envelope');
     }
     if (envelope['protocolVersion'] !== 1) {
@@ -96,7 +97,7 @@ export function executeExternalLeaf(spec, input) {
     }
     if (ok) {
         const result = envelope['result'];
-        if (!isObject(result)) {
+        if (!isRecord(result)) {
             throw protocolError(spec, `success envelope has no result object`, 'result: an object matching the declared output');
         }
         validateResult(spec, result);
@@ -104,7 +105,7 @@ export function executeExternalLeaf(spec, input) {
     }
     // Recoverable command failure → structured CrtrError with the plugin's code.
     const error = envelope['error'];
-    if (!isObject(error) || typeof error['code'] !== 'string' || typeof error['message'] !== 'string') {
+    if (!isRecord(error) || typeof error['code'] !== 'string' || typeof error['message'] !== 'string') {
         throw protocolError(spec, `error envelope is missing a { code, message }`, 'error: { code, message, ... }');
     }
     const code = error['code'];
@@ -146,7 +147,7 @@ function typeMatches(type, v) {
     if (t === 'array' || t.endsWith('[]'))
         return Array.isArray(v);
     if (t === 'object')
-        return isObject(v);
+        return isRecord(v);
     return true;
 }
 function protocolError(spec, received, expected) {
@@ -155,6 +156,3 @@ function protocolError(spec, received, expected) {
 function label(spec) {
     return `plugin "${spec.plugin.name}" command \`${spec.commandPath.join(' ')}\``;
 }
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}

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

@@ -19,6 +19,7 @@ import { validateDeclaredResult } from './exec-invoke.js';
 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
 // ---------------------------------------------------------------------------
@@ -320,7 +321,7 @@ function mapUnary2xx(spec, body) {
     catch {
         throw protocolError(spec, 'response body was not valid JSON', 'a JSON object matching the declared output');
     }
-    if (!isObject(parsed)) {
+    if (!isRecord(parsed)) {
         throw protocolError(spec, `response body was not a JSON object (got ${typeName(parsed)})`, 'a JSON object matching the declared output');
     }
     const issue = validateDeclaredResult(spec.output, parsed);
@@ -482,9 +483,9 @@ function throwNon2xx(spec, status, body) {
     catch {
         parsed = undefined;
     }
-    if (isObject(parsed)) {
+    if (isRecord(parsed)) {
         const err = parsed['error'];
-        if (isObject(err) && typeof err['code'] === 'string' && typeof err['message'] === 'string') {
+        if (isRecord(err) && typeof err['code'] === 'string' && typeof err['message'] === 'string') {
             const code = err['code'];
             const message = err['message'];
             const field = typeof err['field'] === 'string' ? err['field'] : undefined;
@@ -543,9 +544,6 @@ function readAll(res) {
         res.on('error', () => resolve(Buffer.concat(chunks).toString('utf8'))); // best-effort
     });
 }
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 function typeName(v) {
     if (v === null)
         return 'null';

package/dist/core/config.d.ts

@@ -81,7 +81,7 @@ export declare function readMergedLaunchConfig(targetCwd?: string, targetProfile
  *  `developer`, or sub-kind, e.g. `plan/reviewers/security`), across
  *  project > user > builtin precedence. Returns `undefined` for a kind no
  *  scope registers — existence is deliberately NOT validated here (kind
- *  existence/launch-menu enumeration is a Phase 3 caller concern); this only
+ *  existence/launch-menu enumeration is a caller concern); this only
  *  resolves the config for a kind the caller already knows about. */
 export declare function resolveKindConfig(kind: string): KindConfig | undefined;
 /** The sub-kinds available to spawn FROM a given top-level kind — every

package/dist/core/config.js

@@ -560,7 +560,7 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
  *  `developer`, or sub-kind, e.g. `plan/reviewers/security`), across
  *  project > user > builtin precedence. Returns `undefined` for a kind no
  *  scope registers — existence is deliberately NOT validated here (kind
- *  existence/launch-menu enumeration is a Phase 3 caller concern); this only
+ *  existence/launch-menu enumeration is a caller concern); this only
  *  resolves the config for a kind the caller already knows about. */
 export function resolveKindConfig(kind) {
     return readMergedLaunchConfig().kinds[kind];
@@ -622,7 +622,7 @@ function sparseModelLaddersToPersist(rawLadders, baseline, mutated) {
  *  sparse override stays sparse), and only keys the mutation actually changed
  *  are written. `modelLadders` gets sub-field-granular sparse handling via
  *  `sparseModelLaddersToPersist`. Result: a fresh bootstrap or any unrelated
- *  `sys config set` no longer freezes a full concrete `modelLadders` to disk,
+ *  `sys config set` never freezes a full concrete `modelLadders` to disk,
  *  and a direct ladder-rung set still persists only the touched rung -- all
  *  through one lock-protected atomic update path. */
 function mutateConfigAtPath(path, mutate) {

package/dist/core/events/read.js

@@ -4,6 +4,7 @@ import { crtrHome, isSafeNodeId, nodesRoot } from '../canvas/paths.js';
 import { validateOperationId } from './operation-id.js';
 import { MAX_EVENT_RECORD_BYTES } from './serialize.js';
 import { errorClassCodes, } from './types.js';
+import { isRecord } from '../../shared/predicates.js';
 const SNAPSHOT_ITEMS = 200;
 const MAX_CANONICAL_SOURCE_BYTES = 6 * 1024 * 1024;
 const MAX_RAW_SOURCE_BYTES = 256 * 1024;
@@ -41,9 +42,6 @@ const RETRY_DISPOSITIONS = new Set(['auto', 'manual', 'fatal']);
 const ERROR_CLASSES = new Set(errorClassCodes);
 const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
 const GENERATION_RANK = { 2: 0, 1: 1, 0: 2 };
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function hasOwn(value, key) {
     return Object.prototype.hasOwnProperty.call(value, key);
 }

package/dist/core/fault-classifier.js

@@ -1,4 +1,5 @@
 import { hasManagedProviderCoolingDiagnostic } from './runtime/managed-provider-cooling.js';
+import { isRecord } from '../shared/predicates.js';
 const errorClassByFaultKind = {
     'rate-limit': 'rate_limit',
     overloaded: 'overloaded',
@@ -16,9 +17,6 @@ export function errorClassFromFault(fault) {
         retry_disposition: fault.retry.disposition,
     };
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
 function text(value) {
     return typeof value === 'string' ? value : '';
 }

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

@@ -1,9 +1,16 @@
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
+export declare function realpathOrSelf(p: string): string;
+/** Expand a leading `~` against `homeDir` (pi's own convention). Other forms
+ *  — absolute, relative, `~user` — pass through as pi leaves them. */
+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 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. */
+export declare function readJsonOrNull<T = unknown>(path: string): T | null;
 export declare function readTextIfExists(path: string): string | null;
 export declare function readText(path: string): string;
 export declare function writeText(path: string, content: string): void;

package/dist/core/fs-utils.js

@@ -1,6 +1,24 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
-import { platform } from 'node:os';
+import { homedir, platform } from 'node:os';
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
+export function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Expand a leading `~` against `homeDir` (pi's own convention). Other forms
+ *  — absolute, relative, `~user` — pass through as pi leaves them. */
+export function expandTilde(p, homeDir = homedir()) {
+    if (p === '~')
+        return homeDir;
+    if (p.startsWith('~/') || (platform() === 'win32' && p.startsWith('~\\')))
+        return join(homeDir, p.slice(2));
+    return p;
+}
 export function ensureDir(dir) {
     mkdirSync(dir, { recursive: true });
 }
@@ -44,6 +62,15 @@ export function readJsonIfExists(path) {
         return null;
     return readJson(path);
 }
+/** Missing or corrupt reads as absent, so a crash artifact never throws. */
+export function readJsonOrNull(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
 export function readTextIfExists(path) {
     if (!existsSync(path))
         return null;

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

@@ -3,12 +3,11 @@
  * generated slash-command templates to `~/.claude/commands` and
  * `~/.pi/agent/prompts`.
  *
- * crouter no longer exports Agent Skills / SKILL.md bundles. The export pass
- * still prunes old marker-bearing `crtr-skills` bundles so hosts stop surfacing
- * pi/Claude native skills after the memory cutover. Markerless files are
- * user-owned and never removed.
+ * crouter exports no Agent Skills / SKILL.md bundles. The export pass prunes
+ * marker-bearing `crtr-skills` bundles so hosts stop surfacing pi/Claude native
+ * skills. Markerless files are user-owned and never removed.
  *
- * Triggered per-run by cli.ts (argv-gated, exactly as the old writers were) so
+ * Triggered per-run by cli.ts (argv-gated) so
  * first-run provisioning is preserved. Best-effort: a provisioning fault must
  * never break an unrelated `crtr` command (the deliberate, pre-existing
  * behavior of the deleted writers).

package/dist/core/host-exports/export.js

@@ -3,12 +3,11 @@
  * generated slash-command templates to `~/.claude/commands` and
  * `~/.pi/agent/prompts`.
  *
- * crouter no longer exports Agent Skills / SKILL.md bundles. The export pass
- * still prunes old marker-bearing `crtr-skills` bundles so hosts stop surfacing
- * pi/Claude native skills after the memory cutover. Markerless files are
- * user-owned and never removed.
+ * crouter exports no Agent Skills / SKILL.md bundles. The export pass prunes
+ * marker-bearing `crtr-skills` bundles so hosts stop surfacing pi/Claude native
+ * skills. Markerless files are user-owned and never removed.
  *
- * Triggered per-run by cli.ts (argv-gated, exactly as the old writers were) so
+ * Triggered per-run by cli.ts (argv-gated) so
  * first-run provisioning is preserved. Best-effort: a provisioning fault must
  * never break an unrelated `crtr` command (the deliberate, pre-existing
  * behavior of the deleted writers).