dsh-ssh-tui 0.7.4 → 0.8.1

package/lib/types/attach.d.ts

@@ -88,7 +88,9 @@ export interface AttacherDeps {
     /** Stop capturing and return the typing ('' when unsupported). */
     endCapture?(): string;
     inspectLiveHost(sessionId: string): Promise<LiveHost | undefined>;
-    spawnHost(sessionId: string): SpawnedDisplayHost;
+    spawnHost(sessionId: string, options?: {
+        ambiguousWide?: boolean;
+    }): SpawnedDisplayHost;
     waitForDisplaySock(spawned: SpawnedDisplayHost): Promise<void>;
     /**
      * One already-formatted status line for stderr. `transient` marks a line the
@@ -136,7 +138,9 @@ export interface Attacher {
         seed?: string;
     }): Promise<void>;
     /** Attach to a live Host on this session, or spawn a fresh one and attach. */
-    attachOrSpawn(sessionId: string, recover?: boolean): Promise<void>;
+    attachOrSpawn(sessionId: string, recover?: boolean, options?: {
+        ambiguousWide?: boolean;
+    }): Promise<void>;
     /** Recoveries recorded in the current burst window (tests). */
     readonly recoveries: number;
 }

package/lib/types/auth-failure.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Two failure classes that look alike in the transcript and need different fixes.
+ *
+ * 1. **Authentication** — `code: "AUTH"`, and the message says which side said
+ *    no (below).
+ * 2. **Reasoning replay** — a 400 from a thinking-mode gateway that wants the
+ *    previous turn's reasoning passed back; the harness drops it when it rebuilds
+ *    a long multi-turn history. Reported upstream (deepseek-harness #1780, #231),
+ *    so the advice is a workaround, not a fix.
+ *
+ * Where an authentication failure came from.
+ *
+ * A turn can die with `code: "AUTH"` for two very different reasons, and the
+ * difference decides what the reader should do:
+ *
+ *  - **provider**: the request left the machine and the provider (or something
+ *    between it and the model) rejected it. The local credential is present, so
+ *    changing it is the wrong move — the usual causes are a transient upstream
+ *    failure, a plan/quota limit, or a model the account may not call. Retrying
+ *    is reasonable.
+ *  - **local**: nothing usable is configured on this machine, so every request
+ *    would fail the same way. Retrying changes nothing; the key has to be set.
+ *
+ * The host reports both as `AUTH`, and the only place the difference survives is
+ * the message body — which is why this is a text classifier and why it is kept
+ * pure: the caller resolves the actual credential and decides what to say.
+ *
+ * Observed bodies (2026-09-29, command-code):
+ *   provider → `OpenAI API error (403): {"message":"Authentication failed.
+ *               Please check your credentials.","type":"permission_error"}`
+ *   provider → `403 {"type":"error","error":{"type":"permission_error",
+ *               "message":"MODEL_NOT_IN_PLAN: …"}}`
+ *   local    → `dsh-llm: no API key for provider "x" (set X_API_KEY)`
+ * A *missing* credential on that gateway answered with a 401 and its own
+ * envelope (`{"success":false,"error":{"code":"UNAUTHORIZED"}}`), which is why
+ * an HTTP status alone cannot classify this: 401 and 403 both appear on the
+ * provider side.
+ *
+ * @module dsh-ssh-tui/auth-failure
+ */
+/** Which side rejected the request. */
+export type AuthFailureOrigin = 'provider' | 'local';
+export interface AuthFailure {
+    origin: AuthFailureOrigin;
+    /** The HTTP status, when the message carried one. */
+    status?: number;
+}
+/** The HTTP status inside a host-formatted failure, if there is one. */
+export declare function statusOf(message: string): number | undefined;
+/**
+ * Classify one failure message.
+ * @param message - the failure text the host attached to the turn.
+ * @returns the origin (and status when known), or undefined when the message
+ *   says nothing about authentication — an unrelated failure keeps its own row
+ *   and gets no advice.
+ */
+export declare function classifyAuthFailure(message: string): AuthFailure | undefined;
+/**
+ * A thinking-mode gateway refusing a follow-up because the reasoning is missing.
+ *
+ * Seen on the 0.2.0-rc line with the command-code route and `effort: max`
+ * (five times in one long session, always on a *continuation*, never on the
+ * first request of a turn):
+ *
+ *     {"type":"invalid_request_error","code":"invalid_request_error",
+ *      "message":"The `reasoning_text` in the thinking mode must be passed back
+ *                 to the API."}
+ *
+ * Both a live probe and the upstream reports agree on the shape: the client is
+ * expected to send the previous assistant turn's reasoning items back, and the
+ * harness does not do that once a session grows long. Nothing the reader can do
+ * fixes the client, but two workarounds exist — no thinking on that route, or
+ * the same gateway's Anthropic-flavoured route, which carries signed thinking
+ * blocks the harness does replay.
+ * @param message - the failure text the host attached to the turn.
+ * @returns true when this is that failure.
+ */
+export declare function isReasoningReplayFailure(message: string): boolean;

package/lib/types/commands.d.ts

@@ -39,6 +39,15 @@ export declare const LOCAL_COMMANDS: readonly [{
 }, {
     readonly name: "disconnect";
     readonly key: "cmd.disconnect";
+}, {
+    readonly name: "retryauth";
+    readonly key: "cmd.retryauth";
+}, {
+    readonly name: "theme";
+    readonly key: "cmd.theme";
+}, {
+    readonly name: "cleanup";
+    readonly key: "cmd.cleanup";
 }, {
     readonly name: "notify";
     readonly key: "cmd.notify";

package/lib/types/dialogs.d.ts

@@ -16,6 +16,15 @@ export interface ConfirmDialog {
     resolve(value: 'y' | 'n' | 'cancel'): void;
 }
 export interface QuestionDialog {
+    /**
+     * Called whenever the highlighted option moves.
+     *
+     * The theme picker uses it to paint the candidate palette immediately, so the
+     * choice is a preview rather than a list of names — the reader sees the
+     * transcript in the palette before committing to it. Nothing else sets it, and
+     * a dialog without it behaves exactly as before.
+     */
+    onCursor?: (cursor: number) => void;
     kind: 'questions';
     question: AskUserQuestionItem;
     index: number;
@@ -103,6 +112,33 @@ export declare function applyQuestionFilter(dialog: QuestionDialog): void;
 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;
+/**
+ * Which options a fresh question dialog starts with.
+ *
+ * The rule that caused a real mis-answer: a **multi-select** list used to inherit
+ * the single-select default of "the first option is already chosen", so a reader
+ * who moved the highlight to the row they wanted and pressed Enter answered with
+ * the first row instead — the `●` never left it. A multi-select starts empty
+ * unless the caller asks for a specific preselection; `questionSubmit` then falls
+ * back to the highlighted row, which is what pressing Enter means.
+ * @param question - the question being asked.
+ * @param preselected - an index the caller wants chosen up front, if any.
+ * @returns the indexes to select initially.
+ */
+export declare function initialQuestionSelection(question: AskUserQuestionItem, preselected?: number): number[];
+/**
+ * The circle drawn beside one option.
+ *
+ * `●` marks **what Enter will submit**, which is why it sits on the highlighted
+ * row while nothing is ticked — the mark follows the cursor, so what the reader
+ * sees is what the answer will be. A ticked row in a multi-select list carries
+ * `✓` instead: several rows can be chosen at once, and the circle cannot be in
+ * two places without lying about one of them.
+ * @param dialog - the open question dialog.
+ * @param index - the option index being drawn.
+ * @returns the marker for that row.
+ */
+export declare function questionOptionMarker(dialog: QuestionDialog, index: number): '●' | '○' | '✓';
 /** Select option `index`: toggles in a multi-select list, replaces otherwise. */
 export declare function selectQuestionOption(dialog: QuestionDialog, index: number): void;
 /** Handle a hotkey: select its option and report whether it applied. */

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

@@ -0,0 +1,99 @@
+/**
+ * Where the TUI's bytes go when the parent is not a terminal.
+ *
+ * The plugin paints through a display relay, and a relay normally *is* a
+ * terminal: it writes ANSI to stdout, listens for `resize`, and puts stdin in raw
+ * mode. A GUI, a browser terminal or a test harness has none of those, but it can
+ * provide the same three things over pipes — bytes in, bytes out, and a size it
+ * reports as a protocol frame. This module is the switch that says "the parent is
+ * such a relay, do not require a TTY".
+ *
+ * Two entries, one mechanism and one sugar (as chosen when the mode was
+ * designed):
+ *
+ *  - `DSH_TUI_DISPLAY=stdio` in the environment — the mechanism. Setting it *is*
+ *    the parent's statement that it is a relay, so it is also what the no-TTY
+ *    guard consults.
+ *  - `--display stdio` on the command line — the sugar, declared in the profile's
+ *    own grammar so it shows up in `--help` and a typo is an error rather than a
+ *    silently inert plugin.
+ *
+ * @module dsh-ssh-tui/display-mode
+ */
+/** The environment variable that selects the display mode. */
+export declare const DISPLAY_MODE_ENV = "DSH_TUI_DISPLAY";
+/**
+ * `tty` is the default: paint to the process's own terminal. `stdio` means the
+ * parent speaks the display protocol on stdin/stdout.
+ */
+export type DisplayMode = 'tty' | 'stdio';
+/** A mode request, and what to say when the value was not one of the two. */
+export interface DisplayRequest {
+    mode?: DisplayMode;
+    /** The unrecognized value, when one was given. */
+    invalid?: string;
+}
+/**
+ * Parse one mode word.
+ * @param value - a value from the environment or a flag.
+ * @returns the mode, or undefined for anything else (the caller reports it).
+ */
+export declare function parseDisplayMode(value: string | undefined): DisplayMode | undefined;
+/**
+ * The `--display <mode>` value in an argument vector.
+ *
+ * Accepts both spellings a person may type (`--display stdio`,
+ * `--display=stdio`) and only ever reads the pair it owns — everything else is
+ * left where it is, because the same vector is parsed by the profile's own
+ * grammar and by the host.
+ * @param argv - an argument vector (defaults to this process's).
+ * @returns the value found, if any.
+ */
+export declare function displayModeFromArgv(argv?: readonly string[]): string | undefined;
+/**
+ * Resolve the mode request from the environment and the command line.
+ *
+ * The environment wins when both are present: it is the mechanism, and a parent
+ * that sets it is describing the channel it is about to speak on, whereas a flag
+ * is a convenience the reader may have left in a wrapper script.
+ * @param env - the environment to read.
+ * @param argv - the argument vector to read.
+ * @returns the requested mode, plus the offending value when one was useless.
+ */
+export declare function requestedDisplayMode(env?: NodeJS.ProcessEnv, argv?: readonly string[]): DisplayRequest;
+/**
+ * A window-size report: `CSI 8 ; rows ; cols t`.
+ *
+ * This is the sequence a terminal sends when it is asked for its size, and it is
+ * also how a pipe parent says "the panel is now this big". A pipe has no
+ * `resize` event and no SIGWINCH, so without this the embedder's only way to
+ * resize the TUI would be to restart it.
+ */
+export declare const WINDOW_SIZE_REPORT: RegExp;
+/** A size a parent declared: columns first, the way the rest of the code wants it. */
+export interface ParentResize {
+    columns: number;
+    rows: number;
+}
+/**
+ * Split a parent's input into keystrokes and size reports.
+ *
+ * A report can arrive split across two reads (`ESC [ 8 ; 2` then `4 ; 80 t`),
+ * and forwarding half of it as typing would send escape bytes to the model's
+ * prompt. The tail is held until the next read, exactly like the cursor-reply
+ * filter holds a half-arrived reply — with the same deadline that filter gets:
+ * a lone `ESC` matches the prefix, and the byte after it may never come, so a
+ * caller that forwards typing **must** release a {@link pending} run when its
+ * window passes (`flush()`). Waiting for the next read instead swallows the
+ * user's Escape key, and delivers it glued to whatever key follows as an Alt
+ * chord. `TerminalInputGuard` is the same filter with that timer attached.
+ * @returns a filter for one input stream.
+ */
+export declare function createParentResizeFilter(): {
+    push(text: string): {
+        forward: string;
+        sizes: ParentResize[];
+    };
+    flush(): string;
+    readonly pending: boolean;
+};

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

@@ -13,6 +13,15 @@ export declare const FRAME_PROBE_REPLY = 9;
 export declare const FRAME_QUERY = 10;
 /** Host → prober: the answer to {@link FRAME_QUERY}. */
 export declare const FRAME_QUERY_REPLY = 11;
+/**
+ * Relay → host: what this terminal does with the ambiguous glyphs.
+ *
+ * Payload: one byte, bit 0 = the terminal advances two cells, bit 1 = the second
+ * cell has to be reserved by us with a space. Sent right after HELLO, because the
+ * Host decides every width in the session and it is the relay — not the Host —
+ * that owns the terminal to measure on.
+ */
+export declare const FRAME_METRICS = 12;
 /**
  * What a relay's own terminal round trip said.
  *
@@ -105,6 +114,24 @@ export declare function sessionBootstrapPidPath(sessionId: string, dshHome?: str
 /** Pre-digest Host stderr log next to the 0.7.1 socket, when that name differs. */
 export declare function legacySessionErrPath(sessionId: string, dshHome?: string, platform?: NodeJS.Platform): string | undefined;
 export declare function encodeFrame(type: number, payload?: Buffer): Buffer;
+/**
+ * The size a relay should report.
+ *
+ * A terminal knows its own size; a parent that speaks the protocol on pipes is
+ * not a terminal, so it declares one through `COLUMNS`/`LINES` — the convention
+ * every shell and TUI already shares — and corrects it later with a resize frame
+ * if the window changes. Without either, the historical 80×24 stands.
+ * @param stdout - the stream that may be a terminal.
+ * @param env - the environment to read.
+ * @returns the columns and rows to send as the first resize.
+ */
+export declare function relayTerminalSize(stdout?: {
+    columns?: number;
+    rows?: number;
+}, env?: NodeJS.ProcessEnv): {
+    columns: number;
+    rows: number;
+};
 export declare function encodeResize(columns: number, rows: number): Buffer;
 export declare function decodeResize(payload: Buffer): {
     columns: number;
@@ -115,6 +142,16 @@ export declare function decodeRtt(payload: Buffer): number | undefined;
 export declare function encodeProbe(): Buffer;
 export declare function encodeProbeReply(verdict: TerminalVerdict): Buffer;
 export declare function decodeProbeReply(payload: Buffer): TerminalVerdict;
+/** Encode {@link FRAME_METRICS}. */
+export declare function encodeMetrics(metrics: {
+    wide: boolean;
+    reserve: boolean;
+}): Buffer;
+/** Decode {@link FRAME_METRICS}; undefined when the payload is not one byte. */
+export declare function decodeMetrics(payload: Buffer): {
+    wide: boolean;
+    reserve: boolean;
+} | undefined;
 export declare function encodeQuery(): Buffer;
 export declare function encodeQueryReply(verdict: AttachmentVerdict): Buffer;
 export declare function decodeQueryReply(payload: Buffer): AttachmentVerdict;
@@ -130,6 +167,11 @@ export interface DisplayHostHandlers {
     onStdin(bytes: Buffer): void;
     onResize(columns: number, rows: number): void;
     onRtt?(rttMs: number | undefined): void;
+    /** The relay measured this terminal's ambiguous glyphs; adopt the verdict. */
+    onMetrics?(metrics: {
+        wide: boolean;
+        reserve: boolean;
+    }): void;
     onDetach(info?: {
         replaced?: boolean;
     }): void;
@@ -183,6 +225,18 @@ export declare class DisplayHost {
     private settleProbe;
     sendStdout(bytes: Buffer | string): boolean;
     sendGoodbye(): void;
+    /**
+     * Say goodbye and let the frame leave before the socket is reaped.
+     *
+     * The frame is what tells the launcher to exit instead of reading the close as
+     * a crash and re-attaching (`attach.ts`) — the replacement path flushes
+     * `FRAME_REPLACED` for exactly the same reason. A write only *queues* on libuv
+     * until the peer drains it, and reaping the socket cancels what is still
+     * queued: on a busy link, with a starting session still painting into that
+     * socket, the goodbye was dropped along with those frames and the launcher
+     * re-attached over the user's own `/exit` instead of exiting.
+     */
+    private farewellAndReap;
     close(): Promise<void>;
 }
 /**
@@ -274,8 +328,29 @@ export declare function quietTerminalInput(stdin?: NodeJS.ReadStream): number;
  * written into a link that may already be dead.
  */
 export declare function restoreTerminalInput(stdin?: NodeJS.ReadStream): void;
+/**
+ * The environment a detached Host is started with.
+ *
+ * Notable entries: the marker that tells the child it *is* the Host, and the
+ * ambiguous-width decision. The Host paints, but its own stdout is the relay
+ * socket, so it cannot look at a TTY to know how wide the window's terminal
+ * draws `①` or `—`; this process has that terminal, so it decides and hands the
+ * answer over. An explicit value in the environment still wins.
+ * @param env - the parent environment (a test passes its own).
+ * @param onTerminal - whether *this* process owns a terminal; it is the evidence
+ *   the width table is chosen from, and a test harness is not a terminal.
+ * @returns the child environment.
+ */
+export declare function hostChildEnv(env?: NodeJS.ProcessEnv, onTerminal?: boolean, measuredAmbiguousWide?: boolean): NodeJS.ProcessEnv;
 /** Test seam for {@link spawnDetachedHost}; production passes nothing. */
 export interface SpawnHostOptions {
+    /**
+     * What the launcher measured for the ambiguous glyphs, when it measured.
+     *
+     * The Host paints every frame with a socket for stdout, so it cannot ask the
+     * terminal anything; the answer travels in its environment instead.
+     */
+    ambiguousWide?: boolean;
     /**
      * Start the Host through this command instead of resolving the real one, or
      * `null` to spawn it directly even where a bootstrap exists.

package/lib/types/footer.d.ts

@@ -181,7 +181,7 @@ export declare function subagentRouteLabel(model: string, provider?: string, eff
  * The mute (`90`) is reopened after the chip so the rest of the identity row
  * stays dim.
  */
-export declare function paintFooterSubagentChip(line: string, chip: string, foreign: boolean, muteSgr?: string, depth?: ColorDepth): string;
+export declare function paintFooterSubagentChip(line: string, chip: string, foreign: boolean, muteSgr?: string, depth?: ColorDepth, identitySgr?: string): string;
 export declare function footerSubagentForeign(input: Pick<FooterStatusInput, 'provider' | 'subProvider'>): boolean;
 /**
  * The model as the footer shows it: the model's own name, without a

package/lib/types/glyph-measure.d.ts

@@ -0,0 +1,41 @@
+import { TerminalInputPump } from './terminal-input.js';
+/**
+ * The glyphs the probe prints.
+ *
+ * Drawn from the families {@link AMBIGUOUS_WIDE_RANGES} covers — an enclosed
+ * digit, a dash, an ellipsis, a curly quote, a middle dot, a bullet, a roman
+ * numeral. Mixing families is deliberate: a font may cover `①` from a fallback
+ * face while treating `—` as typographic punctuation, and a single-glyph probe
+ * would then decide the whole table from one sample. A terminal that treats the
+ * ambiguous block as full width spends two cells on all seven.
+ */
+export declare const GLYPH_PROBE_TEXT = "\u2460\u2014\u2026\u201C\u201D\u00B7\u2022\u2160";
+export interface GlyphWidthMeasurement {
+    /** True when the terminal spent two cells per probe glyph. */
+    wide: boolean;
+    /** Cells the terminal reported for the whole probe string. */
+    cells: number;
+}
+/**
+ * Measure the ambiguous-glyph width on a real terminal.
+ *
+ * Returns `undefined` — never a guess — when there is no terminal, when it does
+ * not answer, or when the answer matches neither expectation (a font with mixed
+ * metrics: the caller then keeps its locale-based default rather than inventing a
+ * table from one sample).
+ *
+ * The round trip goes through {@link TerminalInputPump.askPosition}, which
+ * swallows the reply. That is not an implementation detail: a cursor reply that
+ * nobody consumes is echoed on screen as literal `^[[1;5R` text, and a
+ * hand-rolled version of this probe did exactly that at boot.
+ * @param options - the streams (or a pump already running on them), the probe
+ *   text, and the reply budget.
+ * @returns what the terminal said, or undefined.
+ */
+export declare function measureAmbiguousGlyphWidth(options?: {
+    stdin?: NodeJS.ReadStream;
+    stdout?: NodeJS.WriteStream;
+    probe?: string;
+    timeoutMs?: number;
+    pump?: TerminalInputPump;
+}): Promise<GlyphWidthMeasurement | undefined>;

package/lib/types/index.d.ts

@@ -36,6 +36,8 @@ export interface Config {
      */
     /** UI language (`/language`); zh unless the environment says otherwise. */
     language?: string;
+    /** Palette (`/theme`): default | catppuccin | gruvbox | mono. */
+    theme?: string;
     /** Newest plugin version whose update notice was dismissed. */
     skipUpdate?: string;
     /** Workspace pane layout (`/view`). */
@@ -46,10 +48,26 @@ export interface Config {
     autoApproval?: string;
     /** Milliseconds a leftover finished Host waits before exiting; 0 = never. */
     idleExit?: number;
+    /**
+     * Retry once when the *provider* rejects a request with 401/403 while a local
+     * credential is configured (see `auth-failure.ts`). Off by default: the retry
+     * re-sends the whole context, which in a long session is expensive.
+     */
+    retryProviderAuth?: boolean;
+    /**
+     * Fail loudly instead of staying inert when there is no terminal.
+     *
+     * The default (`false`) logs one line and mounts nothing — that is what keeps
+     * this plugin harmless in a GUI host with no console (the desktop app) and in
+     * pipes. Set it when a missing terminal *is* an error for the caller: a script
+     * asserting that a terminal profile really starts, for one.
+     */
+    requireTerminal?: boolean;
 }
 /** Every field above, as schemastery resolves them (all optional). */
 interface ConfigFields {
     sessionId?: string;
+    requireTerminal?: boolean;
     showReasoning?: boolean;
     maxToolOutputLines?: number;
     color?: boolean;
@@ -60,11 +78,13 @@ interface ConfigFields {
     model?: string;
     paintIntervalMs?: number;
     language?: string;
+    theme?: string;
     skipUpdate?: string;
     view?: string;
     disconnect?: string;
     autoApproval?: string;
     idleExit?: number;
+    retryProviderAuth?: boolean;
 }
 /**
  * The entry's schema. Everything a launch supplies (`config:` in

package/lib/types/plan.d.ts

@@ -1,6 +1,7 @@
 /**
  * Plan dock, todo lists, /find, prompt-injection cards, and compact errors.
  */
+import { type Theme } from './theme.js';
 import { type TextSegment } from './term-text.js';
 import type { DiffDisplayLine, DisplayKind, PlanTodoItem, Row, SubagentLogEntry } from './transcript-types.js';
 export declare const MAX_SUBAGENT_LOGS = 80;
@@ -83,10 +84,10 @@ export declare function askSummary(value: unknown): string;
 export declare function firstDisplayLine(text: string): string;
 /** Collapse a child-session blob to one short chip/wait-card line. */
 export declare function clipSubagentActivity(text: string, maxChars?: number): string;
-/** Running / ok / aborted / error → ANSI for the status dot and status word. */
+/** Running / ok / aborted / error → theme token for the status dot and word. */
 export declare function subagentStateColor(status: Extract<Row, {
     kind: 'subagent';
-}>['status']): '33' | '32' | '31' | '90';
+}>['status'], theme?: Theme): string;
 /**
  * Rebuild a subagent chip from the parent spawn tool call that survives in the
  * session log. Live `subagent/start` is not replayed, so resume would otherwise
@@ -138,6 +139,8 @@ export declare function buildSubagentHeader(input: {
     inspectHint?: string;
     /** Different provider from the parent: paint the title cyan, not violet. */
     foreign?: boolean;
+    /** Active palette; callers pass the session's theme so `mono` stays monochrome. */
+    theme?: Theme;
 }): {
     plain: string;
     segments: TextSegment[];

package/lib/types/platform.d.ts

@@ -235,3 +235,86 @@ export declare function restrictPathToUserSync(path: string, options?: {
  * @returns true when chrome must be drawn in ASCII.
  */
 export declare function asciiFallbackEnabled(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * What this process can serve.
+ *
+ * The plugin is a *terminal* UI, and the host it is mounted into decides whether
+ * there is a terminal at all:
+ *
+ *  - `host-relay`: this is the detached TUI Host itself (see
+ *    `isTuiHostProcess`); its terminal lives in whichever window attaches to the
+ *    session, so a missing TTY here is expected and it must serve.
+ *  - `terminal`: a real TTY on stdin and stdout.
+ *  - `desktop`: the desktop Harness launcher (Electron-as-Node, GUI subsystem).
+ *    It never has a console, so no terminal profile can ever run under it.
+ *  - `no-tty`: anything else without a TTY — a pipe (`… | tee`), cron, a service.
+ */
+export type TerminalAvailability = 'host-relay' | 'terminal' | 'desktop' | 'no-tty';
+/**
+ * Decide what to serve, from facts the caller can state.
+ *
+ * Pure on purpose: this is the one branch that decides whether the plugin mounts
+ * anything at all, and every caller-visible behaviour difference (a window, a
+ * log line, a hard failure) hangs off it.
+ * @param facts - the host process marker, the two TTY answers, and whether the
+ *   launcher is the desktop's.
+ * @returns the availability bucket.
+ */
+export declare function terminalAvailability(facts: {
+    hostProcess: boolean;
+    stdinIsTty: boolean;
+    stdoutIsTty: boolean;
+    desktop: boolean;
+}): TerminalAvailability;
+/**
+ * Whether this process is the desktop app's launcher rather than a terminal Node.
+ *
+ * The desktop Harness ships a PATH shim that runs its own GUI-subsystem binary
+ * with `ELECTRON_RUN_AS_NODE=1` (`DeepSeek Harness.exe --expose-internals
+ * app.asar/dsh/.../cli.js`). A GUI-subsystem process started from a console does
+ * not attach to it on Windows, so `process.stdin.isTTY` / `stdout.isTTY` stay
+ * undefined and no terminal profile can start under it. That is a property of
+ * the launcher, not of the user's terminal, and the two cases deserve different
+ * advice — which is all this decides.
+ * @param facts - the runtime's own answers (`process.versions`, `execPath`, `argv`).
+ * @returns true when the launcher is the desktop app's Electron-as-Node shim.
+ */
+export declare function desktopLauncher(facts: {
+    electron?: string | undefined;
+    execPath?: string | undefined;
+    argv?: readonly string[] | undefined;
+}): boolean;
+/**
+ * The message a terminal profile fails with when the launcher has no TTY.
+ *
+ * The desktop case is worth its own wording: the generic "must be TTYs" line
+ * sends a desktop user hunting for a broken terminal, while the real answer is
+ * "this launcher never has one — use the npm CLI in a terminal/SSH session, and
+ * note the desktop app does not need this plugin at all".
+ * @param desktop - whether {@link desktopLauncher} recognised the launcher.
+ * @returns the error text for the plugin to throw.
+ */
+export declare function nonTtyErrorMessage(desktop: boolean): string;
+/**
+ * What to log when the plugin has nowhere to draw.
+ *
+ * Deliberately not an error: on the desktop the situation is normal (a GUI app
+ * has no console), and a terminal profile is not a thing the user broke. The
+ * line has to (a) say nothing is running *from this plugin*, (b) explain why,
+ * (c) give the one command that fixes it, and (d) not read as a failure — the
+ * plugin used to throw here, which surfaced as "1 entry did not activate" and,
+ * on the desktop, took the app down with it.
+ * @param availability - `desktop` or `no-tty`.
+ * @returns the log line.
+ */
+export declare function inactiveNotice(availability: 'desktop' | 'no-tty'): string;
+/**
+ * The message for the opt-in hard failure (`requireTerminal: true`).
+ *
+ * Same two situations as {@link inactiveNotice}, but for callers who would
+ * rather a profile fail loudly than quietly do nothing — a script asserting that
+ * a terminal profile really starts, for one.
+ * @param desktop - whether the launcher is the desktop's.
+ * @returns the error text.
+ */
+export declare function requiredTerminalError(desktop: boolean): string;

package/lib/types/session-blank.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What makes a session "blank": a launch that never did anything.
+ *
+ * A fresh TUI start creates a session before the reader has typed anything, so
+ * quitting straight away leaves an artifact behind. The picker hides those, but
+ * they are real files, and other surfaces (the web session list) read the same
+ * artifacts without that filter — which is how a session that was never used
+ * still shows up in another profile's menu.
+ *
+ * The rule lives in its own module, with no host imports, for one reason: three
+ * very different callers have to agree on it — the picker (which prunes while
+ * listing), the TUI (which drops its own session on exit), and
+ * `scripts/prune-blank-sessions.mjs` (which sweeps whatever already accumulated,
+ * outside a running host).
+ *
+ * @module dsh-ssh-tui/session-blank
+ */
+/** Whether one event is a message the reader typed. */
+export declare function isUserMessageEvent(event: unknown): boolean;
+/**
+ * Whether a turn was opened and never closed.
+ *
+ * A session with an open turn is mid-work: it must never be treated as empty,
+ * however little it looks like it has done.
+ * @param events - decoded session events, in order.
+ * @returns true when a `turn/start` has no matching `turn/end`.
+ */
+export declare function hasUnfinishedTurn(events: readonly unknown[]): boolean;
+/**
+ * Whether the session ever produced a reply.
+ *
+ * A failed request counts: the error text is the only thing the reader has to
+ * look at, and deleting it would delete their evidence.
+ * @param events - decoded session events, in order.
+ * @returns true when an assistant message or a failed turn is present.
+ */
+export declare function sessionHasReply(events: readonly unknown[]): boolean;
+/**
+ * Whether a session saw the reader's input, a reply, or an open turn.
+ * @param events - decoded session events, in order.
+ * @returns true when there is something worth keeping.
+ */
+export declare function sessionHasWork(events: readonly unknown[]): boolean;
+/**
+ * Whether a session's events describe a launch that never did anything.
+ * @param events - the session's decoded events.
+ * @returns true when nothing the reader would recognise as work happened. An
+ *   empty event list is *not* blank: it is an unreadable or detached log, and
+ *   guessing there once made a listing delete a live session's directory.
+ */
+export declare function sessionEventsAreBlank(events: readonly unknown[]): boolean;