@phnx-labs/agents-cli 1.20.88 → 1.20.90

package/dist/lib/menubar/install-menubar.d.ts

@@ -124,6 +124,48 @@ export declare function disableMenubarService(): void;
  * Best-effort — never throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
+/** One step of `agents menubar setup`, and how it came out. */
+export interface SetupStep {
+    /** What was configured. */
+    name: string;
+    /** `ok` — already correct or now correct; `changed` — this run fixed it;
+     *  `failed` — could not be configured (setup reports and exits nonzero). */
+    outcome: 'ok' | 'changed' | 'failed';
+    detail: string;
+}
+export interface SetupResult {
+    steps: SetupStep[];
+    /** Every step landed on `ok`/`changed` and exactly one helper is running. */
+    configured: boolean;
+    status: MenubarStatus;
+}
+/**
+ * Decide which live helper processes must be ended so exactly one status item
+ * survives. Pure so the choice is unit-testable without a live menu bar.
+ *
+ * EVERY current process is ended, including the wanted one: the caller
+ * re-kickstarts the launchd service straight after, so the survivor is the one
+ * launchd owns (RunAtLoad + KeepAlive), not whichever copy happened to win a
+ * race. Picking a survivor from a `ps` listing cannot do this — the list says
+ * nothing about which pid launchd will keep alive, so leaving one alive risks
+ * keeping the un-managed copy and re-creating the duplicate on next login.
+ */
+export declare function processesToEnd(status: Pick<MenubarStatus, 'instances' | 'foreignInstances'>): MenubarProcess[];
+/**
+ * `agents menubar setup` — configure the menu bar end-to-end, idempotently.
+ *
+ * The one command that gets a machine to the intended state: exactly one status
+ * item, owned by a launchd service that starts it at login and restarts it if it
+ * dies. Each concern is a reported step, so a partial failure names itself
+ * instead of hiding behind "enabled".
+ *
+ *   1. bundle      — install/refresh the .app at the stable App Support path
+ *   2. signature   — a valid code identity (macOS 26+ SIGKILLs an invalid one)
+ *   3. duplicates  — end every live helper, so the only survivor is launchd's
+ *   4. login item  — write the plist (RunAtLoad + KeepAlive) and bootstrap it
+ *   5. single      — verify exactly one helper came back up
+ */
+export declare function runMenubarSetup(): SetupResult;
 /** A live MenubarHelper process: its pid and the executable it is running. */
 export interface MenubarProcess {
     pid: number;
@@ -131,19 +173,26 @@ export interface MenubarProcess {
 }
 /**
  * Split the live MenubarHelper processes into the installed bundle's own
- * (`running`) and every other copy (`foreign`).
+ * (`own`) and every other copy (`foreign`).
  *
  * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
  * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
  * still reported a healthy `running: yes` — the paste was dead and nothing said
  * so. A foreign copy is the thing to look for, so name it.
  *
+ * `own` is a LIST, not a boolean: two copies of the INSTALLED bundle can run at
+ * once (launchd's KeepAlive service plus a LaunchServices/`open` launch of the
+ * same .app), which is the duplicate the user actually sees — two agents marks
+ * in the menu bar. Collapsing them to `running: true` reported that state as
+ * healthy. The helper now refuses to be the second (SingleInstance.swift), and
+ * `agents menubar setup` ends any duplicate a pre-fix helper left behind.
+ *
  * Identity comes from `comm` (the resolved executable), never from a substring
  * of the command line: matching the latter flags any shell that merely mentions
  * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
  */
 export declare function classifyMenubarProcesses(commOutput: string, commandOutput: string, installedExec: string): {
-    running: boolean;
+    own: MenubarProcess[];
     foreign: MenubarProcess[];
 };
 export interface MenubarStatus {
@@ -155,6 +204,8 @@ export interface MenubarStatus {
     stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
+    /** Live processes of the INSTALLED bundle. More than one is the duplicate. */
+    instances: MenubarProcess[];
     /** Live MenubarHelper processes that are NOT the installed bundle. */
     foreignInstances: MenubarProcess[];
     disabledByUser: boolean;

package/dist/lib/menubar/install-menubar.js

@@ -19,6 +19,7 @@ import { execFileSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { sleepSync } from '../fs-atomic.js';
 import { getRuntimeStateDir, getHelpersDir } from '../state.js';
 import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../version.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
@@ -149,6 +150,27 @@ function copyAppBundle(src, dest) {
         throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
     }
 }
+/**
+ * Register the freshly-installed bundle with LaunchServices.
+ *
+ * The helper is copied to ~/Library/Application Support (not /Applications) and
+ * launched only via launchd, so LaunchServices may never discover it on its own.
+ * A daemon notification posted by the one-shot `MenubarHelper --notify` process is
+ * attributed to this bundle, and macOS resolves the notification's LEFT-hand app
+ * icon from the bundle's LaunchServices record — so a bundle LS doesn't know about
+ * shows a blank app icon there (the right-hand contentImage is unaffected;
+ * appIconImage reads the `.icns` directly). `lsregister -f` registers the bundle at
+ * its current path so the OS can resolve its AppIcon for that slot. Best-effort:
+ * LaunchServices is advisory, and a failure here must never block install.
+ */
+function refreshBundleIconRegistration(appPath) {
+    const lsregister = '/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister';
+    const bin = fs.existsSync(lsregister) ? lsregister : 'lsregister';
+    const r = spawnSync(bin, ['-f', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+    if (r.error) {
+        /* lsregister missing / moved — advisory only, ignore. */
+    }
+}
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export function codesignVerifies(appPath) {
     const r = spawnSync('codesign', ['--verify', '--strict', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
@@ -200,6 +222,10 @@ export function ensureMenubarAppInstalled(opts = {}) {
     }
     copyAppBundle(src, dest);
     ensureValidSignature(dest);
+    // A fresh copy is exactly when the bundle's icon can be new (first install) or
+    // superseded (upgrade) — register it so LaunchServices knows the bundle and can
+    // resolve its AppIcon for the left-hand slot of daemon notifications.
+    refreshBundleIconRegistration(dest);
     return installedExecutablePath();
 }
 function xmlEscape(s) {
@@ -299,24 +325,34 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
         process.stderr.write('agents: menu-bar helper has no valid code signature; skipping launch to avoid a crash loop.\n');
         return false;
     }
-    if (opts.clearOptOut) {
-        try {
-            fs.rmSync(disabledSentinelPath(), { force: true });
-        }
-        catch { /* already gone */ }
+    if (opts.clearOptOut)
+        clearMenubarOptOut();
+    installAndStartService(exec);
+    return true;
+}
+/** Drop the sticky `agents menubar disable` sentinel. */
+function clearMenubarOptOut() {
+    try {
+        fs.rmSync(disabledSentinelPath(), { force: true });
     }
+    catch { /* already gone */ }
+}
+/**
+ * Write the launchd plist for `exec`, restart the job, and stamp the installed
+ * version. Shared by `enableMenubarService` and `runMenubarSetup` so the two
+ * cannot drift on what "installed and started" means — the version stamp in
+ * particular is what the upgrade self-heal reads to decide staleness, and a
+ * path that skipped it would make every later `agents` invocation reinstall.
+ */
+function installAndStartService(exec) {
     const plist = servicePlistPath();
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.writeFileSync(plist, generateServicePlist(exec));
-    const uid = process.getuid?.() ?? 0;
-    restartMenubarLaunchAgent(uid, plist);
-    // Stamp the version we just installed so the upgrade self-heal can tell when
-    // a later release ships a newer helper that needs reinstalling.
+    restartMenubarLaunchAgent(process.getuid?.() ?? 0, plist);
     try {
         fs.writeFileSync(installedVersionMarkerPath(), getCliVersion());
     }
     catch { /* best effort */ }
-    return true;
 }
 /**
  * Pure staleness decision (no I/O) so the truth table is unit-testable. The
@@ -441,6 +477,117 @@ export function installMenubarLaunchAgentOnUpgrade() {
         /* never block startup on the menu bar */
     }
 }
+/**
+ * Decide which live helper processes must be ended so exactly one status item
+ * survives. Pure so the choice is unit-testable without a live menu bar.
+ *
+ * EVERY current process is ended, including the wanted one: the caller
+ * re-kickstarts the launchd service straight after, so the survivor is the one
+ * launchd owns (RunAtLoad + KeepAlive), not whichever copy happened to win a
+ * race. Picking a survivor from a `ps` listing cannot do this — the list says
+ * nothing about which pid launchd will keep alive, so leaving one alive risks
+ * keeping the un-managed copy and re-creating the duplicate on next login.
+ */
+export function processesToEnd(status) {
+    return [...status.instances, ...status.foreignInstances];
+}
+function endProcess(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch { /* already gone */ }
+}
+/**
+ * `agents menubar setup` — configure the menu bar end-to-end, idempotently.
+ *
+ * The one command that gets a machine to the intended state: exactly one status
+ * item, owned by a launchd service that starts it at login and restarts it if it
+ * dies. Each concern is a reported step, so a partial failure names itself
+ * instead of hiding behind "enabled".
+ *
+ *   1. bundle      — install/refresh the .app at the stable App Support path
+ *   2. signature   — a valid code identity (macOS 26+ SIGKILLs an invalid one)
+ *   3. duplicates  — end every live helper, so the only survivor is launchd's
+ *   4. login item  — write the plist (RunAtLoad + KeepAlive) and bootstrap it
+ *   5. single      — verify exactly one helper came back up
+ */
+export function runMenubarSetup() {
+    const steps = [];
+    const step = (name, outcome, detail) => {
+        steps.push({ name, outcome, detail });
+    };
+    if (!onDarwin()) {
+        step('platform', 'failed', `the menu bar helper is macOS only (this is ${process.platform})`);
+        return { steps, configured: false, status: getMenubarStatus() };
+    }
+    const before = getMenubarStatus();
+    if (!sourceAppPath()) {
+        step('bundle', 'failed', 'no menu-bar helper bundle ships with this install');
+        return { steps, configured: false, status: before };
+    }
+    // 3 before 1: end the running copies BEFORE swapping the bundle underneath
+    // them, so no helper keeps a status item alive on a binary that no longer
+    // exists on disk.
+    const doomed = processesToEnd(before);
+    for (const p of doomed)
+        endProcess(p.pid);
+    if (doomed.length > 1) {
+        step('duplicates', 'changed', `ended ${doomed.length} running helpers (${doomed.map((p) => p.pid).join(', ')}) — launchd restarts exactly one`);
+    }
+    else if (doomed.length === 1) {
+        step('duplicates', 'ok', 'one helper was running; restarting it under launchd');
+    }
+    else {
+        step('duplicates', 'ok', 'no helper was running');
+    }
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true });
+    if (!exec) {
+        step('bundle', 'failed', 'could not install the helper bundle');
+        return { steps, configured: false, status: getMenubarStatus() };
+    }
+    step('bundle', before.installedVersion === getCliVersion() ? 'ok' : 'changed', `${installedAppPath()} (${getCliVersion()})`);
+    if (!codesignVerifies(installedAppPath())) {
+        step('signature', 'failed', 'no valid code signature — refusing to start it (launchd KeepAlive would crash-loop)');
+        return { steps, configured: false, status: getMenubarStatus() };
+    }
+    step('signature', 'ok', 'valid');
+    // Clear the sticky opt-out: running `setup` is an explicit request for the
+    // menu bar, so a stale `menubar disable` must not silently win.
+    clearMenubarOptOut();
+    installAndStartService(exec);
+    step('login item', before.serviceInstalled ? 'ok' : 'changed', `${SERVICE_LABEL} — starts at login, restarts if it dies`);
+    // launchd's bootstrap+kickstart is asynchronous; give the status item a beat
+    // to claim the lock before counting instances, or `setup` reports zero on a
+    // machine that is in fact coming up correctly.
+    const after = waitForSingleInstance();
+    if (after.instances.length === 1 && after.foreignInstances.length === 0) {
+        step('single instance', 'ok', `pid ${after.instances[0].pid}`);
+    }
+    else if (after.instances.length === 0) {
+        step('single instance', 'failed', 'the helper did not come back up — see `agents menubar status`');
+    }
+    else {
+        const extra = [...after.instances.slice(1), ...after.foreignInstances];
+        step('single instance', 'failed', `${after.instances.length + after.foreignInstances.length} helpers running (${extra.map((p) => p.pid).join(', ')} are extra)`);
+    }
+    return {
+        steps,
+        configured: steps.every((s) => s.outcome !== 'failed'),
+        status: after,
+    };
+}
+/**
+ * Poll (up to ~3s) for launchd to bring the single helper back. Returns the
+ * last status read either way — the caller decides what a miss means.
+ */
+function waitForSingleInstance() {
+    let status = getMenubarStatus();
+    for (let i = 0; i < 15 && status.instances.length !== 1; i++) {
+        sleepSync(200);
+        status = getMenubarStatus();
+    }
+    return status;
+}
 /** Parse `ps -axo pid=,<field>=` into pid -> field. The field is the rest of the
  *  line, so a path containing spaces (App Support does) survives intact. */
 function parsePsLines(psOutput) {
@@ -454,21 +601,28 @@ function parsePsLines(psOutput) {
 }
 /**
  * Split the live MenubarHelper processes into the installed bundle's own
- * (`running`) and every other copy (`foreign`).
+ * (`own`) and every other copy (`foreign`).
  *
  * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
  * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
  * still reported a healthy `running: yes` — the paste was dead and nothing said
  * so. A foreign copy is the thing to look for, so name it.
  *
+ * `own` is a LIST, not a boolean: two copies of the INSTALLED bundle can run at
+ * once (launchd's KeepAlive service plus a LaunchServices/`open` launch of the
+ * same .app), which is the duplicate the user actually sees — two agents marks
+ * in the menu bar. Collapsing them to `running: true` reported that state as
+ * healthy. The helper now refuses to be the second (SingleInstance.swift), and
+ * `agents menubar setup` ends any duplicate a pre-fix helper left behind.
+ *
  * Identity comes from `comm` (the resolved executable), never from a substring
  * of the command line: matching the latter flags any shell that merely mentions
  * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
  */
 export function classifyMenubarProcesses(commOutput, commandOutput, installedExec) {
     const commands = parsePsLines(commandOutput);
+    const own = [];
     const foreign = [];
-    let running = false;
     for (const [pid, executable] of parsePsLines(commOutput)) {
         if (path.basename(executable) !== 'MenubarHelper')
             continue;
@@ -477,26 +631,26 @@ export function classifyMenubarProcesses(commOutput, commandOutput, installedExe
         if ((commands.get(pid) || '').includes('--notify'))
             continue;
         if (executable === installedExec)
-            running = true;
+            own.push({ pid, executable });
         else
             foreign.push({ pid, executable });
     }
-    return { running, foreign };
+    return { own, foreign };
+}
+/** Live MenubarHelper processes, split by whether they are the installed bundle. */
+function liveMenubarProcesses() {
+    if (!onDarwin())
+        return { own: [], foreign: [] };
+    const ps = (format) => spawnSync('ps', ['-axo', format], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+    const comm = ps('pid=,comm=');
+    const command = ps('pid=,command=');
+    if (comm.status !== 0 || command.status !== 0)
+        return { own: [], foreign: [] };
+    return classifyMenubarProcesses(comm.stdout || '', command.stdout || '', installedExecutablePath());
 }
 export function getMenubarStatus() {
     const dest = installedAppPath();
-    let running = false;
-    let foreignInstances = [];
-    if (onDarwin()) {
-        const ps = (format) => spawnSync('ps', ['-axo', format], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
-        const comm = ps('pid=,comm=');
-        const command = ps('pid=,command=');
-        if (comm.status === 0 && command.status === 0) {
-            const c = classifyMenubarProcesses(comm.stdout || '', command.stdout || '', installedExecutablePath());
-            running = c.running;
-            foreignInstances = c.foreign;
-        }
-    }
+    const { own, foreign } = liveMenubarProcesses();
     const serviceInstalled = menubarServiceInstalled();
     return {
         platform: process.platform,
@@ -506,8 +660,9 @@ export function getMenubarStatus() {
         currentVersion: getCliVersion(),
         stale: onDarwin() && serviceInstalled && menubarSetupStale(),
         serviceInstalled,
-        running,
-        foreignInstances,
+        running: own.length > 0,
+        instances: own,
+        foreignInstances: foreign,
         disabledByUser: menubarDisabledByUser(),
     };
 }

package/dist/lib/picker.d.ts

@@ -77,9 +77,14 @@ export interface DynamicPickerConfig<T, F> {
     /**
      * Side-effecting keys that don't change the filter (e.g. `y` copies a command).
      * Receives the live search `query` so the effect can be search-aware. Return a
-     * short string to flash under the list.
+     * short string to flash under the list, or `{ flash, reload }` when the effect
+     * changed something the rows RENDER (a star, a mark) and the list has to be
+     * rebuilt — the row labels are memoized, so a flash alone leaves them stale.
      */
-    onKey?: (name: string, filter: F, active: T | undefined, query: string) => string | void;
+    onKey?: (name: string, filter: F, active: T | undefined, query: string) => string | void | {
+        flash?: string;
+        reload?: boolean;
+    };
     /** Key that enters search mode (default `s`). */
     searchKey?: string;
     /** Key that toggles the preview pane (default `tab`). */
@@ -89,6 +94,26 @@ export interface DynamicPickerConfig<T, F> {
     loadingMessage?: string;
     enterHint?: string;
 }
+/**
+ * The lookup token for a hotkey: the literal character the key produced, else
+ * readline's key name (`tab`, `escape`, arrows).
+ *
+ * readline reports both `f` and `F` as name `f` — only `sequence` tells them
+ * apart — and gives a punctuation key like `*` no name at all. Keying on the
+ * character makes shifted letters and punctuation bindable, and is a no-op for
+ * every existing binding: for a plain lowercase letter, sequence === name.
+ *
+ * Callers receiving this in `onKey` see the literal character, so a handler that
+ * wants to accept both cases of a letter must say so (`'y'` and `'Y'`); the
+ * keyBindings lookup falls back to the key NAME, which keeps the shifted form of
+ * an existing single-letter binding working without each caller restating it.
+ */
+export declare function hotkeyToken(key: {
+    name?: string;
+    sequence?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+}): string;
 /** The result returned when the user selects a row: the item plus the live filter. */
 export interface DynamicPicked<T, F> {
     item: T;

package/dist/lib/picker.js

@@ -324,6 +324,28 @@ export function multiItemPicker(config) {
     });
     return prompt(config);
 }
+/**
+ * The lookup token for a hotkey: the literal character the key produced, else
+ * readline's key name (`tab`, `escape`, arrows).
+ *
+ * readline reports both `f` and `F` as name `f` — only `sequence` tells them
+ * apart — and gives a punctuation key like `*` no name at all. Keying on the
+ * character makes shifted letters and punctuation bindable, and is a no-op for
+ * every existing binding: for a plain lowercase letter, sequence === name.
+ *
+ * Callers receiving this in `onKey` see the literal character, so a handler that
+ * wants to accept both cases of a letter must say so (`'y'` and `'Y'`); the
+ * keyBindings lookup falls back to the key NAME, which keeps the shifted form of
+ * an existing single-letter binding working without each caller restating it.
+ */
+export function hotkeyToken(key) {
+    const seq = key.sequence;
+    // Printable single characters only — a control code's sequence (`\t`, `\r`,
+    // `\x7f`) must keep resolving to its name.
+    if (!key.ctrl && !key.meta && seq && seq.length === 1 && seq > ' ' && seq !== '\x7f')
+        return seq;
+    return key.name ?? '';
+}
 /**
  * Async-refetch variant of {@link itemPicker}. Holds a `filter` object in state and
  * re-runs `load(filter)` whenever a keybinding mutates it (with a loading placeholder
@@ -349,11 +371,32 @@ export function dynamicPicker(config) {
         const [previewOpen, setPreviewOpen] = useState(Boolean(cfg.buildPreview));
         const [active, setActive] = useState(0);
         const [flash, setFlash] = useState('');
+        // Bumped by an `onKey` that asks for a reload; a dep of the load effect, so a
+        // side effect that changed the rows can rebuild them without a filter change.
+        const [reloadNonce, setReloadNonce] = useState(0);
+        // The counter lives in a ref, not in the state read back from the keypress
+        // closure: that closure can hold a STALE `reloadNonce`, so a second reload
+        // would recompute the same value, the state would not change, and the
+        // repaint would silently never happen (the first star appeared, the second
+        // did not). A ref is always current.
+        const reloadCount = useRef(0);
+        // Bumped when a load RESOLVES. `load` is async, so the render that follows
+        // `setReloadNonce` still sees the pre-load data — memoizing the row labels on
+        // the nonce alone rendered each press's result one press late. Keying them on
+        // load COMPLETION is what actually makes them current.
+        const [loadedSeq, setLoadedSeq] = useState(0);
+        const loadedCount = useRef(0);
         const prefix = usePrefix({ status, theme });
         // Guards against a slow load resolving after a newer filter superseded it.
         const gen = useRef(0);
+        // The filter the last load ran on, so a nonce-only reload (a row's own state
+        // changed) can keep the cursor where the user left it. Snapping back to the
+        // top every time you star a row would make the key unusable for a second one.
+        const loadedFilter = useRef(undefined);
         useEffect(() => {
             const my = ++gen.current;
+            const filterChanged = loadedFilter.current !== filter;
+            loadedFilter.current = filter;
             setLoading(true);
             Promise.resolve(cfg.load(filter))
                 .then((rows) => {
@@ -361,7 +404,9 @@ export function dynamicPicker(config) {
                     return;
                 setItems(rows);
                 setLoading(false);
-                setActive(0);
+                setLoadedSeq((loadedCount.current += 1));
+                if (filterChanged)
+                    setActive(0);
             })
                 .catch(() => {
                 if (my !== gen.current)
@@ -369,7 +414,7 @@ export function dynamicPicker(config) {
                 setItems([]);
                 setLoading(false);
             });
-        }, [filter]);
+        }, [filter, reloadNonce]);
         const results = useMemo(() => {
             const q = query.trim();
             const pool = q && cfg.matches ? items.filter((it) => cfg.matches(it, q)) : items;
@@ -377,7 +422,12 @@ export function dynamicPicker(config) {
                 value: item,
                 label: cfg.labelFor(item, q),
             }));
-        }, [items, query]);
+            // `loadedSeq` is a dep because a reload can legitimately return the SAME
+            // array — `load` hands back its cached pool unchanged when no filter is
+            // active — while what a row RENDERS has changed underneath it. Without this
+            // the labels stay memoized on the old state and the side effect looks like
+            // it silently did nothing (starring a row left the star invisible).
+        }, [items, query, loadedSeq]);
         useEffect(() => {
             if (active >= results.length)
                 setActive(0);
@@ -462,7 +512,13 @@ export function dynamicPicker(config) {
                 setPreviewOpen(!previewOpen);
                 return;
             }
-            const binding = cfg.keyBindings?.[key.name ?? ''];
+            const token = hotkeyToken(key);
+            // Exact character first (so `*` and a shifted `F` are addressable), then
+            // the readline name. The fallback is what preserves the shifted form of an
+            // existing single-letter hotkey: `R`/`C`/`A` used to reach their bindings
+            // via `key.name`, and keying on the character alone would silently retire
+            // them for anyone with caps lock on.
+            const binding = cfg.keyBindings?.[token] ?? cfg.keyBindings?.[key.name ?? ''];
             if (binding) {
                 const next = binding(filter);
                 if (!Object.is(next, filter))
@@ -470,9 +526,17 @@ export function dynamicPicker(config) {
                 return;
             }
             if (cfg.onKey) {
-                const msg = cfg.onKey(key.name ?? '', filter, selected?.value, query);
-                if (msg)
-                    setFlash(msg);
+                const res = cfg.onKey(token, filter, selected?.value, query);
+                if (typeof res === 'string')
+                    setFlash(res);
+                else if (res) {
+                    if (res.flash)
+                        setFlash(res.flash);
+                    // The rows themselves changed — force the load effect to re-run so the
+                    // memoized labels are rebuilt.
+                    if (res.reload)
+                        setReloadNonce((reloadCount.current += 1));
+                }
             }
         });
         const message = theme.style.message(cfg.message, status);

package/dist/lib/platform/process.d.ts

@@ -34,9 +34,11 @@ export declare function killTree(pid: number): void;
  *   sites pass their own `windowsHide` with piped stdio.
  */
 export declare function backgroundSpawnOptions(opts?: {
+    cwd?: string;
     fdStdio?: boolean;
     platform?: NodeJS.Platform;
 }): {
+    cwd: string;
     detached: boolean;
     windowsHide: boolean;
 };

package/dist/lib/platform/process.js

@@ -3,6 +3,7 @@
  */
 import { execFileSync } from 'child_process';
 import { readFileSync } from 'fs';
+import * as os from 'os';
 import { sleepSync } from '../fs-atomic.js';
 /**
  * Forcefully terminate a process AND its descendant tree.
@@ -56,12 +57,13 @@ export function killTree(pid) {
  */
 export function backgroundSpawnOptions(opts = {}) {
     const platform = opts.platform ?? process.platform;
+    const cwd = opts.cwd ?? os.homedir();
     if (platform === 'win32') {
         return opts.fdStdio
-            ? { detached: true, windowsHide: true }
-            : { detached: false, windowsHide: true };
+            ? { cwd, detached: true, windowsHide: true }
+            : { cwd, detached: false, windowsHide: true };
     }
-    return { detached: true, windowsHide: false };
+    return { cwd, detached: true, windowsHide: false };
 }
 /**
  * Is a process with this PID currently alive?