@north-light/crouter 0.3.230 → 0.3.232

package/dist/core/profiles/fuzzy-match.js

@@ -0,0 +1,92 @@
+// Fuzzy matching for a user-TYPED profile operand. Pure — no fs, no manifest
+// reads — so the resolution policy is testable on its own and `manifest.ts`
+// stays the sole owner of path safety and manifest IO.
+//
+// This exists because nobody remembers a profile's exact registered name, let
+// alone its `<slug>-<8hex>` id. `crtr --profile crout` should run the `crouter`
+// profile instead of failing with a list the user then has to read and retype.
+/** Case-, space-, and punctuation-insensitive comparison key. "My Profile",
+ *  "my-profile", and "myprofile" all collapse to the same key, so the common
+ *  near-miss (wrong separator, wrong case) resolves in the first tier. */
+function normalize(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/** The generated id's `-<8 hex>` suffix carries no meaning to a human typing a
+ *  profile, so match against the slug alone as well as the whole id. */
+function idSlug(profileId) {
+    return profileId.replace(/-[0-9a-f]{8}$/, '');
+}
+/** Every string a human might plausibly have been aiming at for one profile. */
+function haystacks(candidate) {
+    const keys = [normalize(candidate.name), normalize(idSlug(candidate.profileId)), normalize(candidate.profileId)];
+    return keys.filter((key, index) => key !== '' && keys.indexOf(key) === index);
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, substitution);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Tiers, strongest first. They are ordered by how confidently a human meant
+ *  this profile, NOT by string similarity — a prefix the user stopped typing is
+ *  a stronger signal than a one-character edit that happens to score well. */
+const TIER_NORMALIZED_EQUAL = 0;
+const TIER_PREFIX = 1;
+const TIER_CONTAINS = 2;
+const TIER_TYPO = 3;
+function scoreOne(needle, candidate) {
+    let best = null;
+    for (const hay of haystacks(candidate)) {
+        const distance = levenshtein(needle, hay);
+        let tier = null;
+        if (needle === hay)
+            tier = TIER_NORMALIZED_EQUAL;
+        else if (hay.startsWith(needle))
+            tier = TIER_PREFIX;
+        else if (hay.includes(needle) || needle.includes(hay))
+            tier = TIER_CONTAINS;
+        // A typo budget that scales with length: one edit for a short name, more
+        // for a long one. Without the floor, a 3-character name would tolerate
+        // nothing; without the scaling, two unrelated long names would collide.
+        else if (distance <= Math.max(1, Math.floor(hay.length / 3)))
+            tier = TIER_TYPO;
+        if (tier === null)
+            continue;
+        if (best === null || tier < best.tier || (tier === best.tier && distance < best.distance)) {
+            best = { candidate, tier, distance };
+        }
+    }
+    return best;
+}
+/** Resolve a typed operand against the profiles on this host. Returns a single
+ *  match only when it is unambiguously the best one: the strongest tier any
+ *  candidate reached, and within it the single lowest edit distance. A genuine
+ *  tie is reported rather than guessed, because silently running under the
+ *  wrong profile is worse than one more prompt. */
+export function fuzzyMatchProfile(operand, candidates) {
+    const needle = normalize(operand);
+    if (needle === '')
+        return { match: null, tied: [] };
+    const scored = candidates.map((c) => scoreOne(needle, c)).filter((s) => s !== null);
+    if (scored.length === 0)
+        return { match: null, tied: [] };
+    const bestTier = Math.min(...scored.map((s) => s.tier));
+    const inTier = scored.filter((s) => s.tier === bestTier);
+    const bestDistance = Math.min(...inTier.map((s) => s.distance));
+    const winners = inTier.filter((s) => s.distance === bestDistance);
+    if (winners.length === 1)
+        return { match: winners[0].candidate, tied: [] };
+    return { match: null, tied: winners.map((s) => s.candidate) };
+}

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

@@ -30,17 +30,24 @@ export interface ProfileEntry {
  *  generated id shape, or whose `profile.json` is missing/corrupt, is skipped
  *  rather than crashing the whole listing. */
 export declare function listProfiles(): ProfileEntry[];
-/** Resolve a CLI operand to its profile — exact id first (checked against the
- *  actually-enumerated dirs, never a blind join), then a unique manifest
- *  `name` match. Ambiguous names fail listing every matching id; no match
- *  fails naming `profile list`/`profile new` as recovery. This is the ONLY
- *  function every command leaf and runtime consumer should
- *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
- *  safe profile id. */
 /** Read one exact profile id without falling back to manifest-name matching.
  * Used at persistence gates that already hold a resolved durable identity. */
 export declare function loadExactProfileManifest(profileId: string): ProfileEntry;
 export declare function loadProfileManifest(profileIdOrName: string): ProfileEntry;
+/** Resolve a profile the USER TYPED — a `--profile` flag or a `<profile>`
+ *  operand. Exact id or name wins outright; only when nothing matches exactly
+ *  does this fall back to fuzzy matching on name and id slug, so a typed
+ *  `crout`, `Crouter`, or `cruoter` reaches the `crouter` profile instead of
+ *  failing with a list the user has to read and retype. A fuzzy hit is
+ *  announced on STDERR (never stdout, which callers pipe) so the user always
+ *  knows which profile actually ran.
+ *
+ *  NEVER call this with a STORED `profile_id` (a node's `meta.profile_id`,
+ *  `CRTR_PROFILE_ID`, a pinned default). A durable id that no longer resolves
+ *  means the profile was deleted — the correct answer there is the not-found
+ *  those callers already handle, not the nearest surviving profile. Use
+ *  `loadProfileManifest` (or `loadExactProfileManifest`) for those. */
+export declare function resolveProfileOperand(operand: string): ProfileEntry;
 /** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
  *  mutations (create/rename/add-project/remove-project/delete/last-used)
  *  below run inside this. */

package/dist/core/profiles/manifest.js

@@ -14,6 +14,7 @@ import { userScopeRoot, resetScopeCache } from '../scope.js';
 import { ensureDir, nowIso } from '../fs-utils.js';
 import { usage, notFound, ambiguous, general } from '../errors.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
+import { fuzzyMatchProfile } from './fuzzy-match.js';
 // ---------------------------------------------------------------------------
 // Path safety — the only code in the tree that builds a path under the
 // profiles root. Every other module reaches profile paths through this file.
@@ -197,13 +198,15 @@ export function listProfiles() {
     }
     return out;
 }
-/** Resolve a CLI operand to its profile — exact id first (checked against the
- *  actually-enumerated dirs, never a blind join), then a unique manifest
- *  `name` match. Ambiguous names fail listing every matching id; no match
- *  fails naming `profile list`/`profile new` as recovery. This is the ONLY
- *  function every command leaf and runtime consumer should
- *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
- *  safe profile id. */
+// Three resolvers, in descending tolerance. `resolveProfileOperand` is what a
+// command leaf calls for a value the USER TYPED: exact id, exact name, then a
+// fuzzy fallback. `loadProfileManifest` is the strict middle — exact id or
+// exact name, no guessing — and is what every runtime consumer holding a
+// stored `profile_id` or `CRTR_PROFILE_ID` calls. `loadExactProfileManifest`
+// skips name matching entirely, for persistence gates already holding a
+// resolved durable identity. All three check the id shape against the
+// actually-enumerated dirs rather than joining a raw operand onto the root, so
+// no caller can traverse out of the profiles root.
 /** Read one exact profile id without falling back to manifest-name matching.
  * Used at persistence gates that already hold a resolved durable identity. */
 export function loadExactProfileManifest(profileId) {
@@ -216,8 +219,11 @@ export function loadExactProfileManifest(profileId) {
         next: 'Run `crtr profile list` to see available profiles.',
     });
 }
-export function loadProfileManifest(profileIdOrName) {
-    const all = listProfiles();
+/** Exact resolution only: the generated id, else a unique manifest `name`.
+ *  Returns `null` when nothing matches exactly; still THROWS when a name is
+ *  shared by several profiles, because that is a real collision the caller
+ *  cannot resolve by guessing (and fuzzy matching would only guess harder). */
+function findExactProfile(all, profileIdOrName) {
     if (ID_SHAPE.test(profileIdOrName)) {
         const byId = all.find((p) => p.profileId === profileIdOrName);
         if (byId !== undefined)
@@ -234,10 +240,13 @@ export function loadProfileManifest(profileIdOrName) {
             next: `Re-run with one exact profile id: ${ids.join(', ')}.`,
         });
     }
-    // Name the actual value set in the failure: a caller that guessed an id or a
-    // stale name can correct itself from this error alone, without a lookup hop.
+    return null;
+}
+/** Name the actual value set in the failure: a caller that guessed an id or a
+ *  stale name can correct itself from this error alone, without a lookup hop. */
+function profileNotFound(all, profileIdOrName) {
     const available = all.map((p) => `${p.profileId} (${p.manifest.name})`);
-    throw notFound(`profile not found: ${profileIdOrName}`, {
+    return notFound(`profile not found: ${profileIdOrName}`, {
         received: profileIdOrName,
         available,
         next: available.length > 0
@@ -245,6 +254,47 @@ export function loadProfileManifest(profileIdOrName) {
             : 'No profiles exist on this host yet — create one with `crtr profile new --name <name>`.',
     });
 }
+export function loadProfileManifest(profileIdOrName) {
+    const all = listProfiles();
+    const exact = findExactProfile(all, profileIdOrName);
+    if (exact !== null)
+        return exact;
+    throw profileNotFound(all, profileIdOrName);
+}
+/** Resolve a profile the USER TYPED — a `--profile` flag or a `<profile>`
+ *  operand. Exact id or name wins outright; only when nothing matches exactly
+ *  does this fall back to fuzzy matching on name and id slug, so a typed
+ *  `crout`, `Crouter`, or `cruoter` reaches the `crouter` profile instead of
+ *  failing with a list the user has to read and retype. A fuzzy hit is
+ *  announced on STDERR (never stdout, which callers pipe) so the user always
+ *  knows which profile actually ran.
+ *
+ *  NEVER call this with a STORED `profile_id` (a node's `meta.profile_id`,
+ *  `CRTR_PROFILE_ID`, a pinned default). A durable id that no longer resolves
+ *  means the profile was deleted — the correct answer there is the not-found
+ *  those callers already handle, not the nearest surviving profile. Use
+ *  `loadProfileManifest` (or `loadExactProfileManifest`) for those. */
+export function resolveProfileOperand(operand) {
+    const all = listProfiles();
+    const exact = findExactProfile(all, operand);
+    if (exact !== null)
+        return exact;
+    const { match, tied } = fuzzyMatchProfile(operand, all.map((p) => ({ profileId: p.profileId, name: p.manifest.name })));
+    if (match !== null) {
+        const picked = all.find((p) => p.profileId === match.profileId);
+        console.error(`crtr: no profile named "${operand}" — using the closest match: ${picked.manifest.name} (${picked.profileId})`);
+        return picked;
+    }
+    if (tied.length > 1) {
+        const ids = tied.map((c) => `${c.profileId} (${c.name})`);
+        throw ambiguous(`"${operand}" is equally close to ${tied.length} profiles: ${ids.join(', ')}`, {
+            received: operand,
+            candidates: tied.map((c) => c.profileId),
+            next: `Re-run with one exact profile id or name: ${ids.join(', ')}.`,
+        });
+    }
+    throw profileNotFound(all, operand);
+}
 function locksDir() {
     return join(profilesRoot(), '.locks');
 }

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

@@ -16,7 +16,9 @@ export declare function selectProfileForCwdReadOnly(cwd: string): string;
 export declare function tildify(p: string): string;
 /** Select the profile a node about to boot at `cwd` should run under.
  *
- *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If
+ *  1. `explicitProfile` present → resolve it as a user-typed operand (exact id,
+ *     exact name, then the closest fuzzy match — nobody recalls the generated
+ *     `<slug>-<8hex>` id, and a near-miss name should still start the session). 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.

package/dist/core/profiles/select.js

@@ -13,7 +13,7 @@ import { homedir } from 'node:os';
 import { basename, resolve as resolvePath, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { emitKeypressEvents } from 'node:readline';
-import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, addProfileProject, ensureRootProfile, ROOT_PROFILE_ID, } from './manifest.js';
+import { listProfiles, loadProfileManifest, resolveProfileOperand, updateProfileLastUsed, createProfile, addProfileProject, ensureRootProfile, ROOT_PROFILE_ID, } from './manifest.js';
 import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, } from './default-binding.js';
 import { stdoutColor } from '../output.js';
 import { inTmux } from '../runtime/placement-tmux.js';
@@ -652,7 +652,9 @@ async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId, bindi
 }
 /** Select the profile a node about to boot at `cwd` should run under.
  *
- *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If
+ *  1. `explicitProfile` present → resolve it as a user-typed operand (exact id,
+ *     exact name, then the closest fuzzy match — nobody recalls the generated
+ *     `<slug>-<8hex>` id, and a near-miss name should still start the session). 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.
@@ -683,7 +685,7 @@ export async function selectProfileForCwd(cwd, explicitProfile, forcePicker = fa
     const resolvedCwd = resolveCwd(cwd);
     const bindings = resolveUserKeybindings();
     if (explicitProfile !== undefined && explicitProfile !== null && explicitProfile !== '') {
-        const entry = loadProfileManifest(explicitProfile);
+        const entry = resolveProfileOperand(explicitProfile);
         // Selecting a profile from a directory it does not yet cover: offer to
         // widen its purview (interactive only, default yes) before pi boots.
         if (!profileCoversCwd(entry, resolvedCwd) && isInteractive()) {

package/dist/core/profiles/state-block.js

@@ -1,6 +1,7 @@
-// The `<profiles>` help state element — every leaf carrying a `--profile` flag
-// enumerates the accepted value set on that same leaf (command-surface rule),
-// so an agent never has to guess an id or take a `crtr profile list` hop.
+// The `<profiles>` help state element. A leaf carrying a selectable `--profile`
+// renders this beside that flag's full contract — in ordinary leaf help when
+// profile selection is common, or in focused `--profile -h` when omission is
+// normal — so an agent never has to guess an id or take a separate list hop.
 import { stateBlock } from '../help.js';
 import { listProfiles } from './manifest.js';
 /** A live `<profiles count=N>` state element — one `<profile_id> — <name>` line

package/dist/core/runtime/boot-root.d.ts

@@ -4,8 +4,9 @@ export interface BootRootOpts {
     name?: string;
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
-    /** Explicit `--profile <id-or-name>` on the front-door invocation, validated
-     *  through `loadProfileManifest`. Omit to run the MRU/create-or-root-profile
+    /** Explicit `--profile <id-or-name>` on the front-door invocation, resolved
+     *  through `resolveProfileOperand` — so a near-miss name still starts the
+     *  session, under the closest profile. Omit to run the MRU/create-or-root-profile
      *  startup 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. */

package/dist/core/runtime/canvas-extensions.d.ts

@@ -10,10 +10,16 @@ export declare const CANVAS_DOC_SUBSTRATE_PATH: string;
 export declare const CANVAS_STRUCTURED_OUTPUT_PATH: string;
 export declare const CANVAS_BASH_VALVE_PATH: string;
 export declare const CANVAS_PREVIEW_RESULT_PATH: string;
+export declare const CANVAS_PROMPT_SCRUB_PATH: string;
 /** The canvas extensions every node loads, in order. The inbox watcher commits
  *  its cursor at agent_settled before the stophook checks it for idle release.
  *  The review boundary must run before the stophook commits companion session
- *  coordinates, and before the context intro appends fork bearings. */
+ *  coordinates, and before the context intro appends fork bearings.
+ *
+ *  Every entry here loads ahead of any installed pi package, which is why the
+ *  prompt scrub belongs in this list rather than in crouter's pi package: the
+ *  Claude subscription adapter is a package, and it must not see pi's docs
+ *  block still in the prompt (see canvas-prompt-scrub.ts). */
 export declare const CANVAS_EXTENSIONS: string[];
 /** Preserve the invariant: mandatory extensions are always present exactly once.
  *

package/dist/core/runtime/canvas-extensions.js

@@ -22,10 +22,16 @@ export const CANVAS_DOC_SUBSTRATE_PATH = resolveExtension('canvas-doc-substrate'
 export const CANVAS_STRUCTURED_OUTPUT_PATH = resolveExtension('canvas-structured-output');
 export const CANVAS_BASH_VALVE_PATH = resolveExtension('canvas-bash-valve');
 export const CANVAS_PREVIEW_RESULT_PATH = resolveExtension('canvas-preview-result');
+export const CANVAS_PROMPT_SCRUB_PATH = resolveExtension('canvas-prompt-scrub');
 /** The canvas extensions every node loads, in order. The inbox watcher commits
  *  its cursor at agent_settled before the stophook checks it for idle release.
  *  The review boundary must run before the stophook commits companion session
- *  coordinates, and before the context intro appends fork bearings. */
+ *  coordinates, and before the context intro appends fork bearings.
+ *
+ *  Every entry here loads ahead of any installed pi package, which is why the
+ *  prompt scrub belongs in this list rather than in crouter's pi package: the
+ *  Claude subscription adapter is a package, and it must not see pi's docs
+ *  block still in the prompt (see canvas-prompt-scrub.ts). */
 export const CANVAS_EXTENSIONS = [
     CANVAS_INBOX_WATCHER_PATH,
     CANVAS_REVIEW_BOUNDARY_PATH,
@@ -39,6 +45,7 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_STRUCTURED_OUTPUT_PATH,
     CANVAS_BASH_VALVE_PATH,
     CANVAS_PREVIEW_RESULT_PATH,
+    CANVAS_PROMPT_SCRUB_PATH,
 ];
 /** Preserve the invariant: mandatory extensions are always present exactly once.
  *

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

@@ -1,8 +1,8 @@
-import type { NodeMeta } from '../canvas/types.js';
+import type { NodeMeta, NodeStatus, ExitIntent } from '../canvas/types.js';
 /** The lifecycle events — the only vocabulary for moving a node's status/intent.
  *  Each maps (in the table below) to a target status and/or intent plus the set
  *  of from-statuses it is legal from. */
-export type LifecycleEvent = 'finish' | 'cancel' | 'crash' | 'yield' | 'release' | 'refresh-launch' | 'revive';
+export type LifecycleEvent = 'finish' | 'park' | 'cancel' | 'crash' | 'yield' | 'release' | 'refresh-launch' | 'revive';
 /** Enact a lifecycle event on a node: validate the from-status against the
  *  table, then write status+intent in ONE atomic statement (so they can never
  *  disagree). Returns the hydrated node view after the write.
@@ -10,3 +10,12 @@ export type LifecycleEvent = 'finish' | 'cancel' | 'crash' | 'yield' | 'release'
  *  Throws on an unknown node or an illegal move. The conditional update makes
  *  legality authoritative at SQLite write time rather than at a stale read. */
 export declare function transition(nodeId: string, event: LifecycleEvent): NodeMeta;
+/** Whether this row is a PARKED node — terminalized by the unattended clock
+ *  rather than by finishing its own work. The one read of the park marker:
+ *  `done` qualified by `intent='parked'`, both written in the same atomic
+ *  statement by the `park` event above. Revival clears it (`revive` writes
+ *  `intent: null`), so a reopened node is an ordinary node again. */
+export declare function isParked(node: {
+    status: NodeStatus;
+    intent?: ExitIntent;
+}): boolean;

package/dist/core/runtime/lifecycle.js

@@ -39,6 +39,11 @@ const LIVE = ['active', 'idle'];
 const TRANSITIONS = {
     // markCleanExitDone (clean quit) · queue cancellation · relaunchRoot park-old.
     finish: { status: 'done', intent: 'done', from: LIVE },
+    // The unattended park: a node whose conversation went idle with nothing left
+    // to wake it. `intent='parked'` IS the durable park marker — it qualifies the
+    // `done` it is written with, and `revive` clears it. Read it through
+    // `isParked` below, never by comparing the string at a call site.
+    park: { status: 'done', intent: 'parked', from: LIVE },
     // closeNode cascade · reapDescendants. Forced teardown of a node that did NOT
     // finish its own work → canceled, intent cleared. (A5: done is reserved for
     // finish; every external reap unifies on canceled.)
@@ -98,7 +103,7 @@ export function transition(nodeId, event) {
     // Wait-cron cleanup — writes a DIFFERENT table (crons) AFTER the atomic
     // status/intent write above, so the single-(status,intent)-writer rule holds.
     // Event-gated; exactly ONE delegated crons helper, never inline cron SQL here:
-    //   finish · cancel → cancelCronsOnWake: delete the cancel-on-wake crons
+    //   finish · park · cancel → cancelCronsOnWake: delete the cancel-on-wake crons
     //     ANCHORED to this node — the deadlines it armed to bound a wait. Ending
     //     the wait deliberately (finish) or having it ended for you (close cascade
     //     · reapDescendants) settles that race, so the deadline must not fire
@@ -109,7 +114,15 @@ export function transition(nodeId, event) {
     //     SURVIVES a node ending.
     //   crash → NOTHING. A fault is not a deliberate end-of-waiting; a pending
     //     deadline MUST survive instance death so the wait still settles.
-    if (event === 'finish' || event === 'cancel')
+    if (event === 'finish' || event === 'park' || event === 'cancel')
         cancelCronsOnWake(nodeId);
     return getNode(nodeId);
 }
+/** Whether this row is a PARKED node — terminalized by the unattended clock
+ *  rather than by finishing its own work. The one read of the park marker:
+ *  `done` qualified by `intent='parked'`, both written in the same atomic
+ *  statement by the `park` event above. Revival clears it (`revive` writes
+ *  `intent: null`), so a reopened node is an ordinary node again. */
+export function isParked(node) {
+    return node.status === 'done' && node.intent === 'parked';
+}

package/dist/core/runtime/model-selection.d.ts

@@ -15,6 +15,10 @@ export declare function defaultProvider(ladders?: ScopeConfig['modelLadders']):
 export declare const STRENGTH_ALIASES: Record<string, ModelStrength>;
 export declare const MODEL_PROVIDER_KEYS: ModelProvider[];
 export declare const MODEL_STRENGTHS: ModelStrength[];
+/** Canonical user-facing grammar for a durable model override. Help and
+ *  recovery paths compose from this one phrase so accepted forms cannot drift. */
+export declare const MODEL_SPEC_FORMS: string;
+export declare const MODEL_SPEC_NEXT: string;
 /** The ladder providers a picker/cycle should OFFER: a provider column is kept
  *  only when at least one of its ladder cells names a runtime provider the
  *  caller reports as signed in (`isConfigured` — e.g. pool occupancy or

package/dist/core/runtime/model-selection.js

@@ -42,6 +42,11 @@ export const STRENGTH_ALIASES = {
 // picker, and the Alt+M cycle. Both participate in automatic turn-time fallback.
 export const MODEL_PROVIDER_KEYS = ['anthropic', 'openai'];
 export const MODEL_STRENGTHS = ['ultra', 'strong', 'medium', 'light'];
+/** Canonical user-facing grammar for a durable model override. Help and
+ *  recovery paths compose from this one phrase so accepted forms cannot drift. */
+export const MODEL_SPEC_FORMS = `an exact registered provider/id; provider/tier where provider is ${MODEL_PROVIDER_KEYS.join('|')} and tier is ${MODEL_STRENGTHS.join('|')}; ` +
+    `a bare tier (${MODEL_STRENGTHS.join('|')}); or a family alias (opus|sonnet|haiku)`;
+export const MODEL_SPEC_NEXT = `Pass ${MODEL_SPEC_FORMS}.`;
 /** The ladder providers a picker/cycle should OFFER: a provider column is kept
  *  only when at least one of its ladder cells names a runtime provider the
  *  caller reports as signed in (`isConfigured` — e.g. pool occupancy or

package/dist/core/runtime/nodes.js

@@ -191,6 +191,11 @@ export function nodeEnv(meta) {
         // multi-project pointer set. '' (never omitted) only for historical
         // null-profile rows, matching every other CRTR_* scalar here.
         CRTR_PROFILE_ID: meta.profile_id ?? '',
+        // The Claude subscription adapter re-injects pi's docs block as a hidden
+        // message whenever a turn's prompt mentions pi. canvas-prompt-scrub already
+        // removes that block from the system prompt, so re-injection would only put
+        // the adapter's own fallback copy back into the conversation. Never inject.
+        PI_CLAUDE_OAUTH_REINJECT_SCOPE: 'never',
     };
     if (meta.parent)
         env['CRTR_PARENT_NODE_ID'] = meta.parent;

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

@@ -20,6 +20,12 @@ export declare function assertFinalizedForReopen(nodeId: string): string;
  *  canonical result. Callers MUST NOT proceed to revive/deliver when this
  *  throws. */
 export declare function commitReopen(nodeId: string, expectedFinalReport: string): void;
+/** Commit the wider message-delivery reopen: make the node resident, then
+ * retract a final latch when one exists. Unlike the revive/fresh gate, an
+ * unlatched node is valid here — it still becomes resident. Writing lifecycle
+ * first leaves a failed latch CAS with the canonical-final pointer intact.
+ * Both writes finish before either delivery channel begins. */
+export declare function commitReopenResident(nodeId: string): void;
 /** Convenience wrapper for a doorway with NO intervening fallible step between
  *  the gate check and the reopen clear (`node lifecycle revive` has nothing
  *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,

package/dist/core/runtime/reopen.js

@@ -38,7 +38,7 @@
 // mutating the live pointer — the explicit operation must not retract a
 // canonical final unless it can actually enact the requested re-task.
 import { join } from 'node:path';
-import { openDb, reportsDir } from '../canvas/index.js';
+import { openDb, reportsDir, updateNode } from '../canvas/index.js';
 import { InputError } from '../io.js';
 function currentFinalReport(nodeId) {
     const row = openDb().prepare('SELECT final_report FROM nodes WHERE node_id = ?').get(nodeId);
@@ -101,6 +101,17 @@ export function commitReopen(nodeId, expectedFinalReport) {
         });
     }
 }
+/** Commit the wider message-delivery reopen: make the node resident, then
+ * retract a final latch when one exists. Unlike the revive/fresh gate, an
+ * unlatched node is valid here — it still becomes resident. Writing lifecycle
+ * first leaves a failed latch CAS with the canonical-final pointer intact.
+ * Both writes finish before either delivery channel begins. */
+export function commitReopenResident(nodeId) {
+    const finalReport = currentFinalReport(nodeId);
+    updateNode(nodeId, { lifecycle: 'resident' });
+    if (finalReport !== null)
+        commitReopen(nodeId, finalReport);
+}
 /** Convenience wrapper for a doorway with NO intervening fallible step between
  *  the gate check and the reopen clear (`node lifecycle revive` has nothing
  *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,

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

@@ -25,6 +25,12 @@ export declare function resumeArgs(meta: NodeMeta, resume: boolean): {
     resumeSessionPath?: string;
     newCycle?: boolean;
 };
+/** Whether a fresh context window would have anything on disk to stand on: a
+ *  goal, a roadmap, or both. The negative is what makes a fresh cycle worse
+ *  than a resume — the new window would wake amnesiac, with no statement of
+ *  what it is for. Read by the parked-resident veto below and by the message
+ *  handler's explicit fresh-revive gate. */
+export declare function hasFreshGroundState(nodeId: string): boolean;
 export interface ReviveResult {
     /** Always null — the broker engine is never placed in a tmux window. Kept on
      *  the result for caller back-compat. */

package/dist/core/runtime/revive.js

@@ -24,7 +24,7 @@ import { existsSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
 import { findNodeBySessionFile, getNode, updateNode, clearPid, recordPid, fullName, subscribersOf, } from '../canvas/index.js';
 import { cancelCronsOnWake } from '../canvas/crons.js';
-import { transition } from './lifecycle.js';
+import { isParked, transition } from './lifecycle.js';
 import { fanDoctrineWake } from './close.js';
 import { InputError } from '../io.js';
 import { buildPiArgv } from './launch.js';
@@ -79,6 +79,18 @@ export function resumeArgs(meta, resume) {
 function isUnstartedBirth(nodeId) {
     return readRoadmap(nodeId) === null && readYieldMessage(nodeId) === null;
 }
+/** Whether a fresh context window would have anything on disk to stand on: a
+ *  goal, a roadmap, or both. The negative is what makes a fresh cycle worse
+ *  than a resume — the new window would wake amnesiac, with no statement of
+ *  what it is for. Read by the parked-resident veto below and by the message
+ *  handler's explicit fresh-revive gate. */
+export function hasFreshGroundState(nodeId) {
+    const goal = readGoal(nodeId);
+    if (goal !== null && goal.trim() !== '')
+        return true;
+    const roadmap = readRoadmap(nodeId);
+    return roadmap !== null && roadmap.trim() !== '';
+}
 // ---------------------------------------------------------------------------
 // reviveNode
 // ---------------------------------------------------------------------------
@@ -181,8 +193,16 @@ export function reviveNode(nodeId, opts) {
     // crash-retry) outranks a caller's strict-resume request. resumeArgs then
     // selects only an existing absolute session path: strict
     // resume continues its leaf, while fresh/cycle mode roots a new one.
+    // A parked node re-enters on a FRESH cycle grounded in goal + roadmap rather
+    // than resuming the transcript its parking turn concluded — the second veto
+    // on strict resume, and a property of the node, so every revival doorway gets
+    // it without learning a predicate. Its one exception is a park with nothing
+    // on disk to ground a fresh window (reachable only on the degraded path,
+    // which writes no summary): resuming an old transcript beats waking amnesiac.
+    // The transition below clears the marker, and this snapshot precedes it.
     const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
-    const effectiveResume = refreshPending ? false : opts.resume;
+    const parkedReentry = isParked(meta) && hasFreshGroundState(nodeId);
+    const effectiveResume = refreshPending || parkedReentry ? false : opts.resume;
     const resume = forkBirthPending ? {} : resumeArgs(meta, effectiveResume);
     // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether
     // as a true resume OR a cycling refresh-yield (resumeArgs sets `newCycle` in

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

@@ -6,6 +6,8 @@ export interface SpawnChildOpts {
     mode?: Mode;
     cwd: string;
     name?: string;
+    /** Caller-supplied description preserved against automatic naming. */
+    description?: string;
     prompt: string;
     /** Override the parent (defaults to the calling node from env). */
     parent?: string;
@@ -52,7 +54,8 @@ export interface SpawnChildOpts {
      *  ladder config edits keep propagating). Omit to use the persona default. */
     model?: string;
     /** Select the profile this node runs under — an exact profile id or a unique
-     *  manifest name, validated through `loadProfileManifest`. Omit to INHERIT the
+     *  manifest name (or the closest match to one), resolved through
+     *  `resolveProfileOperand`. Omit to INHERIT the
      *  spawner's current `profile_id` (managed child or --root alike — --root only
      *  means top-level, it does not reset to a different profile; a shell root
      *  falls back to the stable root profile in the startup selector). Passed
@@ -81,7 +84,7 @@ export interface SpawnChildOpts {
  *  a uuid resolves to zero or multiple sessions. */
 export declare function resolveForkSource(value: string): string;
 /** Resolve the profile a spawned child runs under: an explicit `--profile`
- *  operand (id or name) validated through `loadProfileManifest`, else INHERIT
+ *  operand (id, name, or closest match) resolved through `resolveProfileOperand`, else INHERIT
  *  the spawner's current `profile_id` (null when the spawner has none). `--root`
  *  never resets this to null on its own; only an explicit override does. When
  *  there is NO spawner at all — `crtr node new --root` run directly from a