@crouton-kit/crouter 0.3.47 → 0.3.49

package/dist/core/profiles/select.js

@@ -1,14 +1,17 @@
 // Startup profile selection — the CTO-decided order applied at the front door
-// and at any non-inherited `crtr node new`: explicit `--profile` > a profile
-// whose project dir IS cwd exactly (auto) > an interactive menu of profiles
-// covering cwd from a parent/workspace dir + create (MRU auto when headless) >
-// synchronous create-or-root decision when nothing covers. This is the ONLY
-// place that decision runs; front-door.ts/spawn.ts call it, never re-derive it.
+// and at any non-inherited `crtr node new`: explicit `--profile` > a per-cwd
+// PINNED default (set from the menu with `d`, wins over MRU while it still
+// covers cwd) > a profile whose project dir IS cwd exactly (auto) > an
+// interactive menu of profiles covering cwd from a parent/workspace dir +
+// create (MRU auto when headless) > synchronous create-or-root decision when
+// nothing covers. This is the ONLY place that decision runs; front-door.ts/
+// spawn.ts call it, never re-derive it.
 import { existsSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, resolve as resolvePath, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, addProfileProject, } from './manifest.js';
+import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, } from './default-binding.js';
 import { stdoutColor } from '../output.js';
 /** Resolve cwd to an absolute, realpath'd form so it compares against the
  *  realpath'd project dirs `createProfile`/`addProfileProject` already store
@@ -38,7 +41,11 @@ function projectCovers(cwd, project) {
         return true;
     return false;
 }
-function profileCoversCwd(entry, cwd) {
+/** 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 function profileCoversCwd(entry, cwd) {
     return entry.manifest.projects.some((p) => projectCovers(cwd, p));
 }
 /** `a` more recent than `b`, treating null as the oldest possible value (never
@@ -114,10 +121,11 @@ function writeHeader(title, subtitle) {
     process.stdout.write(`\n  ${bold(title)}\n${sub}\n`);
 }
 /** One option row: `    <key>  <label>  <dim detail>  · default`. `label` is
- *  passed pre-styled; `detail` is dimmed here; the default row gets a marker. */
-function optionRow(k, label, detail, isDefault) {
+ *  passed pre-styled; `detail` is dimmed here; the default row gets a marker
+ *  whose text (`default` vs `default (pinned)`) the caller supplies. */
+function optionRow(k, label, detail, isDefault, defaultText = 'default') {
     const det = detail !== '' ? '  ' + dim(detail) : '';
-    const def = isDefault ? '  ' + accent('\u00b7 default') : '';
+    const def = isDefault ? '  ' + accent('\u00b7 ' + defaultText) : '';
     return `    ${key(k)}  ${label}${det}${def}\n`;
 }
 /** The trailing readline prompt: `  › <dim hint> `. */
@@ -141,7 +149,7 @@ function recoveryMessage(cwd) {
 /** Explicit `--profile` names a profile whose manifest does NOT cover cwd.
  *  Interactive only: offer to widen the profile's purview to include this
  *  directory (default yes), so the next node started here is covered without a
- *  separate `crtr profile add-project`. Declining leaves the manifest untouched
+ *  separate `crtr profile project add`. Declining leaves the manifest untouched
  *  and runs the node under the profile anyway. Same raw-readline rationale as
  *  `promptCreateOrRoot` — this gates pi's boot on the same TTY. */
 async function promptAddDirToProfile(entry, cwd) {
@@ -196,10 +204,15 @@ async function promptCreateOrRoot(cwd) {
  *  here: a claimed/covered directory always has at least a covering profile as a
  *  sane identity, so `[r]oot` belongs only to the no-coverage prompt
  *  (`promptCreateOrRoot`). Same raw-readline / boot-gating rationale. */
-async function promptPickProfileOrCreate(candidates, cwd, exact) {
-    // MRU-first so the most-recently-used candidate is choice 1 / the bare-Enter
-    // default — the same profile the non-interactive path auto-picks.
-    const ordered = [...candidates].sort((a, b) => isMoreRecent(a.manifest.last_used_at, b.manifest.last_used_at) ? -1 : 1);
+async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId) {
+    // MRU-first so the most-recently-used candidate is the bare-Enter default —
+    // the same profile the non-interactive path auto-picks. A per-cwd pin (set
+    // here with `d`) overrides that: it sorts to the top and becomes the
+    // Enter-default, so a single Enter keeps picking the user's chosen profile
+    // for this directory even as global-MRU drifts to other workspaces.
+    const mru = [...candidates].sort((a, b) => isMoreRecent(a.manifest.last_used_at, b.manifest.last_used_at) ? -1 : 1);
+    const pinned = pinnedId !== null ? mru.find((e) => e.profileId === pinnedId) ?? null : null;
+    const ordered = pinned !== null ? [pinned, ...mru.filter((e) => e !== pinned)] : mru;
     // Pad names to a shared column so the dim detail lines up down the menu.
     const nameWidth = Math.max(...ordered.map((e) => e.manifest.name.length));
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -215,21 +228,46 @@ async function promptPickProfileOrCreate(candidates, cwd, exact) {
                 ? relativeUsed(entry.manifest.last_used_at)
                 : `covers ${tildify(entry.manifest.projects.find((p) => projectCovers(cwd, p)) ?? entry.manifest.projects[0])}`;
             const label = bold(entry.manifest.name.padEnd(nameWidth));
-            process.stdout.write(optionRow(String(i + 1), label, detail, i === 0));
+            const defaultText = pinned !== null && ordered[0] === pinned ? 'default (pinned)' : 'default';
+            process.stdout.write(optionRow(String(i + 1), label, detail, i === 0, defaultText));
         });
         process.stdout.write(optionRow('c', dim('create a new profile here'), '', false));
         process.stdout.write('\n');
+        // Action suffixes on a pick: `<n>d` also pins #n as this directory's
+        // default; `<n>a` also widens #n's purview to include cwd (meaningless when
+        // the candidates already claim cwd exactly, so hidden there). `u` clears an
+        // existing pin. A bare letter applies to the default row (choice 1).
+        const parts = ['d=set default'];
+        if (!exact)
+            parts.push('a=add dir here');
+        if (pinned !== null)
+            parts.push('u=unpin');
+        process.stdout.write(`    ${dim(parts.join('  '))}\n\n`);
         const answer = (await rl.question(caret('[1]'))).trim().toLowerCase();
         if (answer === 'c' || answer === 'create')
             return await createProfileHere(rl, cwd);
-        if (answer === '')
+        if (answer === 'u' || answer === 'unpin') {
+            clearDefaultProfile(cwd);
+            process.stdout.write(`  ${accent('\u2713')} ${dim('cleared the default for this directory')}\n`);
             return ordered[0].profileId;
-        const n = Number.parseInt(answer, 10);
-        if (Number.isInteger(n) && n >= 1 && n <= ordered.length)
-            return ordered[n - 1].profileId;
-        // Unrecognized input → the safe default (the MRU candidate); never loop,
-        // since this prompt is gating pi's boot on the shared TTY.
-        return ordered[0].profileId;
+        }
+        const m = /^(\d+)?([da])?$/.exec(answer);
+        // Unrecognized input → the safe default (choice 1); never loop, since this
+        // prompt is gating pi's boot on the shared TTY.
+        if (m === null)
+            return ordered[0].profileId;
+        const [, numStr, action] = m;
+        const idx = numStr !== undefined ? Number.parseInt(numStr, 10) - 1 : 0;
+        const picked = idx >= 0 && idx < ordered.length ? ordered[idx] : ordered[0];
+        if (action === 'd') {
+            setDefaultProfileId(cwd, picked.profileId);
+            process.stdout.write(`  ${accent('\u2713')} ${dim(`"${picked.manifest.name}" is now the default here`)}\n`);
+        }
+        else if (action === 'a') {
+            addProfileProject(picked.profileId, cwd);
+            process.stdout.write(`  ${accent('\u2713')} ${dim(`added this directory to "${picked.manifest.name}"`)}\n`);
+        }
+        return picked.profileId;
     }
     finally {
         rl.close();
@@ -241,6 +279,12 @@ async function promptPickProfileOrCreate(candidates, cwd, exact) {
  *     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
@@ -255,7 +299,7 @@ async function promptPickProfileOrCreate(candidates, cwd, exact) {
  *     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 async function selectProfileForCwd(cwd, explicitProfile) {
+export async function selectProfileForCwd(cwd, explicitProfile, forcePicker = false) {
     const resolvedCwd = resolveCwd(cwd);
     if (explicitProfile !== undefined && explicitProfile !== null && explicitProfile !== '') {
         const entry = loadProfileManifest(explicitProfile);
@@ -269,9 +313,30 @@ export async function selectProfileForCwd(cwd, explicitProfile) {
     }
     const covering = listProfiles().filter((p) => profileCoversCwd(p, resolvedCwd));
     const exact = covering.filter((p) => p.manifest.projects.some((proj) => proj === resolvedCwd));
+    // A per-cwd pinned default (set from the menu with `d`) is the user's
+    // explicit "default to THIS profile HERE". It outranks both the exact-single
+    // auto-pick and global-MRU, so long as it still covers cwd; a stale pin
+    // (profile deleted, or its dir removed from purview) is self-healed away.
+    const pinnedId = getDefaultProfileId(resolvedCwd);
+    const pinned = pinnedId !== null ? covering.find((p) => p.profileId === pinnedId) ?? null : null;
+    if (pinnedId !== null && pinned === null)
+        clearDefaultProfile(resolvedCwd);
+    // A valid pin decides it outright and STOPS ASKING — the whole point of
+    // setting a default. Auto-pick it (interactive too), printing a one-line
+    // breadcrumb so the choice isn't invisible and the user knows how to change
+    // it. `crtr --pick-profile` (forcePicker) re-opens the menu to re-pin/unpin.
+    if (pinned !== null && !forcePicker) {
+        updateProfileLastUsed(pinned.profileId);
+        if (isInteractive()) {
+            process.stdout.write(`  ${accent('\u2713')} ${bold(pinned.manifest.name)} ${dim('\u00b7 default for this directory')}` +
+                `  ${dim('(crtr --pick-profile to change)')}\n`);
+        }
+        return pinned.profileId;
+    }
     // Exactly one profile's project dir IS cwd — unambiguous project root, use it
     // silently, never a prompt. (Several exact claims fall through to the menu.)
-    if (exact.length === 1) {
+    // Suppressed under forcePicker so `--pick-profile` can pin even a lone owner.
+    if (!forcePicker && pinned === null && exact.length === 1) {
         updateProfileLastUsed(exact[0].profileId);
         return exact[0].profileId;
     }
@@ -290,10 +355,11 @@ export async function selectProfileForCwd(cwd, explicitProfile) {
     // Interactive. Several exact claimants → choose among them. Else covered from
     // a parent/workspace dir → menu of covering profiles. Else nothing covers →
     // the create-or-root prompt (root is only ever offered there).
+    const validPinnedId = pinned !== null ? pinned.profileId : null;
     const chosen = exact.length > 1
-        ? await promptPickProfileOrCreate(exact, resolvedCwd, true)
+        ? await promptPickProfileOrCreate(exact, resolvedCwd, true, validPinnedId)
         : covering.length > 0
-            ? await promptPickProfileOrCreate(covering, resolvedCwd, false)
+            ? await promptPickProfileOrCreate(covering, resolvedCwd, false, validPinnedId)
             : await promptCreateOrRoot(resolvedCwd);
     if (chosen !== null)
         updateProfileLastUsed(chosen);

package/dist/core/runtime/bearings.d.ts

@@ -1,8 +1,13 @@
 import { type Trigger } from '../canvas/index.js';
-/** The `<project_context>` block for the files discovered from `cwd`, plus the
- *  cwd/git environment snapshot that now rides at the end of the wrapper.
- *  Always emits the wrapper because the environment snapshot is always present
- *  even when no project instructions exist. Exported for testing. */
+/** The `<project_context>` block — now just the cwd/git `<environment>`
+ *  snapshot (dir listing + git status/worktrees). This USED to also carry a
+ *  `<project_instructions>` block re-rendering the node's AGENTS.md/CLAUDE.md;
+ *  that machinery is gone (hard cut, 2026-07-06) — project guidance now lives
+ *  in the document substrate (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md
+ *  into that dir's own `.crouter/memory/AGENTS.md` at content/content, so it
+ *  surfaces via the `<memory kind="knowledge">` block instead). Always emits
+ *  the wrapper because the environment snapshot is always present. Exported
+ *  for testing. */
 export declare function buildProjectContextBlock(cwd: string): string;
 /** The context-directory note — names the path INLINE (no XML attribute, so it
  *  never scopes a sibling block) and frames the dir as durable, shared scratch.
@@ -85,7 +90,10 @@ export declare function buildWakeBearings(origin: WakeOrigin): string;
  *      from.
  *   2. `<memory kind="knowledge">` — the consultable catalog, a SIBLING of the
  *      bearings (never nested under the context dir). Dropped when empty.
- *   3. `<project_context>` — the AGENTS.md/CLAUDE.md instructions + the cwd/git
- *      environment snapshot, moved OUT of the system prompt (pi's copy is
- *      suppressed via noContextFiles in broker.ts) so it rides this message. */
+ *   3. `<project_context>` — the cwd/git environment snapshot. pi's own
+ *      AGENTS.md/CLAUDE.md system-prompt injection stays suppressed
+ *      (noContextFiles in broker.ts); project guidance instead rides the
+ *      `<memory kind="knowledge">` block above via the document substrate
+ *      (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md into that dir's own
+ *      `.crouter/memory/AGENTS.md`). */
 export declare function buildContextBearings(nodeId: string): string;

package/dist/core/runtime/bearings.js

@@ -13,10 +13,15 @@
 //     the source's whole conversation and then impersonates it. A non-fork
 //     node's bearings are its FIRST entry, so there is nothing earlier to
 //     disown; it gets only the declarative identity line. The message also
-//     carries the <project_context> block (buildProjectContextBlock) — the
-//     AGENTS.md/CLAUDE.md project instructions, moved OUT of the system prompt
-//     (pi's copy is suppressed via noContextFiles in broker.ts) so they ride
-//     this user message instead;
+//     carries the <project_context> block (buildProjectContextBlock) — now just
+//     the cwd/git <environment> snapshot. Project instructions (what used to be
+//     a re-rendered AGENTS.md/CLAUDE.md here) come from the document substrate
+//     instead: `crtr sys sync` migrates each CLAUDE.md/AGENTS.md into that
+//     dir's own `.crouter/memory/AGENTS.md` at content/content, so it rides the
+//     <memory kind="knowledge"> block below (renderKnowledgeBlock) via the
+//     profile-widened boot render, exactly like any other substrate doc — no
+//     parallel re-implementation of pi's project-context loader lives here
+//     anymore (see `crtr memory read taste/document-substrate`);
 //   • promote.ts folds orchestratorContextNote() into the promotion guidance
 //     dump, so a node that becomes an orchestrator MID-LIFE gets the
 //     orchestrator framing it never received at spawn — it spawned as a base
@@ -36,78 +41,10 @@
 // This across-cycles note is the ONE thing a terminal worker's bearings drop.
 import { contextDir, getNode, fullName, subscriptionsOf, } from '../canvas/index.js';
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { readdirSync } from 'node:fs';
 import { cadenceDisplay } from '../wake.js';
 import { renderKnowledgeBlock } from '../substrate/index.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
-// ---------------------------------------------------------------------------
-// Project context (<project_context>) — the AGENTS.md/CLAUDE.md files pi would
-// otherwise inject into its SYSTEM PROMPT, rendered here so they ride the
-// first-message bearings instead (pi's copy is suppressed via
-// resourceLoaderOptions.noContextFiles in broker.ts). We re-implement pi's
-// loadProjectContextFiles + getAgentDir (resource-loader.js / config.js) rather
-// than IMPORT pi: bearings.ts is statically imported by the thin daemon (crtrd,
-// for wakeOriginFrom), so a static @earendil-works import would pull the whole
-// pi engine into the supervisor. The discovery is a stable convention + pure fs.
-// ---------------------------------------------------------------------------
-/** pi's getAgentDir(): the global agent config dir holding a user-wide context
- *  file. Honors PI_CODING_AGENT_DIR (tilde-expanded), else ~/.pi/agent (pi's
- *  piConfig.configDir is ".pi"). */
-function piAgentDir() {
-    const env = process.env['PI_CODING_AGENT_DIR'];
-    if (env !== undefined && env !== '') {
-        return env.startsWith('~') ? join(homedir(), env.slice(1)) : env;
-    }
-    return join(homedir(), '.pi', 'agent');
-}
-/** Per-dir context-file candidates, in pi's precedence order (first match wins). */
-const CONTEXT_FILE_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD'];
-function loadContextFileFromDir(dir) {
-    for (const name of CONTEXT_FILE_CANDIDATES) {
-        const p = join(dir, name);
-        if (existsSync(p)) {
-            try {
-                return { path: p, content: readFileSync(p, 'utf8') };
-            }
-            catch {
-                // Unreadable candidate — skip, mirroring pi (best-effort).
-            }
-        }
-    }
-    return null;
-}
-/** Mirror of pi's loadProjectContextFiles: the global agent-dir file first, then
- *  every AGENTS.md/CLAUDE.md up the cwd's ancestry, ordered root→cwd (so the
- *  most-specific project file reads last). Deduped by absolute path. */
-function loadProjectContextFiles(cwd) {
-    const files = [];
-    const seen = new Set();
-    const global = loadContextFileFromDir(piAgentDir());
-    if (global !== null) {
-        files.push(global);
-        seen.add(global.path);
-    }
-    const ancestors = [];
-    let dir = resolve(cwd);
-    const root = resolve('/');
-    for (;;) {
-        const f = loadContextFileFromDir(dir);
-        if (f !== null && !seen.has(f.path)) {
-            ancestors.unshift(f);
-            seen.add(f.path);
-        }
-        if (dir === root)
-            break;
-        const parent = resolve(dir, '..');
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    files.push(...ancestors);
-    return files;
-}
 function escapeAttribute(value) {
     return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
 }
@@ -175,18 +112,19 @@ function parseWorktrees(lines) {
     }
     return worktrees;
 }
-/** The `<project_context>` block for the files discovered from `cwd`, plus the
- *  cwd/git environment snapshot that now rides at the end of the wrapper.
- *  Always emits the wrapper because the environment snapshot is always present
- *  even when no project instructions exist. Exported for testing. */
+/** The `<project_context>` block — now just the cwd/git `<environment>`
+ *  snapshot (dir listing + git status/worktrees). This USED to also carry a
+ *  `<project_instructions>` block re-rendering the node's AGENTS.md/CLAUDE.md;
+ *  that machinery is gone (hard cut, 2026-07-06) — project guidance now lives
+ *  in the document substrate (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md
+ *  into that dir's own `.crouter/memory/AGENTS.md` at content/content, so it
+ *  surfaces via the `<memory kind="knowledge">` block instead). Always emits
+ *  the wrapper because the environment snapshot is always present. Exported
+ *  for testing. */
 export function buildProjectContextBlock(cwd) {
-    const files = loadProjectContextFiles(cwd);
     const envLines = directoryListingLines(cwd);
     const git = gitSnapshot(cwd);
-    let out = '<project_context>\n\nProject-specific instructions and guidelines:\n\n';
-    for (const { path, content } of files) {
-        out += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
-    }
+    let out = '<project_context>\n\n';
     out += `<environment cwd="${escapeAttribute(cwd)}">\n`;
     out += `Directory:\n${envLines.map((line) => `  ${line}`).join('\n')}\n`;
     out += `${git.lines.map((line) => `${line}`).join('\n')}\n`;
@@ -432,9 +370,12 @@ export function buildWakeBearings(origin) {
  *      from.
  *   2. `<memory kind="knowledge">` — the consultable catalog, a SIBLING of the
  *      bearings (never nested under the context dir). Dropped when empty.
- *   3. `<project_context>` — the AGENTS.md/CLAUDE.md instructions + the cwd/git
- *      environment snapshot, moved OUT of the system prompt (pi's copy is
- *      suppressed via noContextFiles in broker.ts) so it rides this message. */
+ *   3. `<project_context>` — the cwd/git environment snapshot. pi's own
+ *      AGENTS.md/CLAUDE.md system-prompt injection stays suppressed
+ *      (noContextFiles in broker.ts); project guidance instead rides the
+ *      `<memory kind="knowledge">` block above via the document substrate
+ *      (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md into that dir's own
+ *      `.crouter/memory/AGENTS.md`). */
 export function buildContextBearings(nodeId) {
     const node = getNode(nodeId);
     const bearings = ['<crtr-bearings>', buildIdentityAssertion(nodeId)];

package/dist/core/runtime/broker.js

@@ -1706,10 +1706,11 @@ export async function buildBrokerSession(engine, cfg) {
             resourceLoaderOptions: {
                 additionalExtensionPaths: cfg.extensionPaths,
                 appendSystemPrompt: cfg.appendSystemPromptPath !== undefined ? [cfg.appendSystemPromptPath] : undefined,
-                // Suppress pi's <project_context> in the SYSTEM PROMPT — crouter
-                // re-renders the same AGENTS.md/CLAUDE.md files into the first-message
-                // <crtr-context> bearings instead (buildProjectContextBlock), so all
-                // project instructions ride the user message, not the system prompt.
+                // Suppress pi's <project_context> AGENTS.md/CLAUDE.md injection in the
+                // SYSTEM PROMPT unconditionally — crouter reads project guidance through
+                // the document substrate instead (a migrated AGENTS.md doc rides the
+                // <memory kind="knowledge"> block in the first-message bearings; see
+                // bearings.ts and `crtr sys sync`), never pi's own file-based loader.
                 noContextFiles: true,
             },
         });

package/dist/core/runtime/front-door.js

@@ -5,8 +5,11 @@
 //   crtr [dir] ["prompt"]        → root with a starter prompt
 //   crtr --name NAME ...         → named root
 //   crtr --profile <id-or-name>  → root under an explicit profile (else the
-//                                  startup selector: MRU covering cwd, else a
-//                                  synchronous create-or-root prompt)
+//                                  startup selector: a per-cwd pinned default,
+//                                  else MRU covering cwd, else a synchronous
+//                                  create-or-root prompt)
+//   crtr --pick-profile          → force the profile chooser open even when a
+//                                  per-cwd default is pinned (to re-pin/unpin)
 //   crtr <subcommand> ...        → falls through to the normal dispatcher
 //   crtr -h | --help             → root help (dispatcher)
 //
@@ -28,7 +31,7 @@ function isDir(p) {
  *  positional dir/prompt). A leading token in this set still boots a root —
  *  without it, `crtr --name X` would fall through to the dispatcher and error as
  *  an unknown subcommand. */
-const FRONT_DOOR_FLAGS = new Set(['--name', '--kind', '--profile']);
+const FRONT_DOOR_FLAGS = new Set(['--name', '--kind', '--profile', '--pick-profile']);
 /** Parse `[dir] [prompt]` positionals + the front-door flags out of the leftover
  *  tokens after the bare `crtr`. */
 function parseRootArgs(tokens) {
@@ -36,6 +39,7 @@ function parseRootArgs(tokens) {
     let name;
     let kind;
     let profile;
+    let pickProfile = false;
     const positionals = [];
     for (let i = 0; i < tokens.length; i++) {
         const t = tokens[i];
@@ -48,6 +52,9 @@ function parseRootArgs(tokens) {
         else if (t === '--profile') {
             profile = tokens[++i];
         }
+        else if (t === '--pick-profile') {
+            pickProfile = true;
+        }
         else if (t.startsWith('--')) {
             // ignore unknown flags for the front door
         }
@@ -60,7 +67,7 @@ function parseRootArgs(tokens) {
         cwd = resolvePath(positionals.shift());
     }
     const prompt = positionals.length > 0 ? positionals.join(' ') : undefined;
-    return { cwd, prompt, name, kind, profile };
+    return { cwd, prompt, name, kind, profile, pickProfile };
 }
 /** Env marker set on every pi the front door boots. Its presence means we are
  *  already inside a front-door-booted root, so a nested front-door launch must

package/dist/core/runtime/revive.js

@@ -203,7 +203,8 @@ export function reviveNode(nodeId, opts) {
             // without this a manager waiting dormant on this child hangs forever,
             // never told it will not come back on its own. Mirrors closeNode's step-4
             // fan-out (same subscribers table, same active/passive split).
-            fanDoctrineWake(nodeId, subscribersOf(nodeId), `Child crashed — ${fullName(meta)} (${nodeId}) failed to relaunch and is now dead. It will NOT resume on its own.`, { reason: 'child-crashed', child: nodeId });
+            fanDoctrineWake(nodeId, subscribersOf(nodeId), `Child crashed — ${fullName(meta)} (${nodeId}) failed to relaunch and is now dead: ${error.message}\n\n` +
+                `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`, { reason: 'child-crashed', child: nodeId });
         }
         catch {
             /* best-effort cleanup */

package/dist/core/runtime/spawn.d.ts

@@ -11,6 +11,10 @@ export interface BootRootOpts {
      *  selector for `cwd` (see `selectProfileForCwd`) — a root has no spawner to
      *  inherit from, so this is the front door's only source of profile identity. */
     profile?: string | null;
+    /** `crtr --pick-profile`: force the startup profile chooser to open even when
+     *  a per-cwd default is pinned, so the user can re-pin or unpin it. Without
+     *  this a pinned default auto-picks silently (that is what "default" means). */
+    pickProfile?: boolean;
 }
 /** Create the front-door root: launch its broker engine, then exec `crtr surface attach`
  *  inline so THIS terminal becomes the broker's controller-viewer. Does not

package/dist/core/runtime/spawn.js

@@ -69,7 +69,7 @@ export async function bootRoot(opts) {
     // The front door's only source of profile identity — a root has no spawner
     // to inherit from. Runs BEFORE spawnNode: explicit --profile > MRU profile
     // covering cwd > a synchronous create-or-root prompt (or root, headless).
-    const profileId = await selectProfileForCwd(opts.cwd, opts.profile);
+    const profileId = await selectProfileForCwd(opts.cwd, opts.profile, opts.pickProfile ?? false);
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
     const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false });

package/dist/core/substrate/on-read.js

@@ -9,10 +9,12 @@
 //   • POSITIONAL — walk the read file's ancestor dirs; any doc living in an
 //     ancestor PROJECT `.crouter/memory/` surfaces (a doc surfaces when a file
 //     beside/under its own project scope dir is read), UNLESS it carries an
-//     explicit read-trigger (see D5 below). This mirrors nested-context's
-//     `.claude/rules` ancestor walk, but keyed on `.crouter/memory/`. The
-//     user-global `~/.crouter/memory/` store is NOT positional; user docs only
-//     fire on reads through explicit `applies-to` / `read-when` triggers.
+//     explicit read-trigger (see D5 below). This is the substrate's own
+//     ancestor walk keyed on `.crouter/memory/` — the same shape the retired
+//     nested-context pi-extension used for `.claude/rules` before that path
+//     was migrated into substrate docs (`crtr sys sync`). The user-global
+//     `~/.crouter/memory/` store is NOT positional; user docs only fire on
+//     reads through explicit `applies-to` / `read-when` triggers.
 //   • applies-to GLOB — any RESOLVED substrate doc (user/project/builtin scope)
 //     whose `appliesTo` glob matches the read file path surfaces, regardless of
 //     where the read file sits relative to the doc.
@@ -63,8 +65,9 @@ import { cachedSubstrateDocs } from './session-cache.js';
 // is the segment we explicitly join onto each surviving ancestor).
 const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
 // ---------------------------------------------------------------------------
-// Small path helpers (mirror the on-read precedent — nested-context /
-// frontmatter-rules — so the injected envelope matches their faithful shape).
+// Small path helpers (mirror the on-read precedent — frontmatter-rules, and
+// the retired nested-context extension — so the injected envelope matches
+// their faithful shape).
 // ---------------------------------------------------------------------------
 function realpathOrSelf(p) {
     try {

package/dist/daemon/crtrd.js

@@ -119,6 +119,26 @@ const REVIVE_GRACE_MS = 20_000;
 // Per-node first-observed-dead timestamps, for the grace window above. In-memory
 // only — a daemon restart resets it (worst case: one extra grace interval).
 const unhealthySince = new Map();
+// Stranded-relaunch retry cap (2026-07-06 diagnosis, Q4): a relaunch whose
+// broker never re-records its pid (dies before session_start, over and over)
+// used to retry via the boot-grace clock above FOREVER — no attempt cap, no
+// backoff — observed at 5,642 iterations on real nodes before the daemon was
+// finally restarted. Bound the attempts with exponential backoff, then give up
+// ONCE with a doctrine wake instead of spinning quietly for days.
+const STRANDED_RELAUNCH_MAX_ATTEMPTS = 6;
+const STRANDED_RELAUNCH_MAX_BACKOFF_MS = 10 * 60_000; // 10 minutes
+// Per-node stranded-relaunch attempt count + the wall-clock time of the last
+// attempt, backing the cap/backoff above. In-memory only, like unhealthySince
+// — a daemon restart resets them (worst case: one extra round of retries).
+const strandedRelaunchAttempts = new Map();
+const strandedRelaunchLastAttempt = new Map();
+function strandedRelaunchBackoffMs(attempts) {
+    return Math.min(REVIVE_GRACE_MS * 2 ** attempts, STRANDED_RELAUNCH_MAX_BACKOFF_MS);
+}
+function clearStrandedRelaunchState(id) {
+    strandedRelaunchAttempts.delete(id);
+    strandedRelaunchLastAttempt.delete(id);
+}
 // §H refresh-authority grace: how long a node may sit with intent='refresh', its
 // turn OVER (busy marker absent) and its engine still ALIVE before the daemon
 // concludes the refresh stalled and force-kills the engine. The healthy window is
@@ -686,6 +706,7 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
     // engine so the dead-pid refresh branch below revives it fresh.
     if (pid != null && isPidAlive(pid)) {
         unhealthySince.delete(id);
+        clearStrandedRelaunchState(id); // a live engine means the stranding resolved
         handleYieldStall(row, pid, now);
         handleWedgeDetection(id, pid, now);
         handleFatalFault(id, now);
@@ -741,8 +762,29 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
             // the pid-clear, before re-record. Resume it on the saved session — unless
             // that dead relaunch was itself a cycling attempt (cycle_pending), in which
             // case retry it AS a cycle (retryResumeMode) instead of stranding it as a
-            // strict resume into an empty marker branch.
-            process.stderr.write(`[crtrd] revive ${id} (stranded relaunch — pid never re-recorded)\n`);
+            // strict resume into an empty marker branch. Capped + backed off (above) so
+            // a node whose broker NEVER re-records a pid can't spin this branch forever.
+            const attempts = strandedRelaunchAttempts.get(id) ?? 0;
+            if (attempts >= STRANDED_RELAUNCH_MAX_ATTEMPTS) {
+                process.stderr.write(`[crtrd] giving up on ${id} after ${attempts} stranded-relaunch attempts (pid never re-recorded)\n`);
+                clearStrandedRelaunchState(id);
+                transition(id, 'crash');
+                try {
+                    fanDoctrineWake(id, subscribersOf(id), `Child crashed — ${fullName(meta)} (${id}) failed to relaunch after ${attempts} attempts (its engine kept dying before it could re-record a pid) and is now dead. ` +
+                        `It stays dead until you revive it — \`crtr node lifecycle revive ${id}\`.`, { reason: 'child-crashed', child: id });
+                }
+                catch {
+                    /* best-effort, mirrors every other fan-out in this file */
+                }
+                return;
+            }
+            const lastAttempt = strandedRelaunchLastAttempt.get(id);
+            const backoff = strandedRelaunchBackoffMs(attempts);
+            if (lastAttempt !== undefined && now - lastAttempt < backoff)
+                return; // backing off before the next attempt
+            strandedRelaunchAttempts.set(id, attempts + 1);
+            strandedRelaunchLastAttempt.set(id, now);
+            process.stderr.write(`[crtrd] revive ${id} (stranded relaunch — pid never re-recorded, attempt ${attempts + 1}/${STRANDED_RELAUNCH_MAX_ATTEMPTS})\n`);
             reviveNode(id, { resume: retryResumeMode(meta) });
             revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
             return;

package/dist/daemon/manage.d.ts

@@ -1,3 +1,23 @@
+/** Env keys that must NEVER reach the daemon process. Restarting crtrd is
+ *  overwhelmingly done from inside an agent node's own bash tool (`crtr sys
+ *  daemon stop && start`), which inherits that node's FULL env — its identity
+ *  (`CRTR_NODE_ID`/`CRTR_KIND`/…, the `nodeEnv()` shape in `core/runtime/
+ *  nodes.ts`), its front-door recursion-guard flag, and any pi-engine
+ *  resolution seam a prior test/dev session left exported. The daemon is a
+ *  singleton supervisor, never "a node" itself, so none of this belongs in its
+ *  env regardless of whether today's code happens to read it — and at least one
+ *  of these IS actively read: `host.ts`'s broker-engine resolution falls back to
+ *  `process.env['CRTR_BROKER_ENGINE']` verbatim (nodeEnv() never sets that key,
+ *  so nothing overrides it per child launch), so a daemon that inherits a
+ *  stale/dev override throws inside `headlessBrokerHost.launch()` on EVERY
+ *  relaunch it ever attempts, for its whole lifetime — the 2026-07-06 diagnosis
+ *  root cause behind 19 nodes killed with "failed to relaunch and is now dead". */
+export declare const DAEMON_ENV_STRIP_KEYS: readonly string[];
+/** A copy of `process.env` with every `DAEMON_ENV_STRIP_KEYS` entry removed.
+ *  Deliberate global config the user actually wants the daemon to see —
+ *  `CRTR_HOME`, `CRTR_SUBTREE`, `CRTR_LOG`, `CRTR_DEBUG`, etc. — passes through
+ *  untouched; only the node-identity/engine-poisoning surface is stripped. */
+export declare function sanitizedDaemonEnv(): NodeJS.ProcessEnv;
 export interface SpawnDaemonResult {
     /** True when a new daemon process was spawned. */
     started: boolean;