@north-light/crouter 0.3.175 → 0.3.177

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

@@ -17,8 +17,9 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { validateDeclaredResult } from './exec-invoke.js';
 import { CrtrError } from '../../errors.js';
-import { diag, writeStdout } from '../../io.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);
@@ -420,6 +421,7 @@ async function requestStreaming(spec, plan) {
                 if (line.trim() === '')
                     continue; // drop blank records
                 framesEmitted = true;
+                recordPreviewJsonLine(line);
                 const ok = await writeStdout(line + '\n');
                 if (!ok) {
                     // Consumer closed the pipe (EPIPE) — stop cleanly, nothing to report.
@@ -434,6 +436,7 @@ async function requestStreaming(spec, plan) {
         // backend sent no trailing delimiter, so none is added).
         if (partial.trim() !== '') {
             framesEmitted = true;
+            recordPreviewJsonLine(partial);
             await writeStdout(partial);
         }
         return; // clean EOF → SUCCESS
@@ -444,7 +447,13 @@ async function requestStreaming(spec, plan) {
         if (framesEmitted) {
             // After a frame has been emitted: one concise stderr diagnostic + NETWORK
             // exit, and DO NOT throw (that would append an <error> to stdout).
-            diag(`crtr: ${label(spec)}: stream interrupted (${detail})`);
+            const message = `${label(spec)}: stream interrupted (${detail})`;
+            diag(`crtr: ${message}`);
+            recordPreviewError({
+                error: 'stream_interrupted',
+                message,
+                next: 'Retry the command to begin a fresh stream.',
+            });
             process.exitCode = ExitCode.NETWORK;
             return;
         }
@@ -474,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;
@@ -535,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/command.js

@@ -5,7 +5,7 @@
 // A plain array walk + a small flag parser is ~120 lines and has no surprising
 // edge cases.
 import { renderRoot, renderBranch, renderLeafArgv } from './help.js';
-import { readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
+import { beginPreview, publishPreviewResult, readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
 import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
 import { operationIdContext } from './events/operation-id.js';
@@ -614,6 +614,7 @@ export async function runCli(root, argv) {
         // below: `node` is now a reassignable `let` (the §5.1 retry re-walks it),
         // which TS re-widens to the node union across an `await`.
         const leaf = node;
+        beginPreview(path.join(' '));
         const params = leaf.help.params !== undefined ? leaf.help.params : [];
         let providedParams = new Set();
         let contextFilePaths = new Map();
@@ -628,6 +629,7 @@ export async function runCli(root, argv) {
         });
         const context = { providedParams, contextFilePaths };
         const result = await operationIdContext.fresh(() => leaf.run(input, context));
+        publishPreviewResult(result);
         if (result !== undefined && result !== null) {
             if (isJsonOutput()) {
                 emit(result);

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

@@ -1,4 +1,3 @@
-import { mkdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
@@ -7,6 +6,7 @@ import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
 import { profileRoot } from './profiles/manifest.js';
+import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 import { normalizeWorkingGerunds } from '../shared/working-activity.js';
 function configPathFor(root) {
@@ -54,34 +54,11 @@ export function readState(scope) {
         activeCanvas: existing.activeCanvas ?? null,
     };
 }
-const CONFIG_LOCK_TIMEOUT_MS = 5000;
-const CONFIG_LOCK_POLL_MS = 25;
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
 function withConfigPathLock(path, run) {
     ensureDir(dirname(path));
-    const lockPath = `${path}.lock`;
-    const deadline = Date.now() + CONFIG_LOCK_TIMEOUT_MS;
-    for (;;) {
-        try {
-            mkdirSync(lockPath);
-            break;
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            if (Date.now() > deadline)
-                throw new Error(`timed out waiting for config lock: ${path}`);
-            sleepSync(CONFIG_LOCK_POLL_MS);
-        }
-    }
-    try {
-        return run(path);
-    }
-    finally {
-        rmSync(lockPath, { recursive: true, force: true });
-    }
+    return withExclusiveDirectoryLock(`${path}.lock`, () => run(path), {
+        timeoutError: () => new Error(`timed out waiting for config lock: ${path}`),
+    });
 }
 function withConfigLock(scope, run) {
     const root = requireScopeRoot(scope);
@@ -583,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];
@@ -645,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/exclusive-lock.d.ts

@@ -0,0 +1,14 @@
+export interface ExclusiveLockOptions {
+    /** Grace before a lock that names no owner at all is cleared. */
+    staleMs?: number;
+    timeoutMs?: number;
+    /** The error thrown when the wait runs out, so callers keep their own remediation. */
+    timeoutError?: () => Error;
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: ExclusiveLockOptions): T;

package/dist/core/exclusive-lock.js

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readdirSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+const MARKER_PREFIX = 'owner.';
+const POLL_MS = 10;
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+function pause(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+function markerPath(path, token) { return `${path}/${MARKER_PREFIX}${token}`; }
+function observedMarkerToken(path) {
+    try {
+        return readdirSync(path).find((entry) => entry.startsWith(MARKER_PREFIX))?.slice(MARKER_PREFIX.length) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The token opens with the owner's pid, so liveness reads off the name. */
+function ownerIsAlive(token) {
+    const pid = Number(token.split('.', 1)[0]);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function isEmptyDirectory(path) {
+    try {
+        return readdirSync(path).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function ageMs(path) {
+    try {
+        return Date.now() - statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+// Reclamation is bound to the exact instance it observed: it unlinks ONLY that
+// token's marker, then removes the now-empty directory with an empty-guarded
+// rmdir. A successor holds a different random token — a different marker name —
+// so a lagging reclaimer that saw the old dead lock can never strip a live
+// successor: its unlink targets a name that no longer exists.
+function reclaimIfOwnerGone(path, staleMs) {
+    const token = observedMarkerToken(path);
+    if (token !== null) {
+        if (ownerIsAlive(token))
+            return;
+        try {
+            unlinkSync(markerPath(path, token));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    else {
+        // Nothing names an owner. A live holder always has its marker, so this is a
+        // crash between mkdir and the marker write, or a lock left in some older
+        // shape; age is the only evidence, and an empty-guarded rmdir still cannot
+        // take a successor that has since claimed the name.
+        if (ageMs(path) <= staleMs)
+            return;
+        if (!isEmptyDirectory(path)) {
+            rmSync(path, { recursive: true, force: true });
+            return;
+        }
+    }
+    try {
+        rmdirSync(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTEMPTY' && code !== 'EEXIST')
+            throw error;
+    }
+}
+function tryAcquire(path, staleMs) {
+    const token = `${process.pid}.${randomUUID()}`;
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        writeFileSync(markerPath(path, token), '', { flag: 'wx', mode: 0o600 });
+        return { path, token };
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        reclaimIfOwnerGone(path, staleMs);
+        return null;
+    }
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export function withExclusiveDirectoryLock(path, operation, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let lock = tryAcquire(path, staleMs);
+    while (lock === null) {
+        if (Date.now() >= deadline) {
+            throw options.timeoutError?.() ?? new Error(`timed out waiting for the exclusive lock: ${path}`);
+        }
+        pause(POLL_MS);
+        lock = tryAcquire(path, staleMs);
+    }
+    try {
+        return operation();
+    }
+    finally {
+        if (existsSync(markerPath(lock.path, lock.token)))
+            rmSync(lock.path, { recursive: true, force: true });
+    }
+}

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).

package/dist/core/human/claim.js

@@ -1,7 +1,9 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { claimPath, deckPath, readJson, responsePath, reviewPath, withExclusiveDirectoryLock } from './convention.js';
+import { claimPath, deckPath, responsePath, reviewPath } from './convention.js';
+import { readJsonOrNull } from '../fs-utils.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 const REMOTE_STALE_MS = 30_000;
 function parseClaim(raw) {
     if (typeof raw !== 'object' || raw === null)
@@ -11,7 +13,7 @@ function parseClaim(raw) {
         return null;
     return { token: claim.token, host: claim.host, pid: claim.pid, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt, ...(typeof claim.tmuxClient === 'string' ? { tmuxClient: claim.tmuxClient } : {}) };
 }
-export function readTicketClaim(dir) { return parseClaim(readJson(claimPath(dir))); }
+export function readTicketClaim(dir) { return parseClaim(readJsonOrNull(claimPath(dir))); }
 function isLiveLocalPid(pid) { try {
     process.kill(pid, 0);
     return true;

package/dist/core/human/convention.d.ts

@@ -14,17 +14,6 @@ export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 /** Publish one immutable JSON record without replacing an existing winner. */
 export declare function publishJsonExclusive(path: string, value: unknown): boolean;
-export declare function readJson<T>(path: string): T | null;
-/** Runs a short filesystem transition under a token-checked, crash-reclaimable directory lock. */
-export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: {
-    staleMs?: number;
-    timeoutMs?: number;
-}): T;
-/** Async counterpart heartbeats while its operation runs, so a valid long handler is never stolen. */
-export declare function withExclusiveDirectoryLockAsync<T>(path: string, operation: () => Promise<T>, options?: {
-    staleMs?: number;
-    timeoutMs?: number;
-}): Promise<T>;
 export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string, deck?: Deck): string;
 export declare function writeProgress(dir: string, responses: InteractionResponse[]): void;
 export declare function clearProgress(dir: string): void;