@crouton-kit/crouter 0.3.48 → 0.3.50

package/dist/core/__tests__/on-read-identity.test.js

@@ -0,0 +1,68 @@
+// The on-read POSITIONAL loader resolves a doc's identity with the SAME
+// explicit-name-then-path-fallback rule the boot resolver uses (schema.ts's
+// resolveDocName), never deriving `name` from the physical path alone.
+//
+// A migrated AGENTS.md doc (`crtr sys sync`'s CLAUDE.md/AGENTS.md conversion)
+// is written at `file-read-visibility: content` with an explicit frontmatter
+// `name` (the project label, e.g. `crouter`) so sibling project roots do not
+// collapse onto the shared `AGENTS` leaf. `loadPositionalDoc` must inject the
+// doc under that explicit name, not the path-derived `AGENTS`.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/on-read-identity.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { renderOnReadDocs } from '../substrate/on-read.js';
+let home;
+let work;
+let prevHomeEnv;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-onread-identity-home-'));
+    process.env['CRTR_HOME'] = home;
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    resetScopeCache();
+    rmSync(home, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+    work = mkdtempSync(join(tmpdir(), 'crtr-onread-identity-work-'));
+});
+after(() => {
+    closeDb();
+    resetScopeCache();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(work, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+test('a migrated AGENTS doc injects on-read under its explicit frontmatter name, not the path-derived one', () => {
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    // Shape of a `crtr sys sync` CLAUDE.md/AGENTS.md migration: physical filename
+    // stays AGENTS.md, but frontmatter carries the project's explicit identity.
+    const memDir = join(work, '.crouter', 'memory');
+    mkdirSync(memDir, { recursive: true });
+    writeFileSync(join(memDir, 'AGENTS.md'), '---\nkind: knowledge\n' +
+        'name: acme-project\n' +
+        'when-and-why-to-read: When working in acme-project, this knowledge should be read because it is the project\'s operating guide.\n' +
+        'file-read-visibility: content\n---\n' +
+        'ACME PROJECT OPERATING GUIDE\n');
+    const readFile = join(work, 'src', 'file.ts');
+    mkdirSync(join(work, 'src'), { recursive: true });
+    writeFileSync(readFile, 'export const x = 1;\n');
+    const rendered = renderOnReadDocs(node, readFile, new Set());
+    assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the migrated doc fires positionally');
+    assert.ok(rendered.includes('<memory kind="knowledge" name="acme-project"'), `expected explicit frontmatter name "acme-project" in the injected envelope, got: ${rendered}`);
+    assert.ok(!rendered.includes('name="AGENTS"'), 'must not fall back to the path-derived name when frontmatter sets one');
+});

package/dist/core/fs-utils.d.ts

@@ -15,5 +15,5 @@ export declare function linkOrCopy(target: string, linkPath: string, opts?: {
     noSymlink?: boolean;
 }): 'symlink' | 'copy';
 export declare function readSymlinkTarget(path: string): string | null;
-export declare function walkFiles(root: string, predicate?: (name: string) => boolean): string[];
+export declare function walkFiles(root: string, predicate?: (name: string) => boolean, skipDir?: (name: string) => boolean): string[];
 export declare function nowIso(): string;

package/dist/core/fs-utils.js

@@ -90,7 +90,7 @@ export function readSymlinkTarget(path) {
         return null;
     }
 }
-export function walkFiles(root, predicate = () => true) {
+export function walkFiles(root, predicate = () => true, skipDir = () => false) {
     const out = [];
     if (!existsSync(root))
         return out;
@@ -106,8 +106,10 @@ export function walkFiles(root, predicate = () => true) {
         }
         for (const e of entries) {
             const full = join(dir, e.name);
-            if (e.isDirectory())
-                stack.push(full);
+            if (e.isDirectory()) {
+                if (!skipDir(e.name))
+                    stack.push(full);
+            }
             else if (e.isFile() && predicate(e.name))
                 out.push(full);
         }

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

@@ -1,10 +1,17 @@
 import type { InstalledPlugin, Scope } from '../types.js';
 /**
- * Thin memory-document resolver for the document substrate. Resolution is scope
- * + leaf/path only: qualifier parse → scope precedence → direct path lookup →
- * leaf-name fallback. The memory scopes resolve in precedence order project
- * stack > profile > user > builtin. It returns the raw parsed frontmatter +
- * body; it does NOT interpret the schema, kind, gate, or rungs — that is the
+ * Thin memory-document resolver for the document substrate. Precedence is the
+ * OUTER loop, not a global scan: scopes/sources are tried NEAREST-FIRST
+ * (project stack nearest > ... > profile > user > builtin), and WITHIN each
+ * source, in order: (1) exact substrate-identity match (`doc.name === query`
+ * — the explicit frontmatter `name`, or its path-derived fallback), (2) direct
+ * `memory/<name>.md` physical-path lookup (plus the bare-dir/bare-plugin-name
+ * → `INDEX.md` convenience neither identity nor a literal path expresses),
+ * (3) bare leaf-name fallback (final path segment only). The first hit wins,
+ * so a nearer source's match of ANY kind always beats a farther source's
+ * match of any kind — a farther-scope identity can never shadow a
+ * nearer-scope physical file. It returns the raw parsed frontmatter + body;
+ * it does NOT interpret the schema, kind, gate, or rungs — that is the
  * schema/gate layer's job (callers filter by `frontmatter.kind`). Project
  * resolution is a nearest-first stack of every ancestor `.crouter/` (widened by
  * a selected profile's `projects` manifest entries — see `findProjectScopeRoots`
@@ -12,8 +19,9 @@ import type { InstalledPlugin, Scope } from '../types.js';
  * (from `CRTR_PROFILE_ID`), and user/builtin remain singleton scopes.
  */
 export interface MemoryDoc {
-    /** Path-derived identity: the doc's path under the scope's memory/ root, no
-     *  extension, slash-separated — e.g. memory/taste/foo.md → "taste/foo". */
+    /** Resolver identity: the doc's explicit frontmatter `name` when present,
+     *  otherwise its normalized path under the scope's memory/ root — e.g.
+     *  memory/taste/foo.md → "taste/foo". */
     name: string;
     scope: MemoryScope;
     /** Absolute path to the resolved .md file. */
@@ -59,15 +67,23 @@ export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: Mem
  *  caller's first-wins dedup. */
 export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean): MemoryDoc[];
 /**
- * Resolve a path-derived name to a single memory document.
+ * Resolve a memory document name to a single memory document.
  *
  * Accepted identifier forms:
  *   <name>            — bare name; resolved by scope precedence project>user>builtin
  *   <scope>/<name>    — pinned to one scope (user|project)
  * `<name>` may carry topical subdirs (`taste/foo`); a bare leaf (`foo`) falls
- * back to a last-segment match across the resolved scopes.
+ * back to a last-segment match within the resolved scopes.
  *
- * Resolution order: parse qualifier → direct memory/<name>.md lookup
- * (precedence-first) → leaf-name fallback (ambiguity error listing candidates).
+ * Precedence is the outer loop: sources are visited nearest-first, and the
+ * FIRST source with any hit wins outright — a farther source is never even
+ * consulted once a nearer one matches. Within each source, in order: (1)
+ * exact substrate-identity match (`doc.name === query` — the explicit
+ * frontmatter `name`, else its normalized path-derived fallback, the SAME
+ * identity `listAllMemoryDocs` reports); (2) direct `memory/<name>.md`
+ * physical-path lookup (the bare-dir → INDEX.md and bare-plugin-name → plugin
+ * root INDEX.md conveniences neither identity nor a literal path expresses);
+ * (3) bare leaf-name fallback (final path segment), ambiguous only when two
+ * DIFFERENT identities in the SAME source share a leaf.
  */
 export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;

package/dist/core/memory-resolver.js

@@ -6,7 +6,7 @@ import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier }
 import { ambiguous, notFound, usage } from './errors.js';
 import { warn } from './output.js';
 import { pluginMemoryDir, projectScopeRoot, projectScopeRoots, scopeMemoryDir } from './scope.js';
-import { normalizeDocName, normalizeNameSegment } from './substrate/schema.js';
+import { normalizeDocName, normalizeNameSegment, resolveDocName } from './substrate/schema.js';
 import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
@@ -75,14 +75,14 @@ function memorySourcesInPrecedence(scope) {
     }
     return out;
 }
-function loadMemoryDoc(name, scope, path) {
+function loadMemoryDoc(scope, path, fallbackName) {
     const { data, body } = parseFrontmatterGeneric(readText(path));
-    return { name, scope, path, frontmatter: data, body };
+    return { name: resolveDocName(data, fallbackName), scope, path, frontmatter: data, body };
 }
 /** All memory docs in one memory/ dir, scanned recursively for *.md (topical
- *  subdirs supported), sorted by path-derived name. SKILL.md bundles are legacy
- *  Agent Skills and are ignored; crouter memory docs are plain .md files under
- *  memory/. */
+ *  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) {
     if (!dir || !pathExists(dir))
         return [];
@@ -117,7 +117,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(name, scope, path));
+            docs.push(loadMemoryDoc(scope, path, name));
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -164,7 +164,7 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
             continue;
         const name = `${plugin.name}/${derived}`;
         try {
-            docs.push({ ...loadMemoryDoc(name, scope, file), plugin: plugin.name });
+            docs.push({ ...loadMemoryDoc(scope, file, name), plugin: plugin.name });
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -174,16 +174,23 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** All docs belonging to a single resolved source: native docs first, then
+ *  enabled-plugin docs — native wins on a first-wins dedup within the source.
+ *  Shared by `listAllMemoryDocs` (flattens every source) and `resolveMemoryDoc`
+ *  (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)),
+    ];
+}
 /** All memory docs across the resolved sources, in precedence order: each
  *  ancestor project `.crouter/` from nearest to farthest, then the selected
  *  profile's memory (if any), then user, then builtin. Within each source,
  *  native docs are emitted before enabled-plugin docs, so native wins on the
  *  caller's first-wins dedup. */
 export function listAllMemoryDocs(scope, quiet = false) {
-    return memorySourcesInPrecedence(scope).flatMap((source) => [
-        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet),
-        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet)),
-    ]);
+    return memorySourcesInPrecedence(scope).flatMap((source) => sourceMemoryDocs(source, quiet));
 }
 /** Find the direct child of `dir` — a `.md` file (matched on name minus
  *  extension) or a directory — whose NORMALIZED display name equals
@@ -246,9 +253,10 @@ function resolveNormalizedPath(baseDir, segments) {
         dirPath: matchNormalizedChild(curDir, last, 'dir'),
     };
 }
-/** Direct full-path lookup of memory/<name>.md across scopes, precedence-first.
- *  Returns every scope's hit in precedence order; the resolver takes the first
- *  (highest-precedence) one — a fully-specified name is never ambiguous.
+/** Direct full-path lookup of memory/<name>.md within ONE source. Returns that
+ *  source's single hit, or undefined — a source can produce at most one direct
+ *  match (native wins over plugin within the source, and at most one plugin's
+ *  name can match).
  *
  *  A directory INDEX is the cleaner contract: when `<name>.md` is absent but
  *  `<name>/INDEX.md` exists, the bare dir name (`taste`) resolves to the dir's
@@ -259,94 +267,72 @@ function resolveNormalizedPath(baseDir, segments) {
  *  never authored with a numeric prefix); resolution against the physical tree
  *  is prefix-blind via `resolveNormalizedPath` so a normalized name finds an
  *  `NN-`-pinned physical file/dir. */
-function findMemoryMatches(name, scope) {
-    const matches = [];
-    const segments = name.split('/');
+function findMemoryMatchInSource(name, segments, source) {
     const isLegacySkillDoc = segments.at(-1) === 'SKILL';
-    for (const source of memorySourcesInPrecedence(scope)) {
-        // Native memory dir first inside this source (native-before-plugin
-        // precedence), then its enabled plugins. The next source is the next
-        // ancestor `.crouter/`, then user, then builtin.
-        const dir = source.memoryDir;
-        if (dir) {
-            const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
-            if (!isLegacySkillDoc && filePath !== null) {
-                matches.push(loadMemoryDoc(name, source.scope, filePath));
-                continue;
-            }
-            if (dirPath !== null) {
-                const indexPath = join(dirPath, 'INDEX.md');
-                if (pathExists(indexPath)) {
-                    matches.push(loadMemoryDoc(name, source.scope, indexPath));
-                    continue;
-                }
-            }
-        }
-        // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
-        // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
-        // enumerates — `read` must resolve what `list` shows). A BARE plugin name
-        // (no slash) resolves the plugin-root INDEX.md, mirroring the native
-        // bare-dir-name -> INDEX.md contract for the plugin mount root.
-        const slash = name.indexOf('/');
-        const pluginName = slash > 0 ? name.slice(0, slash) : name;
-        const rest = slash > 0 ? name.slice(slash + 1) : '';
-        for (const p of source.plugins) {
-            if (p.name !== pluginName)
-                continue;
-            const pdir = pluginMemoryDir(p);
-            const restSegments = rest ? rest.split('/') : [];
-            if (rest) {
-                const { filePath } = resolveNormalizedPath(pdir, restSegments);
-                if (restSegments.at(-1) !== 'SKILL' && filePath !== null) {
-                    matches.push(loadMemoryDoc(name, source.scope, filePath));
-                    break;
-                }
-            }
-            // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
-            const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
-            if (pIndexDir !== null) {
-                const pindex = join(pIndexDir, 'INDEX.md');
-                if (pathExists(pindex)) {
-                    matches.push(loadMemoryDoc(name, source.scope, pindex));
-                    break;
-                }
-            }
+    // Native memory dir first inside this source (native-before-plugin
+    // precedence), then its enabled plugins.
+    const dir = source.memoryDir;
+    if (dir) {
+        const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
+        if (!isLegacySkillDoc && filePath !== null)
+            return loadMemoryDoc(source.scope, filePath, name);
+        if (dirPath !== null) {
+            const indexPath = join(dirPath, 'INDEX.md');
+            if (pathExists(indexPath))
+                return loadMemoryDoc(source.scope, indexPath, name);
         }
     }
-    return matches;
-}
-/** Leaf-name fallback: match docs whose final path segment equals `leaf`.
- *  Only meaningful for a bare segment (a slashed query can never equal a single
- *  segment). Returns matches precedence-ordered. */
-function findMemoryByLeaf(leaf, scope) {
-    if (leaf.includes('/'))
-        return [];
-    let all;
-    try {
-        // Quiet: a targeted read must not spew other docs' frontmatter warnings
-        // before its own result (esp. a not_found) — corpus health is `lint`'s job.
-        all = listAllMemoryDocs(scope, true);
-    }
-    catch {
-        return [];
+    // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
+    // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
+    // enumerates — `read` must resolve what `list` shows). A BARE plugin name
+    // (no slash) resolves the plugin-root INDEX.md, mirroring the native
+    // bare-dir-name -> INDEX.md contract for the plugin mount root.
+    const slash = name.indexOf('/');
+    const pluginName = slash > 0 ? name.slice(0, slash) : name;
+    const rest = slash > 0 ? name.slice(slash + 1) : '';
+    for (const p of source.plugins) {
+        if (p.name !== pluginName)
+            continue;
+        const pdir = pluginMemoryDir(p);
+        const restSegments = rest ? rest.split('/') : [];
+        if (rest) {
+            const { filePath } = resolveNormalizedPath(pdir, restSegments);
+            if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
+                return loadMemoryDoc(source.scope, filePath, name);
+        }
+        // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
+        const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
+        if (pIndexDir !== null) {
+            const pindex = join(pIndexDir, 'INDEX.md');
+            if (pathExists(pindex))
+                return loadMemoryDoc(source.scope, pindex, name);
+        }
     }
-    return all.filter((d) => (d.name.split('/').pop() ?? d.name) === leaf);
+    return undefined;
 }
 function formatLeafAmbiguous(leaf, matches) {
     const ids = matches.map(memoryDocId).join(', ');
     return `ambiguous memory document: ${leaf} matches multiple documents: ${ids}`;
 }
 /**
- * Resolve a path-derived name to a single memory document.
+ * Resolve a memory document name to a single memory document.
  *
  * Accepted identifier forms:
  *   <name>            — bare name; resolved by scope precedence project>user>builtin
  *   <scope>/<name>    — pinned to one scope (user|project)
  * `<name>` may carry topical subdirs (`taste/foo`); a bare leaf (`foo`) falls
- * back to a last-segment match across the resolved scopes.
+ * back to a last-segment match within the resolved scopes.
  *
- * Resolution order: parse qualifier → direct memory/<name>.md lookup
- * (precedence-first) → leaf-name fallback (ambiguity error listing candidates).
+ * Precedence is the outer loop: sources are visited nearest-first, and the
+ * FIRST source with any hit wins outright — a farther source is never even
+ * consulted once a nearer one matches. Within each source, in order: (1)
+ * exact substrate-identity match (`doc.name === query` — the explicit
+ * frontmatter `name`, else its normalized path-derived fallback, the SAME
+ * identity `listAllMemoryDocs` reports); (2) direct `memory/<name>.md`
+ * physical-path lookup (the bare-dir → INDEX.md and bare-plugin-name → plugin
+ * root INDEX.md conveniences neither identity nor a literal path expresses);
+ * (3) bare leaf-name fallback (final path segment), ambiguous only when two
+ * DIFFERENT identities in the SAME source share a leaf.
  */
 export function resolveMemoryDoc(rawName, opts = {}) {
     const parsed = parseSkillQualifier(rawName);
@@ -357,28 +343,38 @@ export function resolveMemoryDoc(rawName, opts = {}) {
     const name = parsed.segments.join('/');
     if (name === '')
         throw usage(`memory document name required`);
-    // Direct full-path lookup: a fully-specified name resolves by scope precedence.
-    const direct = findMemoryMatches(name, effectiveScope);
-    if (direct.length > 0)
-        return direct[0];
-    // Leaf-name fallback: the caller gave only the final segment (e.g. "foo" for
-    // "taste/foo"). Match by last segment across the resolved scope dirs.
-    const byLeaf = findMemoryByLeaf(name, effectiveScope);
-    if (byLeaf.length > 0) {
-        // Same path-derived name across scopes → precedence wins (return first);
-        // genuinely different docs sharing a leaf → ambiguous.
-        const distinctNames = new Set(byLeaf.map((d) => d.name));
-        if (distinctNames.size === 1)
-            return byLeaf[0];
-        throw ambiguous(formatLeafAmbiguous(name, byLeaf), {
-            memory: name,
-            candidates: byLeaf.map((d) => ({
-                id: memoryDocId(d),
-                scope: d.scope,
-                path: d.path,
-            })),
-            next: 'Multiple documents share this leaf name. Re-run with one of the full names in candidates.',
-        });
+    const segments = name.split('/');
+    const isLeafQuery = !name.includes('/');
+    for (const source of memorySourcesInPrecedence(effectiveScope)) {
+        // Quiet: a targeted read must not spew other docs' frontmatter warnings
+        // before its own result (esp. a not_found) — corpus health is `lint`'s job.
+        const docs = sourceMemoryDocs(source, true);
+        const identity = docs.find((d) => d.name === name);
+        if (identity)
+            return identity;
+        const direct = findMemoryMatchInSource(name, segments, source);
+        if (direct)
+            return direct;
+        if (isLeafQuery) {
+            const leafMatches = docs.filter((d) => (d.name.split('/').pop() ?? d.name) === name);
+            if (leafMatches.length > 0) {
+                // Same path-derived name within this source → precedence wins (return
+                // first); genuinely different docs sharing a leaf → ambiguous. Either
+                // way this source has an answer — a farther source is never checked.
+                const distinctNames = new Set(leafMatches.map((d) => d.name));
+                if (distinctNames.size === 1)
+                    return leafMatches[0];
+                throw ambiguous(formatLeafAmbiguous(name, leafMatches), {
+                    memory: name,
+                    candidates: leafMatches.map((d) => ({
+                        id: memoryDocId(d),
+                        scope: d.scope,
+                        path: d.path,
+                    })),
+                    next: 'Multiple documents share this leaf name. Re-run with one of the full names in candidates.',
+                });
+            }
+        }
     }
     throw notFound(`memory document not found: ${rawName}`, {
         memory: name,

package/dist/core/profiles/default-binding.d.ts

@@ -0,0 +1,10 @@
+/** Resolve cwd to the same absolute, realpath'd form the profile selector and
+ *  manifest use, so the mangled-cwd workspace key lines up with the realpath'd
+ *  project dirs. Falls back to the plain resolved path when the dir can't be
+ *  stat'd. This is the single resolver every entry point (selector + the
+ *  `profile default` commands) routes through, so a pin set from one is found
+ *  by the other. */
+export declare function resolveBindingCwd(cwd: string): string;
+export declare function getDefaultProfileId(cwd: string): string | null;
+export declare function setDefaultProfileId(cwd: string, profileId: string): void;
+export declare function clearDefaultProfile(cwd: string): void;

package/dist/core/profiles/default-binding.js

@@ -0,0 +1,50 @@
+// A per-cwd "default profile" pin — a small binding stored in the per-cwd
+// workspace root (`~/.crouter/workspaces/<mangled-cwd>/default-profile.json`)
+// that says "when a node boots at THIS directory, prefer THIS profile". It is
+// deliberately NOT manifest state: a profile's `projects` list is what it can
+// see (coverage/purview), whereas this pin is which of several covering
+// profiles the user chose to default to here. The two are independent — you
+// can pin a profile that only covers cwd from a parent dir without widening
+// its purview, and widening purview never changes the pin.
+//
+// Consulted by `selectProfileForCwd` (it wins over global-MRU and stops the
+// prompt) and written from the startup menu (`d`) or `crtr profile default`.
+// A stale pin (its profile deleted, or no longer covering cwd) is self-healed
+// away by the selector rather than trusted.
+import { existsSync, realpathSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { workspaceRoot } from '../artifact.js';
+import { readJsonIfExists, writeJson, ensureDir, removePath } from '../fs-utils.js';
+/** Resolve cwd to the same absolute, realpath'd form the profile selector and
+ *  manifest use, so the mangled-cwd workspace key lines up with the realpath'd
+ *  project dirs. Falls back to the plain resolved path when the dir can't be
+ *  stat'd. This is the single resolver every entry point (selector + the
+ *  `profile default` commands) routes through, so a pin set from one is found
+ *  by the other. */
+export function resolveBindingCwd(cwd) {
+    const abs = resolvePath(cwd);
+    if (!existsSync(abs))
+        return abs;
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+function bindingPath(cwd) {
+    return join(workspaceRoot(resolveBindingCwd(cwd)), 'default-profile.json');
+}
+export function getDefaultProfileId(cwd) {
+    const binding = readJsonIfExists(bindingPath(cwd));
+    const id = binding?.profileId;
+    return typeof id === 'string' && id !== '' ? id : null;
+}
+export function setDefaultProfileId(cwd, profileId) {
+    const resolved = resolveBindingCwd(cwd);
+    ensureDir(workspaceRoot(resolved));
+    writeJson(join(workspaceRoot(resolved), 'default-profile.json'), { profileId });
+}
+export function clearDefaultProfile(cwd) {
+    removePath(bindingPath(cwd));
+}

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

@@ -1,9 +1,21 @@
+import { type ProfileEntry } from './manifest.js';
+/** Whether a profile's purview covers `cwd` (cwd at/under one of its project
+ *  dirs, or a project dir under cwd — the workspace-root case). Exported for
+ *  `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;
 /** Select the profile a node about to boot at `cwd` should run under.
  *
  *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If
  *     its manifest does not already cover `cwd` and the session is interactive,
  *     offer to add `cwd` to its purview (default yes). Bump `last_used_at`,
  *     return the id.
+ *  1b. Else, a per-cwd PINNED default (menu `d`) that still covers `cwd` is
+ *     auto-picked outright — interactive and headless alike, no prompt (that is
+ *     what "default" means). Interactive prints a breadcrumb naming it and how
+ *     to change it. `forcePicker` (`crtr --pick-profile`) bypasses the pin to
+ *     re-open the menu. A stale pin (profile gone / no longer covering) is
+ *     cleared and ignored.
  *  2. Else, if EXACTLY ONE profile's project dir IS `cwd` (you're at a project
  *     root, unambiguously one owner), auto-pick it with no prompt — the
  *     strongest signal. If SEVERAL profiles claim `cwd` exactly, it's genuinely
@@ -18,4 +30,4 @@
  *     create a profile here or proceed as root (root lives ONLY here). Non-
  *     interactive (no TTY): default to root (null) and print the recovery
  *     instruction to STDERR — never stdout, which the caller may be piping. */
-export declare function selectProfileForCwd(cwd: string, explicitProfile?: string | null): Promise<string | null>;
+export declare function selectProfileForCwd(cwd: string, explicitProfile?: string | null, forcePicker?: boolean): Promise<string | null>;