@north-light/api 0.3.580 → 0.3.587

package/dist/core/profiles/select.js

@@ -0,0 +1,738 @@
+// Startup profile selection — the CTO-decided order applied at the front door
+// 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 / 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 { spawnSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, resolve as resolvePath, sep } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { emitKeypressEvents } from 'node:readline';
+import { listProfiles, loadProfileManifest, resolveProfileOperand, updateProfileLastUsed, createProfile, addProfileProject, ensureRootProfile, ROOT_PROFILE_ID, } from './manifest.js';
+import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, } from './default-binding.js';
+import { tildify } from '../fs-utils.js';
+import { stdoutColor } from '../output.js';
+import { inTmux } from '../runtime/placement-tmux.js';
+import { surfaceTmuxStyleArgs } from '../runtime/surface-bg.js';
+import { formatBinding, matchesTerminalInput, resolveUserKeybindings, } from '../keybindings/index.js';
+const PROFILE_MENU_ACTIONS = [
+    'crtr.profile.menu.abort', 'crtr.profile.menu.up', 'crtr.profile.menu.down',
+    'crtr.profile.menu.select', 'crtr.profile.menu.accept-default',
+    'crtr.profile.menu.slot.1', 'crtr.profile.menu.slot.2', 'crtr.profile.menu.slot.3',
+    'crtr.profile.menu.slot.4', 'crtr.profile.menu.slot.5', 'crtr.profile.menu.slot.6',
+    'crtr.profile.menu.slot.7', 'crtr.profile.menu.slot.8', 'crtr.profile.menu.slot.9',
+    'crtr.profile.menu.create', 'crtr.profile.menu.search-existing', 'crtr.profile.menu.use-root',
+    'crtr.profile.menu.set-default', 'crtr.profile.menu.add-directory', 'crtr.profile.menu.unpin',
+    'crtr.profile.menu.manage',
+];
+const PROFILE_SEARCH_ACTIONS = [
+    'crtr.profile.search.abort', 'crtr.profile.search.back', 'crtr.profile.search.pick',
+    'crtr.profile.search.up', 'crtr.profile.search.down', 'crtr.profile.search.delete',
+];
+function profileRawInput(str, k) {
+    return {
+        input: k.ctrl === true || k.meta === true ? (k.name ?? str) : str,
+        upArrow: k.name === 'up', downArrow: k.name === 'down',
+        return: k.name === 'return' || k.name === 'enter', escape: k.name === 'escape',
+        backspace: k.name === 'backspace', ctrl: k.ctrl, meta: k.meta, shift: k.shift,
+    };
+}
+function firstProfileMatch(bindings, ids, raw) {
+    return ids.find((id) => matchesTerminalInput(bindings, id, raw)) ?? null;
+}
+export function resolveProfileMenuAction(bindings, raw) {
+    return firstProfileMatch(bindings, PROFILE_MENU_ACTIONS, raw);
+}
+export function resolveProfileSearchAction(bindings, raw) {
+    return firstProfileMatch(bindings, PROFILE_SEARCH_ACTIONS, raw);
+}
+/** Resolve cwd to an absolute, realpath'd form so it compares against the
+ *  realpath'd project dirs `createProfile`/`addProfileProject` already store
+ *  (manifest.ts resolves every project dir through `realpathSync`). Falls back
+ *  to the plain resolved path when the dir can't be stat'd (mirrors
+ *  `resolveExistingProjectDir`'s own fallback). */
+function resolveCwd(cwd) {
+    const abs = resolvePath(cwd);
+    if (!existsSync(abs))
+        return abs;
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** A project dir "covers" cwd when cwd sits at or below it, OR — the
+ *  workspace-root case — the project dir itself sits below cwd (a profile can
+ *  point at one project nested under a wider workspace cwd). */
+function projectCovers(cwd, project) {
+    if (cwd === project)
+        return true;
+    if (cwd.startsWith(project + sep))
+        return true;
+    if (project.startsWith(cwd + sep))
+        return true;
+    return false;
+}
+/** 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.path));
+}
+/** `a` more recent than `b`, treating null as the oldest possible value (never
+ *  wins over a real timestamp). ISO 8601 strings compare correctly lexically. */
+function isMoreRecent(a, b) {
+    if (a === null)
+        return false;
+    if (b === null)
+        return true;
+    return a > b;
+}
+function pickMostRecent(entries) {
+    return entries.reduce((best, cur) => isMoreRecent(cur.manifest.last_used_at, best.manifest.last_used_at) ? cur : best);
+}
+function profileSelectionState(cwd) {
+    const resolvedCwd = resolveCwd(cwd);
+    const covering = listProfiles().filter((profile) => profileCoversCwd(profile, resolvedCwd));
+    const exact = covering.filter((profile) => profile.manifest.projects.some((project) => project.path === resolvedCwd));
+    const pinnedId = getDefaultProfileId(resolvedCwd);
+    const pinned = pinnedId === null ? null : covering.find((profile) => profile.profileId === pinnedId) ?? null;
+    return { covering, exact, pinnedId, pinned };
+}
+/** Resolve the headless selector against existing state without changing it. */
+export function selectProfileForCwdReadOnly(cwd) {
+    const { covering, exact, pinned } = profileSelectionState(cwd);
+    if (pinned !== null)
+        return pinned.profileId;
+    if (exact.length === 1)
+        return exact[0].profileId;
+    const pool = exact.length > 0 ? exact : covering;
+    if (pool.length > 0)
+        return pickMostRecent(pool).profileId;
+    return ROOT_PROFILE_ID;
+}
+function isInteractive() {
+    return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+// Pre-boot prompt presentation. These prompts print to the raw controlling
+// terminal BEFORE pi takes it over (not the attach viewer), so styling is
+// plain ANSI via the house `stdoutColor` helper (NO_COLOR / non-TTY aware) and
+// portable glyphs only — no Nerd Font (the pre-boot terminal may lack it).
+// One shared visual language across all four gates: a bold title + optional
+// dim subtitle, then accent-keyed option rows. We deliberately do NOT echo the
+// user's own cwd back at them (they know where they are) — the only paths
+// worth showing are OTHER dirs: which project root a covering profile owns.
+const dim = stdoutColor.dim;
+const bold = stdoutColor.bold;
+const accent = stdoutColor.cyan;
+/** Selectable key ([1], [c], [r]) — the one thing the eye hunts for. */
+function key(k) {
+    return accent(bold(k));
+}
+/** Coarse "last used" for disambiguating profiles that otherwise look alike
+ *  (notably several profiles claiming the SAME dir). null → never used. */
+function relativeUsed(iso) {
+    if (iso === null)
+        return 'never used';
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return 'used recently';
+    const secs = Math.max(0, Math.floor((Date.now() - then) / 1000));
+    if (secs < 60)
+        return 'used just now';
+    const mins = Math.floor(secs / 60);
+    if (mins < 60)
+        return `used ${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `used ${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30)
+        return `used ${days}d ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12)
+        return `used ${months}mo ago`;
+    return `used ${Math.floor(months / 12)}y ago`;
+}
+/** Blank-line-padded bold title with an optional dim subtitle beneath it. No
+ *  cwd echo — the user already knows their own directory. */
+function writeHeader(title, subtitle) {
+    const sub = subtitle !== undefined ? `  ${dim(subtitle)}\n` : '';
+    process.stdout.write(`\n  ${bold(title)}\n${sub}\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.path)} \u00b7 ${n} dirs total` : tildify(first.path);
+}
+/** ▸ 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(bindings, 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 slot = r.bindingId === undefined ? ++num : 0;
+        const tag = r.bindingId !== undefined
+            ? formatBinding(bindings, r.bindingId)
+            : slot <= 9 ? formatBinding(bindings, `crtr.profile.menu.slot.${slot}`) : '';
+        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(`${formatBinding(bindings, 'crtr.profile.menu.up')}/${formatBinding(bindings, 'crtr.profile.menu.down')} move  ${formatBinding(bindings, 'crtr.profile.menu.select')} select  ${formatBinding(bindings, 'crtr.profile.menu.accept-default')} default  ${formatBinding(bindings, 'crtr.profile.menu.abort')} quit`)}\n`;
+    return out;
+}
+/** Drive a highlighted keypress menu to a resolution. Returns the selected row
+ *  index, plus the semantic action when a row-scoped action was invoked. */
+function runMenu(bindings, title, subtitle, rows, opts = {}) {
+    const numbered = [];
+    rows.forEach((r, i) => {
+        if (r.bindingId === undefined)
+            numbered.push(i);
+    });
+    let sel = opts.initialIndex ?? 0;
+    return new Promise((resolve) => {
+        let prevLines = 0;
+        const draw = () => {
+            const block = renderMenu(bindings, 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) => {
+            const action = resolveProfileMenuAction(bindings, profileRawInput(str, k));
+            if (action === 'crtr.profile.menu.abort') {
+                cleanup();
+                process.stdout.write('\n');
+                process.exit(130);
+            }
+            if (action === 'crtr.profile.menu.up') {
+                sel = (sel - 1 + rows.length) % rows.length;
+                draw();
+                return;
+            }
+            if (action === 'crtr.profile.menu.down') {
+                sel = (sel + 1) % rows.length;
+                draw();
+                return;
+            }
+            if (action === 'crtr.profile.menu.select') {
+                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 (action === 'crtr.profile.menu.accept-default') {
+                cleanup();
+                resolve({ index: opts.initialIndex ?? 0 });
+                return;
+            }
+            if (action?.startsWith('crtr.profile.menu.slot.')) {
+                const d = Number.parseInt(action.slice(-1), 10);
+                if (d >= 1 && d <= numbered.length) {
+                    sel = numbered[d - 1];
+                    draw();
+                }
+                return;
+            }
+            const hk = rows.findIndex((r) => r.bindingId !== undefined && r.bindingId === action);
+            if (hk >= 0) {
+                cleanup();
+                resolve({ index: hk });
+                return;
+            }
+            if (action !== null && opts.actionBindingIds?.includes(action) === true) {
+                cleanup();
+                resolve({ index: sel, action });
+            }
+        };
+        emitKeypressEvents(process.stdin);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('keypress', onKey);
+        draw();
+    });
+}
+// The profile manager. `v` on either selection gate opens the Profiles page of
+// `crtr sys settings` in a tmux popup: this menu is a CHOOSER filtered to cwd,
+// while that page is the whole map — every profile, every directory each one
+// owns, every pin. The popup runs to completion with the raw-mode menu already
+// torn down (runMenu cleans up before resolving an action), and the caller then
+// re-runs the whole selector, so a directory just adopted or a default just
+// pinned decides the menu you come back to.
+/** Open the profiles page in a tmux popup and block until it closes. False when
+ *  there is no tmux to host it — possible only on the `crtr node new` path, as
+ *  the front door requires tmux before it ever selects — after printing the
+ *  pointer, so the caller can simply redraw its menu. */
+function openProfileManager(cwd) {
+    if (!inTmux()) {
+        process.stdout.write(`  ${dim('the profile manager needs tmux \u2014 run `crtr sys settings` instead')}\n`);
+        return false;
+    }
+    spawnSync('tmux', [
+        'display-popup', '-E', '-T', ' profiles ', '-w', '90%', '-h', '85%', '-d', cwd,
+        ...surfaceTmuxStyleArgs(),
+        'crtr sys settings --page profiles',
+    ], { stdio: 'inherit' });
+    return true;
+}
+/** The gate answering "the user managed their profiles" — every prior reading of
+ *  this directory is stale, so `selectProfileForCwd` decides again from the top. */
+const MANAGED = Symbol('profile-manager-ran');
+/** The trailing readline prompt: `  › <dim hint> `. */
+function caret(hint) {
+    return `  ${accent('\u203a')} ${dim(hint)} `;
+}
+function rootProfileMessage(cwd) {
+    return (`crtr: no profile covers ${cwd}, and this session is non-interactive — using the root profile.\n` +
+        `Run \`crtr profile new --name <name> --project ${cwd}\` to create a dedicated profile, or pass --profile <id-or-name> next time.\n`);
+}
+/** The one synchronous (pre-boot) decision point: no profile covers cwd, and
+ *  the session IS interactive. Ask on the controlling terminal — create a
+ *  profile pointing at cwd, or proceed as root — and block until answered.
+ *  Deliberately a minimal `readline` prompt, not `crtr human send`: that bridge
+ *  is asynchronous (registers an interaction in the ticket store, then waits for
+ *  the human to answer it from a separate inbox) and cannot gate pi's boot; those
+ *  entry points (`human send`/`review`) are built for a queued,
+ *  asynchronously-answered interaction, not a two-choice gate on the same TTY pi
+ *  is about to take over — a raw `readline` question is the actual minimal
+ *  fit here. */
+/** 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 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) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        writeHeader(`Profile "${entry.manifest.name}" doesn't cover this directory`);
+        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;
+    await 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(bindings) {
+    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.path).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  ${formatBinding(bindings, 'crtr.profile.search.up')}/${formatBinding(bindings, 'crtr.profile.search.down')} move  ${formatBinding(bindings, 'crtr.profile.search.pick')} pick  ${formatBinding(bindings, 'crtr.profile.search.back')} 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) => {
+            const action = resolveProfileSearchAction(bindings, profileRawInput(str, k));
+            if (action === 'crtr.profile.search.abort') {
+                cleanup();
+                process.stdout.write('\n');
+                process.exit(130);
+            }
+            if (action === 'crtr.profile.search.back') {
+                cleanup();
+                resolve(null);
+                return;
+            }
+            const matches = matchesOf();
+            if (action === 'crtr.profile.search.pick') {
+                if (matches.length > 0) {
+                    cleanup();
+                    resolve(matches[sel].profileId);
+                }
+                return;
+            }
+            if (action === 'crtr.profile.search.up') {
+                if (matches.length > 0) {
+                    sel = (sel - 1 + matches.length) % matches.length;
+                    draw();
+                }
+                return;
+            }
+            if (action === 'crtr.profile.search.down') {
+                if (matches.length > 0) {
+                    sel = (sel + 1) % matches.length;
+                    draw();
+                }
+                return;
+            }
+            if (action === 'crtr.profile.search.delete') {
+                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
+ *  or the no-coverage fallback. */
+async function createProfileHere(rl, cwd) {
+    const defaultName = basename(cwd) || 'profile';
+    const nameInput = (await rl.question(caret(`name the new profile [${defaultName}]`))).trim();
+    const name = nameInput !== '' ? nameInput : defaultName;
+    const profileId = (await createProfile(name, [{ path: cwd }])).profileId;
+    process.stdout.write(`  ${accent('\u2713')} ${dim(`created profile "${name}"`)}\n`);
+    return profileId;
+}
+async function promptCreateOrRoot(cwd, bindings) {
+    // 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: '', bindingId: 'crtr.profile.menu.create' },
+        { label: 'select an existing profile', detail: '', bindingId: 'crtr.profile.menu.search-existing' },
+        { label: dim('use the root profile'), detail: '', bindingId: 'crtr.profile.menu.use-root', isDefault: true },
+    ];
+    for (;;) {
+        const res = await runMenu(bindings, 'No profile covers this directory', undefined, rows, {
+            initialIndex: 2,
+            actionBindingIds: ['crtr.profile.menu.manage'],
+            hint: `${formatBinding(bindings, 'crtr.profile.menu.manage')}=manage profiles`,
+        });
+        // Managing may have given this directory an owner — re-decide from the top
+        // rather than re-showing a menu the manager just made wrong. With no tmux to
+        // host the manager nothing changed, so fall through to a redraw.
+        if (res.action === 'crtr.profile.menu.manage') {
+            if (openProfileManager(cwd))
+                return MANAGED;
+            continue;
+        }
+        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(bindings);
+            // 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 (await ensureRootProfile()).profileId;
+    }
+}
+/** Choose among a set of candidate profiles for `cwd`, or create a new one.
+ *  Reached in two ambiguous cases: MULTIPLE profiles claim `cwd` as their exact
+ *  project dir (`exact` true), or `cwd` merely sits within one or more profiles'
+ *  project dirs from a parent/workspace dir (`exact` false). Present them
+ *  most-recently-used first (choice 1 / the bare-Enter default) plus "create a
+ *  new profile here", and block until answered. Root is deliberately NOT offered
+ *  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, pinnedId, bindings) {
+    // 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 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.path)) ??
+                    entry.manifest.projects[0];
+                return n > 1 ? `matches ${tildify(md.path)} \u00b7 ${n} dirs total` : `matches ${tildify(md.path)}`;
+            })();
+        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: '', bindingId: 'crtr.profile.menu.create' });
+    // Row-scoped actions pin the highlighted profile, widen its purview (hidden
+    // when candidates already claim cwd exactly), or clear an existing pin.
+    const actionBindingIds = ['crtr.profile.menu.set-default', 'crtr.profile.menu.manage'];
+    if (!exact)
+        actionBindingIds.push('crtr.profile.menu.add-directory');
+    if (pinned !== null)
+        actionBindingIds.push('crtr.profile.menu.unpin');
+    const hintParts = [`${formatBinding(bindings, 'crtr.profile.menu.set-default')}=set default`];
+    if (!exact)
+        hintParts.push(`${formatBinding(bindings, 'crtr.profile.menu.add-directory')}=add dir here`);
+    if (pinned !== null)
+        hintParts.push(`${formatBinding(bindings, 'crtr.profile.menu.unpin')}=unpin`);
+    hintParts.push(`${formatBinding(bindings, 'crtr.profile.menu.manage')}=manage profiles`);
+    const res = await runMenu(bindings, exact ? 'Choose a profile' : 'Select a profile', exact
+        ? 'Several profiles claim this directory as their project'
+        : 'This directory falls under existing profile(s)', rows, { actionBindingIds, hint: hintParts.join('  ') });
+    // The manager can adopt dirs, pin a default, create or delete profiles — every
+    // row here may be stale, so the caller re-resolves from the top. Without tmux
+    // nothing changed: re-show this same menu.
+    if (res.action === 'crtr.profile.menu.manage') {
+        return openProfileManager(cwd)
+            ? MANAGED
+            : await promptPickProfileOrCreate(candidates, cwd, exact, pinnedId, bindings);
+    }
+    // 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);
+        }
+        finally {
+            rl.close();
+        }
+    }
+    const picked = ordered[res.index];
+    if (res.action === 'crtr.profile.menu.unpin') {
+        await clearDefaultProfile(cwd);
+        process.stdout.write(`  ${accent('\u2713')} ${dim('cleared the default for this directory')}\n`);
+        return picked.profileId;
+    }
+    if (res.action === 'crtr.profile.menu.set-default') {
+        await setDefaultProfileId(cwd, picked.profileId);
+        process.stdout.write(`  ${accent('\u2713')} ${dim(`"${picked.manifest.name}" is now the default here`)}\n`);
+    }
+    else if (res.action === 'crtr.profile.menu.add-directory') {
+        await 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.
+ *
+ *  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.
+ *  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
+ *     ambiguous: interactive → menu among them + create; headless → MRU.
+ *  3. Else, among profiles whose project list otherwise COVERS `cwd` (cwd sits
+ *     in a subdir of, or a workspace above, one of their project dirs):
+ *       - Interactive: prompt with a MENU of those covering profiles + "create
+ *         a new profile here", BEFORE pi boots (no root option — the directory
+ *         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, 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) {
+    const resolvedCwd = resolveCwd(cwd);
+    const bindings = resolveUserKeybindings();
+    if (explicitProfile !== undefined && explicitProfile !== null && 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()) {
+            await promptAddDirToProfile(entry, resolvedCwd);
+        }
+        await updateProfileLastUsed(entry.profileId);
+        return entry.profileId;
+    }
+    // Looped for the one gate that changes the world before it answers: `v` opens
+    // the profile manager, which can adopt this directory, pin a default, or
+    // create a profile — so the decision is taken again from the top rather than
+    // resumed inside a menu the manager just invalidated.
+    for (;;) {
+        const { covering, exact, pinnedId, pinned } = profileSelectionState(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.
+        if (pinnedId !== null && pinned === null)
+            await clearDefaultProfile(resolvedCwd);
+        // A valid pin decides it outright and STOPS ASKING — the whole point of
+        // setting a default. Auto-pick it silently: the crouton banner the viewer
+        // paints a beat later shows the active profile and the `crtr --pick-profile`
+        // hint, so a boot-time breadcrumb here would just be redundant.
+        // `crtr --pick-profile` (forcePicker) re-opens the menu to re-pin/unpin.
+        if (pinned !== null && !forcePicker) {
+            await updateProfileLastUsed(pinned.profileId);
+            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.)
+        // Suppressed under forcePicker so `--pick-profile` can pin even a lone owner.
+        if (!forcePicker && pinned === null && exact.length === 1) {
+            await updateProfileLastUsed(exact[0].profileId);
+            return exact[0].profileId;
+        }
+        // Non-interactive: cannot prompt. Prefer an exact claimant, else any covering
+        // profile (both MRU), else root.
+        if (!isInteractive()) {
+            const pool = exact.length > 0 ? exact : covering;
+            if (pool.length > 0) {
+                const winner = pickMostRecent(pool);
+                await updateProfileLastUsed(winner.profileId);
+                return winner.profileId;
+            }
+            const root = await ensureRootProfile();
+            process.stderr.write(rootProfileMessage(resolvedCwd));
+            return root.profileId;
+        }
+        // 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, validPinnedId, bindings)
+            : covering.length > 0
+                ? await promptPickProfileOrCreate(covering, resolvedCwd, false, validPinnedId, bindings)
+                : await promptCreateOrRoot(resolvedCwd, bindings);
+        if (chosen === MANAGED)
+            continue;
+        await updateProfileLastUsed(chosen);
+        return chosen;
+    }
+}