@crouton-kit/crouter 0.3.48 → 0.3.50

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,13 +1,8 @@
 import { type Trigger } from '../canvas/index.js';
-/** 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. */
+/** The `<project_context>` block — cwd/git `<environment>` snapshot only
+ *  (dir listing + git status/worktrees). Project guidance lives in the document
+ *  substrate, so this wrapper stays environment-only. It always emits 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.

package/dist/core/runtime/bearings.js

@@ -13,15 +13,13 @@
 //     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) — 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
+//     carries the <project_context> block (buildProjectContextBlock), which is
+//     now only the cwd/git <environment> snapshot. Project guidance rides the
+//     document substrate instead: migrated CLAUDE.md/AGENTS.md docs live in the
+//     source dir's own `.crouter/memory/AGENTS.md` and surface through 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`);
+//     profile-widened boot render — no parallel 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
@@ -112,15 +110,10 @@ function parseWorktrees(lines) {
     }
     return worktrees;
 }
-/** 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. */
+/** The `<project_context>` block — cwd/git `<environment>` snapshot only
+ *  (dir listing + git status/worktrees). Project guidance lives in the document
+ *  substrate, so this wrapper stays environment-only. It always emits because
+ *  the environment snapshot is always present. Exported for testing. */
 export function buildProjectContextBlock(cwd) {
     const envLines = directoryListingLines(cwd);
     const git = gitSnapshot(cwd);

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/index.d.ts

@@ -1,4 +1,4 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, resolveDocName, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject, profileNameFor } from './subject.js';
 export type { NodeConfigSubject } from './subject.js';

package/dist/core/substrate/index.js

@@ -13,7 +13,9 @@ FALLBACK_RUNG,
 // parse + render-shared helpers
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, 
 // display-name normalization
-normalizeNameSegment, normalizeDocName, } from './schema.js';
+normalizeNameSegment, normalizeDocName, 
+// substrate identity (explicit-name-then-path-fallback)
+resolveDocName, } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject, profileNameFor } from './subject.js';
 export { gatePasses } from './gate.js';
 export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';

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

@@ -10,9 +10,9 @@
 //     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 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
+//     ancestor walk keyed on `.crouter/memory/` — project guidance that starts
+//     in CLAUDE.md/AGENTS.md or `.claude/rules` now lives here after
+//     `crtr sys sync` migrates it. 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)
@@ -58,16 +58,16 @@ import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs } from '../memory-resolver.js';
-import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
+import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, } from './index.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 // Ancestor dirs we never look inside for a `.crouter/memory/` store (the read
 // file may live under a build/dependency tree; `.crouter` is NOT junk here — it
 // 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 — frontmatter-rules, and
-// the retired nested-context extension — so the injected envelope matches
-// their faithful shape).
+// Small path helpers (mirror the on-read precedent established by
+// frontmatter-rules so the injected envelope keeps the faithful substrate
+// shape).
 // ---------------------------------------------------------------------------
 function realpathOrSelf(p) {
     try {
@@ -120,13 +120,18 @@ function loadPositionalDoc(file, memDir, scope) {
             .replace(/\.md$/i, '')
             .split(sep)
             .join('/');
-        const name = normalizeDocName(raw);
-        if (name === '')
+        const fallbackName = normalizeDocName(raw);
+        if (fallbackName === '')
             return null;
         const { data, body } = parseFrontmatterGeneric(readText(file));
         const schema = parseSubstrateFrontmatter(data);
         if (schema === null)
             return null;
+        // ONE substrate-identity rule (schema.ts's resolveDocName), shared with the
+        // resolver's loadMemoryDoc: an explicit frontmatter `name` wins over the
+        // path-derived fallback, so a positionally-discovered doc surfaces on-read
+        // under the SAME identity the boot resolver would give it.
+        const name = resolveDocName(data, fallbackName);
         return { ...schema, name, scope, path: file, body };
     }
     catch {

package/dist/core/substrate/render.js

@@ -54,7 +54,7 @@ import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { memoryDir } from '../runtime/memory.js';
 import { projectScopeRoots } from '../scope.js';
-import { assembleNodeSubject, buildCeilingIndex, effectiveRung, gatePasses, indexDirOf, isIndexName, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, rungRank, } from './index.js';
+import { assembleNodeSubject, buildCeilingIndex, effectiveRung, gatePasses, indexDirOf, isIndexName, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './index.js';
 import { cachedNodeSubject, cachedSubstrateDocs } from './session-cache.js';
 // ---------------------------------------------------------------------------
 // Step 1 — winner selection (ceiling + gate + first-wins dedup).
@@ -209,14 +209,18 @@ function nodeLocalDocs(nodeId, subject) {
     const out = [];
     for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
         const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
-        const name = normalizeDocName(raw);
-        if (!name)
+        const fallbackName = normalizeDocName(raw);
+        if (!fallbackName)
             continue;
         try {
             const { data, body } = parseFrontmatterGeneric(readText(file));
             const schema = parseSubstrateFrontmatter(data);
             if (schema === null)
                 continue;
+            // ONE substrate-identity rule (schema.ts's resolveDocName), shared with
+            // the resolver and the on-read positional loader: explicit frontmatter
+            // `name` wins over the physical-path-derived fallback.
+            const name = resolveDocName(data, fallbackName);
             // node-local is NOT a resolver scope; `scope` is a placeholder never read
             // by gate eval (keyed off the NODE subject, not the doc) nor by the
             // renderers (keyed off name / body / rung).

package/dist/core/substrate/schema.d.ts

@@ -20,6 +20,10 @@ export declare function normalizeNameSegment(segment: string): string;
  *  `spine/has-manager`. This is the identity a doc displays, dedups, and
  *  resolves under — distinct from its physical path, which keeps the prefix. */
 export declare function normalizeDocName(name: string): string;
+/** Resolve a doc's identity from its raw frontmatter record: an explicit
+ *  `name` field wins (trimmed + normalized), else `fallbackName` (the
+ *  normalized path-derived name). */
+export declare function resolveDocName(fm: Record<string, unknown> | null | undefined, fallbackName: string): string;
 /** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
  *  the node-config subject. Typed loosely on purpose — the matcher engine owns
  *  validation; structurally it is a field→matcher map with optional
@@ -75,10 +79,12 @@ export interface SubstrateSchema {
     rationale?: string;
 }
 /** A fully-resolved substrate document: the parsed schema PLUS the resolver's
- *  path-derived identity and body. This single object flows through the whole
+ *  identity (explicit frontmatter `name` when present, otherwise the normalized
+ *  path-derived fallback) and body. This single object flows through the whole
  *  pipeline (gate eval → boot/on-read render), so a renderer never re-parses. */
 export interface SubstrateDoc extends SubstrateSchema {
-    /** Path-derived identity, e.g. `taste/document-substrate` (resolver-supplied). */
+    /** Resolver-supplied identity, e.g. `taste/document-substrate` or an explicit
+     *  frontmatter name when one is present. */
     name: string;
     /** The scope this doc resolved from. */
     scope: MemoryScope;

package/dist/core/substrate/schema.js

@@ -51,8 +51,9 @@ export const FALLBACK_RUNG = 'none';
 // prefix is NEVER part of the doc's identity: every identity-facing surface —
 // MemoryDoc.name, direct lookup, leaf fallback, `crtr memory read`/`list`,
 // prompt render, on-read display — derives from the NORMALIZED segments, so
-// `00-runtime-base` displays/dedups/resolves as `runtime-base`. Only the
-// physical path keeps the prefix.
+// `00-runtime-base` displays/dedups/resolves as `runtime-base`. When a doc
+// sets an explicit frontmatter `name`, that normalized name wins instead of
+// the path-derived fallback. Only the physical path keeps the prefix.
 // ---------------------------------------------------------------------------
 const NUMERIC_PREFIX_RE = /^\d{2}-/;
 /** Strip an optional `NN-` ordering prefix from ONE path segment (file or
@@ -69,6 +70,22 @@ export function normalizeDocName(name) {
     return name.split('/').map(normalizeNameSegment).join('/');
 }
 // ---------------------------------------------------------------------------
+// Substrate identity — the ONE explicit-name-then-path-fallback rule. A doc's
+// resolver identity is its explicit frontmatter `name` when present (normalized),
+// otherwise the caller-supplied path-derived fallback. Every loader that turns a
+// physical .md file into a named doc (the resolver's `listMemoryDocsInDir`, the
+// on-read positional loader) calls this ONE helper, so a doc's identity never
+// depends on which path loaded it.
+// ---------------------------------------------------------------------------
+/** Resolve a doc's identity from its raw frontmatter record: an explicit
+ *  `name` field wins (trimmed + normalized), else `fallbackName` (the
+ *  normalized path-derived name). */
+export function resolveDocName(fm, fallbackName) {
+    const raw = fm?.['name'];
+    const explicit = typeof raw === 'string' && raw.trim() !== '' ? normalizeDocName(raw.trim()) : '';
+    return explicit !== '' ? explicit : fallbackName;
+}
+// ---------------------------------------------------------------------------
 // Parse / validate.
 // ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the

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;