@north-light/crouter 0.3.232 → 0.3.234

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

package/dist/core/memory-resolver.js

@@ -1,8 +1,10 @@
+import { envNodeId, envProfileId } from '../shared/env.js';
 import { dirname, join, relative, sep } from 'node:path';
 import { readdirSync } from 'node:fs';
 import { CRTR_DIR_NAME } from '../types.js';
 import { pathExists, readText, realpathOrSelf, walkFiles } from './fs-utils.js';
 import { parseFrontmatterGeneric } from './frontmatter.js';
+import { interpolateNodePaths } from './canvas/paths.js';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from './resolver.js';
 import { notFound, usage } from './errors.js';
 import { warn } from './output.js';
@@ -19,18 +21,16 @@ import { associateRepository } from './memory/repository-association.js';
 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,
     };
 }
 /** The selected profile id from the process env, or '' when none. */
 function selectedProfileId() {
     return ambientTarget().profileId ?? '';
 }
-// ---------------------------------------------------------------------------
 // Store discovery: which physical stores a target sees, in what order, and
 // whether each one's namespace lets it mount.
-// ---------------------------------------------------------------------------
 /** The memory scopes in resolution precedence: node > project stack > profile >
  *  user > builtin. Node is included only when the target names one and ranks
  *  NEAREST — a node doc overrides any wider scope. Project is included only when
@@ -291,10 +291,8 @@ export function nativeMemoryStoresInPrecedence(scope, includeDescendants = false
         .filter((store) => store.mountStatus === 'ready' && store.scope !== 'builtin' && store.plugin === undefined)
         .map((store) => ({ scope: store.scope, memoryDir: store.storeRoot, store }));
 }
-// ---------------------------------------------------------------------------
 // Document loading: one store's markdown files become canonically-identified
 // documents.
-// ---------------------------------------------------------------------------
 function firstLine(e) {
     return (e instanceof Error ? e.message : String(e)).split('\n')[0] ?? '';
 }
@@ -375,9 +373,7 @@ export function loadStoreMemoryDocs(store, quiet = false) {
 export function listPluginMemoryDocs(plugin, scope, quiet = false, projectMemory = NEUTRAL_PROJECT_MEMORY) {
     return loadStoreMemoryDocs(pluginStoreDescriptor(plugin, scope, projectMemory), quiet);
 }
-// ---------------------------------------------------------------------------
 // Views: exact canonical resolution over a loaded corpus.
-// ---------------------------------------------------------------------------
 /** The canonical form of a query: empty segments dropped. An `NN-` ordering
  *  prefix is physical-path-only and is NOT stripped here — a canonical name
  *  never carries one, so `04-base` is simply no document's address. */
@@ -462,9 +458,7 @@ export function loadMemoryTargetView(target, opts = {}) {
 export function loadMemoryStoreView(store, quiet = false) {
     return { store, ...makeView([store], loadStoreMemoryDocs(store, quiet)) };
 }
-// ---------------------------------------------------------------------------
 // Corpus listing.
-// ---------------------------------------------------------------------------
 /** All project-scoped docs visible from an explicit node workspace/profile — the
  *  project-only slice of a `MemoryTarget` view, used where only workspace docs
  *  are wanted (a workspace-open render). For a full-precedence target-addressed
@@ -507,6 +501,16 @@ export function createMemoryDocSnapshot(target = ambientTarget()) {
 export function resolveMemoryDocs(names) {
     return createMemoryDocSnapshot().resolve(names);
 }
+/** 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 function readMemoryDocContent(path, includeFrontmatter = false) {
+    const raw = readText(path);
+    const content = includeFrontmatter ? raw : parseFrontmatterGeneric(raw).body;
+    const nodeId = envNodeId();
+    return nodeId ? interpolateNodePaths(content, nodeId) : content;
+}
 /** The address winner for an exact canonical name in the ambient target. */
 export function resolveMemoryDoc(rawName, opts = {}) {
     return resolveMemoryDocForTarget(rawName, ambientTarget(), opts);
@@ -541,10 +545,8 @@ export function resolveMemoryCandidatesForTarget(rawName, target, opts = {}) {
 export function resolveMemoryDocInStore(rawName, store, opts = {}) {
     return loadMemoryStoreView(store, true).resolve(rawName, opts);
 }
-// ---------------------------------------------------------------------------
 // Physical sidecar lookup: the revision log mirrors the doc tree, so it is
 // addressed by PHYSICAL path segments, not by canonical identity.
-// ---------------------------------------------------------------------------
 /** Find the direct child of `dir` — an `ext` file (matched on name minus
  *  extension) or a directory — whose NORMALIZED display name equals
  *  `segment`. An exact literal match (no prefix to strip) wins over a

package/dist/core/pagination.js

@@ -11,9 +11,7 @@
 // item after it is returned correctly).
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
-// ---------------------------------------------------------------------------
 // Cursor encoding / decoding
-// ---------------------------------------------------------------------------
 /** Encodes a stable sort key into an opaque base64url cursor token. */
 export function encodeCursor(key) {
     const json = JSON.stringify({ k: key });

package/dist/core/preview-registry.d.ts

@@ -14,6 +14,9 @@ export declare const HELP_ICON: string;
  *  paints lives in one file: terminal for `bash`, file-text for `read`, floppy for
  *  `write` (content committed to disk), pencil-square for `edit`. */
 export declare const TOOL_ICON: Readonly<Record<'bash' | 'read' | 'write' | 'edit', string>>;
+/** Per-leaf overrides, keyed by full leaf help-name path (e.g. "memory
+ *  lint"), same shape as SUPPRESS_OUTPUT_LEAVES. */
+export declare const LEAF_ICON_CP: Record<string, number>;
 /** Resolve the Nerd Font glyph for a command's argv tokens: the longest
  *  matching LEAF_ICON_CP prefix, else the tokens[0] family glyph, else the
  *  generic ◆ fallback for an unmapped family. */
@@ -29,7 +32,18 @@ export interface CrtrPreview {
     jsonl?: Record<string, unknown>[];
     error?: Record<string, unknown>;
 }
+type SummaryInput = {
+    result?: Record<string, unknown>;
+    jsonl?: Record<string, unknown>[];
+    error?: Record<string, unknown>;
+};
+type Summarizer = (input: SummaryInput, tokens: readonly string[]) => SummaryLine[] | null;
+export declare const SUMMARIZERS: ReadonlyArray<{
+    path: string;
+    run: Summarizer;
+}>;
 /** Summarize an exact CLI result record. The recorded path is authoritative:
  * shell tokenization is used only for an invocation's static icon/help chrome,
  * never to identify or decode the returned leaf data. */
 export declare function summarizePath(preview: CrtrPreview, tokens?: readonly string[]): SummaryLine[] | null;
+export {};

package/dist/core/preview-registry.js

@@ -42,12 +42,10 @@ export function suppressOutputForPath(tokens) {
     }
     return false;
 }
-// ---------------------------------------------------------------------------
 // Icon registry (rule 12, inline-ui-placement: real Nerd Font glyphs, not the
 // generic ◆ diamond). Every leaf's glyph is looked up first in LEAF_ICON_CP
 // (longest-prefix match, same shape as SUPPRESS_OUTPUT_LEAVES); an unmapped
 // leaf falls back to its root family's glyph in FAMILY_ICON_CP.
-// ---------------------------------------------------------------------------
 /** question-circle — the header glyph for a `-h`/`--help` invocation,
  *  regardless of which command's help was requested. */
 const HELP_ICON_CP = 0xf059;
@@ -83,7 +81,7 @@ const FAMILY_ICON_CP = {
 };
 /** Per-leaf overrides, keyed by full leaf help-name path (e.g. "memory
  *  lint"), same shape as SUPPRESS_OUTPUT_LEAVES. */
-const LEAF_ICON_CP = {
+export const LEAF_ICON_CP = {
     'canvas dashboard': 0xf0e4,
     'canvas snapshot': 0xf030,
     'canvas browse': 0xf14e,
@@ -345,7 +343,7 @@ function summarizeProfileList(input) {
         ...profiles.slice(0, 5).map((profile) => ({ text: `${stringField(profile, 'name')} · ${numberField(profile, 'projects_count')} projects`, tone: 'muted' })),
     ];
 }
-const SUMMARIZERS = [
+export const SUMMARIZERS = [
     { path: 'memory read', run: summarizeMemoryRead },
     { path: 'memory list', run: summarizeArray('docs') },
     { path: 'memory find', run: summarizeArray('hits', 'hits') },