@crouter/api 0.3.387 → 0.3.389

package/dist/api/__tests__/integration/client.test.js

@@ -8,6 +8,7 @@ import { join } from 'node:path';
 import { CrtrClient, safeColdStartDiagnostic } from '../../client.js';
 import { localClient } from '../../node-transport.js';
 import { ApiError } from '../../errors.js';
+import { DaemonExitedBeforeReadyError, daemonAutostartStartupFailure, ensureDaemon, resetDaemonAutostart, } from '../../../daemon/manage.js';
 function startDelayedHealthzServer(socketPath, delayMs) {
     const server = createServer((_req, res) => {
         res.writeHead(200, { 'content-type': 'application/json' });
@@ -177,3 +178,99 @@ test('safeColdStartDiagnostic treats a THROWING hook as absent, not a propagated
         throw new Error('custom hook blew up');
     }), undefined);
 });
+test('a daemon this client started that fails terminally ends the cold-start wait at once with its reason', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-startup-failed-'));
+    const socketPath = join(dir, 'crtrd.sock'); // nothing ever listens
+    let failure;
+    const client = localClient({
+        socketPath,
+        autostart: true,
+        onColdSocket: async () => { setTimeout(() => { failure = 'daemon 7 exited before becoming ready (with exit code 1)\n[crtrd] claim lost: own_identity_indeterminate'; }, 150); },
+        coldStartPollWindowMs: 60_000,
+        coldStartFailure: () => failure,
+        coldStartDiagnostic: () => 'crtrd.log (tail): must not be appended to a reason that already explains itself',
+    });
+    const started = Date.now();
+    try {
+        await assert.rejects(() => client.healthz(), (error) => error instanceof ApiError
+            && error.code === 'daemon_unavailable'
+            && error.message.includes('crtrd failed to start')
+            && error.message.includes('own_identity_indeterminate')
+            && !error.message.includes('crtrd.log (tail)'));
+        assert.ok(Date.now() - started < 5_000, 'must not poll out the 60s window');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a first spawn that failed does not end the wait of a later healthy spawn: failure → backoff → new in-flight attempt', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-stale-failure-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const savedEnv = process.env['CRTR_NO_DAEMON_AUTOSTART'];
+    delete process.env['CRTR_NO_DAEMON_AUTOSTART'];
+    resetDaemonAutostart();
+    let now = 1_000_000;
+    let spawns = 0;
+    let server;
+    let timer;
+    const deps = {
+        isDaemonRunning: () => false,
+        now: () => now,
+        spawnDaemon: () => {
+            spawns += 1;
+            if (spawns === 1)
+                return Promise.reject(new DaemonExitedBeforeReadyError('daemon 1 exited before becoming ready (with exit code 1)', 'FIRST SPAWN EXITED'));
+            // Attempt 2: stays in flight, and its daemon starts listening a moment later.
+            return new Promise((resolve) => {
+                server = createServer((_q, r) => { r.writeHead(200, { 'content-type': 'application/json' }); r.end('{"ok":true}'); });
+                timer = setTimeout(() => { server?.listen(socketPath); resolve({}); }, 400);
+            });
+        },
+    };
+    try {
+        ensureDaemon(deps); // attempt 1 — fails terminally
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.match(daemonAutostartStartupFailure() ?? '', /FIRST SPAWN EXITED/);
+        now += 120_000; // backoff elapsed
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => { ensureDaemon(deps); }, // attempt 2 starts as this client goes cold
+            coldStartPollWindowMs: 5_000,
+            coldStartFailure: daemonAutostartStartupFailure,
+        });
+        assert.ok((await client.healthz()) !== undefined);
+        assert.equal(spawns, 2);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        server?.close();
+        resetDaemonAutostart();
+        if (savedEnv === undefined)
+            delete process.env['CRTR_NO_DAEMON_AUTOSTART'];
+        else
+            process.env['CRTR_NO_DAEMON_AUTOSTART'] = savedEnv;
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('with no reported startup failure the cold-start wait keeps its full window', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-startup-slow-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 400);
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => { },
+            coldStartPollWindowMs: 5_000,
+            coldStartFailure: () => undefined, // a migration still making progress reports nothing
+        });
+        assert.ok((await client.healthz()) !== undefined);
+    }
+    finally {
+        cancel();
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/api/client.d.ts

@@ -58,6 +58,10 @@ export interface CrtrClientOptions {
      *  return synchronously and cheaply — it runs on the failure path, not the
      *  happy path. A thrown/undefined result is treated as "no diagnostic". */
     coldStartDiagnostic?: () => string | undefined;
+    /** Polled during the cold-start wait: a string means the daemon this client
+     *  started has terminally failed (it exited before becoming ready), so the
+     *  wait ends immediately with that text instead of polling out the window. */
+    coldStartFailure?: () => string | undefined;
     /** Strict wall-clock window (ms) for local API availability after a cold
      * socket or interrupted response. Each probe is capped to the remaining
      * budget. Defaults to `HEALTHZ_POLL_WINDOW_MS`. */
@@ -94,7 +98,10 @@ export declare class CrtrClient {
     private readonly localSocketTransport;
     private readonly onColdSocket?;
     private readonly coldStartDiagnostic?;
+    private readonly coldStartFailure?;
     private readonly coldStartPollWindowMs;
+    /** Set when the last availability wait ended on a daemon startup failure, whose message already says why. */
+    private startupFailureReported;
     /** Guards against invoking the daemon-start hook more than once per client. */
     private coldStartAttempted;
     constructor(opts: CrtrClientOptions);

package/dist/api/client.js

@@ -48,7 +48,10 @@ export class CrtrClient {
     localSocketTransport;
     onColdSocket;
     coldStartDiagnostic;
+    coldStartFailure;
     coldStartPollWindowMs;
+    /** Set when the last availability wait ended on a daemon startup failure, whose message already says why. */
+    startupFailureReported = false;
     /** Guards against invoking the daemon-start hook more than once per client. */
     coldStartAttempted = false;
     constructor(opts) {
@@ -65,6 +68,8 @@ export class CrtrClient {
             this.onColdSocket = opts.onColdSocket;
         if (opts.coldStartDiagnostic !== undefined)
             this.coldStartDiagnostic = opts.coldStartDiagnostic;
+        if (opts.coldStartFailure !== undefined)
+            this.coldStartFailure = opts.coldStartFailure;
         this.coldStartPollWindowMs = opts.coldStartPollWindowMs ?? HEALTHZ_POLL_WINDOW_MS;
     }
     // Health / status
@@ -1074,27 +1079,41 @@ export class CrtrClient {
         const remainingBudgetMs = deadlineAt === undefined ? undefined : deadlineAt - Date.now();
         if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
             throw budgetExhausted();
-        await waitForDaemonAvailability({
-            windowMs: Math.min(this.coldStartPollWindowMs, remainingBudgetMs ?? this.coldStartPollWindowMs),
-            initialError,
-            probe: async (timeoutMs) => {
-                const response = await this.transport('GET', routes.healthz(), undefined, { timeout: timeoutMs });
-                if (response.status >= 200 && response.status < 300) {
-                    await drainResponseBody(response);
-                    return;
-                }
-                const text = await response.text();
-                try {
-                    const health = JSON.parse(text);
-                    if (typeof health.startup_blocked === 'string')
+        let startupFailure;
+        try {
+            await waitForDaemonAvailability({
+                windowMs: Math.min(this.coldStartPollWindowMs, remainingBudgetMs ?? this.coldStartPollWindowMs),
+                initialError,
+                retry: (error) => error !== startupFailure,
+                probe: async (timeoutMs) => {
+                    const failure = this.coldStartFailure?.();
+                    if (failure !== undefined) {
+                        startupFailure = new ApiError(503, 'daemon_unavailable', `crtrd failed to start: ${failure}`);
+                        throw startupFailure;
+                    }
+                    const response = await this.transport('GET', routes.healthz(), undefined, { timeout: timeoutMs });
+                    if (response.status >= 200 && response.status < 300) {
+                        await drainResponseBody(response);
                         return;
-                }
-                catch {
-                    // The normal unavailable error below carries the response body.
-                }
-                throw new ApiError(response.status, 'daemon_health_unavailable', `crtrd health check returned HTTP ${response.status}: ${text.slice(0, 500)}`);
-            },
-        });
+                    }
+                    const text = await response.text();
+                    try {
+                        const health = JSON.parse(text);
+                        if (typeof health.startup_blocked === 'string')
+                            return;
+                    }
+                    catch {
+                        // The normal unavailable error below carries the response body.
+                    }
+                    throw new ApiError(response.status, 'daemon_health_unavailable', `crtrd health check returned HTTP ${response.status}: ${text.slice(0, 500)}`);
+                },
+            });
+        }
+        catch (error) {
+            if (error === startupFailure)
+                this.startupFailureReported = true;
+            throw error;
+        }
     }
     /** Optionally start the daemon, then observe availability before retrying the
      * request. Waiting is independent from permission to spawn: externally
@@ -1109,7 +1128,7 @@ export class CrtrClient {
             await this.awaitAvailability(initialError, deadlineAt);
         }
         catch (error) {
-            if (startedHere) {
+            if (startedHere && !this.startupFailureReported) {
                 const diagnostic = safeColdStartDiagnostic(this.coldStartDiagnostic);
                 if (diagnostic !== undefined) {
                     const transportError = toTransportApiError(error);

package/dist/api/dto/config.d.ts

@@ -14,8 +14,18 @@ export interface NodeConfigPatch {
     lifecycle?: LifecycleDTO;
     /** Rename the node (and, when it has a live viewer window, that window). */
     name?: string;
-    /** Repair-only replacement launch directory; exclusive of every other field. */
+    /** Replacement launch directory; exclusive of every other field except `keep_session` and `restart`.
+     *  Without `keep_session` it is repair-only (dormant node, recorded cwd gone, Pi session cleared). */
     cwd?: string;
+    /** With `cwd`: the new path is the SAME directory as the recorded one (a symlink alias, or an
+     *  alias that is already gone — the caller asserts it). Relocates without clearing the Pi session
+     *  and rewrites the transcript header's cwd; allowed for live nodes. */
+    keep_session?: boolean;
+    /** Reassign the node to this profile (id or exact name). Exclusive of every other field except `restart`. */
+    profile?: string;
+    /** With `profile` or `cwd`+`keep_session` on a live node: SIGTERM the broker after the change so the
+     *  daemon resumes it (same transcript) with the new profile/cwd. Ignored for a node with no live broker. */
+    restart?: boolean;
     /** Per-run allow-list. A patch may only remove scopes; it applies to a live broker on its next revive. */
     scopes?: string[];
     /** The node's default listening configuration: event level ("1".."10") → delivery

package/dist/core/asset-root.d.ts

@@ -0,0 +1,7 @@
+/** The source or runtime directory containing every shipped asset tree.
+ *
+ * `import.meta.url` names the module when loaded directly, but names the
+ * attach viewer bundle when esbuild inlines this module. Walking to the
+ * directory marked by the built-in assets preserves one resolution rule for
+ * both loading contexts. */
+export declare function assetRoot(): string;

package/dist/core/asset-root.js

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The source or runtime directory containing every shipped asset tree.
+ *
+ * `import.meta.url` names the module when loaded directly, but names the
+ * attach viewer bundle when esbuild inlines this module. Walking to the
+ * directory marked by the built-in assets preserves one resolution rule for
+ * both loading contexts. */
+export function assetRoot() {
+    for (let current = dirname(fileURLToPath(import.meta.url));; current = dirname(current)) {
+        if (existsSync(join(current, 'builtin-memory')) && existsSync(join(current, 'builtin-pi-packages')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error(`cannot locate crouter assets from ${import.meta.url}`);
+    }
+}

package/dist/core/canvas/boot-id.d.ts

@@ -0,0 +1,6 @@
+/** The Linux kernel's per-boot identity at `/proc/sys/kernel/random/boot_id` —
+ *  a fresh random UUID minted on every kernel boot, or null when unreadable
+ *  (non-Linux dev, or the file is absent). Exact when present: a microVM
+ *  recreate boots a new kernel (new id); a plain daemon restart within the same
+ *  boot leaves it identical. */
+export declare function readKernelBootId(): string | null;

package/dist/core/canvas/boot-id.js

@@ -0,0 +1,26 @@
+// boot-id.ts — the PURE kernel-boot-identity reader, split out of boot.ts so the
+// low-level liveness probe (`canvas/pid.ts`) can import it WITHOUT dragging in
+// boot.ts's `openDb` persistence machinery. boot.ts's boot-change reconciler
+// persists the last-seen identity in canvas.db (hence its top-level `openDb`
+// import); `readKernelBootId` itself is a plain `/proc` read with zero db reach,
+// and `pid.ts` needs only that. Keeping it here means `pid.ts` (and everything
+// that imports it down — including the CLI's daemon-liveness front door) stays
+// canvas.db-free.
+//
+// PURITY: Node built-ins only. Never `core/canvas/db.js` or any db-touching
+// module.
+import { readFileSync } from 'node:fs';
+/** The Linux kernel's per-boot identity at `/proc/sys/kernel/random/boot_id` —
+ *  a fresh random UUID minted on every kernel boot, or null when unreadable
+ *  (non-Linux dev, or the file is absent). Exact when present: a microVM
+ *  recreate boots a new kernel (new id); a plain daemon restart within the same
+ *  boot leaves it identical. */
+export function readKernelBootId() {
+    try {
+        const id = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+        return id.length > 0 ? id : null;
+    }
+    catch {
+        return null; // non-Linux, or unreadable — fall back to the wall-clock epoch
+    }
+}

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

@@ -0,0 +1,72 @@
+/** Runtime-owned records; never a bind source for an app sandbox. */
+export declare function crtrHome(): string;
+/** The canvas home requires durable storage with SQLite WAL locking support. */
+export declare function canvasDbPath(): string;
+export declare function onDiskMigrationLockPath(): string;
+export declare function onDiskMigrationMarkerPath(): string;
+/** The viewer socket belongs to the per-node run folder, not the durable records. */
+export declare function viewSocketPath(nodeId: string): string;
+export declare function nodesRoot(): string;
+export declare function reviewsRoot(): string;
+export declare function reviewDir(reviewId: string): string;
+export declare function reviewResultPath(reviewId: string): string;
+export declare function ensureReviewDir(reviewId: string): void;
+/** Absolute path to crtrd's API listener unix socket, a sibling of
+ *  `canvasDbPath()` under the canvas home (`~/.crouter/canvas/crtrd.sock` unless
+ *  `CRTR_HOME` is set). Pure path builder — no db reach — so both the daemon
+ *  (which binds it) and a CLI-side resolver can import it freely. `src/api`'s
+ *  `defaultSocketPath()` (in `api/node-transport.ts`) deliberately re-derives
+ *  this same path from a Node-builtin `join(crtrHome-equivalent, 'crtrd.sock')`
+ *  rather than importing here, to keep the exported `/api` contract
+ *  dependency-light; the two must agree. */
+export declare function apiSocketPath(): string;
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export declare function sessionListCachePath(): string;
+/** Whether a persisted node ID is safe as a single filesystem path segment. */
+export declare function isSafeNodeId(nodeId: string): boolean;
+export declare function nodeRecordDir(nodeId: string): string;
+/** Existing callers use nodeDir for the daemon's records only. */
+export declare const nodeDir: typeof nodeRecordDir;
+/** Pure path builder. A broker may resolve its own app from its launch identity;
+ *  every other caller must supply the app from the daemon's node row. */
+export declare function nodeAgentDir(nodeId: string, grantee?: string): string;
+/** The home folder of one node of an isolated run, `/apps/<A>/nodes/<id>/home`, used
+ *  in place of the app's shared `home` so two isolated runs share no writable folder. */
+export declare function isolatedNodeHome(nodeId: string, grantee: string): string;
+/** The HOME a node's processes get: its own home in an isolated run, else the app's. */
+export declare function nodeHome(nodeId: string, grantee: string, isolated: boolean): string;
+export declare function nodeRunDir(nodeId: string): string;
+export declare function contextDir(nodeId: string, grantee?: string): string;
+/** Replace the literal env-var tokens `$CRTR_CONTEXT_DIR` / `$CRTR_NODE_ID` in
+ *  agent-facing doc text with the node's real values, so a doc surfaced INTO a
+ *  node hands it a concrete absolute path instead of a shell-only string. The
+ *  env vars only expand in bash; an agent that pastes `$CRTR_CONTEXT_DIR/x.md`
+ *  into the (non-expanding) Write tool creates a literal `$CRTR_CONTEXT_DIR/`
+ *  dir under the project repo. The resolved absolute path works in both bash and
+ *  Write, so this substitution is strictly safer. Callers must only apply it
+ *  when they have a concrete node to render for (never on generic, node-less
+ *  output). Pure string work — no I/O. */
+export declare function interpolateNodePaths(text: string, nodeId: string, grantee?: string): string;
+export declare function jobDir(nodeId: string): string;
+export declare function nodeRunJobDir(nodeId: string): string;
+/** Overflow store for inbox entries whose inline body exceeds the digest's
+ *  bounded preview (a direct `node message send` or a close/cancel doctrine
+ *  wake) — the full body spills here, mirroring how a
+ *  push's body always lives in a file, never inline; the inbox entry then
+ *  carries `ref` at this path, same as a push pointer. */
+export declare function messagesDir(nodeId: string): string;
+export declare function nodeMetaPath(nodeId: string): string;
+export declare function inboxPath(nodeId: string): string;
+/** Rendered ambient context lives outside the user-authored context directory. */
+export declare function situationalContextPath(nodeId: string): string;
+export declare function passivePath(nodeId: string): string;
+export declare function transcriptPath(nodeId: string): string;
+export declare function sessionPtrPath(nodeId: string): string;
+/** Create the full directory skeleton for a node. Idempotent. The agent and
+ *  run folders are app-writable, so their subfolders are made beneath them. */
+export declare function ensureNodeDirs(nodeId: string, grantee: string): void;
+/** Ensure the canvas home exists. Idempotent. */
+export declare function ensureHome(): void;

package/dist/core/canvas/paths.js

@@ -0,0 +1,163 @@
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { appSpace, runtimeRoot, socketDir } from '../layout.js';
+import { envGrantee, envNodeId } from '../../shared/env.js';
+import { withDirBeneath } from '../spaces/open-beneath.js';
+/** Runtime-owned records; never a bind source for an app sandbox. */
+export function crtrHome() { return runtimeRoot(); }
+/** The canvas home requires durable storage with SQLite WAL locking support. */
+export function canvasDbPath() {
+    return join(crtrHome(), 'canvas.db');
+}
+export function onDiskMigrationLockPath() {
+    return join(crtrHome(), 'on-disk-migration.lock');
+}
+export function onDiskMigrationMarkerPath() {
+    return join(crtrHome(), 'on-disk-migrations.json');
+}
+/** The viewer socket belongs to the per-node run folder, not the durable records. */
+export function viewSocketPath(nodeId) {
+    return join(nodeRunDir(nodeId), 'view.sock');
+}
+export function nodesRoot() {
+    return join(crtrHome(), 'nodes');
+}
+export function reviewsRoot() {
+    return join(crtrHome(), 'reviews');
+}
+export function reviewDir(reviewId) {
+    assertSafeNodeId(reviewId);
+    return join(reviewsRoot(), reviewId);
+}
+export function reviewResultPath(reviewId) {
+    return join(reviewDir(reviewId), 'result.json');
+}
+export function ensureReviewDir(reviewId) {
+    mkdirSync(reviewDir(reviewId), { recursive: true, mode: 0o700 });
+}
+/** Absolute path to crtrd's API listener unix socket, a sibling of
+ *  `canvasDbPath()` under the canvas home (`~/.crouter/canvas/crtrd.sock` unless
+ *  `CRTR_HOME` is set). Pure path builder — no db reach — so both the daemon
+ *  (which binds it) and a CLI-side resolver can import it freely. `src/api`'s
+ *  `defaultSocketPath()` (in `api/node-transport.ts`) deliberately re-derives
+ *  this same path from a Node-builtin `join(crtrHome-equivalent, 'crtrd.sock')`
+ *  rather than importing here, to keep the exported `/api` contract
+ *  dependency-light; the two must agree. */
+export function apiSocketPath() {
+    return join(socketDir(), 'api.sock');
+}
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export function sessionListCachePath() {
+    return join(crtrHome(), 'session-list-cache.json');
+}
+const MAX_NODE_ID_BYTES = 128;
+/** Whether a persisted node ID is safe as a single filesystem path segment. */
+export function isSafeNodeId(nodeId) {
+    return typeof nodeId === 'string'
+        && nodeId !== ''
+        && nodeId !== '.'
+        && nodeId !== '..'
+        && !/[\\/\0]/u.test(nodeId)
+        && Buffer.byteLength(nodeId, 'utf8') <= MAX_NODE_ID_BYTES;
+}
+function assertSafeNodeId(nodeId) {
+    if (!isSafeNodeId(nodeId)) {
+        throw new TypeError('node_id must be a non-empty path segment of at most 128 UTF-8 bytes');
+    }
+}
+export function nodeRecordDir(nodeId) {
+    assertSafeNodeId(nodeId);
+    return join(nodesRoot(), nodeId);
+}
+/** Existing callers use nodeDir for the daemon's records only. */
+export const nodeDir = nodeRecordDir;
+/** Pure path builder. A broker may resolve its own app from its launch identity;
+ *  every other caller must supply the app from the daemon's node row. */
+export function nodeAgentDir(nodeId, grantee) {
+    assertSafeNodeId(nodeId);
+    const app = grantee ?? (envNodeId() === nodeId ? envGrantee() : undefined);
+    if (!app)
+        throw new Error(`node ${nodeId} has no app assignment`);
+    return join(appSpace(app).nodes, nodeId);
+}
+/** The home folder of one node of an isolated run, `/apps/<A>/nodes/<id>/home`, used
+ *  in place of the app's shared `home` so two isolated runs share no writable folder. */
+export function isolatedNodeHome(nodeId, grantee) {
+    return join(nodeAgentDir(nodeId, grantee), 'home');
+}
+/** The HOME a node's processes get: its own home in an isolated run, else the app's. */
+export function nodeHome(nodeId, grantee, isolated) {
+    return isolated ? isolatedNodeHome(nodeId, grantee) : appSpace(grantee).home;
+}
+export function nodeRunDir(nodeId) {
+    assertSafeNodeId(nodeId);
+    return process.platform === 'linux' ? join(socketDir(), 'nodes', nodeId) : join(nodeRecordDir(nodeId), 'run');
+}
+export function contextDir(nodeId, grantee) {
+    return join(nodeAgentDir(nodeId, grantee), 'context');
+}
+/** Replace the literal env-var tokens `$CRTR_CONTEXT_DIR` / `$CRTR_NODE_ID` in
+ *  agent-facing doc text with the node's real values, so a doc surfaced INTO a
+ *  node hands it a concrete absolute path instead of a shell-only string. The
+ *  env vars only expand in bash; an agent that pastes `$CRTR_CONTEXT_DIR/x.md`
+ *  into the (non-expanding) Write tool creates a literal `$CRTR_CONTEXT_DIR/`
+ *  dir under the project repo. The resolved absolute path works in both bash and
+ *  Write, so this substitution is strictly safer. Callers must only apply it
+ *  when they have a concrete node to render for (never on generic, node-less
+ *  output). Pure string work — no I/O. */
+export function interpolateNodePaths(text, nodeId, grantee) {
+    return text
+        .replaceAll('$CRTR_CONTEXT_DIR', contextDir(nodeId, grantee))
+        .replaceAll('$CRTR_NODE_ID', nodeId);
+}
+export function jobDir(nodeId) {
+    return join(nodeRecordDir(nodeId), 'job');
+}
+export function nodeRunJobDir(nodeId) {
+    return join(nodeRunDir(nodeId), 'job');
+}
+/** Overflow store for inbox entries whose inline body exceeds the digest's
+ *  bounded preview (a direct `node message send` or a close/cancel doctrine
+ *  wake) — the full body spills here, mirroring how a
+ *  push's body always lives in a file, never inline; the inbox entry then
+ *  carries `ref` at this path, same as a push pointer. */
+export function messagesDir(nodeId) {
+    return join(nodeDir(nodeId), 'messages');
+}
+export function nodeMetaPath(nodeId) {
+    return join(nodeDir(nodeId), 'meta.json');
+}
+export function inboxPath(nodeId) {
+    return join(nodeDir(nodeId), 'inbox.jsonl');
+}
+/** Rendered ambient context lives outside the user-authored context directory. */
+export function situationalContextPath(nodeId) {
+    return join(nodeRunDir(nodeId), 'situational-context.md');
+}
+export function passivePath(nodeId) {
+    return join(nodeDir(nodeId), 'passive.jsonl');
+}
+export function transcriptPath(nodeId) {
+    return join(nodeDir(nodeId), 'transcript.jsonl');
+}
+export function sessionPtrPath(nodeId) {
+    return join(nodeDir(nodeId), 'session.ptr');
+}
+/** Create the full directory skeleton for a node. Idempotent. The agent and
+ *  run folders are app-writable, so their subfolders are made beneath them. */
+export function ensureNodeDirs(nodeId, grantee) {
+    const agent = nodeAgentDir(nodeId, grantee);
+    mkdirSync(nodeRecordDir(nodeId), { recursive: true });
+    mkdirSync(jobDir(nodeId), { recursive: true });
+    for (const d of ['context', 'reports', 'attachments', 'worktree']) {
+        withDirBeneath(appSpace(grantee).nodes, join(agent, d), () => undefined, true);
+    }
+    withDirBeneath(nodeRunDir(nodeId), nodeRunJobDir(nodeId), () => undefined, true);
+}
+/** Ensure the canvas home exists. Idempotent. */
+export function ensureHome() {
+    mkdirSync(nodesRoot(), { recursive: true });
+}