@north-light/crouter 0.3.220 → 0.3.222

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];

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

@@ -1,4 +1,5 @@
 import { type InstalledPlugin, type Scope } from '../types.js';
+import type { ProfileProjectMemory } from '../api/dto/profiles.js';
 /**
  * Thin memory-document resolver for the document substrate. Resolution has
  * two passes. First, scopes/sources are tried NEAREST-FIRST (node > project
@@ -17,6 +18,11 @@ import { type InstalledPlugin, type Scope } from '../types.js';
  * a selected profile's `projects` manifest entries — see `findProjectScopeRoots`
  * in scope.ts), profile is the selected profile's own singleton `memory/` store
  * (from `CRTR_PROFILE_ID`), and user/builtin remain singleton scopes.
+ *
+ * Every doc also carries its project store's profile relationship ceiling
+ * (`projectMemory`) for the automatic delivery paths to clamp against.
+ * Resolution itself never consults it: the full corpus resolves and lists
+ * regardless of the ceiling.
  */
 export interface MemoryDoc {
     /** Resolver identity: the doc's explicit frontmatter `name` when present,
@@ -41,6 +47,12 @@ export interface MemoryDoc {
      *  managed by `crtr pkg`, not writable/deletable as scope docs — consumers
      *  that mutate the store gate on this. */
     plugin?: string;
+    /** The selected profile relationship's ceiling for the project store this doc
+     *  came from: the maximum rung AUTOMATIC boot and workspace-open delivery may
+     *  disclose it at. Always present; `content` (neutral, i.e. uncapped) for
+     *  every non-project scope and for a project root no profile entry
+     *  contributes. Resolution, listing, and targeted reads ignore it entirely. */
+    projectMemory: ProfileProjectMemory;
 }
 /** The memory-only scope union: the global `Scope` (`user|project|builtin`)
  *  plus `profile` and `node`. Confined to the memory resolver/list/read/write/
@@ -107,7 +119,7 @@ export declare function listMemoryDocs(scope: MemoryScope, quiet?: boolean): Mem
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
-export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: MemoryScope, quiet?: boolean): MemoryDoc[];
+export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: MemoryScope, quiet?: boolean, projectMemory?: ProfileProjectMemory): MemoryDoc[];
 /** 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

package/dist/core/memory-resolver.js

@@ -6,7 +6,7 @@ import { parseFrontmatterGeneric } from './frontmatter.js';
 import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier } from './resolver.js';
 import { ambiguous, notFound, usage } from './errors.js';
 import { warn } from './output.js';
-import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from './scope.js';
+import { NEUTRAL_PROJECT_MEMORY, pluginMemoryDir, projectScopeRoots, projectScopeRootsWithMemory, scopeMemoryDir } from './scope.js';
 import { effectiveDocKind, normalizeDocName, normalizeNameSegment, resolveDocName } from './substrate/schema.js';
 import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 import { memoryDir as nodeMemoryDir } from './runtime/memory.js';
@@ -74,22 +74,26 @@ function memorySourcesInPrecedence(target, scope, includeDescendants = false) {
     const out = [];
     for (const s of scopesInPrecedence(target, scope)) {
         if (s === 'project') {
-            const roots = projectScopeRoots(target.cwd, target.profileId);
-            for (const root of roots) {
+            const annotated = projectScopeRootsWithMemory(target.cwd, target.profileId);
+            for (const { root, memory } of annotated) {
                 out.push({
                     scope: 'project',
                     memoryDir: join(root, 'memory'),
                     plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
+                    projectMemory: memory,
                 });
             }
             // Descendant stores rank after every ancestor source (and before
             // profile): an ancestor doc always beats a nested doc on a name tie.
+            // They carry the neutral ceiling — no profile entry names them, and
+            // descendant discovery is off for every automatic delivery path.
             if (includeDescendants) {
-                for (const root of descendantStoreRoots(roots)) {
+                for (const root of descendantStoreRoots(annotated.map(({ root: r }) => r))) {
                     out.push({
                         scope: 'project',
                         memoryDir: join(root, 'memory'),
                         plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
+                        projectMemory: NEUTRAL_PROJECT_MEMORY,
                     });
                 }
             }
@@ -99,7 +103,7 @@ function memorySourcesInPrecedence(target, scope, includeDescendants = false) {
             if (profileId !== '') {
                 try {
                     const { profileId: resolvedId } = loadProfileManifest(profileId);
-                    out.push({ scope: 'profile', memoryDir: profileMemoryDir(resolvedId), plugins: [] });
+                    out.push({ scope: 'profile', memoryDir: profileMemoryDir(resolvedId), plugins: [], projectMemory: NEUTRAL_PROJECT_MEMORY });
                 }
                 catch {
                     // Missing/deleted/invalid selected profile: no profile memory source.
@@ -111,27 +115,28 @@ function memorySourcesInPrecedence(target, scope, includeDescendants = false) {
             // Silently absent when the target names no node.
             const nodeId = target.nodeId ?? '';
             if (nodeId !== '')
-                out.push({ scope: 'node', memoryDir: nodeMemoryDir(nodeId), plugins: [] });
+                out.push({ scope: 'node', memoryDir: nodeMemoryDir(nodeId), plugins: [], projectMemory: NEUTRAL_PROJECT_MEMORY });
         }
         else {
             out.push({
                 scope: s,
                 memoryDir: scopeMemoryDir(s),
                 plugins: listInstalledPlugins(s).filter((p) => p.enabled),
+                projectMemory: NEUTRAL_PROJECT_MEMORY,
             });
         }
     }
     return out;
 }
-function loadMemoryDoc(scope, root, path, fallbackName) {
+function loadMemoryDoc(scope, root, path, fallbackName, projectMemory = NEUTRAL_PROJECT_MEMORY) {
     const { data, body } = parseFrontmatterGeneric(readText(path));
-    return { name: resolveDocName(data, fallbackName), scope, path, root, frontmatter: data, body };
+    return { name: resolveDocName(data, fallbackName), scope, path, root, frontmatter: data, body, projectMemory };
 }
 /** All memory docs in one memory/ dir, scanned recursively for *.md (topical
  *  subdirs supported), sorted by resolver identity (explicit frontmatter name
  *  when present, else path-derived). SKILL.md bundles are legacy Agent Skills
  *  and are ignored; crouter memory docs are plain .md files under memory/. */
-function listMemoryDocsInDir(scope, dir, quiet = false) {
+function listMemoryDocsInDir(scope, dir, quiet = false, projectMemory = NEUTRAL_PROJECT_MEMORY) {
     if (!dir || !pathExists(dir))
         return [];
     const docs = [];
@@ -171,7 +176,7 @@ function listMemoryDocsInDir(scope, dir, quiet = false) {
         // `quiet` suppresses the notice for a targeted resolve (a leaf-name read),
         // where another doc's health is irrelevant noise before the result.
         try {
-            docs.push(loadMemoryDoc(scope, dir, path, name));
+            docs.push(loadMemoryDoc(scope, dir, path, name, projectMemory));
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -214,7 +219,7 @@ export function listMemoryDocs(scope, quiet = false) {
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
-export function listPluginMemoryDocs(plugin, scope, quiet = false) {
+export function listPluginMemoryDocs(plugin, scope, quiet = false, projectMemory = NEUTRAL_PROJECT_MEMORY) {
     const dir = pluginMemoryDir(plugin);
     if (!pathExists(dir))
         return [];
@@ -225,7 +230,7 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
             continue;
         const name = `${plugin.name}/${derived}`;
         try {
-            docs.push({ ...loadMemoryDoc(scope, dir, file, name), plugin: plugin.name });
+            docs.push({ ...loadMemoryDoc(scope, dir, file, name, projectMemory), plugin: plugin.name });
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -241,8 +246,8 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
  *  (consults one source's docs at a time, nearest source first). */
 function sourceMemoryDocs(source, quiet = false) {
     return [
-        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet),
-        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet)),
+        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet, source.projectMemory),
+        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet, source.projectMemory)),
     ];
 }
 /** All project-scoped docs visible from an explicit node workspace/profile — the
@@ -250,10 +255,11 @@ function sourceMemoryDocs(source, quiet = false) {
  *  are wanted (a workspace-open render). For a full-precedence target-addressed
  *  lookup, use `resolveMemoryDocForTarget`. */
 export function listProjectMemoryDocs(startDir = process.cwd(), profileId = selectedProfileId() || null, quiet = false) {
-    return projectScopeRoots(startDir, profileId).flatMap((root) => sourceMemoryDocs({
+    return projectScopeRootsWithMemory(startDir, profileId).flatMap(({ root, memory }) => sourceMemoryDocs({
         scope: 'project',
         memoryDir: join(root, 'memory'),
         plugins: listInstalledPluginsInRoot('project', root).filter((plugin) => plugin.enabled),
+        projectMemory: memory,
     }, quiet));
 }
 /** All memory docs across the resolved sources, in precedence order: each
@@ -307,7 +313,7 @@ function matchNormalizedChild(dir, segment, want, ext = '.md') {
  *  directory by normalized name, then resolve the final segment as either a
  *  `.md` file or a directory. Either half is null when
  *  the segment path does not resolve that way. This is what makes
- *  `00-runtime-base.md` findable as `runtime-base` and `01-spine/00-has-manager`
+ *  `00-runtime-base/00-authoring.md` findable as `runtime-base/authoring` and `01-spine/00-has-manager`
  *  findable as `spine/has-manager` — the physical path keeps its pins, only
  *  lookup is prefix-blind. */
 function resolveNormalizedPath(baseDir, segments, ext = '.md') {
@@ -351,11 +357,11 @@ function findMemoryMatchInSource(name, segments, source, legacyDirectoryIndex =
     if (dir) {
         const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
         if (!isLegacySkillDoc && filePath !== null)
-            return loadMemoryDoc(source.scope, dir, filePath, name);
+            return loadMemoryDoc(source.scope, dir, filePath, name, source.projectMemory);
         if (legacyDirectoryIndex && dirPath !== null) {
             const indexPath = join(dirPath, 'INDEX.md');
             if (pathExists(indexPath))
-                return loadMemoryDoc(source.scope, dir, indexPath, name);
+                return loadMemoryDoc(source.scope, dir, indexPath, name, source.projectMemory);
         }
     }
     // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
@@ -374,14 +380,14 @@ function findMemoryMatchInSource(name, segments, source, legacyDirectoryIndex =
         if (restSegments.length > 0) {
             const { filePath } = resolveNormalizedPath(pdir, restSegments);
             if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
-                return loadMemoryDoc(source.scope, pdir, filePath, name);
+                return loadMemoryDoc(source.scope, pdir, filePath, name, source.projectMemory);
         }
         if (legacyDirectoryIndex) {
             const indexDir = rest === '' ? pdir : resolveNormalizedPath(pdir, restSegments).dirPath;
             if (indexDir !== null) {
                 const indexPath = join(indexDir, 'INDEX.md');
                 if (pathExists(indexPath))
-                    return loadMemoryDoc(source.scope, pdir, indexPath, name);
+                    return loadMemoryDoc(source.scope, pdir, indexPath, name, source.projectMemory);
             }
         }
     }

package/dist/core/profiles/manifest.d.ts

@@ -1,9 +1,16 @@
 import type { ProfileManifest } from '../../types.js';
+import type { ProfileProject, ProfileProjectMemory } from '../../api/dto/profiles.js';
 export declare const ROOT_PROFILE_ID = "root-00000000";
 export declare function profilesRoot(): string;
 export declare function profileRoot(profileId: string): string;
 export declare function profileManifestPath(profileId: string): string;
 export declare function profileMemoryDir(profileId: string): string;
+/** Reject anything a valid project array may not carry. Shape only: takes
+ *  `unknown` because an API body and a hand-edited manifest both prove nothing
+ *  at runtime, and deliberately says nothing about whether a path exists —
+ *  existence and realpath resolution belong to the create/add paths alone, so
+ *  a request naming a since-deleted directory still validates. */
+export declare function assertProfileProjects(entries: unknown): asserts entries is ProfileProject[];
 /** The directory a node running under `profileId` is pinned to — the profile's
  *  home, but only while it still exists on disk (a node pinned to a deleted dir
  *  cannot boot). Null for the root profile, a profile with no projects, a home
@@ -52,7 +59,7 @@ export declare function assertProfileMetadata(entries: unknown): asserts entries
  *  Never throws; on an env-name collision the first entry wins (matching
  *  injection, where a deterministic winner beats insertion-order luck). */
 export declare function sanitizeProfileMetadata(stored: unknown): Record<string, string>;
-export declare function createProfile(name: string, projects?: string[], opts?: {
+export declare function createProfile(name: string, projects?: ProfileProject[], opts?: {
     defaultKind?: string;
     metadata?: Record<string, string>;
 }): ProfileEntry;
@@ -80,7 +87,11 @@ export declare function updateProfileMetadata(profileId: string, set: Record<str
  *  over a bad profile id (mirrors `readProfileEnvVars`). */
 export declare function readProfileMetadata(profileId: string | null): Record<string, string>;
 export declare function renameProfile(profileId: string, name: string): ProfileEntry;
-export declare function addProfileProject(profileId: string, dir: string, opts?: {
+/** Upsert: a new path appends, an existing one keeps its position and takes
+ *  the supplied memory value. Every caller names a memory value — a profile
+ *  relationship never acquires one by default. */
+export declare function addProfileProject(profileId: string, dir: string, opts: {
+    memory: ProfileProjectMemory;
     home?: boolean;
 }): ProfileEntry;
 export declare function removeProfileProject(profileId: string, dir: string): ProfileEntry;

package/dist/core/profiles/manifest.js

@@ -9,6 +9,7 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, join, relative, resolve as resolvePath, sep } from 'node:path';
 import { SCHEMA_VERSION, PROFILE_DIR } from '../../types.js';
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
 import { userScopeRoot, resetScopeCache } from '../scope.js';
 import { ensureDir, nowIso } from '../fs-utils.js';
 import { usage, notFound, ambiguous, general } from '../errors.js';
@@ -84,15 +85,68 @@ export function profileMemoryDir(profileId) {
  *  the user started them, not in whatever dir was last added to its purview. */
 function normalizeHome(profileId, manifest) {
     const stored = typeof manifest.home === 'string' && manifest.home !== '' ? manifest.home : null;
-    const home = profileId === ROOT_PROFILE_ID ? stored : stored ?? manifest.projects[0] ?? null;
+    const home = profileId === ROOT_PROFILE_ID ? stored : stored ?? manifest.projects[0]?.path ?? null;
     const pausedAt = typeof manifest.paused_at === 'string' && manifest.paused_at !== '' ? manifest.paused_at : null;
     return { ...manifest, home, paused_at: pausedAt };
 }
+/** Reject anything a valid project array may not carry. Shape only: takes
+ *  `unknown` because an API body and a hand-edited manifest both prove nothing
+ *  at runtime, and deliberately says nothing about whether a path exists —
+ *  existence and realpath resolution belong to the create/add paths alone, so
+ *  a request naming a since-deleted directory still validates. */
+export function assertProfileProjects(entries) {
+    const memories = PROFILE_PROJECT_MEMORY_VALUES.join(', ');
+    if (!Array.isArray(entries)) {
+        throw usage('projects must be an array of {path, memory} objects', {
+            received: typeof entries,
+            field: 'projects',
+            next: `Pass entries like {"path": "/abs/dir", "memory": "content"} — memory is one of: ${memories}.`,
+        });
+    }
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw usage(`invalid project entry: ${JSON.stringify(entry)}`, {
+                field: 'projects',
+                next: 'Every project is an object like {"path": "/abs/dir", "memory": "content"}.',
+            });
+        }
+        const { path, memory } = entry;
+        if (typeof path !== 'string' || path.trim() === '') {
+            throw usage(`project entry has no path: ${JSON.stringify(entry)}`, {
+                field: 'projects',
+                next: 'Give every project entry a non-empty directory path.',
+            });
+        }
+        if (typeof memory !== 'string' || !PROFILE_PROJECT_MEMORY_VALUES.includes(memory)) {
+            throw usage(`invalid project memory value: ${JSON.stringify(memory)}`, {
+                received: String(memory),
+                field: 'projects',
+                next: `Set memory on ${path} to one of: ${memories}.`,
+            });
+        }
+    }
+}
+function hasCurrentProjectShape(projects) {
+    try {
+        assertProfileProjects(projects);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A manifest whose projects are not the current object shape is unreadable —
+ *  the same treatment as corrupt JSON, so nothing downstream ever guesses a
+ *  memory value. `crtr sys migrate` reads raw bytes and is the only converter
+ *  of pre-object manifests. */
 function readManifestFile(path, profileId) {
     if (!existsSync(path))
         return null;
     try {
-        return normalizeHome(profileId, JSON.parse(readFileSync(path, 'utf8')));
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!hasCurrentProjectShape(parsed.projects))
+            return null;
+        return normalizeHome(profileId, parsed);
     }
     catch {
         return null;
@@ -231,14 +285,15 @@ function resolveExistingProjectDir(dir) {
         return abs;
     }
 }
-function dedupeOrdered(values) {
+/** First-wins by resolved path, manifest order preserved. */
+function dedupeProjects(entries) {
     const seen = new Set();
     const out = [];
-    for (const v of values) {
-        if (seen.has(v))
+    for (const entry of entries) {
+        if (seen.has(entry.path))
             continue;
-        seen.add(v);
-        out.push(v);
+        seen.add(entry.path);
+        out.push(entry);
     }
     return out;
 }
@@ -374,14 +429,15 @@ export function createProfile(name, projects = [], opts = {}) {
         throw usage('profile name must not be empty');
     if (opts.metadata !== undefined)
         assertProfileMetadata(opts.metadata);
-    const resolvedProjects = dedupeOrdered(projects.map(resolveExistingProjectDir));
+    assertProfileProjects(projects);
+    const resolvedProjects = dedupeProjects(projects.map((p) => ({ path: resolveExistingProjectDir(p.path), memory: p.memory })));
     const profileId = generateProfileId(trimmed);
     return withProfileManifestLock(profileId, () => {
         const manifest = {
             schema_version: SCHEMA_VERSION,
             name: trimmed,
             projects: resolvedProjects,
-            home: resolvedProjects[0] ?? null,
+            home: resolvedProjects[0]?.path ?? null,
             paused_at: null,
             ...(opts.defaultKind !== undefined ? { default_kind: opts.defaultKind } : {}),
             ...(opts.metadata !== undefined && Object.keys(opts.metadata).length > 0 ? { metadata: { ...opts.metadata } } : {}),
@@ -510,13 +566,23 @@ export function renameProfile(profileId, name) {
     resetScopeCache();
     return result;
 }
-export function addProfileProject(profileId, dir, opts = {}) {
+/** Upsert: a new path appends, an existing one keeps its position and takes
+ *  the supplied memory value. Every caller names a memory value — a profile
+ *  relationship never acquires one by default. */
+export function addProfileProject(profileId, dir, opts) {
+    assertProfileProjects([{ path: dir, memory: opts.memory }]);
     const resolved = resolveExistingProjectDir(dir);
-    const result = mutateManifest(profileId, (m) => ({
-        ...m,
-        projects: dedupeOrdered([...m.projects, resolved]),
-        ...(opts.home === true ? { home: resolved } : {}),
-    }));
+    const result = mutateManifest(profileId, (m) => {
+        const existing = m.projects.some((p) => p.path === resolved);
+        const projects = existing
+            ? m.projects.map((p) => (p.path === resolved ? { ...p, memory: opts.memory } : p))
+            : dedupeProjects([...m.projects, { path: resolved, memory: opts.memory }]);
+        return {
+            ...m,
+            projects,
+            ...(opts.home === true ? { home: resolved } : {}),
+        };
+    });
     resetScopeCache();
     return result;
 }
@@ -534,15 +600,15 @@ export function removeProfileProject(profileId, dir) {
         /* dir no longer exists — fall back to comparing by its resolved path */
     }
     const result = mutateManifest(profileId, (m) => {
-        const filtered = m.projects.filter((p) => p !== real && p !== abs);
+        const filtered = m.projects.filter((p) => p.path !== real && p.path !== abs);
         // Dropping the home dir from purview falls the home back to the first
         // remaining project, exactly as `normalizeHome` would for a manifest that
         // never named one — never leaves the profile pointing outside its purview.
-        const home = m.home === real || m.home === abs ? filtered[0] ?? null : m.home;
+        const home = m.home === real || m.home === abs ? filtered[0]?.path ?? null : m.home;
         if (filtered.length === m.projects.length) {
             throw notFound(`project not found on profile: ${dir}`, {
                 received: dir,
-                next: `Current projects: ${m.projects.length > 0 ? m.projects.join(', ') : '(none)'}.`,
+                next: `Current projects: ${m.projects.length > 0 ? m.projects.map((p) => p.path).join(', ') : '(none)'}.`,
             });
         }
         return { ...m, projects: filtered, home };

package/dist/core/profiles/select.d.ts

@@ -9,6 +9,8 @@ export declare function resolveProfileSearchAction(bindings: BindingResolution<B
  *  `crtr profile default set`, which rejects pinning a profile that doesn't
  *  cover cwd (the selector would ignore/self-heal such a pin anyway). */
 export declare function profileCoversCwd(entry: ProfileEntry, cwd: string): boolean;
+/** Resolve the headless selector against existing state without changing it. */
+export declare function selectProfileForCwdReadOnly(cwd: string): string;
 /** Select the profile a node about to boot at `cwd` should run under.
  *
  *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If

package/dist/core/profiles/select.js

@@ -79,7 +79,7 @@ function projectCovers(cwd, project) {
  *  `crtr profile default set`, which rejects pinning a profile that doesn't
  *  cover cwd (the selector would ignore/self-heal such a pin anyway). */
 export function profileCoversCwd(entry, cwd) {
-    return entry.manifest.projects.some((p) => projectCovers(cwd, p));
+    return entry.manifest.projects.some((p) => projectCovers(cwd, p.path));
 }
 /** `a` more recent than `b`, treating null as the oldest possible value (never
  *  wins over a real timestamp). ISO 8601 strings compare correctly lexically. */
@@ -93,6 +93,26 @@ function isMoreRecent(a, b) {
 function pickMostRecent(entries) {
     return entries.reduce((best, cur) => isMoreRecent(cur.manifest.last_used_at, best.manifest.last_used_at) ? cur : best);
 }
+function profileSelectionState(cwd) {
+    const resolvedCwd = resolveCwd(cwd);
+    const covering = listProfiles().filter((profile) => profileCoversCwd(profile, resolvedCwd));
+    const exact = covering.filter((profile) => profile.manifest.projects.some((project) => project.path === resolvedCwd));
+    const pinnedId = getDefaultProfileId(resolvedCwd);
+    const pinned = pinnedId === null ? null : covering.find((profile) => profile.profileId === pinnedId) ?? null;
+    return { covering, exact, pinnedId, pinned };
+}
+/** Resolve the headless selector against existing state without changing it. */
+export function selectProfileForCwdReadOnly(cwd) {
+    const { covering, exact, pinned } = profileSelectionState(cwd);
+    if (pinned !== null)
+        return pinned.profileId;
+    if (exact.length === 1)
+        return exact[0].profileId;
+    const pool = exact.length > 0 ? exact : covering;
+    if (pool.length > 0)
+        return pickMostRecent(pool).profileId;
+    return ROOT_PROFILE_ID;
+}
 function isInteractive() {
     return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
 }
@@ -161,7 +181,7 @@ function purviewSummary(entry) {
     const first = entry.manifest.projects[0];
     if (first === undefined)
         return relativeUsed(entry.manifest.last_used_at);
-    return n > 1 ? `${tildify(first)} \u00b7 ${n} dirs total` : tildify(first);
+    return n > 1 ? `${tildify(first.path)} \u00b7 ${n} dirs total` : tildify(first.path);
 }
 /** ▸ marks the highlighted row. */
 const HILITE = accent('\u25b8');
@@ -330,7 +350,7 @@ async function offerAddDirToProfile(rl, entry, cwd) {
         .toLowerCase();
     if (choice === 'n' || choice === 'no')
         return;
-    addProfileProject(entry.profileId, cwd);
+    addProfileProject(entry.profileId, cwd, { memory: 'content' });
     process.stdout.write(`  ${accent('\u2713')} ${dim(`added this directory to "${entry.manifest.name}"`)}\n`);
 }
 /** Search-and-pick among EVERY existing profile (root excluded — it is the
@@ -355,7 +375,7 @@ async function promptSelectExistingProfile(bindings) {
     const matchesOf = () => filter === ''
         ? all
         : all.filter((e) => e.manifest.name.toLowerCase().includes(filter) ||
-            e.manifest.projects.some((p) => tildify(p).toLowerCase().includes(filter)));
+            e.manifest.projects.some((p) => tildify(p.path).toLowerCase().includes(filter)));
     return new Promise((resolve) => {
         let prevLines = 0;
         const draw = () => {
@@ -447,7 +467,7 @@ async function createProfileHere(rl, cwd) {
     const defaultName = basename(cwd) || 'profile';
     const nameInput = (await rl.question(caret(`name the new profile [${defaultName}]`))).trim();
     const name = nameInput !== '' ? nameInput : defaultName;
-    const profileId = createProfile(name, [cwd]).profileId;
+    const profileId = createProfile(name, [{ path: cwd, memory: 'content' }]).profileId;
     process.stdout.write(`  ${accent('\u2713')} ${dim(`created profile "${name}"`)}\n`);
     return profileId;
 }
@@ -524,9 +544,9 @@ async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId, bindi
         const detail = exact
             ? `${relativeUsed(entry.manifest.last_used_at)}${n > 1 ? ` \u00b7 ${n} dirs total` : ''}`
             : (() => {
-                const md = entry.manifest.projects.find((p) => projectCovers(cwd, p)) ??
+                const md = entry.manifest.projects.find((p) => projectCovers(cwd, p.path)) ??
                     entry.manifest.projects[0];
-                return n > 1 ? `matches ${tildify(md)} \u00b7 ${n} dirs total` : `matches ${tildify(md)}`;
+                return n > 1 ? `matches ${tildify(md.path)} \u00b7 ${n} dirs total` : `matches ${tildify(md.path)}`;
             })();
         const defaultText = pinned !== null && ordered[0] === pinned ? 'default (pinned)' : 'default';
         return {
@@ -573,7 +593,7 @@ async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId, bindi
         process.stdout.write(`  ${accent('\u2713')} ${dim(`"${picked.manifest.name}" is now the default here`)}\n`);
     }
     else if (res.action === 'crtr.profile.menu.add-directory') {
-        addProfileProject(picked.profileId, cwd);
+        addProfileProject(picked.profileId, cwd, { memory: 'content' });
         process.stdout.write(`  ${accent('\u2713')} ${dim(`added this directory to "${picked.manifest.name}"`)}\n`);
     }
     return picked.profileId;
@@ -620,14 +640,11 @@ export async function selectProfileForCwd(cwd, explicitProfile, forcePicker = fa
         updateProfileLastUsed(entry.profileId);
         return entry.profileId;
     }
-    const covering = listProfiles().filter((p) => profileCoversCwd(p, resolvedCwd));
-    const exact = covering.filter((p) => p.manifest.projects.some((proj) => proj === resolvedCwd));
+    const { covering, exact, pinnedId, pinned } = profileSelectionState(resolvedCwd);
     // A per-cwd pinned default (set from the menu with `d`) is the user's
     // explicit "default to THIS profile HERE". It outranks both the exact-single
     // auto-pick and global-MRU, so long as it still covers cwd; a stale pin
     // (profile deleted, or its dir removed from purview) is self-healed away.
-    const pinnedId = getDefaultProfileId(resolvedCwd);
-    const pinned = pinnedId !== null ? covering.find((p) => p.profileId === pinnedId) ?? null : null;
     if (pinnedId !== null && pinned === null)
         clearDefaultProfile(resolvedCwd);
     // A valid pin decides it outright and STOPS ASKING — the whole point of

package/dist/core/render.js

@@ -32,6 +32,13 @@ function scalarStr(v) {
         return JSON.stringify(v);
     return String(v);
 }
+function fencedJson(value) {
+    const json = JSON.stringify(value, null, 2);
+    let fence = '```';
+    while (json.includes(fence))
+        fence += '`';
+    return `${fence}json\n${json}\n${fence}`;
+}
 /** A string field is prose when it is named as such, spans lines, or is long
  *  enough that it reads as a sentence rather than an identifier. */
 function isProse(name, v) {
@@ -122,6 +129,10 @@ export function renderError(p) {
     // the value the caller supplied.
     if (p.http_status !== undefined)
         lines.push(`http status: ${p.http_status}`);
+    if ('primaryCompleted' in p && p.primaryCompleted === true) {
+        lines.push('primaryCompleted: true');
+        lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);
+    }
     lines.push(`Next: ${p.next}`);
     return `<error code="${attrEsc(p.error)}">\n${lines.join('\n')}\n</error>`;
 }

package/dist/core/runtime/advertised-command-invocation.d.ts

@@ -0,0 +1,20 @@
+import type { BrokerSession } from './broker/read-ops.js';
+export interface AdvertisedCommandInvocationMetadata {
+    crouterAdvertisedCommandInvocation: {
+        raw: string;
+    };
+}
+/** Restore extension-owned details while projecting persisted invocation
+ * metadata onto the runtime custom message. */
+export declare function hydratePersistedAdvertisedCommandMessages(messages: readonly unknown[]): void;
+/** Add live invocation metadata without changing extension-owned content or
+ * details. EventProjection calls this before relaying a custom message. */
+export declare function hydrateLiveAdvertisedCommandMessage(message: unknown): void;
+/** Bind the imminent message_end persistence call to the exact queued app
+ * message rather than to a payload-equality search across pending queues. */
+export declare function prepareAdvertisedCommandPersistence(session: BrokerSession, message: unknown): void;
+/** Install persistence/reload plumbing once on a newly built broker session. */
+export declare function installAdvertisedCommandInvocationContract(session: BrokerSession): void;
+/** Preserve a chat-advertised extension command's exact submitted text on the
+ * first displayed custom message its handler persists. */
+export declare function promptWithAdvertisedCommandInvocation<T>(session: BrokerSession, raw: string, runPrompt: () => Promise<T>): Promise<T>;