@north-light/api 0.0.0-stage → 0.3.414

package/dist/api/routes.js

@@ -0,0 +1,197 @@
+// API version + route path builders (spec §4.1). Every route is prefixed `/v1`
+// EXCEPT `GET /healthz`, which stays unversioned so any-version probes (incl.
+// the P2 provisioning ladder) can reach it. A version mismatch surfaces as a
+// 404 — there is no negotiation, no Accept-header versioning, no compat shim.
+//
+// These builders carry NO logic — they are pure string constructors. Every
+// interpolated param (node id, target, cron id, profile name, provider) MUST
+// be a pre-validated single path segment (e.g. `isSafeNodeId`-gated ids;
+// upstream-constrained names) — nothing here parses, encodes, or branches, so a
+// param carrying `/` or `..` would corrupt the path.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** The single API version constant; every versioned path prepends it. */
+export const API_VERSION = 'v1';
+const V = `/${API_VERSION}`;
+/** Route path builders. Keys mirror the spec §6 route table. */
+export const routes = {
+    // Health / status
+    healthz: () => '/healthz',
+    status: () => `${V}/status`,
+    due: () => `${V}/due`,
+    daemonRestart: () => `${V}/daemon/restart`,
+    daemonMigrate: () => `${V}/daemon/migrate`,
+    daemonAdmit: () => `${V}/daemon/admit`,
+    // Nodes — collection + item
+    nodes: () => `${V}/nodes`,
+    reviveAll: () => `${V}/nodes/revive-all`,
+    node: (id) => `${V}/nodes/${id}`,
+    nodeMemoryReads: (id) => `${V}/nodes/${id}/memory-reads`,
+    nodeOutcome: (id) => `${V}/nodes/${id}/outcome`,
+    nodeOutcomeDelivery: (id) => `${V}/nodes/${id}/outcome-delivery`,
+    nodeEvents: (id) => `${V}/nodes/${id}/events`,
+    // Node reads
+    nodeSnapshot: (id) => `${V}/nodes/${id}/snapshot`,
+    nodeSubject: (id) => `${V}/nodes/${id}/subject`,
+    nodeSession: (id) => `${V}/nodes/${id}/session`,
+    nodeChatInventory: (id) => `${V}/nodes/${id}/chat-inventory`,
+    prospectiveChatInventory: () => `${V}/prospective-chat-inventory`,
+    nodeTranscript: (id) => `${V}/nodes/${id}/transcript`,
+    nodeContext: (id) => `${V}/nodes/${id}/context`,
+    nodeReports: (id) => `${V}/nodes/${id}/reports`,
+    nodeResult: (id) => `${V}/nodes/${id}/result`,
+    nodeJobs: (id) => `${V}/nodes/${id}/jobs`,
+    nodeJob: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}`,
+    nodeJobBackground: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}/background`,
+    nodeDelivery: (id) => `${V}/nodes/${id}/delivery`,
+    deliveryDryRun: () => `${V}/delivery/dry-run`,
+    deliveryRetry: (id) => `${V}/deliveries/${encodeURIComponent(id)}/retry`,
+    // Node messages / feed
+    nodeMessages: (id) => `${V}/nodes/${id}/messages`,
+    nodeInterrupt: (id) => `${V}/nodes/${id}/interrupt`,
+    // Node lifecycle actions
+    nodeFork: (id) => `${V}/nodes/${id}/fork`,
+    nodeRevive: (id) => `${V}/nodes/${id}/revive`,
+    nodeRelaunchRoot: (id) => `${V}/nodes/${id}/relaunch-root`,
+    nodeBrokerSessionBound: (id) => `${V}/nodes/${id}/broker/session-bound`,
+    nodeBrokerSettle: (id) => `${V}/nodes/${id}/broker/settle`,
+    nodeBrokerParkComplete: (id) => `${V}/nodes/${id}/broker/park-complete`,
+    nodeBrokerParkActivity: (id) => `${V}/nodes/${id}/broker/park-activity`,
+    nodeBrokerTelemetry: (id) => `${V}/nodes/${id}/broker/telemetry`,
+    nodeLog: (id) => `${V}/nodes/${id}/records/log`,
+    nodeTelemetry: (id) => `${V}/nodes/${id}/records/telemetry`,
+    nodeRecap: (id) => `${V}/nodes/${id}/records/recap`,
+    nodeInboxReport: (id) => `${V}/nodes/${id}/records/inbox`,
+    nodePassiveMessage: (id) => `${V}/nodes/${id}/records/passive`,
+    nodePushedFinal: (id) => `${V}/nodes/${id}/records/pushed-final`,
+    nodeMailClaim: (id) => `${V}/nodes/${id}/mail/claim`,
+    nodeMailAcknowledge: (id) => `${V}/nodes/${id}/mail/acknowledge`,
+    nodeBrokerModel: (id) => `${V}/nodes/${id}/broker/model`,
+    nodeBrokerExtensionState: (id) => `${V}/nodes/${id}/broker/extension-state`,
+    nodeBrokerSignals: (id) => `${V}/nodes/${id}/broker/signals`,
+    nodeBrokerGeneratedName: (id) => `${V}/nodes/${id}/broker/generated-name`,
+    nodeBrokerPersonaAck: (id) => `${V}/nodes/${id}/broker/persona-ack`,
+    brokerTurn: (id) => `${V}/broker/${id}/turn`,
+    brokerProviderRetry: (id) => `${V}/broker/${id}/provider-retry`,
+    brokerFault: (id) => `${V}/broker/${id}/fault`,
+    brokerRecovery: (id) => `${V}/broker/${id}/recovery`,
+    nodeFault: (id) => `${V}/nodes/${id}/fault`,
+    nodeClose: (id) => `${V}/nodes/${id}/close`,
+    nodeRecycle: (id) => `${V}/nodes/${id}/recycle`,
+    nodeDemote: (id) => `${V}/nodes/${id}/demote`,
+    nodePromote: (id) => `${V}/nodes/${id}/promote`,
+    nodeYield: (id) => `${V}/nodes/${id}/yield`,
+    nodeWait: (id) => `${V}/nodes/${id}/wait`,
+    nodeConfig: (id) => `${V}/nodes/${id}/config`,
+    kinds: () => `${V}/kinds`,
+    nodeWorktreeClose: (id) => `${V}/nodes/${id}/worktree/close`,
+    nodeWorktreeAbandon: (id) => `${V}/nodes/${id}/worktree/abandon`,
+    quarantinedWorktrees: () => `${V}/worktrees/quarantined`,
+    spaces: () => `${V}/spaces`,
+    limits: () => `${V}/limits`,
+    limitsApp: (app) => `${V}/limits/apps/${encodeURIComponent(app)}`,
+    nodeAttach: (id) => `${V}/nodes/${id}/attach`,
+    // Focuses (viewer registry — the canvas.db `focuses` table)
+    focuses: () => `${V}/focuses`,
+    focusByNode: () => `${V}/focuses/by-node`,
+    focusByPane: () => `${V}/focuses/by-pane`,
+    focus: (focusId) => `${V}/focuses/${focusId}`,
+    // Subscriptions
+    nodeSubscriptions: (id) => `${V}/nodes/${id}/subscriptions`,
+    nodeSubscription: (id, target) => `${V}/nodes/${id}/subscriptions/${target}`,
+    // Crons (the cron-spec scheduler)
+    crons: () => `${V}/crons`,
+    cron: (cronId) => `${V}/crons/${cronId}`,
+    cronPause: (cronId) => `${V}/crons/${cronId}/pause`,
+    cronResume: (cronId) => `${V}/crons/${cronId}/resume`,
+    cronRun: (cronId) => `${V}/crons/${cronId}/run`,
+    cronsPoke: () => `${V}/crons/poke`,
+    // Canvas maintenance / reads
+    canvasAttention: () => `${V}/canvas/attention`,
+    canvasAttentionCounts: () => `${V}/canvas/attention/counts`,
+    canvasHistorySearch: () => `${V}/canvas/history/search`,
+    canvasHistoryGrep: () => `${V}/canvas/history/grep`,
+    canvasHistoryRead: () => `${V}/canvas/history/read`,
+    canvasHistoryStats: () => `${V}/canvas/history/stats`,
+    canvasSnapshot: () => `${V}/canvas/snapshot`,
+    canvasRoster: () => `${V}/canvas/roster`,
+    canvasBrowse: () => `${V}/canvas/browse`,
+    canvasAnalytics: () => `${V}/canvas/analytics`,
+    canvasGraph: () => `${V}/canvas/graph`,
+    canvasPrune: () => `${V}/canvas/prune`,
+    // Daemon-owned document reviews and comments. All interpolated ids are
+    // guarded by `CrtrClient` before they reach these pure builders.
+    humanReviews: () => `${V}/human/reviews`,
+    humanReview: (reviewId) => `${V}/human/reviews/${reviewId}`,
+    humanReviewSubmit: (reviewId) => `${V}/human/reviews/${reviewId}/submit`,
+    humanReviewCancel: (reviewId) => `${V}/human/reviews/${reviewId}/cancel`,
+    humanReviewDocument: (reviewId) => `${V}/human/reviews/${reviewId}/document`,
+    humanReviewComments: (reviewId) => `${V}/human/reviews/${reviewId}/comments`,
+    humanReviewCommentEvents: (reviewId) => `${V}/human/reviews/${reviewId}/comment-events`,
+    humanReviewCommentRanges: (reviewId) => `${V}/human/reviews/${reviewId}/comment-ranges`,
+    humanComment: (commentId) => `${V}/human/comments/${commentId}`,
+    humanCommentEdit: (commentId) => `${V}/human/comments/${commentId}/edit`,
+    humanCommentResolve: (commentId) => `${V}/human/comments/${commentId}/resolve`,
+    humanCommentReopen: (commentId) => `${V}/human/comments/${commentId}/reopen`,
+    humanCommentDelete: (commentId) => `${V}/human/comments/${commentId}/delete`,
+    humanCommentFork: (commentId) => `${V}/human/comments/${commentId}/fork`,
+    // Humanloop inbox (crouter cloud crouter-inbox v1, inbox-contract.md §A)
+    humanInbox: () => `${V}/human/inbox`,
+    humanInboxTicket: (ticketId) => `${V}/human/inbox/${ticketId}`,
+    humanInboxRespond: (ticketId) => `${V}/human/inbox/${ticketId}/respond`,
+    humanInboxProgress: (ticketId) => `${V}/human/inbox/${ticketId}/progress`,
+    humanInboxResponse: (ticketId) => `${V}/human/inbox/${ticketId}/response`,
+    humanInboxCancel: (ticketId) => `${V}/human/inbox/${ticketId}/cancel`,
+    humanInboxFeedbackResolve: (ticketId, commentId) => `${V}/human/inbox/${ticketId}/feedback-comments/${commentId}/resolve`,
+    // Durable programmatic human requests. A request id is separate from the
+    // opaque inbox ticket id used by `/v1/human/inbox`.
+    humanRequests: () => `${V}/human/requests`,
+    humanComponents: () => `${V}/human/components`,
+    humanRequest: (requestId) => `${V}/human/requests/${requestId}`,
+    humanRequestReplace: (requestId) => `${V}/human/requests/${requestId}/replace`,
+    humanRequestRespond: (requestId) => `${V}/human/requests/${requestId}/respond`,
+    humanRequestDismiss: (requestId) => `${V}/human/requests/${requestId}/dismiss`,
+    humanRequestCancel: (requestId) => `${V}/human/requests/${requestId}/cancel`,
+    // Profiles (deletion is daemon-owned because it crosses canvas state)
+    profiles: () => `${V}/profiles`,
+    profile: (name) => `${V}/profiles/${name}`,
+    profilePause: (name) => `${V}/profiles/${name}/pause`,
+    profileResume: (name) => `${V}/profiles/${name}/resume`,
+    profileMetadata: (name) => `${V}/profiles/${name}/metadata`,
+    appEnv: () => `${V}/apps/self/env`,
+    appEnvVar: (variable) => `${V}/apps/self/env/${encodeURIComponent(variable)}`,
+    profileEnv: (name) => `${V}/profiles/${name}/env`,
+    profileEnvVar: (name, variable) => `${V}/profiles/${name}/env/${variable}`,
+    // Model auth
+    modelAuths: () => `${V}/model-auth`,
+    modelAuthReadiness: () => `${V}/model-auth/readiness`,
+    modelAuth: (provider) => `${V}/model-auth/${provider}`,
+    modelAuthFlows: () => `${V}/model-auth/flows`,
+    modelAuthFlow: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}`,
+    modelAuthFlowComplete: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}/complete`,
+    modelAuthFlowCancel: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}/cancel`,
+    // Host file read (browser file-peek panel). The absolute path rides as a
+    // `path` query param, not a path segment — it is not a single safe segment.
+    filePeek: () => `${V}/files/peek`,
+    fileWrite: () => `${V}/files/write`,
+    fileList: () => `${V}/files/list`,
+    bash: () => `${V}/bash`,
+    // Canvas objects and documents. A ref (name or id) may contain `/`, so it is
+    // always one percent-encoded path segment.
+    objects: () => `${V}/objects`,
+    object: (ref) => `${V}/objects/${encodeURIComponent(ref)}`,
+    objectsSearch: () => `${V}/objects/search`,
+    objectWatch: (ref) => `${V}/objects/${encodeURIComponent(ref)}/watch`,
+    customObjects: () => `${V}/custom-objects`,
+    customObject: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}`,
+    customObjectEvents: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/events`,
+    customObjectDeliveries: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/deliveries`,
+    customObjectAck: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/deliveries/ack`,
+    objectEdges: (ref) => `${V}/objects/${encodeURIComponent(ref)}/edges`,
+    docs: () => `${V}/docs`,
+    doc: (ref) => `${V}/docs/${encodeURIComponent(ref)}`,
+    docMove: (ref) => `${V}/docs/${encodeURIComponent(ref)}/move`,
+    docHistory: (ref) => `${V}/docs/${encodeURIComponent(ref)}/history`,
+    docsLint: () => `${V}/docs/lint`,
+    documentsReconcilePackages: () => `${V}/documents/reconcile-packages`,
+};

package/dist/api/runtime-version.d.ts

@@ -0,0 +1,31 @@
+/** Response header carrying the runtime's release version, e.g. `0.3.389`. */
+export declare const RUNTIME_VERSION_HEADER = "Crouter-Runtime-Version";
+/** Compares two `major.minor.patch` versions numerically (a prerelease or build
+ *  suffix is ignored). Negative when `a` is older, zero when equal, positive when
+ *  newer. A version that does not parse sorts below every version that does. */
+export declare function compareReleaseVersions(a: string, b: string): number;
+/** Request header naming the oldest runtime release the caller accepts, e.g. `0.3.396`. The SDK sends its own
+ *  version on every request except `/healthz`. Optional: absent means no check. The router in front of a hosted
+ *  runtime and the runtime itself each refuse a request that names a newer release than the runtime's, before any
+ *  handler runs (so nothing is accepted and no idempotency key is recorded). */
+export declare const MINIMUM_RUNTIME_VERSION_HEADER = "Crouter-Minimum-Runtime-Version";
+/** The refusal a runtime answers instead of handling a request, or `null` when the request may be handled.
+ *  - `required` absent: handled.
+ *  - `required` not `major.minor.patch` (optional `v`, optional suffix): 400 `invalid_request`.
+ *  - `runtimeVersion` older than `required`, or not a release version: 426 `runtime_version_unsupported`
+ *    (details `{sdk_version, runtime_version}`, the SDK's `RuntimeVersionDetails`). */
+export type MinimumRuntimeRefusal = {
+    status: 400;
+    code: 'invalid_request';
+    message: string;
+    param: string;
+} | {
+    status: 426;
+    code: 'runtime_version_unsupported';
+    message: string;
+    details: {
+        sdk_version: string;
+        runtime_version: string | null;
+    };
+};
+export declare function minimumRuntimeRefusal(required: string | undefined, runtimeVersion: string | null): MinimumRuntimeRefusal | null;

package/dist/api/runtime-version.js

@@ -0,0 +1,50 @@
+// The runtime's release version on every response (P2: latest only).
+//
+// The runtime sends its package version (`crouter` `package.json`) in this
+// header on every `/v1` answer of the owner API and the app listener. A client
+// built from the same release set compares it with its own version and refuses
+// an older runtime: there is no capability negotiation, so a client's types are
+// true only for a runtime at or above its own release.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** Response header carrying the runtime's release version, e.g. `0.3.389`. */
+export const RUNTIME_VERSION_HEADER = 'Crouter-Runtime-Version';
+/** Compares two `major.minor.patch` versions numerically (a prerelease or build
+ *  suffix is ignored). Negative when `a` is older, zero when equal, positive when
+ *  newer. A version that does not parse sorts below every version that does. */
+export function compareReleaseVersions(a, b) {
+    const left = parseRelease(a);
+    const right = parseRelease(b);
+    if (left === null || right === null)
+        return left === right ? 0 : left === null ? -1 : 1;
+    for (let i = 0; i < 3; i++)
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    return 0;
+}
+function parseRelease(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
+    return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** Request header naming the oldest runtime release the caller accepts, e.g. `0.3.396`. The SDK sends its own
+ *  version on every request except `/healthz`. Optional: absent means no check. The router in front of a hosted
+ *  runtime and the runtime itself each refuse a request that names a newer release than the runtime's, before any
+ *  handler runs (so nothing is accepted and no idempotency key is recorded). */
+export const MINIMUM_RUNTIME_VERSION_HEADER = 'Crouter-Minimum-Runtime-Version';
+export function minimumRuntimeRefusal(required, runtimeVersion) {
+    if (required === undefined)
+        return null;
+    if (parseRelease(required) === null) {
+        return { status: 400, code: 'invalid_request', param: MINIMUM_RUNTIME_VERSION_HEADER, message: `${MINIMUM_RUNTIME_VERSION_HEADER} must be a release version like 0.3.396.` };
+    }
+    if (runtimeVersion !== null && parseRelease(runtimeVersion) !== null && compareReleaseVersions(runtimeVersion, required) >= 0)
+        return null;
+    const sdkVersion = required.trim();
+    return {
+        status: 426, code: 'runtime_version_unsupported',
+        message: runtimeVersion === null
+            ? `The runtime did not name its version; the caller requires a runtime at ${sdkVersion} or later. Roll the runtime forward.`
+            : `The runtime is ${runtimeVersion}; the caller requires a runtime at ${sdkVersion} or later. Roll the runtime forward.`,
+        details: { sdk_version: sdkVersion, runtime_version: runtimeVersion },
+    };
+}

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 });
+}