@crouton-kit/crouter 0.3.47 → 0.3.49

package/dist/commands/sys/sync.js

@@ -1,18 +1,29 @@
 // `crtr sys sync` — explicit migration from legacy host Agent Skill bundles into
 // crouter memory documents. It is NOT a bidirectional SKILL.md sync surface: the
 // crouter side after a sync is a plain memory/<name>.md document.
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { gitSync } from '../../core/git.js';
 import { pathExists, readJsonIfExists, readText, walkFiles, writeJson, writeText } from '../../core/fs-utils.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
 import { findProjectScopeRoot, scopeMemoryDir } from '../../core/scope.js';
+import { CRTR_DIR_NAME } from '../../types.js';
 import { memoryFilePath, resolveWriteTarget, serializeMemoryDoc } from '../memory/shared.js';
 const LEGACY_BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 const HOST_SKILL_FILE = 'SKILL.md';
 const IGNORE_FILE = 'skill-import-ignore.json';
+// Directories a project-doc walk never descends into — build/dependency trees
+// plus crouter's own state dir (mirrors nested-context's JUNK_DIRS, the
+// now-deleted extension this migration replaces).
+const PROJECT_DOC_JUNK_DIRS = new Set([
+    'node_modules', '.git', '.venv', 'venv', 'dist', 'build', '.next', '.cache', '.yalc', '.sisyphus', CRTR_DIR_NAME,
+]);
+// First-match-per-dir order mirrors pi's own loader (AGENTS.md wins over CLAUDE.md).
+const PROJECT_DOC_FILENAMES = ['AGENTS.md', 'CLAUDE.md'];
 function projectDir() {
     const root = findProjectScopeRoot();
     return root ? dirname(root) : null;
@@ -115,6 +126,208 @@ function targetMemoryDir(scope) {
         return resolveWriteTarget(scope).memoryDir;
     return dir;
 }
+/** Discovery roots for the project-doc walk: an explicit `--source` pins a
+ *  single dir; otherwise cwd plus (when a profile is selected) every project
+ *  in its purview — the same profile-widened idea `findProjectScopeRoots`
+ *  applies to the boot render, so one invocation can migrate a whole
+ *  workspace instead of one repo at a time. Deduped, cwd first; never throws
+ *  on a missing/unreadable profile (cwd-only fallback). */
+function projectDocRoots(sourceArg) {
+    if (sourceArg !== undefined)
+        return [resolve(sourceArg)];
+    const roots = [resolve(process.cwd())];
+    const profileId = process.env['CRTR_PROFILE_ID'];
+    if (profileId !== undefined && profileId !== '') {
+        try {
+            const { manifest } = loadProfileManifest(profileId);
+            for (const p of manifest.projects) {
+                const r = resolve(p);
+                if (!roots.includes(r))
+                    roots.push(r);
+            }
+        }
+        catch {
+            // No/unreadable profile — cwd-only root.
+        }
+    }
+    return roots;
+}
+/** Walk `root` (skipping PROJECT_DOC_JUNK_DIRS) collecting every dir's
+ *  CLAUDE.md/AGENTS.md (first match per dir) plus every `.claude/rules/*.md`.
+ *  Each result names the directory whose OWN `.crouter/memory/` it targets. */
+function collectProjectDocCandidates(root) {
+    const out = [];
+    if (!existsSync(root) || !statSync(root).isDirectory())
+        return out;
+    const rootResolved = resolve(root);
+    const stack = [rootResolved];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        const isWalkRoot = dir === rootResolved;
+        for (const name of PROJECT_DOC_FILENAMES) {
+            const p = join(dir, name);
+            if (existsSync(p) && statSync(p).isFile()) {
+                out.push({ kind: 'agents', path: p, sourceDir: dir, isWalkRoot });
+                break;
+            }
+        }
+        const rulesDir = join(dir, '.claude', 'rules');
+        if (existsSync(rulesDir)) {
+            for (const file of walkFiles(rulesDir, (n) => n.endsWith('.md'))) {
+                out.push({ kind: 'rule', path: file, sourceDir: dir, isWalkRoot });
+            }
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !PROJECT_DOC_JUNK_DIRS.has(e.name))
+                stack.push(join(dir, e.name));
+        }
+    }
+    return out;
+}
+/** First non-empty line, heading markers stripped, truncated — the `short-form`
+ *  gist synthesized from a body with no frontmatter description to draw from. */
+function synthesizeShortForm(body) {
+    for (const raw of body.split('\n')) {
+        const cleaned = raw.replace(/^#+\s*/, '').replace(/\s+/g, ' ').trim();
+        if (cleaned !== '')
+            return cleaned.length > 200 ? `${cleaned.slice(0, 197)}...` : cleaned;
+    }
+    return 'Migrated project guidance.';
+}
+/** `.claude/rules` frontmatter `paths:` normalizes to a glob list — a single
+ *  string, an array, or absent (positional, unconditional rule). */
+function normalizeRulePaths(v) {
+    if (typeof v === 'string')
+        return v.trim() === '' ? [] : [v.trim()];
+    if (Array.isArray(v))
+        return v.filter((g) => typeof g === 'string' && g.trim() !== '');
+    return [];
+}
+/** The main repo root's directory name, found via `git rev-parse
+ *  --git-common-dir` — unlike `--show-toplevel`, this resolves through a
+ *  LINKED WORKTREE to the shared `.git` of the repo it belongs to, so a
+ *  canvas worktree checked out under a node-id path (e.g.
+ *  `.../worktrees/mr9vsbtn-ecd74d1b`) still resolves to the real project
+ *  name (`crouter`), not the worktree's own basename. Returns undefined when
+ *  `dir` isn't inside a git repo at all. */
+function gitRepoRootName(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--git-common-dir'], dir);
+    if (res.status !== 0)
+        return undefined;
+    const gitCommonDir = res.stdout.trim();
+    if (gitCommonDir === '')
+        return undefined;
+    return basename(dirname(gitCommonDir));
+}
+/** First Markdown H1 heading in the doc body, heading marker stripped. */
+function h1Title(body) {
+    for (const raw of body.split('\n')) {
+        const m = raw.match(/^#\s+(.+)$/);
+        if (m) {
+            const title = m[1].replace(/\s+/g, ' ').trim();
+            if (title !== '')
+                return title;
+        }
+    }
+    return undefined;
+}
+/** Routing-text label for the WALK-ROOT project doc: the raw basename of that
+ *  directory is unreliable (a worktree/canvas checkout's basename is a node
+ *  id, not the project name), so prefer the actual git repo's root dirname,
+ *  falling back to the doc's own H1 title, falling back to the raw basename
+ *  only as a last resort. Nested-dir docs don't need this — their own
+ *  subdirectory basename already names them correctly. */
+function projectRootLabel(dir, body) {
+    return gitRepoRootName(dir) ?? h1Title(body) ?? basename(dir) ?? dir;
+}
+/** AGENTS.md/CLAUDE.md → `<sourceDir>/.crouter/memory/AGENTS.md` at
+ *  content/content (the CTO's ruling, 2026-07-06: an AGENTS.md-style doc is
+ *  always-relevant AND wholly-important, so full-body at `content` is
+ *  sanctioned — see `taste/document-substrate`). Doc name is fixed `AGENTS`
+ *  (never `INDEX`, which carries ceiling/subtree-capping semantics here). */
+function prepareAgentsCandidate(candidate) {
+    const body = parseFrontmatterGeneric(readText(candidate.path)).body;
+    const dirLabel = candidate.isWalkRoot
+        ? projectRootLabel(candidate.sourceDir, body)
+        : basename(candidate.sourceDir) || candidate.sourceDir;
+    const frontmatter = {
+        kind: 'knowledge',
+        'when-and-why-to-read': `When working in ${dirLabel}, this knowledge should be read because it is the project's operating guide.`,
+        'short-form': synthesizeShortForm(body),
+        'system-prompt-visibility': 'content',
+        'file-read-visibility': 'content',
+    };
+    return {
+        candidate,
+        name: 'AGENTS',
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), 'AGENTS'),
+        frontmatter,
+        body,
+    };
+}
+/** `.claude/rules/<name>.md` → `<sourceDir>/.crouter/memory/<name>.md`. A
+ *  `paths:` rule becomes an `applies-to` glob trigger at none/content; a
+ *  pathless rule is positional (surfaces like AGENTS.md on any read under its
+ *  own project scope) at the same none/content rungs. */
+function prepareRuleCandidate(candidate) {
+    const raw = readText(candidate.path);
+    const parsed = parseFrontmatterGeneric(raw);
+    const fm = parsed.data ?? {};
+    const name = normalizedName(basename(candidate.path));
+    const description = scalarString(fm['description']) ?? '';
+    const dirLabel = candidate.isWalkRoot
+        ? projectRootLabel(candidate.sourceDir, parsed.body)
+        : basename(candidate.sourceDir) || candidate.sourceDir;
+    const frontmatter = {
+        kind: 'knowledge',
+        'when-and-why-to-read': description !== ''
+            ? routeFromDescription(description, 'knowledge')
+            : `When working under ${dirLabel}, this knowledge should be read because it is migrated project rule guidance.`,
+        'short-form': description !== '' ? description.replace(/\s+/g, ' ').trim() : synthesizeShortForm(parsed.body),
+        'system-prompt-visibility': 'none',
+        'file-read-visibility': 'content',
+    };
+    const globs = normalizeRulePaths(fm['paths']);
+    if (globs.length > 0)
+        frontmatter['applies-to'] = globs;
+    return {
+        candidate,
+        name,
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), name),
+        frontmatter,
+        body: parsed.body,
+    };
+}
+/** Write (or dry-run report) a prepared project doc — copy-not-move,
+ *  skip-existing unless `--overwrite`, mirroring `convertPrepared` above. */
+function convertProjectDoc(prepared, opts) {
+    if (pathExists(prepared.target) && !opts.overwrite) {
+        return {
+            source: prepared.candidate.path,
+            target: prepared.target,
+            name: prepared.name,
+            scope: 'project',
+            status: 'skipped',
+            reason: 'target memory doc already exists; re-run with --overwrite to replace it',
+        };
+    }
+    if (!opts.dryRun)
+        writeText(prepared.target, serializeMemoryDoc(prepared.frontmatter, prepared.body));
+    return {
+        source: prepared.candidate.path,
+        target: prepared.target,
+        name: prepared.name,
+        scope: 'project',
+        status: opts.dryRun ? 'would-import' : 'imported',
+    };
+}
 function readIgnoreState() {
     let doc;
     try {
@@ -257,32 +470,33 @@ function renderSummary(results, ignoreMode) {
 }
 export const sysSyncLeaf = defineLeaf({
     name: 'sync',
-    description: 'convert legacy SKILL.md bundles into crouter memory docs',
-    whenToUse: 'migrating host-native Agent Skill bundles into the crouter memory-doc model. This is a one-way import from SKILL.md to memory/<name>.md; it never exports memory docs back to SKILL.md and never treats SKILL.md as an active crouter guidance surface.',
+    description: 'convert legacy SKILL.md bundles and CLAUDE.md/AGENTS.md/.claude/rules into crouter memory docs',
+    whenToUse: 'migrating legacy guidance surfaces into the crouter memory-doc model: host-native Agent Skill bundles (SKILL.md, one-way import into a scope-root memory dir) AND per-project CLAUDE.md/AGENTS.md/.claude/rules (one-way copy into that same directory\'s OWN .crouter/memory/, so the doc travels with the repo and gets positional on-read for free). Both are one-way; sync never exports memory docs back to any of these files and never treats them as an active crouter guidance surface once migrated — crouter stops reading the originals unconditionally.',
     help: {
         name: 'sys sync',
-        summary: 'one-way import: SKILL.md bundles → crouter memory docs',
+        summary: 'one-way import: SKILL.md bundles + CLAUDE.md/AGENTS.md/.claude/rules → crouter memory docs',
         params: [
-            { kind: 'flag', name: 'source', type: 'string', required: false, constraint: 'A SKILL.md file, a single skill bundle dir containing SKILL.md, or a skills root to scan recursively. Default: user/project Claude and pi skill roots that exist.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Target memory scope. Default: user for user host roots and project for project host roots; explicit value applies to every imported source.' },
+            { kind: 'flag', name: 'source', type: 'string', required: false, constraint: 'For SKILL.md: a SKILL.md file, a single skill bundle dir containing SKILL.md, or a skills root to scan recursively; default is the user/project Claude and pi skill roots that exist. For CLAUDE.md/AGENTS.md/.claude/rules: the root to walk recursively for those files; default is cwd plus every project in the current profile\'s purview (when one is selected). One value drives both discoveries.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Target memory scope for imported SKILL.md sources only. Default: user for user host roots and project for project host roots; explicit value applies to every imported SKILL.md source. Does not affect CLAUDE.md/AGENTS.md/.claude/rules migration — those always target their own source directory\'s .crouter/memory/, never a scope root.' },
             { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Show what would be imported without writing memory docs.' },
             { kind: 'flag', name: 'overwrite', type: 'bool', required: false, constraint: 'Replace an existing target memory doc. Default: skip existing docs to avoid clobbering user-authored memory.' },
-            { kind: 'flag', name: 'ignore', type: 'bool', required: false, constraint: `Permanently ignore every selected source by recording it in ~/.crouter/${IGNORE_FILE}. Honors --source/--scope; with no --source, ignores every currently discovered default host skill candidate.` },
-            { kind: 'flag', name: 'include-ignored', type: 'bool', required: false, constraint: 'Include ignored candidates in the report without making sync read-only. Pair with --dry-run to audit the full candidate set without importing non-ignored skills.' },
+            { kind: 'flag', name: 'ignore', type: 'bool', required: false, constraint: `Permanently ignore every selected SKILL.md source by recording it in ~/.crouter/${IGNORE_FILE}. Honors --source/--scope; with no --source, ignores every currently discovered default host skill candidate. Does not apply to CLAUDE.md/AGENTS.md/.claude/rules — that migration is skipped entirely when --ignore is present.` },
+            { kind: 'flag', name: 'include-ignored', type: 'bool', required: false, constraint: 'Include ignored SKILL.md candidates in the report without making sync read-only. Pair with --dry-run to audit the full candidate set without importing non-ignored skills.' },
         ],
         output: [
-            { name: 'imported', type: 'number', required: true, constraint: 'Count of memory docs written.' },
-            { name: 'skipped', type: 'number', required: true, constraint: 'Count of SKILL.md files skipped.' },
+            { name: 'imported', type: 'number', required: true, constraint: 'Count of memory docs written, across both SKILL.md and CLAUDE.md/AGENTS.md/.claude/rules sources.' },
+            { name: 'skipped', type: 'number', required: true, constraint: 'Count of source files skipped (existing target without --overwrite, or an unimportable SKILL.md).' },
             { name: 'ignored', type: 'number', required: true, constraint: 'Count of selected SKILL.md files that are permanently ignored.' },
             { name: 'wouldIgnore', type: 'number', required: true, constraint: 'Count of selected SKILL.md files that would be ignored under --dry-run.' },
-            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status may be imported, skipped, would-import, ignored, or would-ignore.' },
+            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status may be imported, skipped, would-import, ignored, or would-ignore. A CLAUDE.md/AGENTS.md/.claude/rules row never carries ignored/would-ignore.' },
         ],
         outputKind: 'object',
         effects: [
             'Writes memory/<name>.md in the selected crouter scope with substrate frontmatter and the SKILL.md body.',
+            'Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/AGENTS.md at system-prompt-visibility/file-read-visibility content/content, and each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md at none/content (applies-to set from the rule\'s paths: globs when present) — copy, not move; original files are left untouched.',
             'Skips existing memory docs unless --overwrite is present.',
             'Skips marker-bearing generated crtr boot skills; host exports prune those legacy artifacts instead.',
-            `With --ignore: writes ~/.crouter/${IGNORE_FILE} and does not import the selected sources.`,
+            `With --ignore: writes ~/.crouter/${IGNORE_FILE} and does not import the selected SKILL.md sources; the CLAUDE.md/AGENTS.md/.claude/rules migration does not run at all in this mode.`,
             'With --dry-run: read-only; writes nothing.',
         ],
     },
@@ -328,6 +542,22 @@ export const sysSyncLeaf = defineLeaf({
         }
         if (changedIgnoreState)
             writeIgnoreState(ignoreState);
+        // Project-doc migration (CLAUDE.md/AGENTS.md/.claude/rules) — independent
+        // of --ignore (a skill-only verb); an explicit --source pins its walk root
+        // too, so one invocation with --source drives both machineries over the
+        // same tree.
+        if (!ignoreMode) {
+            const docSeen = new Set();
+            for (const root of projectDocRoots(sourceArg)) {
+                for (const c of collectProjectDocCandidates(root)) {
+                    if (docSeen.has(c.path))
+                        continue;
+                    docSeen.add(c.path);
+                    const prepared = c.kind === 'agents' ? prepareAgentsCandidate(c) : prepareRuleCandidate(c);
+                    results.push(convertProjectDoc(prepared, { dryRun, overwrite }));
+                }
+            }
+        }
         const imported = results.filter((r) => r.status === 'imported').length;
         const wouldImport = results.filter((r) => r.status === 'would-import').length;
         const skipped = results.filter((r) => r.status === 'skipped').length;

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -83,11 +83,13 @@ test('C3b — broker splits model thinking suffix before SDK registry lookup', a
         rmSync(cwd, { recursive: true, force: true });
     }
 });
-// (C4 — project AGENTS.md/CLAUDE.md injection — was removed: crouter now sets
-// `noContextFiles: true` in buildBrokerSession and re-renders project context
-// into the first-message <crtr-context> bearings instead of pi's system prompt
-// (broker.ts). That behavior is covered by context-intro.test.ts's "project
-// instructions ride the bearings, not the system prompt" test.)
+// (C4 — project AGENTS.md/CLAUDE.md injection — was removed: crouter sets
+// `noContextFiles: true` in buildBrokerSession unconditionally (broker.ts) and
+// no longer re-renders those files into the bearings either (hard cut,
+// 2026-07-06) — project guidance now comes from the document substrate
+// (`crtr sys sync` migrates CLAUDE.md/AGENTS.md into a memory doc). Covered by
+// context-intro.test.ts's "a CLAUDE.md in the node's cwd no longer rides the
+// bearings" test.)
 // ===========================================================================
 // C2 — zero-viewer dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
 // hanging the turn and never waiting on a per-dialog timeout. Drives the REAL

package/dist/core/__tests__/context-intro.test.js

@@ -20,14 +20,9 @@ import { personaDrift } from '../runtime/persona.js';
 import { memoryDir } from '../runtime/memory.js';
 import registerCanvasContextIntro, { buildContextIntro, renderContextMessage, CONTEXT_INTRO_CUSTOM_TYPE, } from '../../pi-extensions/canvas-context-intro.js';
 let home;
-let prevAgentDir;
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-ctxintro-'));
     process.env['CRTR_HOME'] = home;
-    // Isolate pi's global agent dir to an empty path so buildProjectContextBlock
-    // can't pick up the dev machine's real ~/.pi/agent/AGENTS.md (hermeticity).
-    prevAgentDir = process.env['PI_CODING_AGENT_DIR'];
-    process.env['PI_CODING_AGENT_DIR'] = join(home, 'no-agent-dir');
 });
 beforeEach(() => {
     closeDb();
@@ -38,10 +33,6 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
-    if (prevAgentDir === undefined)
-        delete process.env['PI_CODING_AGENT_DIR'];
-    else
-        process.env['PI_CODING_AGENT_DIR'] = prevAgentDir;
 });
 test('worker bearings: base framing + <knowledge> block, NO across-cycles framing', () => {
     // Bug-regression: review finding M1 — buildContextBearings renders the
@@ -78,20 +69,22 @@ test('worker bearings: base framing + <knowledge> block, NO across-cycles framin
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-bearings>/);
 });
-test('project instructions (AGENTS.md/CLAUDE.md) ride the bearings, not the system prompt', () => {
-    // pi's <project_context> is suppressed in the system prompt (broker.ts
-    // noContextFiles) and re-rendered into the first-message bearings here. The
-    // discovery walks the node cwd ancestry, so a CLAUDE.md in the node's cwd must
-    // surface inside a <project_context> block AFTER the <crtr-bearings> block.
+test('a CLAUDE.md in the node\'s cwd no longer rides the bearings; only the <environment> snapshot does (hard cut, 2026-07-06)', () => {
+    // buildProjectContextBlock used to re-render the node's AGENTS.md/CLAUDE.md
+    // into a <project_instructions> block (pi's own copy stays suppressed via
+    // broker.ts noContextFiles). That machinery is gone: project guidance now
+    // comes from the document substrate (a migrated AGENTS.md doc rides the
+    // <memory kind="knowledge"> block instead — see `crtr sys sync`), so a bare
+    // on-disk CLAUDE.md is simply never read by crtr at boot any more.
     const proj = mkdtempSync(join(tmpdir(), 'crtr-proj-'));
     writeFileSync(join(proj, 'CLAUDE.md'), 'PROJECT_MARKER: build then commit.\n');
     const meta = spawnNode({ kind: 'general', cwd: proj, parent: null });
     const block = buildContextIntro(meta.node_id);
-    assert.match(block, /<project_context>/, 'project_context block present in the bearings');
-    assert.match(block, new RegExp(`<project_instructions path="${join(proj, 'CLAUDE.md')}">`), 'the project CLAUDE.md is rendered with its path');
-    assert.match(block, /PROJECT_MARKER: build then commit\./, 'project file content rides the message');
-    assert.match(block, /<environment cwd=".*crtr-proj-.*">/, 'environment block is appended inside project_context');
-    assert.match(block, /Directory:\n  CLAUDE\.md\n/, 'environment block includes an ls-style listing');
+    assert.doesNotMatch(block, /<project_instructions/, 'no <project_instructions> block is ever emitted');
+    assert.doesNotMatch(block, /PROJECT_MARKER: build then commit\./, 'the CLAUDE.md body never rides the bearings');
+    assert.match(block, /<project_context>/, 'project_context wrapper still present');
+    assert.match(block, /<environment cwd=".*crtr-proj-.*">/, 'environment block still rides inside project_context');
+    assert.match(block, /Directory:\n  CLAUDE\.md\n/, 'environment block still includes an ls-style listing');
     assert.match(block, /Git: not a git repository\./, 'git snapshot degrades cleanly for a non-repo');
     assert.match(block, /<environment[\s\S]*<\/environment>\n<\/project_context>$/, 'environment block closes project_context');
     assert.ok(block.indexOf('</crtr-bearings>') < block.indexOf('<project_context>'), 'project_context follows the crtr-bearings block');

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