@north-light/crouter 0.3.233 → 0.3.235

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

@@ -5,8 +5,15 @@ export declare function realpathOrSelf(p: string): string;
 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 interface AtomicWriteOptions {
+    /** Force this mode regardless of any existing file's mode. Omitted: preserve the existing file's mode, or default a new file to `0o600`. */
+    mode?: number;
+}
+export declare function atomicWriteJson(path: string, data: unknown, opts?: AtomicWriteOptions): void;
+/** Replace one file's contents in a single rename, so a concurrent reader — the
+ *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export declare function atomicWriteText(path: string, content: string | Uint8Array, opts?: AtomicWriteOptions): 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. */

package/dist/core/fs-utils.js

@@ -26,24 +26,16 @@ export function writeJson(path, data) {
     ensureDir(dirname(path));
     writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
 }
-export function atomicWriteJson(path, data) {
-    ensureDir(dirname(path));
-    const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
-    try {
-        writeFileSync(temp, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode });
-        chmodSync(temp, mode);
-        renameSync(temp, path);
-    }
-    finally {
-        if (existsSync(temp))
-            rmSync(temp, { force: true });
-    }
+export function atomicWriteJson(path, data, opts) {
+    atomicWriteText(path, JSON.stringify(data, null, 2) + '\n', opts);
 }
-export function atomicWriteText(path, content) {
+/** Replace one file's contents in a single rename, so a concurrent reader — the
+ *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export function atomicWriteText(path, content, opts) {
     ensureDir(dirname(path));
     const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+    const mode = opts?.mode ?? (existsSync(path) ? statSync(path).mode & 0o777 : 0o600);
     try {
         writeFileSync(temp, content, { mode });
         chmodSync(temp, mode);

package/dist/core/help.js

@@ -2,9 +2,7 @@
 // Pure functions — no side effects, no commander, no process.exit.
 // Rendering matches reference.md shapes exactly:
 //   root L11-32, branch L43-58, leaf L65-189.
-// ---------------------------------------------------------------------------
 // Internal helpers
-// ---------------------------------------------------------------------------
 /** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
  *  subtree that owns the state authors it through this, so the tag name and any
  *  scalar metadata (e.g. a count) travel with the data and render identically
@@ -42,9 +40,7 @@ function maxLen(names) {
 function pad(s, width) {
     return s + ' '.repeat(Math.max(0, width - s.length));
 }
-// ---------------------------------------------------------------------------
 // renderRoot
-// ---------------------------------------------------------------------------
 const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is agent-ready markdown/XML you\n' +
     'act on directly — read it as a continuation of your prompt, don\'t parse it as data.\n' +
     'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h; a leaf may route an uncommon flag to focused --flag -h guidance.';
@@ -132,9 +128,7 @@ export function renderRoot(h) {
     lines.push(CAPABILITY_DISCOVERY);
     return lines.join('\n');
 }
-// ---------------------------------------------------------------------------
 // renderBranch
-// ---------------------------------------------------------------------------
 /** Escape a value for a rendered XML attribute. Output is light XML around
  *  markdown read as prose by a model, not parsed — so we only guard the
  *  double-quote that would visually break the attribute, swapping it for a
@@ -170,9 +164,7 @@ export function renderBranch(h) {
     lines.push('</command>');
     return lines.join('\n');
 }
-// ---------------------------------------------------------------------------
 // renderLeafArgv
-// ---------------------------------------------------------------------------
 /** Build the display label for a param entry (left column). */
 function paramLabel(p) {
     if (p.kind === 'positional')

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

@@ -20,8 +20,8 @@ import type { RootDef } from '../command.js';
 export declare function writeIfOurs(path: string, content: string, markerPrefix: string): void;
 /** Render and write every built-in export artifact to every present host, while
  *  pruning legacy generated artifacts that should no longer be surfaced.
- *  Best-effort: swallows errors (debug-logged) so a provisioning fault never
- *  breaks an unrelated `crtr` command. Kill switch: `CRTR_NO_EXPORTS=1`. */
+ *  Best-effort: reports errors without breaking an unrelated `crtr` command.
+ *  Kill switch: `CRTR_NO_EXPORTS=1`. */
 export declare function pruneLegacyExports(argv?: string[]): void;
 /** Write every built-in export artifact to every present host. Split from the
  *  prune above because the prune must run BEFORE the front door boots (stale

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

@@ -16,6 +16,7 @@ import { writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { ensureDir, pathExists, readText, removePath } from '../fs-utils.js';
+import { envNoExports } from '../../shared/env.js';
 import { builtinExportPairs, legacyExportArtifacts } from './builtins.js';
 const SKIP_SUBCOMMANDS = new Set([
     'help',
@@ -73,11 +74,11 @@ function removeIfOurs(path, target, markerPrefix) {
 }
 /** Render and write every built-in export artifact to every present host, while
  *  pruning legacy generated artifacts that should no longer be surfaced.
- *  Best-effort: swallows errors (debug-logged) so a provisioning fault never
- *  breaks an unrelated `crtr` command. Kill switch: `CRTR_NO_EXPORTS=1`. */
+ *  Best-effort: reports errors without breaking an unrelated `crtr` command.
+ *  Kill switch: `CRTR_NO_EXPORTS=1`. */
 export function pruneLegacyExports(argv = process.argv) {
     try {
-        if (process.env.CRTR_NO_EXPORTS === '1')
+        if (envNoExports())
             return;
         if (shouldSkipAllForArgv(argv))
             return;
@@ -90,10 +91,8 @@ export function pruneLegacyExports(argv = process.argv) {
         }
     }
     catch (e) {
-        if (process.env.CRTR_DEBUG === '1') {
-            const msg = e instanceof Error ? e.message : String(e);
-            process.stderr.write(`crtr: exports prune error: ${msg}\n`);
-        }
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`crtr: exports prune error: ${msg}\n`);
     }
 }
 /** Write every built-in export artifact to every present host. Split from the
@@ -103,7 +102,7 @@ export function pruneLegacyExports(argv = process.argv) {
  *  for building the full command tree just to reach a no-op. */
 export function provisionExports(root, argv = process.argv) {
     try {
-        if (process.env.CRTR_NO_EXPORTS === '1')
+        if (envNoExports())
             return;
         if (shouldSkipAllForArgv(argv))
             return;
@@ -119,9 +118,7 @@ export function provisionExports(root, argv = process.argv) {
         }
     }
     catch (e) {
-        if (process.env.CRTR_DEBUG === '1') {
-            const msg = e instanceof Error ? e.message : String(e);
-            process.stderr.write(`crtr: exports error: ${msg}\n`);
-        }
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`crtr: exports error: ${msg}\n`);
     }
 }

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

@@ -1,4 +1,4 @@
-import { type CommentAnchor, type PageResponses, type PageSlot } from './page-schema.js';
+import { type PageCommentAnchor, type PageResponses, type PageSlot } from './page-schema.js';
 export type PageAnswer = {
     title: string;
     subtitle?: string;
@@ -34,7 +34,7 @@ export type PageAnswerGroup = {
     }[];
 };
 /** Stored responses predating the `whole` anchor's removal still carry it; answers keep rendering them. */
-export type LegacyCommentAnchor = CommentAnchor | {
+export type LegacyCommentAnchor = PageCommentAnchor | {
     kind: 'whole';
 };
 export type PageAnswerComment = {

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

@@ -1,3 +1,5 @@
+import { atomicWriteJson, atomicWriteText } from '../fs-utils.js';
+export { atomicWriteJson, atomicWriteText };
 /** The authored page source path, derived from the persisted dialect. */
 export declare function pagePath(dir: string, dialect?: 'jsx' | 'html'): string;
 /** The compiled module the Gateway evaluates for JSX pages. */
@@ -24,11 +26,6 @@ export declare function isResolved(dir: string): boolean;
 export declare function isClaimed(dir: string): boolean;
 /** Resolve and verify a ticket directory without a registry. */
 export declare function requireTicket(dir: string): string;
-/** Replace one file's contents in a single rename, so a concurrent reader —
- *  the tmux inbox watcher, or crtrd serving a ticket read — sees either the old
- *  bytes or the new ones and never a truncated file mid-write. */
-export declare function atomicWriteText(path: string, contents: string): 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 clearProgress(dir: string): void;

package/dist/core/human/convention.js

@@ -1,5 +1,7 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { atomicWriteJson, atomicWriteText } from '../fs-utils.js';
+export { atomicWriteJson, atomicWriteText };
 /** The authored page source path, derived from the persisted dialect. */
 export function pagePath(dir, dialect = 'jsx') { return `${dir}/page.${dialect === 'jsx' ? 'tsx' : 'html'}`; }
 /** The compiled module the Gateway evaluates for JSX pages. */
@@ -51,18 +53,6 @@ export function requireTicket(dir) {
     }
     return canonicalDir;
 }
-/** Replace one file's contents in a single rename, so a concurrent reader —
- *  the tmux inbox watcher, or crtrd serving a ticket read — sees either the old
- *  bytes or the new ones and never a truncated file mid-write. */
-export function atomicWriteText(path, contents) {
-    const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(tmp, contents, { mode: 0o600 });
-    renameSync(tmp, path);
-}
-export function atomicWriteJson(path, value) {
-    atomicWriteText(path, `${JSON.stringify(value, null, 2)}\n`);
-}
 /** Publish one immutable JSON record without replacing an existing winner. */
 export function publishJsonExclusive(path, value) {
     const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;

package/dist/core/human/page-schema.d.ts

@@ -2,14 +2,14 @@ import { z } from 'zod';
 import { BUILTIN_PAGE_KINDS } from './page-catalog.js';
 import type { ProductPageComponents } from '../../types.js';
 export declare const PAGE_SLOT_ID_PATTERN: RegExp;
-export declare const commentAnchorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const pageCommentAnchorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"option">;
     optionId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"row">;
     rowId: z.ZodString;
 }, z.core.$strict>], "kind">;
-export type CommentAnchor = z.infer<typeof commentAnchorSchema>;
+export type PageCommentAnchor = z.infer<typeof pageCommentAnchorSchema>;
 export declare const commentSchema: z.ZodObject<{
     id: z.ZodString;
     anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/core/human/page-schema.js

@@ -17,11 +17,11 @@ function uniqueIds(items, ctx, label) {
 // one of a question's options, or a table row. Feedback on rendered page content — including
 // the question text itself — is a ticket-level feedback comment (feedback.ts), not part of
 // any response.
-export const commentAnchorSchema = z.discriminatedUnion('kind', [
+export const pageCommentAnchorSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('option'), optionId: itemIdSchema }).strict(),
     z.object({ kind: z.literal('row'), rowId: itemIdSchema }).strict(),
 ]);
-export const commentSchema = z.object({ id: z.string().min(1), anchor: commentAnchorSchema, text: z.string() }).strict();
+export const commentSchema = z.object({ id: z.string().min(1), anchor: pageCommentAnchorSchema, text: z.string() }).strict();
 export const optionSchema = z.object({ id: itemIdSchema, label: z.string().min(1), description: z.string().optional(), recommended: z.boolean().optional() }).strict();
 export const optionsConfigSchema = z.object({
     label: z.string().optional(),

package/dist/core/human/root.js

@@ -1,7 +1,7 @@
-import { mkdirSync, realpathSync, watch, writeFileSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { basename, dirname, join } from 'node:path';
-import { crtrHome, nodeDir, nodesRoot } from '../canvas/paths.js';
+import { nodeDir, nodesRoot } from '../canvas/paths.js';
+import { activityPath, signalActivity, watchActivity } from '../activity-signal.js';
 export function ticketsRoot() {
     return nodesRoot();
 }
@@ -17,29 +17,12 @@ export function ticketDir(ticketId) {
     return nodeDir(ticketId);
 }
 export function inboxActivityPath() {
-    return join(crtrHome(), 'signals', 'inbox-activity');
+    return activityPath('inbox-activity');
 }
 /** Signal one durable ticket mutation to every open inbox without watching every ticket directory. */
 export function signalInboxActivity() {
-    try {
-        mkdirSync(dirname(inboxActivityPath()), { recursive: true, mode: 0o700 });
-        writeFileSync(inboxActivityPath(), `${Date.now()}\n`, { mode: 0o600 });
-    }
-    catch {
-        // A later inbox scan is still authoritative.
-    }
+    signalActivity('inbox-activity');
 }
 export function watchInboxActivity(onChange) {
-    const activityPath = inboxActivityPath();
-    try {
-        mkdirSync(dirname(activityPath), { recursive: true, mode: 0o700 });
-        const watcher = watch(dirname(activityPath), (_event, filename) => {
-            if (String(filename) === basename(activityPath))
-                onChange();
-        });
-        return () => watcher.close();
-    }
-    catch {
-        return () => { };
-    }
+    return watchActivity('inbox-activity', onChange);
 }

package/dist/core/human/scan.js

@@ -7,6 +7,10 @@ import { pageAwaitsResponse, pageOverviewActions } from './page-schema.js';
 import { parsePage } from './page.js';
 import { pageTicketState, readTicketResult } from './tickets.js';
 import { ticketsRoot } from './root.js';
+import { emitEvent } from '../events/emit.js';
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function claimSummary(dir) {
     const claim = readJsonOrNull(claimPath(dir));
     if (claim === null || typeof claim.host !== 'string' || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
@@ -94,7 +98,14 @@ export function scanInbox() {
         }
         if (isResolved(dir))
             continue;
-        const item = reviewSummary(dir, basename(dir)) ?? pageSummary(dir, basename(dir));
+        let item;
+        try {
+            item = reviewSummary(dir, basename(dir)) ?? pageSummary(dir, basename(dir));
+        }
+        catch (error) {
+            emitEvent({ level: 'warn', event: 'human.scan.ticket_unreadable', fields: { ticket_id: basename(dir), error: errorText(error) } });
+            continue;
+        }
         if (item !== null && (item.kind !== 'page' || item.inbox))
             items.push(item);
     }
@@ -124,13 +135,19 @@ export function scanPageHistory(nodeId) {
         catch {
             continue;
         }
-        const summary = pageSummary(dir, basename(dir));
-        if (summary === null)
-            continue;
-        if (nodeId !== undefined && summary.source.nodeId !== nodeId)
+        try {
+            const summary = pageSummary(dir, basename(dir));
+            if (summary === null)
+                continue;
+            if (nodeId !== undefined && summary.source.nodeId !== nodeId)
+                continue;
+            const result = summary.state === 'resolved' ? readTicketResult(dir) : null;
+            items.push({ ...summary, ...(result?.kind === 'page' ? { answerDigest: result.summary.replace(/\s+/g, ' ').trim() } : {}) });
+        }
+        catch (error) {
+            emitEvent({ level: 'warn', event: 'human.scan.ticket_unreadable', fields: { ticket_id: basename(dir), error: errorText(error) } });
             continue;
-        const result = summary.state === 'resolved' ? readTicketResult(dir) : null;
-        items.push({ ...summary, ...(result?.kind === 'page' ? { answerDigest: result.summary.replace(/\s+/g, ' ').trim() } : {}) });
+        }
     }
     return items.sort((a, b) => Date.parse(a.emittedAt) - Date.parse(b.emittedAt) || a.id.localeCompare(b.id));
 }

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

@@ -1,7 +1,10 @@
 import type { ReviewDescriptor, TicketResult } from './types.js';
 import type { ProductPageComponents } from '../../types.js';
 import { type PageDelivery, type PageManifest, type PageResponses, type PageSource } from './page-schema.js';
-/** Strict decoder for the only canonical final marker. */
+/** Strict decoder for the only canonical final marker. Only a missing file reads
+ *  as absent — a corrupt (unparseable) response is a real anomaly and throws,
+ *  since silently treating it as "no result yet" would mask data loss instead
+ *  of surfacing it to whichever caller owns the failure boundary. */
 export declare function readTicketResult(dir: string): TicketResult | null;
 export interface SubmitPageOptions {
     dir: string;

package/dist/core/human/tickets.js

@@ -27,14 +27,20 @@ const pageResultSchema = z.object({ schema: z.literal('crtr.page-response/v1'),
 const pageProgressSchema = z.object({ kind: z.literal('page'), responses: z.record(z.string(), slotResponseSchema), savedAt: iso }).strict();
 const reviewResultSchema = z.object({ schema: z.literal('humanloop.review-response/v1'), kind: z.literal('review'), result: feedbackSchema, completedAt: iso }).strict();
 const canceledResultSchema = z.object({ schema: z.literal('humanloop.cancel/v1'), kind: z.literal('canceled'), canceledAt: iso, reason: z.string().optional(), actor: z.string().optional(), disposition: z.enum(['canceled', 'dismissed']).optional() }).strict();
-/** Strict decoder for the only canonical final marker. */
+/** Strict decoder for the only canonical final marker. Only a missing file reads
+ *  as absent — a corrupt (unparseable) response is a real anomaly and throws,
+ *  since silently treating it as "no result yet" would mask data loss instead
+ *  of surfacing it to whichever caller owns the failure boundary. */
 export function readTicketResult(dir) {
+    const path = responsePath(dir);
+    if (!existsSync(path))
+        return null;
     let raw;
     try {
-        raw = JSON.parse(readFileSync(responsePath(dir), 'utf8'));
+        raw = JSON.parse(readFileSync(path, 'utf8'));
     }
-    catch {
-        return null;
+    catch (error) {
+        throw new Error(`corrupt ticket result: ${path}`, { cause: error });
     }
     const page = pageResultSchema.safeParse(raw);
     if (page.success)
@@ -246,7 +252,10 @@ function completePageLocked(dir, responses, claimToken, opts) {
     const result = { schema: 'crtr.page-response/v1', kind: 'page', responses: parsedResponses, summary: buildPageSummary(manifest, parsedResponses), completedAt: opts.completedAt ?? new Date().toISOString(), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
     const won = exclusiveResult(dir, result);
     clearOwnedWork(dir, claimToken);
-    return { won, result: won ? result : readTicketResult(dir) ?? result };
+    // Lost the race: the winner's result must already be on disk, so a null read
+    // here is an anomaly worth surfacing rather than silently falling back to
+    // this loser's own uncommitted result.
+    return { won, result: won ? result : (readTicketResult(dir) ?? (() => { throw new Error(`lost the completion race but no winning result is on disk: ${dir}`); })()) };
 }
 export function completePage(dir, responses, claimToken, opts = {}) {
     const ticket = requireTicket(dir);
@@ -288,7 +297,12 @@ export function cancelTicket(dir, opts = {}) {
             requireCancelablePage(ticket);
         const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }), ...(opts.disposition === undefined ? {} : { disposition: opts.disposition }) };
         const won = exclusiveResult(ticket, result);
-        return { status: won ? 'canceled' : 'already_resolved', result: won ? result : readTicketResult(ticket) ?? result };
+        // Same anomaly as completePageLocked: losing the race with no winning
+        // result on disk means the ticket state is broken, not just contended.
+        return {
+            status: won ? 'canceled' : 'already_resolved',
+            result: won ? result : (readTicketResult(ticket) ?? (() => { throw new Error(`lost the cancellation race but no winning result is on disk: ${ticket}`); })()),
+        };
     });
     if (canceled.status === 'canceled')
         signalInboxActivity();

package/dist/core/io.js

@@ -9,9 +9,7 @@ import { ExitCode } from '../types.js';
 import { PREVIEW_RESULT_PATH_ENV } from './preview-result-path.js';
 import { renderError } from './render.js';
 import { ApiError } from '../api/index.js';
-// ---------------------------------------------------------------------------
 // output mode — prose (default) vs raw JSON (--json global, for tooling)
-// ---------------------------------------------------------------------------
 let jsonOutput = false;
 let preview;
 /** A preview is bounded UI metadata, never a bulk-data channel. One
@@ -98,9 +96,7 @@ export class InputError extends CrtrError {
         this.payload = payload;
     }
 }
-// ---------------------------------------------------------------------------
 // stdin
-// ---------------------------------------------------------------------------
 /** Read raw stdin to EOF. Returns empty string when stdin is a TTY (no pipe).
  *  Called by the argv parser for leaves declaring a `stdin` parameter. */
 export async function readStdinRaw() {
@@ -148,9 +144,7 @@ export async function peekStdinRaw(timeoutMs = 200) {
         process.stdin.resume();
     });
 }
-// ---------------------------------------------------------------------------
 // stdout — the result, nothing else
-// ---------------------------------------------------------------------------
 /** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
  *  default path renders the result as prose instead — see render.ts. */
 export function emit(obj) {
@@ -192,15 +186,11 @@ export function writeStdout(s) {
         }
     });
 }
-// ---------------------------------------------------------------------------
 // stderr — diagnostics the agent MAY capture, never the result
-// ---------------------------------------------------------------------------
 export function diag(message) {
     process.stderr.write(message + '\n');
 }
-// ---------------------------------------------------------------------------
 // errors
-// ---------------------------------------------------------------------------
 function payloadOf(e) {
     if (e instanceof InputError)
         return e.payload;
@@ -259,7 +249,6 @@ function jsonSafeResult(result) {
         message: 'The completed primary result could not be represented as JSON.',
     };
 }
-// ---------------------------------------------------------------------------
 // ApiError → clean CLI error — the ONE shared translation (plan C-5)
 //
 // A daemon `ApiError` is NOT a `CrtrError`, so left unhandled it falls through
@@ -268,7 +257,6 @@ function jsonSafeResult(result) {
 // error the pre-API leaves surfaced, so every re-plumbed verb shares one
 // contract instead of re-implementing the mapping per command. io.ts importing
 // `ApiError` from `src/api` is canvas-clean (src/api is Node-built-ins only).
-// ---------------------------------------------------------------------------
 /** Map a daemon HTTP status to the stable CLI error code the pre-API leaves
  *  used, so agent-facing error contracts survive the re-plumb. Used only as the
  *  fallback when the server did NOT round-trip a full structured payload. */

package/dist/core/memory/identity.js

@@ -4,12 +4,10 @@
 // (a project's declaration, an installed plugin's mount prefix, or empty), and
 // its canonical name — the only address resolution accepts — is namespace ⊕
 // local. Pure and side-effect free.
-// ---------------------------------------------------------------------------
 // Segment normalization — the optional `NN-` ordering pin. A physical path may
 // carry a two-digit prefix on any segment (`00-runtime-base/`, `01-spine/`)
 // purely to pin structural order against natural sort. The prefix is NEVER part
 // of identity: only the physical path keeps it.
-// ---------------------------------------------------------------------------
 const NUMERIC_PREFIX_RE = /^\d{2}-/;
 const SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
 /** The filename (and path segment) whose document fronts its directory. */
@@ -85,9 +83,7 @@ export function physicalRelativePathFor(localName, representation) {
     }
     return representation === 'directory-index' ? `${local}/${INDEX_SEGMENT}.md` : `${local}.md`;
 }
-// ---------------------------------------------------------------------------
 // Local name and canonical composition.
-// ---------------------------------------------------------------------------
 /** A document's explicit frontmatter `name` as a local name — normalized with
  *  one trailing `INDEX` collapsed — or `null` when it carries none. */
 export function explicitLocalName(fm) {

package/dist/core/memory/inline-ref-inventory.js

@@ -1,6 +1,7 @@
 // Authoritative broker-side inventory for inline memory references. It uses one
 // target view, exact canonical winners, and the canonical tree for directory
 // browse names; gates, rungs, and slash flags do not affect referenceability.
+import { envNodeId, envProfileId } from '../../shared/env.js';
 import { loadMemoryTargetView } from '../memory-resolver.js';
 import { buildMemoryTree } from './tree.js';
 import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from './extensions.js';
@@ -21,8 +22,8 @@ const SCOPE_SORT_RANK = {
 export function buildRefInventory() {
     const target = {
         cwd: process.cwd(),
-        profileId: process.env['CRTR_PROFILE_ID'] || null,
-        nodeId: process.env['CRTR_NODE_ID'] || null,
+        profileId: envProfileId() || null,
+        nodeId: envNodeId() || null,
     };
     const view = loadMemoryTargetView(target, { quiet: true });
     const winners = new Map();

package/dist/core/memory/lint.js

@@ -10,6 +10,7 @@
 // a non-fatal authoring smell, `notice` is inspection data (duplicate stores are
 // legitimate, so equal-canonical candidates across stores are reported, never
 // failed).
+import { envNodeId, envProfileId } from '../../shared/env.js';
 import { basename, join, matchesGlob, relative, sep } from 'node:path';
 import { pathExists, readText, realpathOrSelf, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
@@ -51,7 +52,6 @@ function makeResult(findings, checked, documents, storesLinted) {
         notices: findings.filter((f) => f.severity === 'notice'),
     };
 }
-// ---------------------------------------------------------------------------
 // Body-length caps, measured in WORDS (frontmatter excluded). Words, not lines:
 // house style writes each paragraph as ONE logical line and lets the editor
 // soft-wrap, so a line count measures wrapping style rather than context cost.
@@ -68,7 +68,6 @@ function makeResult(findings, checked, documents, storesLinted) {
 // composes into an agent's persona — are structurally exempt: an agent reads its
 // whole persona by construction. Suppression elsewhere is deliberate and
 // per-doc: `lint-ignore: length`, surfaced ONLY by the finding itself.
-// ---------------------------------------------------------------------------
 const BOOT_CONTENT_MAX_WORDS = 1000;
 const EVENT_CONTENT_MAX_WORDS = 1000;
 const BOOT_PREVIEW_MAX_WORDS = 3000;
@@ -116,9 +115,7 @@ export function lintShortPreviewBody(fm, body) {
     const noun = previewEvents.length === 1 ? 'entry delivers' : 'entries deliver';
     return `body is ${words} words but the ${previewEvents.join('/')} ${noun} \`preview\`; use \`at: content\` so agents receive the whole rule without a separate memory read`;
 }
-// ---------------------------------------------------------------------------
 // Reference resolution: what a `[[link]]` or a `memory-read` route may name.
-// ---------------------------------------------------------------------------
 /** Every canonical name a reference may target in a corpus: each document's
  *  exact identity plus every canonical directory, because reading a directory
  *  answers with its own document and its listing. Derived from the canonical
@@ -455,8 +452,8 @@ function lintMemoryReadEntry(entry, doc, fm, resolvable, mounted, add) {
 function ambientTarget() {
     return {
         cwd: process.cwd(),
-        profileId: process.env['CRTR_PROFILE_ID'] || null,
-        nodeId: process.env['CRTR_NODE_ID'] || null,
+        profileId: envProfileId() || null,
+        nodeId: envNodeId() || null,
     };
 }
 /** Lint every store a target sees, then the diagnostics only the merged view

package/dist/core/memory-resolver.d.ts

@@ -242,6 +242,11 @@ export declare function createMemoryDocSnapshot(target?: MemoryTarget): MemoryDo
 /** Resolve several canonical names over one memory-source snapshot. Failed
  * names are omitted so callers can preserve their per-document error behavior. */
 export declare function resolveMemoryDocs(names: readonly string[]): Map<string, MemoryDoc>;
+/** Load the body at an already-resolved memory path with the same frontmatter
+ * stripping and in-node path interpolation as `memory read`. Callers that
+ * already have the resolved path (such as slash-command discovery) avoid
+ * re-walking every memory store for each document. */
+export declare function readMemoryDocContent(path: string, includeFrontmatter?: boolean): string;
 /** The address winner for an exact canonical name in the ambient target. */
 export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;
 /** Resolve a memory document as ANOTHER node would see it — the same precedence