@north-light/crouter 0.3.220 → 0.3.221

package/dist/commands/sys/__tests__/migrate.test.js

@@ -25,16 +25,17 @@ function write(path, content) {
     writeFileSync(path, content);
 }
 function manifest(name, projects) {
+    const first = projects[0];
     return JSON.stringify({
         schema_version: 1,
         name,
         projects,
-        home: projects[0] ?? null,
+        home: (typeof first === 'string' ? first : first?.path) ?? null,
         created_at: '2026-01-01T00:00:00.000Z',
         last_used_at: null,
     });
 }
-test('sys migrate covers profile-aware refs and every descendant project/plugin store', () => {
+test('sys migrate converges profile manifests, then profile-aware refs and every descendant project/plugin store', () => {
     const home = mkdtempSync(join(tmpdir(), 'crtr-sys-migrate-'));
     const userRoot = join(home, '.crouter');
     const rootProfile = join(userRoot, 'profiles', 'root-00000000');
@@ -52,8 +53,11 @@ test('sys migrate covers profile-aware refs and every descendant project/plugin
     const pluginDoc = join(pluginRoot, 'memory', 'plugin.md');
     const embeddedPluginDoc = join(embeddedPluginRoot, 'memory', 'plugin.md');
     try {
-        write(join(rootProfile, 'profile.json'), manifest('root', []));
-        write(join(appletProfile, 'profile.json'), manifest('applet-inactive', [appletProject, nestedOnlyProject]));
+        // Root's string entries migrate to `preview`; every other profile's to
+        // `content`. The applet manifest is mixed: its already-current entry must
+        // survive untouched while the string beside it converts.
+        write(join(rootProfile, 'profile.json'), manifest('root', [appletProject]));
+        write(join(appletProfile, 'profile.json'), manifest('applet-inactive', [{ path: appletProject, memory: 'name' }, nestedOnlyProject]));
         write(userDoc, `${OLD_DOC}\nSee [[user/scoped]].\n`);
         write(join(userRoot, 'memory', 'scoped', 'INDEX.md'), CURRENT_DOC);
         write(rootDoc, `${OLD_DOC}\nSee [[shared]].\n`);
@@ -78,8 +82,15 @@ test('sys migrate covers profile-aware refs and every descendant project/plugin
         const result = spawnSync(process.execPath, ['--conditions=crtr-src', '--import', TSX_LOADER, CLI, 'sys', 'migrate', '--json'], { cwd: home, env, encoding: 'utf8' });
         assert.equal(result.status, 0, result.stderr);
         const output = JSON.parse(result.stdout);
+        assert.equal(output.profiles, 2);
         assert.equal(output.stores, 7);
-        assert.equal(output.changed, 7);
+        assert.equal(output.changed, 9);
+        const readProjects = (dir) => JSON.parse(readFileSync(join(dir, 'profile.json'), 'utf8')).projects;
+        assert.deepEqual(readProjects(rootProfile), [{ path: appletProject, memory: 'preview' }]);
+        assert.deepEqual(readProjects(appletProfile), [
+            { path: appletProject, memory: 'name' },
+            { path: nestedOnlyProject, memory: 'content' },
+        ]);
         for (const path of [userDoc, rootDoc, appletDoc, projectDoc, deepDoc, pluginDoc, embeddedPluginDoc]) {
             const migrated = readFileSync(path, 'utf8');
             assert.doesNotMatch(migrated, /system-prompt-visibility|file-read-visibility/);

package/dist/commands/sys/doctor.js

@@ -13,10 +13,11 @@ import { readFault } from '../../core/runtime/fault.js';
 import { detectNerdFont, nerdFontInstallCommand, NERD_FONT_SELECT_HINT } from '../../core/runtime/nerd-font.js';
 import { detectPackageManager } from './setup-core.js';
 import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { discoverHookRegistry } from '../../core/command-hooks/discovery.js';
 import { resolveBinContributions } from '../../core/runtime/bin-contributions.js';
 import { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
 import { listAllPlugins } from '../../core/resolver.js';
-import { SUBTREE_NAMES, coreCommandPaths } from '../../build-root.js';
+import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
 import { processGeneration, processLocatedGeneration, runtimeManifest, selectedGeneration } from './shared.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
@@ -141,6 +142,34 @@ async function runCommandPluginChecks(scopes) {
     }
     return results;
 }
+/** Statically inspect the complete effective hook registry. This shares the
+ * runtime target catalog but never enters hook execution, preserving doctor as
+ * the recovery path for broken hooks. */
+async function runHookPluginChecks(scopes) {
+    const inScope = new Set(scopes);
+    const registry = discoverHookRegistry(await coreHookCatalog());
+    const results = [];
+    for (const validation of registry.validations) {
+        const plugin = validation.plugin;
+        if (!inScope.has(plugin.scope))
+            continue;
+        const issues = registry.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope);
+        if (issues.length === 0) {
+            const declarations = validation.hooks.map((hook) => `${hook.target} [${hook.phase} ${hook.op}]`).join('; ');
+            results.push(pass(plugin.scope, `plugin:${plugin.name}:hooks`, `effective hook declaration(s): ${declarations}`));
+            continue;
+        }
+        issues.forEach((issue, index) => {
+            const source = validation.manifestPath ?? join(plugin.root, '.crouter-plugin', 'plugin.json');
+            const detail = issue.path !== undefined ? `${source}:${issue.path}` : source;
+            results.push(failCheck(plugin.scope, `plugin:${plugin.name}:hooks[${index}]`, `${issue.code} at ${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, {
+                kind: 'human_action',
+                description: `${issue.next} Inspect with \`crtr pkg plugin show ${plugin.name}\`; then disable (\`crtr pkg plugin disable ${plugin.name} --scope ${plugin.scope}\`), update (\`crtr pkg plugin update --name ${plugin.name}\`), or remove (\`crtr pkg plugin remove ${plugin.name}\`) the plugin.`,
+            }));
+        });
+    }
+    return results;
+}
 /**
  * Report every bare-binary contribution (`bin` in a plugin manifest or a scope
  * `config.json`) that failed to reach a node's PATH, plus the ones that did.
@@ -467,7 +496,7 @@ function runChecksForScope(scope, opts) {
 export const sysDoctorLeaf = defineLeaf({
     name: 'doctor',
     description: 'diagnose installation health',
-    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or a plugin command manifest/transport is malformed. Reports each problem with a structured remediation, and can apply the safe repairs for you.',
+    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or a plugin command/hook declaration is malformed. Reports each problem with a structured remediation, and can apply the safe repairs for you.',
     help: {
         name: 'sys doctor',
         summary: 'diagnose runtime integrity, missing manifests, and broken config entries',
@@ -477,13 +506,13 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin manifest checks appear as plugin:<name>:commands (validated statically, never executed); their remediation is always a human_action (disable/update/remove the plugin). remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/collision problems and carry disable/update/remove/show remediation; healthy hooks list effective target, phase, and op. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
-            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command manifests, bare-binary (`bin`) declarations, and advisory `requires` PATH checks never execute plugin or contributed binaries.',
-            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and plugin command findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
+            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command and hook manifests, bare-binary (`bin`) declarations, and advisory `requires` PATH checks never execute plugin or contributed binaries.',
+            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and plugin command/hook findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
             'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with its command) so callers can apply it directly without --fix.',
         ],
     },
@@ -500,6 +529,7 @@ export const sysDoctorLeaf = defineLeaf({
         if (scopes.includes('user'))
             allResults.push(runNerdFontCheck());
         allResults.push(...await runCommandPluginChecks(scopes));
+        allResults.push(...await runHookPluginChecks(scopes));
         allResults.push(...runBinContributionChecks(scopes));
         allResults.push(...runRequiresChecks(scopes));
         allResults.push(...await runFaultChecks());

package/dist/commands/sys/migrate.js

@@ -1,24 +1,32 @@
-// `crtr sys migrate` — the convergent-lane state-migration runner: converge
-// every writable memory store's documents to the current document format.
-// (Journaled canvas-db migrations run in the db's own ordered chain when the
-// daemon opens it; this leaf owns only the on-disk document stores.)
+// `crtr sys migrate` — the on-disk state-migration runner: converge every
+// stored profile manifest to the current manifest format, then every writable
+// memory store's documents to the current document format. (Journaled
+// canvas-db migrations run in the db's own ordered chain when the daemon opens
+// it; this leaf owns only the on-disk state.)
+//
+// Manifests come FIRST and are read as raw bytes under the profile lock: the
+// current reader treats a pre-migration manifest exactly like corrupt JSON, so
+// `listProfiles()` sees nothing until this lane has run. Store discovery below
+// therefore works from the lane's post-migration snapshots — which are equally
+// coherent under `--dry-run`, where the same fold ran and nothing was written.
 import { dirname, join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { pathExists, realpathOrSelf } from '../../core/fs-utils.js';
 import { createMemoryDocSnapshot } from '../../core/memory-resolver.js';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
 import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
-import { listProfiles, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { profileMemoryDir, profilesRoot, withProfileManifestLock } from '../../core/profiles/manifest.js';
 import { descendantStoreRootsExhaustive } from '../../core/nested-stores.js';
 import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
 import { runConvergentMigrations } from '../../migrations/convergent.js';
+import { runProfileManifestMigrations } from '../../migrations/profile-manifests.js';
 function targetKey(target) {
     return `${realpathOrSelf(target.cwd)}\u0000${target.profileId ?? ''}\u0000${target.nodeId ?? ''}`;
 }
 /** Every writable memory store — the lint corpus minus builtin (package-owned,
  *  regenerated on every install, so migrating it would fight the package).
  *  Physical stores dedupe once while retaining every owning target corpus. */
-function migratableStores() {
+function migratableStores(profiles) {
     const stores = new Map();
     const add = (dir, target) => {
         if (dir === null || dir === '' || !pathExists(dir))
@@ -49,18 +57,18 @@ function migratableStores() {
     };
     const selectedProfileId = process.env['CRTR_PROFILE_ID'] || null;
     addProjectRoots(projectScopeRoots(process.cwd(), null), selectedProfileId);
-    const profiles = listProfiles();
     const profileTargets = [];
     for (const { profileId, manifest } of profiles) {
+        const home = manifest.home !== null && manifest.home !== '' ? manifest.home : null;
         const profileTarget = {
-            cwd: manifest.home ?? manifest.projects[0] ?? process.cwd(),
+            cwd: home ?? manifest.projects[0]?.path ?? process.cwd(),
             profileId,
             nodeId: null,
         };
         profileTargets.push(profileTarget);
         add(profileMemoryDir(profileId), profileTarget);
         const roots = [
-            ...new Set(manifest.projects.flatMap((project) => [join(project, '.crouter'), ...projectScopeRoots(project, null)])),
+            ...new Set(manifest.projects.flatMap((project) => [join(project.path, '.crouter'), ...projectScopeRoots(project.path, null)])),
         ];
         addProjectRoots(roots, profileId);
     }
@@ -82,23 +90,25 @@ function migratableStores() {
 }
 export const sysMigrateLeaf = defineLeaf({
     name: 'migrate',
-    description: 'converge every writable memory store to the current document format',
-    whenToUse: 'after a crtr update whose release notes name a document-format migration, or when old-format docs resurface (a restore, a sync, a hand-authored file). Convergent and idempotent: re-running over a current corpus changes nothing, so use --dry-run first only when you want to review the rewrite.',
+    description: 'converge every profile manifest and writable memory store to the current on-disk format',
+    whenToUse: 'after a crtr update whose release notes name a state migration, when profiles stop resolving on a home that predates the update, or when old-format docs resurface (a restore, a sync, a hand-authored file). Convergent and idempotent: re-running over current state changes nothing, so use --dry-run first only when you want to review the rewrite.',
     help: {
         name: 'sys migrate',
-        summary: 'run the registered document-format migrations over every writable memory store',
+        summary: 'run the registered state migrations over every profile manifest and writable memory store',
         params: [
             { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Plan and report every rewrite without writing any file.' },
         ],
         output: [
+            { name: 'profiles', type: 'number', required: true, constraint: 'Profile manifests scanned.' },
             { name: 'stores', type: 'number', required: true, constraint: 'Memory stores scanned.' },
-            { name: 'changed', type: 'number', required: true, constraint: 'Files rewritten (or, under --dry-run, that would be).' },
-            { name: 'applied', type: 'object[]', required: true, constraint: 'One row per migration that changed files in a store: {store, migration, files}. Empty when the corpus is already current.' },
-            { name: 'skipped', type: 'object[]', required: true, constraint: 'Docs left untouched because their frontmatter is not valid YAML: {store, relPath, error}. Fix the doc, then re-run.' },
+            { name: 'changed', type: 'number', required: true, constraint: 'Files rewritten (or, under --dry-run, that would be) — manifests and documents together.' },
+            { name: 'applied', type: 'object[]', required: true, constraint: 'One row per migration that changed files: {store, lane, migration, files}, lane one of profile-manifest, convergent. Empty when the state is already current.' },
+            { name: 'skipped', type: 'object[]', required: true, constraint: 'Files left untouched because they could not be parsed — a doc whose frontmatter is not valid YAML, or a manifest that is not valid JSON: {store, relPath, error}. Fix the file, then re-run.' },
             { name: 'dryRun', type: 'boolean', required: true, constraint: 'True when nothing was written (preview only).' },
         ],
         outputKind: 'object',
         effects: [
+            'Rewrites old-format `profile.json` manifests in place (atomic, under the same per-profile lock `profile project add/remove` take). A manifest whose structure cannot be converted fails the whole run — no project setting is ever guessed.',
             'Rewrites old-format memory documents in place (atomic per-file writes) across the writable stores: every profile and every profile-owned project (plus nested descendant stores and installed plugin stores), the current project, user, and this node\'s store. Builtin docs are package-owned and never touched.',
             'Under --dry-run: read-only, writes nothing.',
         ],
@@ -107,7 +117,15 @@ export const sysMigrateLeaf = defineLeaf({
         const dryRun = input.dryRun === true;
         const applied = [];
         const skipped = [];
-        const stores = migratableStores();
+        const profilesDir = profilesRoot();
+        const profileRun = runProfileManifestMigrations(profilesDir, { dryRun, withLock: withProfileManifestLock });
+        for (const row of profileRun.applied) {
+            applied.push({ store: profilesDir, lane: 'profile-manifest', migration: row.migration, files: [row.path] });
+        }
+        for (const row of profileRun.skipped) {
+            skipped.push({ store: profilesDir, relPath: `${row.profileId}/profile.json`, error: row.error });
+        }
+        const stores = migratableStores(profileRun.snapshots);
         const snapshots = new Map();
         for (const store of stores) {
             const resolvers = store.targets.map((target) => (name) => {
@@ -137,21 +155,22 @@ export const sysMigrateLeaf = defineLeaf({
                 },
             });
             for (const row of result.applied)
-                applied.push({ store: store.dir, migration: row.migration, files: row.files });
+                applied.push({ store: store.dir, lane: 'convergent', migration: row.migration, files: row.files });
             for (const s of result.skipped)
                 skipped.push({ store: store.dir, relPath: s.relPath, error: s.error });
         }
         const changed = applied.reduce((n, row) => n + row.files.length, 0);
         return {
+            profiles: profileRun.profiles,
             stores: stores.length,
             changed,
             applied,
             skipped,
             dryRun,
             follow_up: skipped.length > 0
-                ? 'Some docs have invalid YAML frontmatter and were left untouched — fix each named file, then re-run `crtr sys migrate`.'
+                ? 'Some files could not be parsed and were left untouched — fix each named file, then re-run `crtr sys migrate`.'
                 : changed === 0
-                    ? 'Corpus already current — nothing to rewrite.'
+                    ? 'State already current — nothing to rewrite.'
                     : dryRun
                         ? 'Preview only — re-run without --dry-run to write these changes.'
                         : undefined,

package/dist/commands/sys/setup-core.js

@@ -535,7 +535,7 @@ export async function executeSetupSubmission(submission) {
                 const registered = ensureMarketplaceRegistered(marketplace);
                 if (registered !== null)
                     installedPackages.push(registered);
-                installFromMarketplace({ marketplace: marketplace, plugin: plugin }, 'user');
+                await installFromMarketplace({ marketplace: marketplace, plugin: plugin }, 'user');
                 installedPackages.push(entry.name);
             }
             catch (e) {

package/dist/commands/sys/sync-project-guidance.js

@@ -36,7 +36,7 @@ function projectDocRoots(sourceArg) {
         try {
             const { manifest } = loadProfileManifest(profileId);
             for (const p of manifest.projects) {
-                const r = resolve(p);
+                const r = resolve(p.path);
                 if (!roots.includes(r))
                     roots.push(r);
             }

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.js

@@ -271,7 +271,7 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         homes.push(userHome);
         process.env.HOME = userHome;
         try {
-            const profile = createProfile('paused watcher', ['/tmp']);
+            const profile = createProfile('paused watcher', [{ path: '/tmp', memory: 'content' }]);
             pauseProfile(profile.profileId);
             process.env['CRTR_PROFILE_ID'] = profile.profileId;
             const pi = makeFakePi();

package/dist/core/__tests__/fixtures/c5-command-boundary-ext.js

@@ -5,4 +5,28 @@ export default function (pi) {
             /* never invoked — isLeadingEngineCommand only checks registration */
         },
     });
+    pi.registerCommand('gatewaycmd', {
+        description: 'Gateway-advertised custom-message fixture',
+        gateway: true,
+        handler: async () => {
+            pi.sendMessage({
+                customType: 'fixture-output',
+                content: 'expanded agent input',
+                display: true,
+                details: { fixture: true },
+            });
+        },
+    });
+    pi.registerCommand('gatewaynext', {
+        description: 'Queued Gateway custom-message fixture',
+        gateway: true,
+        handler: async () => {
+            pi.sendMessage({
+                customType: 'fixture-next-output',
+                content: null,
+                display: true,
+                details: 'extension-details',
+            }, { deliverAs: 'nextTurn' });
+        },
+    });
 }

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -107,6 +107,28 @@ interface SessionTreeNode {
     entry: TreeEntry;
     children: SessionTreeNode[];
 }
+/** The real SessionManager surface the broker reads and patches. A method
+ *  missing here is a broken fixture, not a degraded one — the broker throws
+ *  during session build and never boots. */
+interface FakeSessionManager {
+    buildSessionContext: () => {
+        messages: AgentMessage[];
+        thinkingLevel: string;
+        model: null;
+    };
+    getLeafId: () => string | null;
+    getEntry: (id: string) => TreeEntry | undefined;
+    getTree: () => SessionTreeNode[];
+    getUserMessagesForForking: () => Array<{
+        entryId: string;
+        text: string;
+        timestamp?: string;
+    }>;
+    getSessionId: () => string;
+    getSessionFile: () => string;
+    getSessionDir: () => string;
+    appendCustomMessageEntry: (customType: string, content: unknown, display: boolean, details?: unknown) => string;
+}
 declare class FakeSession {
     private readonly sm;
     private readonly loader;
@@ -142,24 +164,8 @@ declare class FakeSession {
     private readonly modelRt;
     constructor(sm: SessionManager, loader: ResourceLoader | undefined, model?: FakeModel, modelRuntime?: FakeModelRuntime);
     get messages(): AgentMessage[];
-    get sessionManager(): {
-        buildSessionContext: () => {
-            messages: AgentMessage[];
-            thinkingLevel: string;
-            model: null;
-        };
-        getLeafId: () => string | null;
-        getEntry: (id: string) => TreeEntry | undefined;
-        getTree: () => SessionTreeNode[];
-        getUserMessagesForForking: () => Array<{
-            entryId: string;
-            text: string;
-            timestamp?: string;
-        }>;
-        getSessionId: () => string;
-        getSessionFile: () => string;
-        getSessionDir: () => string;
-    };
+    private smFacade;
+    get sessionManager(): FakeSessionManager;
     get sessionId(): string;
     get sessionFile(): string | undefined;
     get model(): FakeModel | undefined;

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -341,8 +341,13 @@ class FakeSession {
     // truth, since `session.messages` can be sliced by pi's retry/overflow/
     // compaction recovery. Mirror that surface so the fake's snapshot still serves
     // the accrued history (G2/G3). The fake's persisted analog is the active branch.
+    // Built once and cached: the real SessionManager is a single object the
+    // broker's advertised-command contract monkey-patches
+    // (appendCustomMessageEntry), so a fresh literal per access would silently
+    // discard that patch.
+    smFacade;
     get sessionManager() {
-        return {
+        this.smFacade ??= {
             buildSessionContext: () => this.tree.buildSessionContext(),
             getLeafId: () => this.tree.getLeafId(),
             getEntry: (id) => this.tree.getEntry(id),
@@ -351,7 +356,9 @@ class FakeSession {
             getSessionId: () => this.sm.getSessionId(),
             getSessionFile: () => this.sm.getSessionFile(),
             getSessionDir: () => this.sm.getSessionDir(),
+            appendCustomMessageEntry: (customType, content, display, details) => this.tree.append({ role: 'custom', customType, content, display, details }).id,
         };
+        return this.smFacade;
     }
     get sessionId() {
         return this.sm.getSessionId();

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -14,6 +14,7 @@ import { resetScopeCache } from '../scope.js';
 import { clearSessionCache } from '../substrate/session-cache.js';
 import { memoryDir as nodeMemoryDir } from '../runtime/memory.js';
 import { buildRefInventory } from '../memory/inline-ref-inventory.js';
+import { gatewayMemoryRows } from '../runtime/broker-inventory.js';
 // ---------------------------------------------------------------------------
 // Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
 // backed (node/project/user scope docs on disk), since precedence dedup,
@@ -47,6 +48,21 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
     function nodeScopeMemoryDir() {
         return nodeMemoryDir(NODE_ID);
     }
+    function plantNorthlightVisibilityExtension() {
+        const manifestDir = join(userHome, '.crouter', 'plugins', 'northlight', '.crouter-plugin');
+        mkdirSync(manifestDir, { recursive: true });
+        writeFileSync(join(manifestDir, 'plugin.json'), JSON.stringify({
+            name: 'northlight',
+            memory_extensions: {
+                visibility: {
+                    type: 'boolean',
+                    default: true,
+                    write_help: 'Control chat visibility.',
+                    edit_help: 'Control chat visibility.',
+                },
+            },
+        }));
+    }
     before(() => {
         prevCanvasHome = process.env['CRTR_HOME'];
         prevUserHome = process.env['HOME'];
@@ -148,12 +164,30 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         // A sibling doc in the same corpus is unaffected.
         assert.ok(names.has('crtr-inline-ref-fixture-sibling'));
     });
-    test('refs are metadata-only: exactly {name, kind, scope, shortForm}, no body/path', () => {
+    test('refs are metadata-only: exactly {name, kind, scope, shortForm, gatewayVisible}, no body/path', () => {
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-meta.md', "kind: knowledge\nshort-form: 'hook'");
         const { refs } = buildRefInventory();
         const ref = refs.find((r) => r.name === 'crtr-inline-ref-fixture-meta');
         assert.ok(ref);
-        assert.deepEqual(Object.keys(ref).sort(), ['kind', 'name', 'scope', 'shortForm']);
+        assert.deepEqual(Object.keys(ref).sort(), ['gatewayVisible', 'kind', 'name', 'scope', 'shortForm']);
+    });
+    test('Gateway eligibility excludes builtins and effective Northlight-hidden refs without changing resolution', () => {
+        plantNorthlightVisibilityExtension();
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-hidden.md', 'kind: knowledge\nextensions:\n  northlight:\n    visibility: false');
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-visible.md', 'kind: knowledge');
+        const { refs, names } = buildRefInventory();
+        const hidden = refs.find((ref) => ref.name === 'crtr-inline-ref-fixture-hidden');
+        const visible = refs.find((ref) => ref.name === 'crtr-inline-ref-fixture-visible');
+        assert.equal(hidden?.gatewayVisible, false);
+        assert.equal(visible?.gatewayVisible, true);
+        assert.ok(names.has('crtr-inline-ref-fixture-hidden'));
+        assert.ok(names.has('crtr-inline-ref-fixture-visible'));
+        assert.ok(refs.some((ref) => ref.scope === 'builtin'));
+        assert.ok(refs.filter((ref) => ref.scope === 'builtin').every((ref) => !ref.gatewayVisible));
+        const chatRows = gatewayMemoryRows(refs);
+        assert.ok(!chatRows.some((ref) => ref.name === 'crtr-inline-ref-fixture-hidden'));
+        assert.ok(chatRows.some((ref) => ref.name === 'crtr-inline-ref-fixture-visible'));
+        assert.ok(!chatRows.some((ref) => ref.scope === 'builtin'));
     });
     test('a malformed doc (no valid kind) is omitted from the inventory', () => {
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-malformed.md', "short-form: 'no kind here'");