@north-light/crouter 0.3.219 → 0.3.221

package/dist/core/command-hooks/transport/exec-invoke.js

@@ -0,0 +1,274 @@
+import { spawn } from 'node:child_process';
+import { posixProcessGroupSpawnOptions, terminateProcessGroup } from '../../../hook-process.js';
+import { ExitCode } from '../../../types.js';
+import { isRecord } from '../../../shared/predicates.js';
+import { validateCoreDeclaredResult } from '../../command-plugins/transport/exec-invoke.js';
+import { CrtrError } from '../../errors.js';
+import { diag } from '../../io.js';
+const MAX_STDOUT = 10 * 1024 * 1024;
+export const EXEC_HOOK_TIMEOUT_MS = 15_000;
+const RESERVED_CODES = new Set([
+    'internal',
+    'unknown_path',
+    'command_collision',
+    'command_hook_collision',
+    'plugin_protocol_error',
+    'hook_protocol_error',
+]);
+const SNAKE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+const OPERATION_ID = /^[0-9a-f]{32}$/;
+const NEXT = 'Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.';
+/** Invoke one hook executable; after failures retain the completed primary result. */
+export async function invokeExecHook(spec, invocation) {
+    const cwd = process.cwd();
+    const request = buildRequest(spec, invocation, cwd);
+    const res = await runHookProcess(spec, invocation, JSON.stringify(request), cwd);
+    if (res.signal !== null) {
+        throw protocolError(spec, invocation, `executable was killed by signal ${res.signal}`, 'a clean exit with one JSON envelope on stdout');
+    }
+    const envelope = parseEnvelope(spec, invocation, res.stdout);
+    if (envelope.ok && res.status !== 0) {
+        diag(`crtr: ${label(spec)} returned ok:true but exited ${res.status} (honoring the envelope)`);
+    }
+    else if (!envelope.ok && res.status === 0) {
+        diag(`crtr: ${label(spec)} returned ok:false but exited 0 (honoring the envelope)`);
+    }
+    if (!envelope.ok)
+        throwHookFailure(spec, invocation, envelope);
+    if (spec.phase !== 'replace')
+        return;
+    const result = envelope.result;
+    if (!isRecord(result)) {
+        throw protocolError(spec, invocation, 'replacement success result was not an object', 'result: an object matching the target output declaration');
+    }
+    const output = spec.output;
+    if (output === undefined) {
+        throw protocolError(spec, invocation, 'replacement target output declaration was missing', 'the target leaf output declaration');
+    }
+    const issue = validateCoreDeclaredResult(output, result);
+    if (issue !== null) {
+        const field = output.find((candidate) => candidate.name === issue.field);
+        if (issue.receivedType !== undefined) {
+            throw protocolError(spec, invocation, `replacement output field "${issue.field}" has the wrong type`, `${issue.field}: ${field?.type ?? 'unknown'}`);
+        }
+        throw protocolError(spec, invocation, `replacement result is missing required output field "${issue.field}"`, `a "${issue.field}" field of type ${field?.type ?? 'unknown'}`);
+    }
+    return result;
+}
+async function runHookProcess(spec, invocation, input, cwd) {
+    let child;
+    try {
+        child = spawn(spec.executable, ['--crtr-hook-protocol', '1'], {
+            cwd,
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'inherit'],
+            ...posixProcessGroupSpawnOptions(),
+        });
+    }
+    catch (error) {
+        throw protocolError(spec, invocation, `executable could not be run (${describeError(error)})`, 'a runnable hook executable');
+    }
+    return new Promise((resolve, reject) => {
+        let stdoutBytes = 0;
+        const stdout = [];
+        let failure;
+        let closed = false;
+        let cleaned = false;
+        let status = null;
+        let signal = null;
+        let timeout;
+        const finish = () => {
+            if (!closed || (failure !== undefined && !cleaned))
+                return;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (failure?.kind === 'timeout') {
+                reject(protocolError(spec, invocation, `executable timed out after ${EXEC_HOOK_TIMEOUT_MS}ms`, 'one JSON envelope before the execution timeout'));
+                return;
+            }
+            if (failure?.kind === 'output_limit') {
+                reject(protocolError(spec, invocation, 'stdout exceeded the 10 MiB cap', 'one JSON envelope under 10 MiB on stdout'));
+                return;
+            }
+            if (failure?.kind === 'spawn') {
+                reject(protocolError(spec, invocation, `executable could not be run (${describeError(failure.error)})`, 'a runnable hook executable'));
+                return;
+            }
+            if (failure?.kind === 'cleanup') {
+                reject(protocolError(spec, invocation, `executable cleanup failed (${describeError(failure.error)})`, 'a hook executable whose process group can be terminated'));
+                return;
+            }
+            resolve({ stdout: Buffer.concat(stdout).toString('utf8'), status, signal });
+        };
+        const terminate = (reason) => {
+            if (failure !== undefined)
+                return;
+            failure = reason;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            void terminateProcessGroup(child).then(() => {
+                cleaned = true;
+                finish();
+            }, (error) => {
+                failure = { kind: 'cleanup', error };
+                cleaned = true;
+                finish();
+            });
+        };
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.byteLength;
+            if (stdoutBytes > MAX_STDOUT) {
+                terminate({ kind: 'output_limit' });
+                return;
+            }
+            stdout.push(chunk);
+        });
+        child.once('error', (error) => {
+            if (child.pid === undefined) {
+                failure = { kind: 'spawn', error };
+                closed = true;
+                cleaned = true;
+                finish();
+                return;
+            }
+            terminate({ kind: 'spawn', error });
+        });
+        child.once('close', (nextStatus, nextSignal) => {
+            status = nextStatus;
+            signal = nextSignal;
+            closed = true;
+            finish();
+        });
+        timeout = setTimeout(() => terminate({ kind: 'timeout' }), EXEC_HOOK_TIMEOUT_MS);
+        child.stdin.end(input);
+    });
+}
+function buildRequest(spec, invocation, cwd) {
+    if (!OPERATION_ID.test(invocation.operationId)) {
+        throw protocolError(spec, invocation, 'operationId was not a 32-character lowercase hexadecimal string', 'a valid crouter operation identity');
+    }
+    if (!isJson(invocation.input)) {
+        throw protocolError(spec, invocation, 'input was not JSON-compatible', 'a JSON object');
+    }
+    if (!invocation.providedParams.every((param) => typeof param === 'string')) {
+        throw protocolError(spec, invocation, 'providedParams contained a non-string value', 'an array of parameter names');
+    }
+    const base = {
+        protocolVersion: 1,
+        op: spec.op,
+        command: [...spec.commandPath],
+        operationId: invocation.operationId,
+        input: invocation.input,
+        context: { cwd, providedParams: [...invocation.providedParams] },
+    };
+    if (spec.phase === 'after') {
+        if (invocation.result === undefined || !isJson(invocation.result)) {
+            throw protocolError(spec, invocation, 'after hook result was missing or not JSON-compatible', 'the completed primary result');
+        }
+        return { ...base, phase: 'after', result: invocation.result };
+    }
+    if (invocation.result !== undefined) {
+        throw protocolError(spec, invocation, `${spec.phase} hook invocation included a result`, 'result only for after hooks');
+    }
+    return { ...base, phase: spec.phase };
+}
+function parseEnvelope(spec, invocation, stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout.trim());
+    }
+    catch {
+        throw protocolError(spec, invocation, 'stdout was not a single JSON envelope', 'exactly one JSON envelope on stdout');
+    }
+    if (!isRecord(value)) {
+        throw protocolError(spec, invocation, 'stdout was not a JSON object', 'a { protocolVersion: 1, ok: boolean, ... } envelope');
+    }
+    if (value['protocolVersion'] !== 1) {
+        throw protocolError(spec, invocation, `unsupported protocolVersion ${String(value['protocolVersion'])}`, 'protocolVersion exactly 1');
+    }
+    if (value['ok'] === true) {
+        const expectedKeys = spec.phase === 'replace' ? ['protocolVersion', 'ok', 'result'] : ['protocolVersion', 'ok'];
+        if (!hasExactKeys(value, expectedKeys)) {
+            throw protocolError(spec, invocation, 'success envelope had missing or extra fields', `{ ${expectedKeys.join(', ')} } only`);
+        }
+        if (spec.phase === 'replace') {
+            if (!isJson(value['result'])) {
+                throw protocolError(spec, invocation, 'replacement result was not JSON-compatible', 'a JSON result');
+            }
+            return { protocolVersion: 1, ok: true, result: value['result'] };
+        }
+        return { protocolVersion: 1, ok: true };
+    }
+    if (value['ok'] !== false || !hasExactKeys(value, ['protocolVersion', 'ok', 'error'])) {
+        throw protocolError(spec, invocation, 'failure envelope had missing or extra fields', '{ protocolVersion, ok, error } only');
+    }
+    const error = value['error'];
+    if (!isRecord(error) || !hasExactKeys(error, ['code', 'message'], ['field', 'next'])) {
+        throw protocolError(spec, invocation, 'error envelope was missing fields or contained extra fields', 'error: { code, message, field?, next? }');
+    }
+    if (typeof error['code'] !== 'string' || error['code'] === '' || typeof error['message'] !== 'string' || error['message'] === '') {
+        throw protocolError(spec, invocation, 'error envelope had an empty or non-string code/message', 'non-empty error code and message strings');
+    }
+    if ((error['field'] !== undefined && typeof error['field'] !== 'string') || (error['next'] !== undefined && typeof error['next'] !== 'string')) {
+        throw protocolError(spec, invocation, 'error envelope had a non-string field/next', 'string field and next values when present');
+    }
+    return {
+        protocolVersion: 1,
+        ok: false,
+        error: {
+            code: error['code'],
+            message: error['message'],
+            ...(error['field'] === undefined ? {} : { field: error['field'] }),
+            ...(error['next'] === undefined ? {} : { next: error['next'] }),
+        },
+    };
+}
+function throwHookFailure(spec, invocation, failure) {
+    const { code, message, field, next } = failure.error;
+    if (!SNAKE.test(code) || RESERVED_CODES.has(code)) {
+        throw protocolError(spec, invocation, `error code "${code}" was invalid or reserved`, 'a non-reserved lowercase snake_case code');
+    }
+    throw new CrtrError(code, `${label(spec)}: ${message}`, ExitCode.GENERAL, failureDetails(spec, invocation, field, next));
+}
+function protocolError(spec, invocation, received, expected) {
+    return new CrtrError('hook_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, failureDetails(spec, invocation, undefined, NEXT, received));
+}
+function failureDetails(spec, invocation, field, next, received) {
+    const identity = {
+        plugin: spec.plugin,
+        op: spec.op,
+        phase: spec.phase,
+        command: [...spec.commandPath],
+        ...(received === undefined ? {} : { received }),
+        ...(field === undefined ? {} : { field }),
+    };
+    if (spec.phase !== 'after')
+        return { ...identity, next: next ?? NEXT };
+    const guidance = 'Do not retry the original command; its primary action completed. Inspect and reconcile the failed after hook.';
+    return {
+        ...identity,
+        primaryCompleted: true,
+        result: invocation.result,
+        next: next === undefined || next === NEXT ? guidance : `${next} ${guidance}`,
+    };
+}
+function label(spec) {
+    return `plugin "${spec.plugin}" ${spec.phase} hook "${spec.op}" for \`${spec.commandPath.join(' ')}\``;
+}
+function hasExactKeys(value, required, optional = []) {
+    const keys = Object.keys(value);
+    return required.every((key) => Object.hasOwn(value, key))
+        && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+function isJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJson);
+    return isRecord(value) && Object.values(value).every(isJson);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/command-plugins/presence.d.ts

@@ -0,0 +1,2 @@
+/** Whether an enabled command plugin survives nearest-scope name shadowing. */
+export declare function hasEffectiveCommandPlugins(startDir?: string, profileId?: string | null): boolean;

package/dist/core/command-plugins/presence.js

@@ -0,0 +1,17 @@
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
+import { projectScopeRoots } from '../scope.js';
+/** Whether an enabled command plugin survives nearest-scope name shadowing. */
+export function hasEffectiveCommandPlugins(startDir = process.cwd(), profileId) {
+    const seen = new Set();
+    const consider = (plugin) => {
+        if (seen.has(plugin.name))
+            return false;
+        seen.add(plugin.name);
+        return plugin.enabled && (plugin.manifest.commands !== undefined || plugin.manifest.transport !== undefined);
+    };
+    for (const root of projectScopeRoots(startDir, profileId)) {
+        if (listInstalledPluginsInRoot('project', root).some(consider))
+            return true;
+    }
+    return listInstalledPlugins('user').some(consider);
+}

package/dist/core/command-plugins/transport/exec-invoke.d.ts

@@ -16,6 +16,11 @@ export declare function validateDeclaredResult(output: Field[], result: Record<s
     field: string;
     receivedType?: string;
 } | null;
+/** Core leaf declarations may explicitly require a nullable field. */
+export declare function validateCoreDeclaredResult(output: Field[], result: Record<string, unknown>): {
+    field: string;
+    receivedType?: string;
+} | null;
 /** Execute one external leaf and return its result object (crtr renders it via
  *  the generic renderer; `--json` mirrors it). Throws a CrtrError for any
  *  protocol violation or the plugin's own recoverable error. */

package/dist/core/command-plugins/transport/exec-invoke.js

@@ -21,13 +21,23 @@ const NEXT = 'Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plu
  *  Returns null if valid; otherwise returns a { field, receivedType } error.
  *  Transport-neutral: used by exec and HTTP transport adapters. */
 export function validateDeclaredResult(output, result) {
+    return validateFields(output, result, false);
+}
+/** Core leaf declarations may explicitly require a nullable field. */
+export function validateCoreDeclaredResult(output, result) {
+    return validateFields(output, result, true);
+}
+function validateFields(output, result, honorDeclaredNull) {
     for (const f of output) {
-        const present = Object.prototype.hasOwnProperty.call(result, f.name) && result[f.name] !== undefined && result[f.name] !== null;
-        if (f.required && !present) {
+        const value = result[f.name];
+        const present = Object.prototype.hasOwnProperty.call(result, f.name)
+            && value !== undefined
+            && (honorDeclaredNull || value !== null);
+        if (f.required && !present)
             return { field: f.name };
-        }
-        if (present && !typeMatches(f.type, result[f.name])) {
-            return { field: f.name, receivedType: typeof result[f.name] };
+        const matches = honorDeclaredNull ? coreTypeMatches(f.type, value) : typeMatches(f.type, value);
+        if (present && !matches) {
+            return { field: f.name, receivedType: value === null ? 'null' : typeof value };
         }
     }
     return null;
@@ -150,6 +160,49 @@ function typeMatches(type, v) {
         return isRecord(v);
     return true;
 }
+function coreTypeMatches(type, v) {
+    const alternatives = type.split('|').map((part) => part.trim()).filter(Boolean);
+    if (alternatives.length === 1 && !knownType(alternatives[0]))
+        return true;
+    const allKnown = alternatives.every((part) => knownType(part) || /^[a-z][a-z0-9_-]*$/.test(part));
+    if (!allKnown)
+        return true;
+    return alternatives.some((part) => atomMatches(part, v));
+}
+function knownType(type) {
+    const t = type.toLowerCase();
+    return t === 'null'
+        || t === 'string'
+        || t === 'path'
+        || t === 'markdown'
+        || t === 'int'
+        || t === 'integer'
+        || t === 'number'
+        || t === 'float'
+        || t === 'bool'
+        || t === 'boolean'
+        || t === 'array'
+        || t.endsWith('[]')
+        || t === 'object';
+}
+function atomMatches(type, v) {
+    const t = type.toLowerCase();
+    if (t === 'null')
+        return v === null;
+    if (t === 'string' || t === 'path' || t === 'markdown')
+        return typeof v === 'string';
+    if (t === 'int' || t === 'integer')
+        return typeof v === 'number' && Number.isInteger(v);
+    if (t === 'number' || t === 'float')
+        return typeof v === 'number';
+    if (t === 'bool' || t === 'boolean')
+        return typeof v === 'boolean';
+    if (t === 'array' || t.endsWith('[]'))
+        return Array.isArray(v);
+    if (t === 'object')
+        return isRecord(v);
+    return typeof v === 'string' && v === type;
+}
 function protocolError(spec, received, expected) {
     return new CrtrError('plugin_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, { received, next: NEXT });
 }

package/dist/core/command.d.ts

@@ -1,4 +1,4 @@
-import type { RootHelp, RootEntry, BranchHelp, LeafHelp, InputParam, SubTier } from './help.js';
+import type { RootHelp, RootEntry, BranchHelp, LeafHelp, EffectiveLeafHelp, InputParam, SubTier } from './help.js';
 import { CrtrError } from './errors.js';
 /** Runtime context passed to a leaf's run function. Includes metadata about
  *  which parameters were explicitly provided vs. defaulted. Used by configured
@@ -47,6 +47,11 @@ export interface LeafDef {
      *  'hidden' keeps an internal leaf out of every listing. */
     tier?: SubTier;
     help: LeafHelp;
+    /** Invocation-local immutable help view. Present only on hook-eligible core
+     *  leaves; static discovery may change Effects but never executes hooks. */
+    effectiveHelp?: () => Promise<EffectiveLeafHelp>;
+    /** Opt this conditionally-void leaf out of core command hooks. */
+    hookEligible?: false;
     /** Opt into editor slash-command exposure (see SlashSpec). */
     slash?: SlashSpec;
     run: (input: Record<string, unknown>, context?: LeafRunContext) => Promise<Record<string, unknown> | void>;
@@ -100,6 +105,8 @@ export declare function defineLeaf(opts: {
     tier?: SubTier;
     help: LeafHelp;
     slash?: SlashSpec;
+    /** Opt this conditionally-void leaf out of core command hooks. */
+    hookEligible?: false;
     run: (input: Record<string, unknown>, context?: LeafRunContext) => Promise<Record<string, unknown> | void>;
     render?: (result: Record<string, unknown>) => string;
 }): LeafDef;

package/dist/core/command.js

@@ -34,6 +34,7 @@ export function defineLeaf(opts) {
         tier: opts.tier,
         help: freezeCommandMetadata(opts.help),
         slash: opts.slash === undefined ? undefined : freezeCommandMetadata(opts.slash),
+        hookEligible: opts.hookEligible,
         run: opts.run,
         render: opts.render,
     });
@@ -187,19 +188,20 @@ function renderNode(node) {
         return renderBranch(node.help);
     return renderLeafArgv(node.help);
 }
-/** Render a node's help plus any plugin help addenda targeting its walked
- *  command path — append-only, attributed blocks a plugin adds beneath core
- *  contract text, never inside it. Plugin discovery loads only here (dynamic
- *  import on the help path), so the dispatch path's module graph and cold
- *  start are unchanged; the lookup reads stored manifest bytes only. The
- *  lookup receives the install gate's exact strict-validation inputs (reserved
- *  core names + the full core command path set, both from build-root), so a
- *  manifest rejected at ingress contributes nothing here either — loading
- *  every subtree for that path set is a help-path-only cost. */
+/** Render effective Effects for a hook-eligible core leaf, then append any
+ *  commands.json helpAddenda beneath the contract. Both lookups read stored
+ *  manifest bytes only. Addenda validation receives the install gate's exact
+ *  reserved core names and full core path set, so a manifest rejected at
+ *  ingress contributes nothing here either. */
 async function renderNodeWithAddenda(node, path) {
-    const body = renderNode(node);
+    const body = node.kind === 'leaf' && node.effectiveHelp !== undefined
+        ? renderLeafArgv(await node.effectiveHelp())
+        : renderNode(node);
     if (path.length === 0)
         return body;
+    const { hasEffectiveCommandPlugins } = await import('./command-plugins/presence.js');
+    if (!hasEffectiveCommandPlugins())
+        return body;
     const [{ collectHelpAddenda }, { SUBTREE_NAMES, coreCommandPaths }] = await Promise.all([
         import('./command-plugins/help-addenda.js'),
         import('../build-root.js'),

package/dist/core/help.d.ts

@@ -216,6 +216,12 @@ export interface LeafHelp {
      *  default preview behaviour. */
     preview?: PreviewMeta;
 }
+/** Invocation-local help view for one hook-eligible core leaf. It shares every
+ *  non-effects field with the frozen core help and owns a separately frozen
+ *  effects list that describes the effective pipeline. */
+export type EffectiveLeafHelp = Readonly<Omit<LeafHelp, 'effects'> & {
+    effects: readonly string[];
+}>;
 /** 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
@@ -225,4 +231,4 @@ export interface LeafHelp {
 export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
 export declare function renderRoot(h: RootHelp): string;
 export declare function renderBranch(h: BranchHelp): string;
-export declare function renderLeafArgv(h: LeafHelp): string;
+export declare function renderLeafArgv(h: LeafHelp | EffectiveLeafHelp): string;

package/dist/core/io.d.ts

@@ -30,7 +30,7 @@ export declare function setJsonOutput(v: boolean): void;
 export declare function isJsonOutput(): boolean;
 /** Structured error payload. `error` is a stable code the agent branches on;
  *  `next` is the recovery road sign. */
-export interface ErrorPayload {
+interface ErrorPayloadBase {
     error: string;
     message: string;
     received?: unknown;
@@ -41,6 +41,13 @@ export interface ErrorPayload {
     http_status?: number;
     next: string;
 }
+export type ErrorPayload = ErrorPayloadBase & ({
+    primaryCompleted: true;
+    result: Record<string, unknown>;
+} | {
+    primaryCompleted?: never;
+    result?: never;
+});
 /** A command-level failure: surfaces as the JSON response on stdout. */
 export declare class InputError extends CrtrError {
     payload: ErrorPayload;
@@ -94,3 +101,4 @@ export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrEr
  *  Runtime/internal failures go to stderr as `{error:"internal"}` — raw traces
  *  never reach the agent. Exits non-zero either way. */
 export declare function handle(e: unknown): void;
+export {};

package/dist/core/io.js

@@ -193,16 +193,58 @@ function payloadOf(e) {
     if (e instanceof InputError)
         return e.payload;
     const d = (e.details !== undefined ? e.details : {});
+    const result = d.primaryCompleted === true
+        && d.result !== null
+        && typeof d.result === 'object'
+        && !Array.isArray(d.result)
+        ? jsonSafeResult(d.result)
+        : undefined;
     const next = d.next !== undefined
         ? d.next
         : 'Inspect the error and adjust the call. See -h for the schema.';
-    return {
+    const base = {
         error: e.code,
         message: e.message,
         received: d.received,
         field: d.field,
         ...(typeof d.http_status === 'number' ? { http_status: d.http_status } : {}),
-        next,
+    };
+    return result === undefined
+        ? { ...base, next }
+        : { ...base, primaryCompleted: true, result, next };
+}
+/** Detach completed results from getters/prototypes and keep every error sink
+ * JSON-safe. Tagged values preserve a truthful representation when a trusted
+ * primary violates its declared JSON result contract. */
+function jsonSafeResult(result) {
+    const seen = new WeakSet();
+    try {
+        const encoded = JSON.stringify(result, (_key, value) => {
+            if (typeof value === 'bigint')
+                return { $crtrType: 'bigint', value: value.toString() };
+            if (typeof value === 'number' && !Number.isFinite(value))
+                return { $crtrType: 'number', value: String(value) };
+            if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+                return { $crtrType: typeof value };
+            }
+            if (value !== null && typeof value === 'object') {
+                if (seen.has(value))
+                    return { $crtrType: 'circular' };
+                seen.add(value);
+            }
+            return value;
+        });
+        if (encoded !== undefined) {
+            const decoded = JSON.parse(encoded);
+            if (decoded !== null && typeof decoded === 'object' && !Array.isArray(decoded)) {
+                return decoded;
+            }
+        }
+    }
+    catch { /* a throwing getter/toJSON must not suppress the partial failure */ }
+    return {
+        $crtrType: 'unavailable',
+        message: 'The completed primary result could not be represented as JSON.',
     };
 }
 // ---------------------------------------------------------------------------

package/dist/core/memory/inline-ref-inventory.d.ts

@@ -6,7 +6,8 @@ import type { RefMeta } from '../runtime/broker-protocol.js';
  * (`refs`, stably sorted by winning scope then name) plus the resolution set
  * (`names` — doc names plus every proper directory prefix, because a bare-dir
  * ref is a legal listing link) that both the broker's per-submission resolver
- * and `buildGuidance` test tokens against.
+ * and `buildGuidance` test tokens against. `refs` additionally labels Gateway
+ * eligibility; the terminal viewer still receives every referenceable row.
  */
 export declare function buildRefInventory(): {
     refs: RefMeta[];

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

@@ -30,8 +30,9 @@
 // `/reload` — this module itself holds no cache beyond the session parse
 // cache it reads through.
 import { listAllMemoryDocs } from '../memory-resolver.js';
+import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from './extensions.js';
 import { parseSubstrateDoc } from '../substrate/schema.js';
-import { cachedSubstrateDocsInclusive } from '../substrate/session-cache.js';
+import { cachedAllMemoryDocsInclusive, cachedSubstrateDocsInclusive } from '../substrate/session-cache.js';
 // Display-sort weight matching resolution precedence (node > project >
 // profile > user > builtin) — display-only; resolution itself is
 // name-only (`names.has(candidate)`), never scope-aware.
@@ -49,21 +50,27 @@ const SCOPE_SORT_RANK = {
  * (`refs`, stably sorted by winning scope then name) plus the resolution set
  * (`names` — doc names plus every proper directory prefix, because a bare-dir
  * ref is a legal listing link) that both the broker's per-submission resolver
- * and `buildGuidance` test tokens against.
+ * and `buildGuidance` test tokens against. `refs` additionally labels Gateway
+ * eligibility; the terminal viewer still receives every referenceable row.
  */
 export function buildRefInventory() {
-    const docs = cachedSubstrateDocsInclusive(listAllMemoryDocs, parseSubstrateDoc);
+    const memoryDocs = cachedAllMemoryDocsInclusive(listAllMemoryDocs);
+    const substrateDocs = cachedSubstrateDocsInclusive(listAllMemoryDocs, parseSubstrateDoc);
+    const substrateDocsByPath = new Map(substrateDocs.map((doc) => [doc.path, doc]));
     // First-wins by canonical name: docs arrive already in precedence order
     // (listAllMemoryDocs' nearest-first source ordering), so the first doc seen
     // for a name is the winner.
     const winners = new Map();
-    for (const doc of docs) {
-        if (!winners.has(doc.name))
-            winners.set(doc.name, doc);
+    for (const memoryDoc of memoryDocs) {
+        const doc = substrateDocsByPath.get(memoryDoc.path);
+        if (doc !== undefined && !winners.has(doc.name))
+            winners.set(doc.name, { doc, memoryDoc });
     }
     const refs = [];
-    for (const [name, doc] of winners) {
-        refs.push({ name, kind: doc.kind, scope: doc.scope, shortForm: doc.shortForm });
+    for (const [name, { doc, memoryDoc }] of winners) {
+        const gatewayVisible = doc.scope !== 'builtin'
+            && projectEffectiveMemoryExtensions(memoryDoc.frontmatter?.['extensions'], memoryExtensionEffectiveCatalog(memoryDoc))['northlight']?.['visibility'] !== false;
+        refs.push({ name, kind: doc.kind, scope: doc.scope, shortForm: doc.shortForm, gatewayVisible });
     }
     refs.sort((a, b) => {
         const scopeDelta = SCOPE_SORT_RANK[a.scope] - SCOPE_SORT_RANK[b.scope];