@phnx-labs/agents-cli 1.20.89 → 1.20.91

package/dist/lib/hosts/dispatch.js

@@ -93,7 +93,25 @@ export function remoteCdPrefix(remoteCwd, opts = {}) {
  * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
  */
 export function withActorEnv(env) {
-    return { ...actorEnv(resolveActor()), ...(env ?? {}) };
+    return { ...actorEnv(resolveActor()), ...terminalIdEnv(), ...(env ?? {}) };
+}
+/**
+ * Forward the launching editor tab's `AGENT_TERMINAL_ID` across the SSH hop.
+ *
+ * Factory stamps it on every terminal it spawns, and the remote `agents run`
+ * records it in its pid registry (`writePidSessionEntry`) — which is what lets a
+ * tab ask the device "which session is MY terminal running?" instead of guessing
+ * from local state. Without the forward the remote registry has no terminal id,
+ * that question is unanswerable, and the tab is stuck with its spawn-time id even
+ * after the agent has moved to a different session (a `/clear`, or an exit and
+ * rerun in the same tab).
+ *
+ * Same shape as the actor provenance above: absent when the launch did not come
+ * from a tracked terminal, never fabricated.
+ */
+function terminalIdEnv() {
+    const terminalId = process.env.AGENT_TERMINAL_ID?.trim();
+    return terminalId ? { AGENT_TERMINAL_ID: terminalId } : {};
 }
 /**
  * Launch a detached login-shell command in its own Unix session/process group.

package/dist/lib/hq/floor.js

@@ -30,6 +30,18 @@ function teammateName(session, teammatesById) {
 function moodForSession(session, hasOpenBlock) {
     if (session.status === 'abandoned')
         return 'blocked';
+    // A crashed session is NOT `done` — it stopped without finishing, and its last
+    // parsed turn often still says `working`, which would otherwise reach the Floor
+    // as a happily-running agent. Both lost-host states need a human.
+    if (session.status === 'crashed')
+        return 'blocked';
+    // An orphaned session that is genuinely mid-question needs an answer; one that
+    // is merely idle-and-unwatched needs someone to reattach or clean it up. Same
+    // distinction `isAwaitingUser` draws — giving both the high-intensity "needs
+    // input" alert would train the operator to ignore it.
+    if (session.status === 'orphaned') {
+        return session.activity === 'waiting_input' ? 'waiting' : 'blocked';
+    }
     if (session.status === 'closed')
         return 'done';
     if (session.status === 'input_required' || session.activity === 'waiting_input' || hasOpenBlock)

package/dist/lib/overdue.d.ts

@@ -11,6 +11,7 @@
  * Surfaced two ways: a desktop notification on daemon startup, and a
  * `agents routines catchup` command that runs them on demand.
  */
+import { type JobConfig } from './routines.js';
 export interface OverdueJob {
     name: string;
     /** Most recent expected fire time per the cron expression. */
@@ -18,6 +19,19 @@ export interface OverdueJob {
     /** Start time of the most recent recorded run, or null if never run. */
     lastRanAt: Date | null;
 }
+/**
+ * When a routine started existing, and therefore the earliest fire it can
+ * sensibly be judged against.
+ *
+ * `createdAt` is stamped by `writeJob`. Routines written before that field
+ * existed have none, so the file's own mtime stands in — it is the closest
+ * honest answer available on disk, and it only ever moves the floor later,
+ * never earlier, so it cannot manufacture a false "overdue".
+ *
+ * Returns null when neither is available, which leaves the routine unfloored
+ * (previous behaviour) rather than silently skipping it.
+ */
+export declare function routineEffectiveStart(job: JobConfig): Date | null;
 /** Return every enabled, recurring job whose most recent expected fire was
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export declare function detectOverdueJobs(now?: Date): OverdueJob[];

package/dist/lib/overdue.js

@@ -11,8 +11,9 @@
  * Surfaced two ways: a desktop notification on daemon startup, and a
  * `agents routines catchup` command that runs them on demand.
  */
+import * as fs from 'fs';
 import { Cron } from 'croner';
-import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
+import { listJobs, getLatestRun, getJobPath, jobRunsOnThisDevice } from './routines.js';
 import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
@@ -36,6 +37,34 @@ function previousExpectedFire(cron, now) {
     }
     return last;
 }
+/**
+ * When a routine started existing, and therefore the earliest fire it can
+ * sensibly be judged against.
+ *
+ * `createdAt` is stamped by `writeJob`. Routines written before that field
+ * existed have none, so the file's own mtime stands in — it is the closest
+ * honest answer available on disk, and it only ever moves the floor later,
+ * never earlier, so it cannot manufacture a false "overdue".
+ *
+ * Returns null when neither is available, which leaves the routine unfloored
+ * (previous behaviour) rather than silently skipping it.
+ */
+export function routineEffectiveStart(job) {
+    if (job.createdAt) {
+        const stamped = new Date(job.createdAt);
+        if (!isNaN(stamped.getTime()))
+            return stamped;
+    }
+    const path = getJobPath(job.name);
+    if (!path)
+        return null;
+    try {
+        return new Date(fs.statSync(path).mtimeMs);
+    }
+    catch {
+        return null;
+    }
+}
 /** Return every enabled, recurring job whose most recent expected fire was
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export function detectOverdueJobs(now = new Date()) {
@@ -66,6 +95,13 @@ export function detectOverdueJobs(now = new Date()) {
         }
         if (!expected)
             continue;
+        // A fire that predates the routine never could have happened, so it is not
+        // a miss. Without this, any newly created routine on a daily/weekly cron is
+        // instantly "overdue" for the previous occurrence — and with auto-catchup
+        // that means `agents routines add` runs the routine once, immediately.
+        const start = routineEffectiveStart(job);
+        if (start && expected.getTime() < start.getTime())
+            continue;
         const latest = getLatestRun(job.name);
         const lastRanAt = latest ? new Date(latest.startedAt) : null;
         const isOverdue = !lastRanAt || lastRanAt.getTime() < expected.getTime() - GRACE_MS;

package/dist/lib/perf/db.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
+ *
+ * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
+ */
+import Database from '../sqlite.js';
+import type { AggregateOptions, PerfAggregateRow } from './types.js';
+export type { AggregateOptions, PerfAggregateRow, PerfSample } from './types.js';
+export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
+export declare const PERF_SCHEMA_VERSION = 1;
+export declare const DEFAULT_RETENTION_DAYS = 30;
+/** Test seam — redirect the warehouse path (like AGENTS_EVENTS_PATH). */
+export declare function _resetPerfDbForTest(overridePath?: string | null): void;
+/** Drain the NDJSON spool into samples. Idempotent; truncates on success. */
+export declare function drainSpool(db?: Database.Database): number;
+/** Percentile of a sorted-ascending array. p in [0,100]. */
+export declare function percentile(sorted: number[], p: number): number;
+/**
+ * Aggregate samples by (kind, label) with p50/p99. Drains the spool first.
+ */
+export declare function aggregateSamples(opts?: AggregateOptions): PerfAggregateRow[];
+export declare function perfDbPath(): string;
+export declare function perfSpoolPath(): string;
+export declare function ensurePerfDir(): string;

package/dist/lib/perf/db.js

@@ -0,0 +1,290 @@
+/**
+ * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
+ *
+ * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from '../sqlite.js';
+import { getPerfDbPath, getPerfDir } from '../state.js';
+import { localMachineId } from '../session/origin-machine.js';
+import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
+export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
+export const PERF_SCHEMA_VERSION = 1;
+export const DEFAULT_RETENTION_DAYS = 30;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS samples (
+  id INTEGER PRIMARY KEY,
+  ts_ms INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  label TEXT NOT NULL,
+  duration_ms REAL NOT NULL,
+  session_id TEXT,
+  session_short TEXT,
+  agent TEXT,
+  agent_version TEXT,
+  machine TEXT,
+  hostname TEXT,
+  actor TEXT,
+  cwd TEXT,
+  cache TEXT,
+  exit_code INTEGER,
+  status TEXT,
+  meta_json TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_perf_ts ON samples(ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_kind_ts ON samples(kind, ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_label_ts ON samples(label, ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_machine_ts ON samples(machine, ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_session ON samples(session_id);
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+let _db = null;
+let _dbPath = null;
+let _disabled = false;
+/** Test seam — redirect the warehouse path (like AGENTS_EVENTS_PATH). */
+export function _resetPerfDbForTest(overridePath) {
+    if (_db) {
+        try {
+            _db.close();
+        }
+        catch { /* ignore */ }
+    }
+    _db = null;
+    _dbPath = overridePath === undefined ? null : overridePath;
+    _disabled = false;
+    if (overridePath) {
+        _resetPerfSpoolForTest(path.join(path.dirname(overridePath), 'spool.jsonl'));
+    }
+    else if (overridePath === null) {
+        _resetPerfSpoolForTest(null);
+    }
+}
+function resolveDbPath() {
+    return process.env.AGENTS_PERF_DB || _dbPath || getPerfDbPath();
+}
+function isDisabled() {
+    if (_disabled)
+        return true;
+    const v = process.env.AGENTS_DISABLE_PERF;
+    return v === '1' || v === 'true';
+}
+function openDb() {
+    if (isDisabled())
+        return null;
+    const dbPath = resolveDbPath();
+    if (_db && _dbPath === dbPath)
+        return _db;
+    if (_db) {
+        try {
+            _db.close();
+        }
+        catch { /* ignore */ }
+        _db = null;
+    }
+    try {
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true, mode: 0o700 });
+        const db = new Database(dbPath);
+        db.pragma('journal_mode = WAL');
+        db.pragma('synchronous = NORMAL');
+        db.pragma('busy_timeout = 2000');
+        db.exec(SCHEMA);
+        const row = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
+        if (!row) {
+            db.prepare(`INSERT INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(PERF_SCHEMA_VERSION));
+        }
+        _db = db;
+        _dbPath = dbPath;
+        drainSpool(db);
+        maybeRetain(db);
+        return db;
+    }
+    catch {
+        _disabled = true;
+        return null;
+    }
+}
+/** Drain the NDJSON spool into samples. Idempotent; truncates on success. */
+export function drainSpool(db) {
+    const spool = resolveSpoolPath();
+    if (!fs.existsSync(spool))
+        return 0;
+    let raw;
+    try {
+        raw = fs.readFileSync(spool, 'utf-8');
+    }
+    catch {
+        return 0;
+    }
+    if (!raw.trim()) {
+        try {
+            fs.writeFileSync(spool, '');
+        }
+        catch { /* ignore */ }
+        return 0;
+    }
+    const target = db ?? openDb();
+    if (!target)
+        return 0;
+    let n = 0;
+    const insert = target.prepare(`
+    INSERT INTO samples (
+      ts_ms, kind, label, duration_ms,
+      session_id, session_short, agent, agent_version,
+      machine, hostname, actor, cwd,
+      cache, exit_code, status, meta_json
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const txn = target.transaction((lines) => {
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let o;
+            try {
+                o = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const label = String(o.label ?? o.hook ?? '');
+            const durationMs = Number(o.duration_ms ?? o.durationMs ?? o.ms);
+            if (!label || !Number.isFinite(durationMs))
+                continue;
+            const sessionId = o.session_id != null ? String(o.session_id)
+                : o.sessionId != null ? String(o.sessionId) : null;
+            const tsMs = Number(o.ts_ms ?? o.tsMs) || (typeof o.ts === 'string' ? Date.parse(o.ts) : Date.now());
+            insert.run(Number.isFinite(tsMs) ? tsMs : Date.now(), String(o.kind ?? 'hook.fire'), label, durationMs, sessionId, o.session_short != null ? String(o.session_short) : shortSessionId(sessionId) ?? null, o.agent != null ? String(o.agent) : null, o.agent_version != null ? String(o.agent_version) : o.agentVersion != null ? String(o.agentVersion) : null, o.machine != null ? String(o.machine) : localMachineId(), o.hostname != null ? String(o.hostname) : null, o.actor != null ? String(o.actor) : null, o.cwd != null ? String(o.cwd) : null, o.cache != null ? String(o.cache) : null, o.exit_code != null ? Number(o.exit_code) : o.exit != null ? Number(o.exit) : null, o.status != null ? String(o.status) : null, o.meta_json != null ? String(o.meta_json) : null);
+            n++;
+        }
+    });
+    try {
+        txn(raw.split('\n'));
+        fs.writeFileSync(spool, '');
+    }
+    catch {
+        return 0;
+    }
+    return n;
+}
+function maybeRetain(db) {
+    try {
+        const last = db.prepare(`SELECT value FROM meta WHERE key = 'last_retain_ms'`).get();
+        const lastMs = last ? parseInt(last.value, 10) : 0;
+        const now = Date.now();
+        if (now - lastMs < 3_600_000)
+            return;
+        const cutoff = now - DEFAULT_RETENTION_DAYS * 86_400_000;
+        db.prepare(`DELETE FROM samples WHERE ts_ms < ?`).run(cutoff);
+        db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('last_retain_ms', ?)`).run(String(now));
+    }
+    catch {
+        // ignore
+    }
+}
+/** Percentile of a sorted-ascending array. p in [0,100]. */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+/**
+ * Aggregate samples by (kind, label) with p50/p99. Drains the spool first.
+ */
+export function aggregateSamples(opts = {}) {
+    const db = openDb();
+    if (!db)
+        return [];
+    drainSpool(db);
+    const days = opts.days ?? 7;
+    const sinceMs = Date.now() - days * 86_400_000;
+    const minN = opts.minN ?? 1;
+    const clauses = ['ts_ms >= ?'];
+    const params = [sinceMs];
+    if (opts.kinds && opts.kinds.length > 0) {
+        clauses.push(`kind IN (${opts.kinds.map(() => '?').join(',')})`);
+        params.push(...opts.kinds);
+    }
+    if (opts.label) {
+        clauses.push('label = ?');
+        params.push(opts.label);
+    }
+    if (opts.machine) {
+        clauses.push('machine = ?');
+        params.push(opts.machine);
+    }
+    if (opts.agent) {
+        clauses.push('agent = ?');
+        params.push(opts.agent);
+    }
+    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code
+     FROM samples WHERE ${clauses.join(' AND ')}`).all(...params);
+    const map = new Map();
+    for (const r of rows) {
+        const key = `${r.kind}\0${r.label}`;
+        let b = map.get(key);
+        if (!b) {
+            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0 };
+            map.set(key, b);
+        }
+        b.durations.push(Number(r.duration_ms));
+        if (r.cache === 'hit')
+            b.hits++;
+        else if (r.cache === 'stale-prefetch')
+            b.stale++;
+        else if (r.cache === 'miss' || r.cache === 'none')
+            b.misses++;
+        if (typeof r.exit_code === 'number' && r.exit_code !== 0)
+            b.errors++;
+    }
+    const out = [];
+    for (const b of map.values()) {
+        if (b.durations.length < minN)
+            continue;
+        const sorted = b.durations.slice().sort((a, c) => a - c);
+        const n = sorted.length;
+        const sum = sorted.reduce((a, c) => a + c, 0);
+        const row = {
+            kind: b.kind,
+            label: b.label,
+            n,
+            p50Ms: Math.round(percentile(sorted, 50)),
+            p99Ms: Math.round(percentile(sorted, 99)),
+            meanMs: Math.round(sum / n),
+            maxMs: sorted[n - 1],
+            minMs: sorted[0],
+        };
+        if (b.hits + b.stale + b.misses > 0) {
+            row.cacheHitPct = Math.round((b.hits / n) * 100);
+            row.cacheStalePct = Math.round((b.stale / n) * 100);
+            row.cacheMissPct = Math.round((b.misses / n) * 100);
+        }
+        if (b.errors > 0)
+            row.errorCount = b.errors;
+        out.push(row);
+    }
+    out.sort((a, b) => b.p99Ms - a.p99Ms);
+    return out;
+}
+export function perfDbPath() {
+    return resolveDbPath();
+}
+export function perfSpoolPath() {
+    return resolveSpoolPath();
+}
+export function ensurePerfDir() {
+    const dir = process.env.AGENTS_PERF_DIR || (_dbPath ? path.dirname(_dbPath) : getPerfDir());
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}

package/dist/lib/perf/spool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hot-path perf writers — append-only NDJSON spool, no SQLite.
+ *
+ * Loaded from the CLI root `postAction` and from `events.ts` timing helpers.
+ * Must stay free of `../sqlite.js` so ordinary commands never load node:sqlite
+ * (which emits ExperimentalWarning on stderr).
+ */
+import type { PerfSample } from './types.js';
+export type { PerfSample } from './types.js';
+/** Test seam — pair with db._resetPerfDbForTest. */
+export declare function _resetPerfSpoolForTest(spoolPath?: string | null): void;
+export declare function resolveSpoolPath(): string;
+/** Short session id: first 8 chars (sessions.short_id shape). */
+export declare function shortSessionId(sessionId: string | undefined | null): string | undefined;
+/**
+ * Append one sample to the spool. Never throws. Never opens SQLite.
+ */
+export declare function recordSample(sample: PerfSample): void;

package/dist/lib/perf/spool.js

@@ -0,0 +1,79 @@
+/**
+ * Hot-path perf writers — append-only NDJSON spool, no SQLite.
+ *
+ * Loaded from the CLI root `postAction` and from `events.ts` timing helpers.
+ * Must stay free of `../sqlite.js` so ordinary commands never load node:sqlite
+ * (which emits ExperimentalWarning on stderr).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getPerfSpoolPath } from '../state.js';
+import { localMachineId } from '../session/origin-machine.js';
+let _spoolOverride = null;
+let _disabled = false;
+/** Test seam — pair with db._resetPerfDbForTest. */
+export function _resetPerfSpoolForTest(spoolPath) {
+    _spoolOverride = spoolPath === undefined ? null : spoolPath;
+    _disabled = false;
+}
+export function resolveSpoolPath() {
+    if (process.env.AGENTS_PERF_SPOOL)
+        return process.env.AGENTS_PERF_SPOOL;
+    if (_spoolOverride)
+        return _spoolOverride;
+    return getPerfSpoolPath();
+}
+function isDisabled() {
+    if (_disabled)
+        return true;
+    const v = process.env.AGENTS_DISABLE_PERF;
+    return v === '1' || v === 'true';
+}
+/** Short session id: first 8 chars (sessions.short_id shape). */
+export function shortSessionId(sessionId) {
+    if (!sessionId)
+        return undefined;
+    const cleaned = sessionId.replace(/^session_/, '');
+    return cleaned.length >= 8 ? cleaned.slice(0, 8) : cleaned || undefined;
+}
+/**
+ * Append one sample to the spool. Never throws. Never opens SQLite.
+ */
+export function recordSample(sample) {
+    if (isDisabled())
+        return;
+    if (!sample.label || !Number.isFinite(sample.durationMs))
+        return;
+    try {
+        const tsMs = sample.tsMs ?? Date.now();
+        const sessionId = sample.sessionId;
+        const sessionShort = sample.sessionShort ?? shortSessionId(sessionId);
+        const machine = sample.machine ?? localMachineId();
+        const hostname = sample.hostname ?? os.hostname();
+        const line = JSON.stringify({
+            ts_ms: tsMs,
+            kind: sample.kind,
+            label: sample.label,
+            duration_ms: sample.durationMs,
+            session_id: sessionId,
+            session_short: sessionShort,
+            agent: sample.agent,
+            agent_version: sample.agentVersion,
+            machine,
+            hostname,
+            actor: sample.actor,
+            cwd: sample.cwd,
+            cache: sample.cache,
+            exit_code: sample.exitCode,
+            status: sample.status,
+            meta_json: sample.metaJson,
+        });
+        const spool = resolveSpoolPath();
+        fs.mkdirSync(path.dirname(spool), { recursive: true, mode: 0o700 });
+        fs.appendFileSync(spool, line + '\n', { mode: 0o600 });
+    }
+    catch {
+        // Fail soft.
+    }
+}

package/dist/lib/perf/types.d.ts

@@ -0,0 +1,45 @@
+/** Shared perf sample shape (spool NDJSON + SQLite rows). */
+export type PerfKind = 'hook.fire' | 'perf.timing' | 'command.end' | string;
+export interface PerfSample {
+    tsMs?: number;
+    kind: PerfKind;
+    label: string;
+    durationMs: number;
+    /** Full session id — same string as sessions.id when known. */
+    sessionId?: string;
+    /** First 8 chars of sessionId (sessions.short_id shape). */
+    sessionShort?: string;
+    agent?: string;
+    agentVersion?: string;
+    /** Fleet registry name (sessions.machine), preferred over raw hostname. */
+    machine?: string;
+    hostname?: string;
+    actor?: string;
+    cwd?: string;
+    cache?: string;
+    exitCode?: number;
+    status?: string;
+    metaJson?: string;
+}
+export interface PerfAggregateRow {
+    kind: string;
+    label: string;
+    n: number;
+    p50Ms: number;
+    p99Ms: number;
+    meanMs: number;
+    maxMs: number;
+    minMs: number;
+    cacheHitPct?: number;
+    cacheStalePct?: number;
+    cacheMissPct?: number;
+    errorCount?: number;
+}
+export interface AggregateOptions {
+    days?: number;
+    kinds?: string[];
+    label?: string;
+    machine?: string;
+    agent?: string;
+    minN?: number;
+}

package/dist/lib/perf/types.js

@@ -0,0 +1,2 @@
+/** Shared perf sample shape (spool NDJSON + SQLite rows). */
+export {};

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;