dsh-ssh-tui 0.6.4 → 0.7.0-rc.2

package/lib/types/approval-cache.d.ts

@@ -0,0 +1,125 @@
+/**
+ * A TTL cache for approval verdicts the AI reviewer already produced.
+ *
+ * `/approval auto` hands every shape the rule table cannot judge to a
+ * subagent-configured model: one `llm.stream` call, up to 15 seconds, and the
+ * user's quota. The same shape repeats inside one session — `pytest -q`,
+ * `npm install`, `docker compose up` — and each repeat paid the full review
+ * again. This module remembers a verdict for a bounded time so an identical
+ * request is decided from the cache.
+ *
+ * Two rules keep that safe, and both are structural rather than heuristic:
+ *
+ * 1. Only requests the classifier marked `ask` are ever looked up or stored.
+ *    Rule allows and denials are free, and `DANGER_PATTERNS` returns before the
+ *    cache is consulted at all, so a remembered verdict can never widen what
+ *    the rule table refuses.
+ * 2. The key is an exact identity, not a prefix: the tool, the canonical
+ *    command, its raw arguments, the sandbox mode, the workspace, the locale,
+ *    the reviewer that produced the verdict, and a fingerprint of the user
+ *    message that authorized it. A verdict handed out while `npm publish` was
+ *    authorized never answers `npm publish --tag next`, and an escalation
+ *    justified in one message is not replayed for the next one.
+ *
+ * Opaque interpreter payloads (`bash -c`, `python -e`) are excluded on purpose:
+ * the review result there depends entirely on a script the key cannot see.
+ * @module dsh-ssh-tui/approval-cache
+ */
+import type { ReviewVerdict } from './approval-reviewer.js';
+/** How long one remembered verdict stays usable. */
+export declare const DEFAULT_VERDICT_TTL_MS: number;
+/** How many verdicts are remembered at once; the least recently used go first. */
+export declare const DEFAULT_VERDICT_CAPACITY = 32;
+/**
+ * Everything the reviewer's verdict actually depends on.
+ *
+ * `args` and `authorization` are load-bearing: the `workspace-write` escalation
+ * is allowed purely because the model read a justification out of the request,
+ * and `latestUserAuthorizationText` is what the reviewer weighs when it decides
+ * whether the user asked for this. Dropping either would let one authorization
+ * cover a later, different call.
+ */
+export interface VerdictKeyInput {
+    toolName: string;
+    command: string;
+    args?: string | undefined;
+    reason?: string | undefined;
+    sandboxMode?: string | undefined;
+    /** The agent the request came from: a subagent's authorization is its own. */
+    agentId: string;
+    workspaceCwd: string;
+    locale: string;
+    /** The model that produced the verdict; a different reviewer may differ. */
+    reviewer: {
+        provider: string;
+        model: string;
+    };
+    /** One-way fingerprint of the user message that authorized the request. */
+    authorization: string;
+}
+/** Whitespace-insensitive form of a command, so spacing alone cannot miss. */
+export declare function canonicalCommand(command: string): string;
+/**
+ * Whether a verdict for this request may be remembered.
+ *
+ * A request without a command has nothing to key on, and an interpreter
+ * wrapper hides its payload behind `-c`/`-e`, so its review says nothing about
+ * the next invocation of the same wrapper.
+ * @param input - the identity a verdict would be stored under.
+ * @returns whether the cache may serve and store this shape.
+ */
+export declare function cacheableShape(input: VerdictKeyInput): boolean;
+/**
+ * The cache key for one reviewed request.
+ * @param input - the identity a verdict would be stored under.
+ * @returns a stable, collision-resistant digest.
+ */
+export declare function verdictKey(input: VerdictKeyInput): string;
+export interface CachedVerdict {
+    verdict: ReviewVerdict;
+    storedAt: number;
+}
+/**
+ * A bounded, time-limited map from a reviewed request to its verdict.
+ *
+ * Both limits are injectable so tests can drive the clock instead of sleeping.
+ * The instance is per TUI: a fresh session starts with an empty cache, and
+ * nothing is written to disk.
+ */
+export declare class ApprovalVerdictCache {
+    private readonly options;
+    private readonly entries;
+    private hitCount;
+    constructor(options?: {
+        ttlMs?: number;
+        capacity?: number;
+        now?: () => number;
+    });
+    private get ttlMs();
+    private get capacity();
+    private get now();
+    /**
+     * The remembered verdict for a key, if it is still inside its TTL.
+     * @param key - {@link verdictKey} of the request being decided.
+     * @returns the verdict and its age, or `undefined` for a miss or an expiry.
+     */
+    lookup(key: string): {
+        verdict: ReviewVerdict;
+        ageMs: number;
+    } | undefined;
+    /**
+     * Remember one reviewed verdict, evicting the least recently used entry past
+     * the capacity.
+     * @param key - {@link verdictKey} of the reviewed request.
+     * @param verdict - what the reviewer concluded.
+     */
+    store(key: string, verdict: ReviewVerdict): void;
+    /** Drop every remembered verdict; returns how many were held. */
+    clear(): number;
+    /** How many verdicts are held right now. */
+    get size(): number;
+    /** How many lookups were served from the cache over this instance's life. */
+    get hits(): number;
+    /** The TTL as whole minutes, for the status line. */
+    get ttlMinutes(): number;
+}

package/lib/types/attach.d.ts

@@ -22,6 +22,26 @@ export declare const RECOVERY_BURST_WINDOW_MS = 10000;
 export declare const RECOVERY_BURST_LIMIT = 3;
 /** How long to wait for a freshly spawned Host to accept on its channel. */
 export declare const HOST_START_TIMEOUT_MS = 15000;
+/**
+ * Waits between the automatic re-attach attempts of one run.
+ *
+ * A single retry was not enough for a link that flaps for half a minute: the
+ * burst breaker cut the run at three tries inside ten seconds and told the user
+ * to come back later, when one more try would have caught the link. One run now
+ * backs off — 250ms, 500ms, 1s, 2s, 4s — and only then gives up; the breaker
+ * still stops *runs* from fighting each other, which is what it was for.
+ */
+export declare const RECOVERY_BACKOFF_MS: readonly [250, 500, 1000, 2000, 4000];
+/**
+ * How long to wait before attempt `attempt` (0-based), with jitter.
+ *
+ * Two windows that drop together must not retry in lockstep, so each wait is
+ * taken from the upper half of its base: 0.5–1× the nominal delay.
+ * @param attempt - 0 for the first retry after the initial failure.
+ * @param random - injectable for tests.
+ * @returns milliseconds to wait.
+ */
+export declare function recoveryDelay(attempt: number, random?: () => number): number;
 /** True when a relay error means the peer vanished rather than a real fault. */
 export declare function attachPeerVanished(error: unknown, elapsedMs: number): boolean;
 export interface LiveHost {
@@ -86,6 +106,15 @@ export interface AttacherDeps {
         windowMs?: number;
         limit?: number;
     };
+    /** Override the backoff schedule (tests); defaults to {@link RECOVERY_BACKOFF_MS}. */
+    backoff?: readonly number[];
+    /** Jitter source for {@link recoveryDelay} (tests). */
+    random?: () => number;
+    /** One run recovered after at least one retry; the Host side reports it. */
+    onReconnected?(info: {
+        attempts: number;
+        elapsedMs: number;
+    }): void;
 }
 export interface Attacher {
     /**

package/lib/types/auto-approval.d.ts

@@ -47,6 +47,17 @@ export declare function touchesSensitivePath(text: string): boolean;
  * pattern — unknown shapes ask (and detach to a rejection when unattended).
  */
 export declare function classifyCommand(command: string): ApprovalDecision;
+/**
+ * Whether a command is an opaque interpreter payload (`bash -c …`, `python -e …`).
+ *
+ * The rule table asks about these instead of denying them (a quoted `rm -rf`
+ * must not match `DANGER_PATTERNS`), and the AI reviewer judges the script it is
+ * shown — so its verdict says nothing about the next invocation of the same
+ * wrapper. The approval cache uses this to refuse to remember them.
+ * @param command - the command string a request carried.
+ * @returns whether the payload, not the command line, decides the risk.
+ */
+export declare function isOpaqueInterpreterCommand(command: string): boolean;
 export declare function classifyCommandDetailed(command: string): ClassifiedApproval;
 export interface ClassifyApprovalInput {
     toolName: string;

package/lib/types/color-depth.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How much colour the terminal can take, and what to do when it cannot take
+ * what a caller asked for.
+ *
+ * A truecolor pair (`38;2;…`) on an 8-colour terminal is not a cosmetic loss: a
+ * terminal that does not understand it either ignores the sequence or renders
+ * the row in the wrong colour, and the diff rows are the ones that suffer. The
+ * palette is downgraded here instead, by hue family rather than by nearest RGB
+ * distance — the diff colours are deliberately muted, and nearest-RGB maps them
+ * to grey, which throws away the only signal they carry. Status is never colour
+ * alone in this TUI (a `+`/`-`/`●`/`⚠`/`✖` is always present), so a downgraded
+ * palette stays readable.
+ * @module dsh-ssh-tui/color-depth
+ */
+/** What the terminal advertised, or what the user forced. */
+export type ColorDepth = 'truecolor' | '256' | '8' | 'none';
+/**
+ * Decide the palette from the environment.
+ *
+ * `DSH_TUI_COLOR_DEPTH` wins outright so a user can correct a wrong guess.
+ * Otherwise: no colour at all when `NO_COLOR` is set or `TERM` names a
+ * monochrome terminal; truecolor when `COLORTERM` says so; 256 for a
+ * `*256color` terminal and for tmux/screen (their default palette is 256 and
+ * they translate truecolor poorly); 8 for everything else.
+ * @param env - the environment to read (tests pass their own).
+ * @returns the palette to paint with.
+ */
+export declare function colorDepth(env?: NodeJS.ProcessEnv): ColorDepth;
+/** The xterm 256-colour cube index back to RGB. */
+export declare function rgbFrom256(index: number): [number, number, number];
+/**
+ * The nearest standard colour, by hue family.
+ *
+ * Brightness picks the bright half of the palette; a colour whose channels are
+ * nearly equal becomes a grey. Everything else keeps its hue, so a muted green
+ * stays green instead of collapsing to grey the way nearest-RGB would leave it.
+ */
+export declare function basicSgrFor(r: number, g: number, b: number): number;
+/**
+ * Rewrite one SGR parameter list for the palette in use.
+ *
+ * Attributes (bold, dim, italic, underline, reverse) always survive: they are
+ * what carries meaning when colour cannot. Colour parameters are dropped at
+ * `none`, mapped to the standard 16 at `8`, and mapped into the 256-cube at
+ * `256`.
+ * @param code - the parameter list, e.g. `1;38;2;77;107;253`.
+ * @param depth - the palette to rewrite for.
+ * @returns the parameter list to emit, possibly empty.
+ */
+export declare function downgradeSgr(code: string, depth: ColorDepth): string;

package/lib/types/commands.d.ts

@@ -75,6 +75,15 @@ export declare const LOCAL_COMMANDS: readonly [{
     readonly name: "lang";
     readonly key: "cmd.language";
     readonly aliasOf: "language";
+}, {
+    readonly name: "doctor";
+    readonly key: "cmd.doctor";
+}, {
+    readonly name: "fix";
+    readonly key: "cmd.fix";
+}, {
+    readonly name: "preset";
+    readonly key: "cmd.preset";
 }, {
     readonly name: "dialog-test";
     readonly key: "cmd.dialog-test";

package/lib/types/dialogs.d.ts

@@ -22,6 +22,21 @@ export interface QuestionDialog {
     total: number;
     selected: Set<number>;
     cursor: number;
+    /**
+     * The typed filter, once the user pressed `/`. Letters and digits are the
+     * list's hotkeys, so filtering is entered explicitly instead of hijacking
+     * every keystroke — the two would otherwise fight over the same keys.
+     */
+    filter?: string;
+    /** True while the filter is being typed; Enter applies it, Esc clears it. */
+    filtering?: boolean;
+    /**
+     * Machine names for the options, indexed like `question.options`. The option
+     * shape belongs to the questions package and carries only display text, so a
+     * preset id would otherwise be unmatchable — and `routing-suite` is exactly
+     * what a user types to find it.
+     */
+    matchKeys?: readonly string[];
     resolve(selection: {
         selected: string[];
         custom?: string;
@@ -51,6 +66,21 @@ export declare function optionsLength(dialog: Dialog): number;
  * the painted keys or names no option.
  */
 export declare function questionOptionIndex(key: string, optionCount: number): number | undefined;
+/**
+ * The option indexes the current filter leaves visible, in list order.
+ *
+ * An empty or absent filter keeps everything. The match is the same shape the
+ * pickers use: the label or the description, case-insensitively.
+ */
+export declare function visibleQuestionIndexes(dialog: QuestionDialog): number[];
+/** Append a typed character to the filter (filter mode only). */
+export declare function typeQuestionFilter(dialog: QuestionDialog, text: string): boolean;
+/** Remove the last character of the filter; the caller exits when it is empty. */
+export declare function backspaceQuestionFilter(dialog: QuestionDialog): boolean;
+/** Leave filter mode, keeping whatever was typed (Enter applies it). */
+export declare function applyQuestionFilter(dialog: QuestionDialog): void;
+/** Leave filter mode and show the whole list again (Esc clears it). */
+export declare function clearQuestionFilter(dialog: QuestionDialog): void;
 /** Move the question highlight, clamped to its options. Returns false if not a question dialog. */
 export declare function moveQuestionCursor(dialog: QuestionDialog, delta: number): boolean;
 /** Select option `index`: toggles in a multi-select list, replaces otherwise. */
@@ -67,11 +97,12 @@ export type QuestionSubmit = {
     kind: 'none';
 };
 /**
- * What Enter means for a question dialog. A single-select list answers with the
- * option its highlight sits on: the list opens on the first option, so Enter
- * without arrowing answers that default instead of cancelling, and Esc stays the
- * explicit cancel. A multi-select list may answer with an empty selection. With
- * no options at all, the typed text is the answer.
+ * What Enter means for a question dialog. Enter never answers with nothing: the
+ * list opens on the first option, and that highlight is the answer for a
+ * single-select list and a multi-select one alike — pressing Enter without
+ * touching anything returns the option under the cursor, and Esc stays the
+ * explicit cancel. Space (or a digit/letter) still builds a multi-select set,
+ * and a list with no options at all answers with the typed text.
  */
 export declare function questionSubmit(dialog: QuestionDialog, input: string): QuestionSubmit;
 /** y/n/ctrl-c/esc answers for a confirm prompt. */

package/lib/types/display-sock.d.ts

@@ -115,6 +115,12 @@ export interface HostExitWatch {
     /** Stop watching; call once the channel is confirmed up. */
     dispose(): void;
 }
+/**
+ * How long a dead-pid report waits for the child's `exit` event before giving
+ * up on its code. The event is normally delivered within a tick; the bound only
+ * exists so a host that never reports still fails fast.
+ */
+export declare const HOST_EXIT_GRACE_MS = 250;
 export declare function waitForDisplaySock(path: string, timeoutMs?: number, pid?: number, errFile?: string, exitWatch?: HostExitWatch): Promise<void>;
 export declare function hostArgvForSession(sessionId: string, argv?: string[], execArgv?: string[]): string[];
 export interface SpawnedHost {

package/lib/types/doctor.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `/doctor`: one pass over the deployment's composition, dependencies, and
+ * compatibility, each verdict carrying the row, line, or path behind it.
+ *
+ * `/diag` answers "why can't I get in?" about one session's channel, lock, and
+ * Host. `/doctor` answers the other half — "is this install composed the way
+ * the plugin needs?" — which is where 0.6.3's regression lived: 0.5.1 dropped
+ * the roster rows to pass a store check, and the only symptom was `/mode`
+ * reporting a missing service months later. Every check therefore reports the
+ * concrete row (with its line) or path, plus the command that acts on it.
+ *
+ * The verdicts are a pure function of collected facts, so they are testable
+ * without a Host, a profile, or a filesystem; collection lives in
+ * `collectDoctor` and every probe is best-effort. Nothing leaves the machine.
+ * @module dsh-ssh-tui/doctor
+ */
+import { type PatchAnalysis, type PatchRowRef, type RosterRow } from './preset-rows.js';
+export type DoctorStatus = 'ok' | 'warn' | 'fail';
+export interface DoctorCheck {
+    id: string;
+    status: DoctorStatus;
+    /** One line: the conclusion. */
+    summary: string;
+    /** The rows, lines, and paths behind the conclusion. */
+    details: string[];
+    /** Whether `/doctor --fix` (or `/fix <row>`) can act on this check. */
+    fixable?: boolean;
+}
+/** One route's model list, for the routing self-consistency check. */
+export interface DoctorRouting {
+    provider?: string;
+    model?: string;
+    /** Every provider id the llm-pi-ai section configures. */
+    routes: readonly string[];
+    /** Model ids the selected provider's route lists. */
+    routeModels: readonly string[];
+    subProvider?: string;
+    subModel?: string;
+}
+export interface DoctorFacts {
+    pluginVersion: string;
+    hostVersion: string;
+    nodeVersion: string;
+    profile: string;
+    dshHome: string;
+    patchPath: string;
+    /** Services the running composition actually registered. */
+    services: {
+        /** `agentPresets` — the roster `/mode` lists. */
+        roster: boolean;
+        /** `codeRuntime` — what the PTC preset mounts. */
+        codeRuntime: boolean;
+    };
+    /** The profile patch. `readable` is false when it does not exist yet. */
+    patch: {
+        readable: boolean;
+        text: string;
+        analysis: PatchAnalysis;
+    };
+    /** Rows the plugin's own bundle patch mounts. */
+    bundleRows: readonly PatchRowRef[];
+    /** The manifest's compatibility declaration, when the package is readable. */
+    compatibility?: {
+        range?: string;
+        releases: Record<string, string>;
+    };
+    /** Distinct installs of `@deepseek-ai/dsh-scope` found from the anchors. */
+    scopeCopies: readonly string[];
+    /** Absent when routing could not be read (no settings service). */
+    routing?: DoctorRouting;
+}
+/**
+ * Every check, in report order. Pure: same facts in, same verdicts out.
+ * @param facts - one collected snapshot.
+ * @returns the checks, each with its conclusion and evidence.
+ */
+export declare function doctorChecks(facts: DoctorFacts): DoctorCheck[];
+/** The whole report as transcript lines. Pure. */
+export declare function formatDoctorReport(facts: DoctorFacts, checks: readonly DoctorCheck[]): string[];
+/**
+ * Distinct installs of `@deepseek-ai/dsh-scope` reachable from the anchors.
+ *
+ * Anchors are the running CLI entry and the plugin's module base, the same two
+ * the provider catalog walks: a nested npm install puts a second copy under one
+ * of them, and preset composition then fails with "refusing to compose an
+ * unscoped context".
+ * @param anchors - file or directory paths that plausibly sit inside the install.
+ * @returns real paths, deduplicated; empty when none was found.
+ */
+export declare function findScopeCopies(anchors: ReadonlyArray<string | undefined>): string[];
+/**
+ * Gather one snapshot. Every probe is best-effort: a failure is reported by the
+ * check that needed it, never thrown.
+ * @param options - identity, services, and the already-read routing facts.
+ * @returns the facts {@link doctorChecks} turns into verdicts.
+ */
+export declare function collectDoctor(options: {
+    profile: string;
+    dshHome: string;
+    hostVersion: string;
+    services: DoctorFacts['services'];
+    anchors: ReadonlyArray<string | undefined>;
+    routing?: DoctorRouting;
+}): Promise<DoctorFacts>;
+/** Rows `/doctor --fix` would mount, given the services the composition registered. */
+export declare function rowsToRepair(facts: DoctorFacts): RosterRow[];
+/**
+ * What to tell a user whose boot died on the module-copy trap.
+ *
+ * `/doctor` cannot answer this one: the composition fails before the TUI exists,
+ * so the launcher's own failure report is the only place the hint can land. The
+ * signature is `agent-presets` refusing an unscoped context, which happens when
+ * the plugin and the host resolve different `@deepseek-ai/dsh-scope` instances
+ * (a profile that links the plugin into a checkout is the usual shape).
+ * @param detail - the host failure text the launcher is about to print.
+ * @returns the hint, or `undefined` for every other failure.
+ */
+export declare function copyTrapHint(detail: string): string | undefined;

package/lib/types/footer.d.ts

@@ -44,6 +44,8 @@ export declare function contextPressureView(sample: ContextPressureSample): Cont
  */
 export declare const CONTEXT_RING_EMPTY = "\u28C0";
 export declare const CONTEXT_RING_SEGMENTS: readonly ["⣀", "⠉", "⠋", "⠛", "⠞", "⠟", "⠿", "⡿", "⣿"];
+/** The full cell of the same Braille family, for bars built like the ring. */
+export declare const CONTEXT_RING_FULL = "\u28FF";
 export declare function formatContextPressureRing(percent: number): string;
 export declare function contextPressureRingColor(level: ContextPressureView['level']): string;
 export declare function formatContextPressureChip(view: ContextPressureView, color?: boolean): string;
@@ -70,6 +72,39 @@ export interface FooterStatsInput {
 }
 /** Stats groups in drop order (last is dropped first when the row is too wide). */
 export declare function footerStatsGroups(stats: FooterStatsInput): string[];
+/**
+ * One group in the status strip, with the graphic-only form a narrow terminal
+ * keeps. `priority` orders the losses: 0 is the last thing to go.
+ */
+export interface FooterChip {
+    id: string;
+    /** Glyph plus text: what a wide terminal shows. */
+    long: string;
+    /** Glyph only, or `''` for a group that is pure text. */
+    short: string;
+    priority: number;
+}
+/**
+ * Fit an ordered strip into `width` cells, losing text before graphics.
+ *
+ * The old fitter dropped whole groups from the end, so a narrow terminal lost
+ * the ⚠ and the context ring — the two signals that say something is wrong —
+ * while keeping long numeric groups. Two passes now: every chip trades its text
+ * for its glyph in reverse priority order, and only then do whole groups go,
+ * again lowest priority first. The result never exceeds the width.
+ *
+ * Chips may carry SGR accents (the link pips, the ⚠) and the caller may pass a
+ * styled separator, so both the measurement and the final cut are ANSI-aware:
+ * feeding styled text to a plain-text truncator strips the accent's `ESC` and
+ * leaves its `[32m` body on the grid.
+ */
+export declare function fitFooterChips(chips: readonly FooterChip[], width: number, separator?: string): string;
+/**
+ * The roster's health as a chip: absent means `/mode` cannot switch presets and
+ * the preset-owned tools are missing. It leads the strip and keeps its glyph
+ * longest, because it is the one group that reports a broken install.
+ */
+export declare function footerHealthChip(missing: boolean, color?: boolean): FooterChip | undefined;
 export declare function fitFooterStatsLine(chip: string, groups: readonly string[], width: number): string;
 export type FooterActivityKind = 'plan-review' | 'waiting' | 'compacting' | 'retry' | 'subagents' | 'tools' | 'plan-open' | 'plan-pending' | 'goal' | 'waiting-llm' | 'idle';
 export interface FooterStatusInput {

package/lib/types/keymap.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Rebindable keys: a small set of high-frequency actions, and the rules for
+ * applying a user's overrides without breaking the defaults.
+ *
+ * The TUI dispatches on raw byte sequences (`\x1b[5~` for PageUp, `\x1b` for
+ * Esc), which is fine until someone's terminal sends something else for a key,
+ * or their hands want the action elsewhere. Only actions are rebindable — never
+ * arbitrary bytes — so a typo cannot invent a key that does nothing, and a key
+ * that two actions claim is refused rather than silently winning by order.
+ * @module dsh-ssh-tui/keymap
+ */
+/** The actions a user may move. */
+export type KeyAction = 'pageUp' | 'pageDown' | 'toggleCard' | 'copy' | 'cancel';
+/** Every action, in the order reports list them. */
+export declare const KEY_ACTIONS: readonly KeyAction[];
+/** The key each action answers to out of the box. */
+export declare const DEFAULT_KEYMAP: Readonly<Record<KeyAction, string>>;
+/**
+ * The bytes one key name stands for, or undefined when the name means nothing.
+ *
+ * Accepts the named keys above, `ctrl+<letter>`, and a single character.
+ * @param name - the name from the config or the default table.
+ * @returns the sequence, or undefined for an unknown name.
+ */
+export declare function keySequence(name: string): string | undefined;
+/** What a config's `keys` section asked for, and what was wrong with it. */
+export interface ResolvedKeymap {
+    /** Sequence to action, for the keys that survived. */
+    sequences: Map<string, KeyAction>;
+    /** Names the config used that no action has. */
+    unknownActions: string[];
+    /** Keys the config asked for that are not keys this TUI knows. */
+    unknownKeys: string[];
+    /** Keys two actions claim; the first (default order) keeps it. */
+    conflicts: Array<{
+        key: string;
+        actions: KeyAction[];
+    }>;
+    /**
+     * Actions the config actually moved. Only these are dispatched through the
+     * keymap, so a key the user did not touch keeps the handling it always had —
+     * Enter in the input box still submits, Esc still closes a dialog.
+     */
+    overridden: Set<KeyAction>;
+    /**
+     * Sequences that used to be a default and are now unclaimed. Pressing one
+     * does nothing instead of falling through to the old hard-coded branch.
+     */
+    suppressed: Set<string>;
+}
+/**
+ * Apply a user's overrides to the defaults.
+ *
+ * Order matters and is deliberate: the defaults are laid down first, then the
+ * overrides in {@link KEY_ACTIONS} order. A key that ends up claimed twice is
+ * removed from the map and reported, so neither action surprises the other —
+ * the user is told, and pressing that key does nothing rather than the wrong
+ * thing. An action whose override is unusable keeps its default.
+ * @param overrides - the config's `keys` section, action to key name.
+ * @returns the keymap, plus what to tell the user about it.
+ */
+export declare function resolveKeymap(overrides?: Readonly<Record<string, unknown>>): ResolvedKeymap;
+/**
+ * One line describing what was wrong with a config's keys, or undefined when
+ * there is nothing to say. Silent acceptance is how a user ends up pressing a
+ * key that does nothing and blaming the TUI.
+ */
+export declare function keymapReport(resolved: ResolvedKeymap): string | undefined;