@north-light/crouter 0.3.220 → 0.3.221

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

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
@@ -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.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. */
@@ -161,7 +161,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 +330,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 +355,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 +447,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 +524,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 +573,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;
@@ -621,7 +621,7 @@ export async function selectProfileForCwd(cwd, explicitProfile, forcePicker = fa
         return entry.profileId;
     }
     const covering = listProfiles().filter((p) => profileCoversCwd(p, resolvedCwd));
-    const exact = covering.filter((p) => p.manifest.projects.some((proj) => proj === resolvedCwd));
+    const exact = covering.filter((p) => p.manifest.projects.some((proj) => proj.path === 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