@crouton-kit/crouter 0.3.66 → 0.3.68

package/dist/core/command.js

@@ -10,6 +10,8 @@ import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
 import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
 // ---------------------------------------------------------------------------
 // Factory functions
 // ---------------------------------------------------------------------------
@@ -34,6 +36,14 @@ function visibleSubCount(def) {
     return (def.help.listing ?? []).filter((c) => c.tier !== 'hidden').length;
 }
 export function defineBranch(opts) {
+    // A passthrough branch must be childless: walk() only stops at the deepest
+    // matched node, so a passthrough branch with children would let some
+    // invocations descend into a child (tree dispatch) while others hit the
+    // passthrough interception — silently inconsistent transparency. Fail loudly
+    // at construction instead of letting that split happen at runtime.
+    if (opts.passthrough !== undefined && opts.children.length > 0) {
+        throw new Error(`defineBranch("${opts.name}"): a passthrough branch must declare no children (found ${opts.children.length})`);
+    }
     // Assemble the parent-level listing straight from the child defs — each node
     // owns its own description/whenToUse/tier, so the parent copies nothing
     // (principle 16). Bottom-up construction guarantees a child branch's listing
@@ -57,6 +67,7 @@ export function defineBranch(opts) {
         help: opts.help,
         rootEntry: opts.rootEntry,
         slash: opts.slash,
+        passthrough: opts.passthrough,
         children: opts.children,
     };
 }
@@ -169,6 +180,59 @@ function renderNode(node) {
 function helpRequested(remaining) {
     return remaining.some((t) => t === '-h' || t === '--help');
 }
+/** Recover the RAW argv slice after a matched passthrough branch's path,
+ *  unaffected by the `--json`-stripping done to build `tokens`. `path` is a
+ *  prefix of non-`--json` tokens in order, so walking `rawTokens` while
+ *  skipping `--json` occurrences until `path` is fully matched lands the
+ *  cursor exactly where the branch's own args begin — including a literal
+ *  `--json` the external binary itself accepts. */
+function rawArgsAfterPath(rawTokens, path) {
+    let matched = 0;
+    for (let i = 0; i < rawTokens.length; i++) {
+        if (matched === path.length)
+            return rawTokens.slice(i);
+        if (rawTokens[i] === '--json')
+            continue;
+        if (rawTokens[i] === path[matched])
+            matched++;
+    }
+    return [];
+}
+/** Forward `args` to an external binary verbatim: stdio inherited (streaming
+ *  preserved), and the child's exit code propagated. Never returns — either
+ *  exits with the child's status or throws a structured CrtrError (ENOENT ->
+ *  install hint) for the caller's existing error handler to render. */
+function runPassthrough(passthrough, args) {
+    const result = spawnSync(passthrough.bin, args, { stdio: 'inherit' });
+    if (result.error !== undefined) {
+        // Any launch-time failure (not found, not executable, ...) means this
+        // binary isn't usable from here — surface one structured error with the
+        // install hint rather than branching on a specific errno. (Node/libuv can
+        // report EACCES instead of ENOENT for a genuinely-missing binary when PATH
+        // contains malformed entries — e.g. a literal `~/...` segment — so a
+        // ENOENT-only check would miss real missing-binary cases on such hosts.)
+        const err = result.error;
+        throw new CrtrError('binary_missing', `${passthrough.bin} could not be run (${err.code ?? err.message})`, ExitCode.USAGE, {
+            received: passthrough.bin,
+            next: passthrough.installHint,
+        });
+    }
+    if (result.status !== null) {
+        process.exit(result.status);
+    }
+    if (result.signal !== null) {
+        // Signal-terminated: exit(1) would break the transparent exit-propagation
+        // contract (a direct shell invocation would show 128+signal, e.g. 143 for
+        // SIGTERM). Map to the standard 128+signal-number convention.
+        const signalNumber = osConstants.signals[result.signal];
+        if (signalNumber !== undefined) {
+            process.exit(128 + signalNumber);
+        }
+    }
+    // Truly impossible per Node's spawnSync contract (status and signal are
+    // mutually exclusive and one is always set on a completed run) — fallback only.
+    process.exit(1);
+}
 /** Build a structured unknown-path error. Names valid children of the deepest
  *  matched node and names the entry command per the spec. The entry command is
  *  the full path to the matched node (not just its local name), so the recovery
@@ -367,6 +431,14 @@ export async function runCli(root, argv) {
     }
     const { node, path, remaining } = walk(root, tokens);
     try {
+        // Passthrough branches (e.g. `crtr capture`) opt out of the tree model
+        // entirely: forward every token after the branch verbatim to an external
+        // binary before any of the normal unknown-path / help / dispatch logic
+        // runs, so `crtr capture -h`, `crtr capture <args>`, and bare `crtr capture`
+        // all reach the external CLI untouched.
+        if (node.kind === 'branch' && node.passthrough !== undefined) {
+            runPassthrough(node.passthrough, rawArgsAfterPath(rawTokens, path));
+        }
         // A root/branch node's `remaining` is only non-empty because walk hit
         // -h/--help or an unmatched child name (a leaf always consumes the rest
         // of the path itself). So a non-help leading token here is always the

package/dist/core/config.js

@@ -38,6 +38,7 @@ export function readState(scope) {
         plugins: existing.plugins ?? {},
         last_self_check: existing.last_self_check,
         bootstrap_done: existing.bootstrap_done,
+        activeCanvas: existing.activeCanvas ?? null,
     };
 }
 export function writeConfig(scope, config) {
@@ -245,7 +246,7 @@ function mergeKinds(raw, base = defaultKindsConfig()) {
 }
 /** Validate one raw `remoteCanvas.targets.<name>` entry, or drop it (return
  *  null) rather than throwing — same rule `normalizeKindEntry` follows. A
- *  valid entry needs a non-empty `previewEndpoint` and `relayTokenEnv`; the
+ *  valid entry needs a non-empty `previewEndpoint` and `relayTokenRef`; the
  *  token itself is never stored here (see `RemoteCanvasTarget`). */
 function normalizeRemoteCanvasTarget(raw) {
     if (raw === null || typeof raw !== 'object')
@@ -253,9 +254,9 @@ function normalizeRemoteCanvasTarget(raw) {
     const r = raw;
     if (typeof r.previewEndpoint !== 'string' || r.previewEndpoint.trim() === '')
         return null;
-    if (typeof r.relayTokenEnv !== 'string' || r.relayTokenEnv.trim() === '')
+    if (typeof r.relayTokenRef !== 'string' || r.relayTokenRef.trim() === '')
         return null;
-    const out = { previewEndpoint: r.previewEndpoint, relayTokenEnv: r.relayTokenEnv };
+    const out = { previewEndpoint: r.previewEndpoint, relayTokenRef: r.relayTokenRef };
     if (typeof r.cpOrigin === 'string' && r.cpOrigin.trim() !== '')
         out.cpOrigin = r.cpOrigin;
     return out;

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

@@ -27,7 +27,10 @@ export declare function profileCoversCwd(entry: ProfileEntry, cwd: string): bool
  *         is covered). Default is the MRU covering profile.
  *       - Non-interactive: auto-pick the MRU covering profile, no prompt.
  *  4. Else — nothing covers cwd walking all the way up. Interactive: prompt to
- *     create a profile here or use the root profile. Non-interactive (no TTY):
+ *     create a profile here, select an existing profile (a searchable list of
+ *     every profile, for when you started somewhere none of them cover and
+ *     can't recall the exact name — the pick then offers to adopt cwd), or use
+ *     the root profile. Non-interactive (no TTY):
  *     default to the root profile and print the recovery instruction to STDERR —
  *     never stdout, which the caller may be piping. */
 export declare function selectProfileForCwd(cwd: string, explicitProfile?: string | null, forcePicker?: boolean): Promise<string>;

package/dist/core/profiles/select.js

@@ -3,14 +3,16 @@
 // 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/
+// create (MRU auto when headless) > synchronous create / select-existing /
+// 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, ensureRootProfile, } from './manifest.js';
+import { emitKeypressEvents } from 'node:readline';
+import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, addProfileProject, ensureRootProfile, ROOT_PROFILE_ID, } 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
@@ -120,13 +122,134 @@ function writeHeader(title, subtitle) {
     const sub = subtitle !== undefined ? `  ${dim(subtitle)}\n` : '';
     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
- *  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 ' + defaultText) : '';
-    return `    ${key(k)}  ${label}${det}${def}\n`;
+/** Compact one-line summary of a profile's whole purview: its first project
+ *  dir plus a `· N dirs total` tail when it owns more than one. Used where
+ *  there is no cwd-match to point at (the searchable select list). */
+function purviewSummary(entry) {
+    const n = entry.manifest.projects.length;
+    const first = entry.manifest.projects[0];
+    if (first === undefined)
+        return relativeUsed(entry.manifest.last_used_at);
+    return n > 1 ? `${tildify(first)} \u00b7 ${n} dirs total` : tildify(first);
+}
+/** ▸ marks the highlighted row. */
+const HILITE = accent('\u25b8');
+const cursorUp = (n) => (n > 0 ? `\u001b[${n}A\r` : '');
+const CLEAR_DOWN = '\u001b[0J';
+const ANSI_RE = /\u001b\[[0-9;]*m/g;
+/** Terminal rows a just-written block occupies — i.e. how far the cursor
+ *  advanced, so a redraw can move exactly that far back up. Counts each '\n'
+ *  as one row AND adds the extra rows a long line wraps into at the current
+ *  terminal width (ANSI color codes stripped so they don't count toward width).
+ *  A logical-line count alone undershoots in a narrow pane, stacking redraws. */
+function blockRows(block) {
+    const cols = process.stdout.columns ?? 80;
+    const segs = block.split('\n');
+    const newlines = segs.length - 1; // block ends with '\n' → last seg is ''
+    let extra = 0;
+    for (let i = 0; i < newlines; i++) {
+        const w = segs[i].replace(ANSI_RE, '').length;
+        if (cols > 0 && w > cols)
+            extra += Math.ceil(w / cols) - 1;
+    }
+    return newlines + extra;
+}
+function renderMenu(title, subtitle, rows, sel, hint) {
+    let out = `\n  ${bold(title)}\n`;
+    if (subtitle !== undefined)
+        out += `  ${dim(subtitle)}\n`;
+    out += '\n';
+    let num = 0;
+    for (const [i, r] of rows.entries()) {
+        const tag = r.hotkey ?? String(++num);
+        const mark = i === sel ? HILITE : ' ';
+        const det = r.detail !== '' ? '  ' + dim(r.detail) : '';
+        const def = r.isDefault ? '  ' + accent('\u00b7 ' + (r.defaultText ?? 'default')) : '';
+        out += `  ${mark} ${key(tag)}  ${r.label}${det}${def}\n`;
+    }
+    if (hint !== undefined)
+        out += `\n    ${dim(hint)}\n`;
+    out += `\n  ${dim('\u2191\u2193/jk move  \u21b5 select  esc default  ^C quit')}\n`;
+    return out;
+}
+/** Drive a highlighted keypress menu to a resolution. Returns the selected row
+ *  index, plus the action letter when one of `actionKeys` was pressed on the
+ *  highlighted row. */
+function runMenu(title, subtitle, rows, opts = {}) {
+    const numbered = [];
+    rows.forEach((r, i) => {
+        if (r.hotkey === undefined)
+            numbered.push(i);
+    });
+    let sel = opts.initialIndex ?? 0;
+    return new Promise((resolve) => {
+        let prevLines = 0;
+        const draw = () => {
+            const block = renderMenu(title, subtitle, rows, sel, opts.hint);
+            process.stdout.write((prevLines > 0 ? cursorUp(prevLines) + CLEAR_DOWN : '') + block);
+            prevLines = blockRows(block);
+        };
+        const cleanup = () => {
+            process.stdin.off('keypress', onKey);
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(false);
+            process.stdin.pause();
+        };
+        const onKey = (str, k) => {
+            if (k.ctrl === true && k.name === 'c') {
+                cleanup();
+                process.stdout.write('\n');
+                process.exit(130);
+            }
+            if (k.name === 'up' || k.name === 'k' || str === 'k') {
+                sel = (sel - 1 + rows.length) % rows.length;
+                draw();
+                return;
+            }
+            if (k.name === 'down' || k.name === 'j' || str === 'j') {
+                sel = (sel + 1) % rows.length;
+                draw();
+                return;
+            }
+            if (k.name === 'return' || k.name === 'enter') {
+                cleanup();
+                resolve({ index: sel });
+                return;
+            }
+            // Esc cancels navigation and accepts the default row (the MRU/pinned
+            // profile, or the root row on the no-coverage menu) — a safe exit, never
+            // a dead key. Ctrl-C still aborts crtr entirely.
+            if (k.name === 'escape') {
+                cleanup();
+                resolve({ index: opts.initialIndex ?? 0 });
+                return;
+            }
+            if (str !== undefined && /^[0-9]$/.test(str)) {
+                const d = Number.parseInt(str, 10);
+                if (d >= 1 && d <= numbered.length) {
+                    sel = numbered[d - 1];
+                    draw();
+                }
+                return;
+            }
+            const hk = rows.findIndex((r) => r.hotkey !== undefined && r.hotkey === str);
+            if (hk >= 0) {
+                cleanup();
+                resolve({ index: hk });
+                return;
+            }
+            if (str !== undefined && opts.actionKeys?.includes(str) === true) {
+                cleanup();
+                resolve({ index: sel, action: str });
+            }
+        };
+        emitKeypressEvents(process.stdin);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('keypress', onKey);
+        draw();
+    });
 }
 /** The trailing readline prompt: `  › <dim hint> `. */
 function caret(hint) {
@@ -156,17 +279,131 @@ async function promptAddDirToProfile(entry, cwd) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         writeHeader(`Profile "${entry.manifest.name}" doesn't cover this directory`);
-        const choice = (await rl.question(caret('add it to the profile? [Y/n]')))
-            .trim()
-            .toLowerCase();
-        if (choice === 'n' || choice === 'no')
-            return;
-        addProfileProject(entry.profileId, cwd);
+        await offerAddDirToProfile(rl, entry, cwd);
     }
     finally {
         rl.close();
     }
 }
+/** Ask (default yes) whether to widen `entry`'s purview to include `cwd`, on an
+ *  ALREADY-OPEN readline. Shared by the explicit-`--profile` path
+ *  (`promptAddDirToProfile`) and the select-existing path in
+ *  `promptCreateOrRoot`, so a profile chosen for a directory it doesn't cover
+ *  can adopt that directory without a separate `crtr profile project add`. */
+async function offerAddDirToProfile(rl, entry, cwd) {
+    const choice = (await rl.question(caret(`add this directory to "${entry.manifest.name}"? [Y/n]`)))
+        .trim()
+        .toLowerCase();
+    if (choice === 'n' || choice === 'no')
+        return;
+    addProfileProject(entry.profileId, cwd);
+    process.stdout.write(`  ${accent('\u2713')} ${dim(`added this directory to "${entry.manifest.name}"`)}\n`);
+}
+/** Search-and-pick among EVERY existing profile (root excluded — it is the
+ *  separate `[r]` option). Reached from the no-coverage prompt so the user can
+ *  run under a profile they can't fully name when they've started crtr in a
+ *  directory none of their profiles cover. A live search box: type to filter
+ *  (matched against name AND project paths — you may recall the directory, not
+ *  the name), ↑/↓ (or Ctrl-N/P) move the highlight, Enter picks it, Esc backs
+ *  out (returns null → caller falls back to root). Because typing filters,
+ *  navigation here is arrows-only — j/k are literal filter characters (fzf
+ *  convention), unlike the non-search menus where j/k move. */
+async function promptSelectExistingProfile() {
+    const all = [...listProfiles()]
+        .filter((e) => e.profileId !== ROOT_PROFILE_ID)
+        .sort((a, b) => (isMoreRecent(a.manifest.last_used_at, b.manifest.last_used_at) ? -1 : 1));
+    if (all.length === 0) {
+        process.stdout.write(`  ${dim('no existing profiles to select')}\n`);
+        return null;
+    }
+    let filter = '';
+    let sel = 0;
+    const matchesOf = () => filter === ''
+        ? all
+        : all.filter((e) => e.manifest.name.toLowerCase().includes(filter) ||
+            e.manifest.projects.some((p) => tildify(p).toLowerCase().includes(filter)));
+    return new Promise((resolve) => {
+        let prevLines = 0;
+        const draw = () => {
+            const matches = matchesOf();
+            if (sel >= matches.length)
+                sel = Math.max(0, matches.length - 1);
+            let block = `\n  ${bold('Select an existing profile')}\n`;
+            block += `  ${dim('across every profile, not just this directory')}\n\n`;
+            if (matches.length === 0) {
+                block += `    ${dim(`no match for "${filter}"`)}\n`;
+            }
+            else {
+                const nameWidth = Math.max(...matches.map((e) => e.manifest.name.length));
+                matches.forEach((e, i) => {
+                    const mark = i === sel ? HILITE : ' ';
+                    block += `  ${mark} ${bold(e.manifest.name.padEnd(nameWidth))}  ${dim(purviewSummary(e))}\n`;
+                });
+            }
+            block += `\n  ${accent('\u203a')} ${filter}${dim('\u2588')}\n`;
+            block += `  ${dim('type to filter  \u2191\u2193 move  \u21b5 pick  esc back')}\n`;
+            process.stdout.write((prevLines > 0 ? cursorUp(prevLines) + CLEAR_DOWN : '') + block);
+            prevLines = blockRows(block);
+        };
+        const cleanup = () => {
+            process.stdin.off('keypress', onKey);
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(false);
+            process.stdin.pause();
+        };
+        const onKey = (str, k) => {
+            if (k.ctrl === true && k.name === 'c') {
+                cleanup();
+                process.stdout.write('\n');
+                process.exit(130);
+            }
+            if (k.name === 'escape') {
+                cleanup();
+                resolve(null);
+                return;
+            }
+            const matches = matchesOf();
+            if (k.name === 'return' || k.name === 'enter') {
+                if (matches.length > 0) {
+                    cleanup();
+                    resolve(matches[sel].profileId);
+                }
+                return;
+            }
+            if (k.name === 'up' || (k.ctrl === true && k.name === 'p')) {
+                if (matches.length > 0) {
+                    sel = (sel - 1 + matches.length) % matches.length;
+                    draw();
+                }
+                return;
+            }
+            if (k.name === 'down' || (k.ctrl === true && k.name === 'n')) {
+                if (matches.length > 0) {
+                    sel = (sel + 1) % matches.length;
+                    draw();
+                }
+                return;
+            }
+            if (k.name === 'backspace') {
+                filter = filter.slice(0, -1);
+                sel = 0;
+                draw();
+                return;
+            }
+            if (str !== undefined && str.length === 1 && str >= ' ' && k.ctrl !== true) {
+                filter += str.toLowerCase();
+                sel = 0;
+                draw();
+            }
+        };
+        emitKeypressEvents(process.stdin);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('keypress', onKey);
+        draw();
+    });
+}
 /** Ask for a name (defaulting to cwd's basename) and create a profile pointing
  *  at cwd on the SAME open readline — shared by both interactive create paths
  *  so the name prompt reads identically whether reached via the covering menu
@@ -180,19 +417,47 @@ async function createProfileHere(rl, cwd) {
     return profileId;
 }
 async function promptCreateOrRoot(cwd) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    try {
-        writeHeader('No profile covers this directory');
-        process.stdout.write(optionRow('c', 'create a profile here', '', false));
-        process.stdout.write(optionRow('r', dim('use the root profile'), '', true));
-        process.stdout.write('\n');
-        const choice = (await rl.question(caret('[c/r]'))).trim().toLowerCase();
-        if (choice !== 'c' && choice !== 'create')
-            return ensureRootProfile().profileId;
-        return await createProfileHere(rl, cwd);
-    }
-    finally {
-        rl.close();
+    // Root is the highlighted default so a bare Enter (or Esc) still lands on the
+    // safe no-op, exactly as the old `[c/s/r]` prompt defaulted. Looped so Esc
+    // out of the search sub-list returns HERE rather than silently dropping to
+    // root — the create/select/root choice is always the fallback, never skipped.
+    const rows = [
+        { label: 'create a profile here', detail: '', hotkey: 'c' },
+        { label: 'select an existing profile', detail: '', hotkey: 's' },
+        { label: dim('use the root profile'), detail: '', hotkey: 'r', isDefault: true },
+    ];
+    for (;;) {
+        const res = await runMenu('No profile covers this directory', undefined, rows, {
+            initialIndex: 2,
+        });
+        if (res.index === 0) {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await createProfileHere(rl, cwd);
+            }
+            finally {
+                rl.close();
+            }
+        }
+        if (res.index === 1) {
+            const selected = await promptSelectExistingProfile();
+            // Esc/back out of the search list (or no profiles to pick) → re-show this
+            // create/select/root menu, not a silent fall-through to root.
+            if (selected === null)
+                continue;
+            const entry = loadProfileManifest(selected);
+            // The picked profile does not cover cwd (nothing does here) — offer to
+            // widen its purview so the next node started here is covered too.
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                await offerAddDirToProfile(rl, entry, cwd);
+            }
+            finally {
+                rl.close();
+            }
+            return entry.profileId;
+        }
+        return ensureRootProfile().profileId;
     }
 }
 /** Choose among a set of candidate profiles for `cwd`, or create a new one.
@@ -215,63 +480,70 @@ async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId) {
     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 });
-    try {
-        writeHeader(exact ? 'Choose a profile' : 'Select a profile', exact
-            ? 'Several profiles claim this directory as their project'
-            : 'This directory falls under existing profile(s)');
-        ordered.forEach((entry, i) => {
-            // For exact ties the covered path is identical, so surface last-used to
-            // tell them apart; for parent/workspace coverage, WHICH dir covers cwd
-            // is the useful differentiator.
-            const detail = 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));
-            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')
+    const rows = ordered.map((entry, i) => {
+        const n = entry.manifest.projects.length;
+        // For exact ties the matched path is cwd itself, so surface last-used to
+        // tell them apart; for parent/workspace coverage, WHICH of the profile's
+        // dirs matches cwd is the differentiator. Either way append the total dir
+        // count so "covers X" is never mistaken for the profile's full purview.
+        const detail = exact
+            ? `${relativeUsed(entry.manifest.last_used_at)}${n > 1 ? ` \u00b7 ${n} dirs total` : ''}`
+            : (() => {
+                const md = entry.manifest.projects.find((p) => projectCovers(cwd, p)) ??
+                    entry.manifest.projects[0];
+                return n > 1 ? `matches ${tildify(md)} \u00b7 ${n} dirs total` : `matches ${tildify(md)}`;
+            })();
+        const defaultText = pinned !== null && ordered[0] === pinned ? 'default (pinned)' : 'default';
+        return {
+            label: bold(entry.manifest.name.padEnd(nameWidth)),
+            detail,
+            isDefault: i === 0,
+            defaultText,
+        };
+    });
+    rows.push({ label: dim('create a new profile here'), detail: '', hotkey: 'c' });
+    // Action letters resolve on the highlighted row: `d` pins it as this
+    // directory's default; `a` widens its purview to include cwd (meaningless
+    // when the candidates already claim cwd exactly, so hidden there); `u` clears
+    // an existing pin.
+    const actionKeys = ['d'];
+    if (!exact)
+        actionKeys.push('a');
+    if (pinned !== null)
+        actionKeys.push('u');
+    const hintParts = ['d=set default'];
+    if (!exact)
+        hintParts.push('a=add dir here');
+    if (pinned !== null)
+        hintParts.push('u=unpin');
+    const res = await runMenu(exact ? 'Choose a profile' : 'Select a profile', exact
+        ? 'Several profiles claim this directory as their project'
+        : 'This directory falls under existing profile(s)', rows, { actionKeys, hint: hintParts.join('  ') });
+    // The create row is last; selecting it (Enter on it, or `c`) creates here.
+    if (res.index >= ordered.length) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
             return await createProfileHere(rl, cwd);
-        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 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`);
+        finally {
+            rl.close();
         }
+    }
+    const picked = ordered[res.index];
+    if (res.action === 'u') {
+        clearDefaultProfile(cwd);
+        process.stdout.write(`  ${accent('\u2713')} ${dim('cleared the default for this directory')}\n`);
         return picked.profileId;
     }
-    finally {
-        rl.close();
+    if (res.action === 'd') {
+        setDefaultProfileId(cwd, picked.profileId);
+        process.stdout.write(`  ${accent('\u2713')} ${dim(`"${picked.manifest.name}" is now the default here`)}\n`);
+    }
+    else if (res.action === 'a') {
+        addProfileProject(picked.profileId, cwd);
+        process.stdout.write(`  ${accent('\u2713')} ${dim(`added this directory to "${picked.manifest.name}"`)}\n`);
     }
+    return picked.profileId;
 }
 /** Select the profile a node about to boot at `cwd` should run under.
  *
@@ -296,7 +568,10 @@ async function promptPickProfileOrCreate(candidates, cwd, exact, pinnedId) {
  *         is covered). Default is the MRU covering profile.
  *       - Non-interactive: auto-pick the MRU covering profile, no prompt.
  *  4. Else — nothing covers cwd walking all the way up. Interactive: prompt to
- *     create a profile here or use the root profile. Non-interactive (no TTY):
+ *     create a profile here, select an existing profile (a searchable list of
+ *     every profile, for when you started somewhere none of them cover and
+ *     can't recall the exact name — the pick then offers to adopt cwd), or use
+ *     the root profile. Non-interactive (no TTY):
  *     default to the root profile and print the recovery instruction to STDERR —
  *     never stdout, which the caller may be piping. */
 export async function selectProfileForCwd(cwd, explicitProfile, forcePicker = false) {

package/dist/core/runtime/__tests__/node-env.test.d.ts

@@ -0,0 +1 @@
+export {};