dsh-ssh-tui 0.7.2 → 0.7.4

package/lib/types/preset-rows.d.ts

@@ -7,8 +7,8 @@
  * STORE accepts additive rows with plugin-owned ids and no `@deepseek-ai/*`
  * module names. The profile's user layer is the supported home for the row, so
  * both the install script and the running TUI write the same block here — the
- * TUI needs it because `dsh plugin add dsh-ssh-tui@latest` (the in-app update
- * path) never runs `scripts/`, which npm installs do not ship.
+ * TUI needs it because the in-app update (`dsh plugin add`, at whatever version)
+ * never runs `scripts/`, which npm installs do not ship.
  *
  * The roster is not cosmetic: without it `/mode` cannot switch, and the tools
  * the shipped presets own (`ask_user_question`, `present`, PTC's presentation)
@@ -19,6 +19,9 @@
  * must never lose the previous content or touch a row the user wrote.
  * @module dsh-ssh-tui/preset-rows
  */
+import type { SettingsGeneration } from './dsh-compat.js';
+/** Which host line the profile being repaired boots on. */
+export type HostGeneration = SettingsGeneration;
 /** One host row the roster block mounts. */
 export interface RosterRow {
     id: string;
@@ -27,23 +30,68 @@ export interface RosterRow {
     config?: readonly string[];
 }
 /**
- * The rows the terminal profile has to mount itself: the roster `/mode` lists,
- * the TypeScript runtime the PTC preset needs, and the host-owned subagent
- * delegation setting.
+ * The rows a 0.1.5 terminal profile has to mount itself: the roster `/mode`
+ * lists, the TypeScript runtime the PTC preset needs, and the host-owned
+ * subagent delegation setting.
  */
 export declare const ROSTER_ROWS: readonly RosterRow[];
+/**
+ * The rows a 0.1.7 terminal profile mounts for itself.
+ *
+ * 0.1.7 deleted the roster this plugin used to list and switch: presets became
+ * per-session declarations a surface mounts (`@deepseek-ai/dsh-agent-preset`
+ * rows over the `agent-preset-registry` service), and `dsh-base` keeps the
+ * agent-plane rows enabled for the TUI, which is single-session and composes
+ * its agent process-wide. Beyond the base, upstream's standard preset declares a
+ * persona and these two tools. Only the tools are mounted here: a *preset* is an
+ * agent scope, but a profile is not one, and `@deepseek-ai/dsh-persona`
+ * registers the two prompt sections `dsh-system-prompt` already owns at this
+ * layer — the loader rejects the row ("prompt section
+ * \"deployment:persona-prefix\" is already registered") and one entry then
+ * silently never activates. The deployment persona this line ships with is
+ * `dsh-system-prompt`'s own empty default, which is what a profile is meant to
+ * use unless it deliberately sets one.
+ */
+export declare const FORMS_ROWS: readonly RosterRow[];
+/** The rows one host line's profile has to mount. */
+export declare function rosterRows(generation: HostGeneration): readonly RosterRow[];
+/** Every row either line knows about, for name-to-row lookups. */
+export declare const ALL_ROSTER_ROWS: readonly RosterRow[];
 /** The comment header the block introduces itself with, in both writers. */
 export declare const ROSTER_PATCH_HEADER = "# dsh-ssh-tui /mode: the agent-preset roster (standard / minimal / PTC /\n# cordis, plus every preset under $DSH_HOME/.agent-presets) and the two host\n# services the shipped presets need. dsh-base composes no roster in a terminal\n# profile, and a third-party bundle patch may not mount an @deepseek-ai row, so\n# the profile's user layer owns them.\n";
-/** One top-level `- insert:` entry mounting exactly these rows. */
-export declare function rosterInsertEntry(rows: readonly RosterRow[]): string;
+/** The same header on a host that composes its agent process-wide. */
+export declare const FORMS_PATCH_HEADER = "# dsh-ssh-tui: the agent-plane rows a 0.1.7 terminal profile mounts for itself.\n# That line composes the agent process-wide (presets are a per-session Web\n# feature now), and dsh-base already carries the rest of what the standard\n# preset declares: dsh-system-prompt owns the persona sections at this layer, so\n# only the two tools are left to mount. @deepseek-ai/dsh-persona is deliberately\n# absent \u2014 mounting it here collides with those sections and never activates.\n";
+/** The header for one host line. */
+export declare function rosterPatchHeader(generation: HostGeneration): string;
+/**
+ * The entries one host line's rows need: a single `- insert:` list.
+ * @param rows - the rows to write.
+ * @returns the YAML text, ending in a newline.
+ */
+export declare function rosterEntriesText(rows: readonly RosterRow[]): string;
 /**
  * The exact profile patch block that mounts the roster and the two host
  * services the shipped presets need. `scripts/ensure-profile-rows.sh` carries
  * the same text; a test compares the two so they cannot drift.
  */
 export declare const ROSTER_PATCH_BLOCK: string;
+/** The 0.1.7 block, the same way. */
+export declare const FORMS_PATCH_BLOCK: string;
+/** The block for one host line. */
+export declare function rosterPatchBlock(generation: HostGeneration): string;
 /** The profile patch file the roster block belongs in. */
 export declare function rosterPatchPath(home: string, profile: string): string;
+/**
+ * Whether a profile patch already declares every 0.1.7 agent-plane row.
+ *
+ * Synchronous on purpose: the footer chip is rendered from the main loop and
+ * cannot await a read. The file is small and this runs at startup and after a
+ * repair, not per frame.
+ * @param home - the harness home carrying `profiles/`.
+ * @param profile - the profile to inspect.
+ * @returns whether all three rows are declared (or the row is unreachable).
+ */
+export declare function formsRowsDeclared(home: string, profile: string): boolean;
 /** One row a patch file declares, with enough position to point at it. */
 export interface PatchRowRef {
     /** Insert id, or the target of an override/disable entry. */
@@ -88,7 +136,7 @@ export declare function duplicatePatchRows(rows: readonly PatchRowRef[]): PatchR
 /** Whether a patch already declares one roster row, by id or by module name. */
 export declare function patchNamesRow(rows: readonly PatchRowRef[], row: RosterRow): boolean;
 /** The roster rows a patch does not declare yet. */
-export declare function missingRosterRows(rows: readonly PatchRowRef[]): RosterRow[];
+export declare function missingRosterRows(rows: readonly PatchRowRef[], candidates?: readonly RosterRow[]): RosterRow[];
 export interface PatchRepair {
     text: string;
     /** Roster rows this repair adds, by id. */
@@ -108,10 +156,11 @@ export interface PatchRepair {
  * (the profile template) is replaced; anything else keeps its content and gains
  * a new `- insert:` entry after a blank line.
  * @param existing - the patch file's current text.
- * @param missing - the roster rows to mount; defaults to all of them.
+ * @param missing - the roster rows to mount; defaults to the 0.1.5 set.
+ * @param generation - which host line the profile boots on.
  * @returns the new text, or `undefined` when nothing has to change.
  */
-export declare function planRosterRepair(existing: string, missing?: readonly RosterRow[]): PatchRepair | undefined;
+export declare function planRosterRepair(existing: string, missing?: readonly RosterRow[], generation?: HostGeneration): PatchRepair | undefined;
 /**
  * The patch text with every repeated insert removed, or `undefined` when the
  * file has no duplicate.
@@ -132,10 +181,11 @@ export declare function planDuplicateRepair(existing: string): PatchRepair | und
  * half-written patch would only be seen by the next launch.
  * @param home - the harness home carrying `profiles/`.
  * @param profile - the profile to patch.
- * @param missing - the rows to mount; defaults to the whole roster.
+ * @param missing - the rows to mount; defaults to the 0.1.5 set.
+ * @param generation - which host line the profile boots on.
  * @returns `present` when the row already exists, else `written`.
  */
-export declare function ensureRosterRows(home: string, profile: string, missing?: readonly RosterRow[]): Promise<'present' | 'written'>;
+export declare function ensureRosterRows(home: string, profile: string, missing?: readonly RosterRow[], generation?: HostGeneration): Promise<'present' | 'written'>;
 /**
  * Write a repaired patch next to a copy of the previous content.
  *
@@ -148,4 +198,4 @@ export declare function ensureRosterRows(home: string, profile: string, missing?
  */
 export declare function writePatchWithBackup(path: string, text: string, stamp?: string): Promise<string | undefined>;
 /** The patch text the roster block would produce on its own, for callers that report it. */
-export declare function rosterPatchText(existing: string): string | undefined;
+export declare function rosterPatchText(existing: string, generation?: HostGeneration): string | undefined;

package/lib/types/question-wait.d.ts

@@ -0,0 +1,221 @@
+/**
+ * What a question does while nobody is attached to answer it.
+ *
+ * A dropped SSH link leaves the question queued in memory, and the only trace of
+ * it used to be a transcript line written *after* the user reconnected — which is
+ * how a turn spent waiting for an answer went unnoticed until then. Two signals
+ * exist before that:
+ *
+ * - a marker file under `$DSH_HOME/tui-socks/`, so logging back into the jump
+ *   host shows a session waiting on an answer before the TUI is even open;
+ * - one command the user configured, run once, carrying the question in its
+ *   environment. Mail and WeCom are presets of that command rather than clients
+ *   of their own: a jump host has whichever of them it already has, and neither
+ *   belongs in this plugin's dependency tree.
+ * @module dsh-ssh-tui/question-wait
+ */
+import { spawn } from 'node:child_process';
+/** One question waiting on a person who is not attached. */
+export interface WaitingQuestion {
+    /** The session the question belongs to. */
+    sessionId: string;
+    /** How many questions are waiting, this one included. */
+    count: number;
+    /** The question text, already clipped. */
+    question: string;
+    /** When the wait started, so a later reader can say how long it has been. */
+    since: number;
+}
+/**
+ * The marker for one session.
+ *
+ * Beside the session's stderr log, under the same digested label, so a long id
+ * stays inside a Windows path and two ids that sanitize to the same stem do not
+ * share a file. `.waiting` rather than a dotfile: the point is that `ls` shows it.
+ * @param sessionId - the session that is waiting.
+ * @param dshHome - the harness home; defaults to the process one.
+ * @returns the marker path.
+ */
+export declare function waitingMarkerPath(sessionId: string, dshHome?: string): string;
+/**
+ * Write the marker, replacing one already there.
+ *
+ * The question text is the only sensitive part, so the file is owner-only. A
+ * failure to write is reported as `false` and never thrown: the question is
+ * still queued, and a marker is not worth failing it over.
+ *
+ * Deliberately a plain `writeFile`, not a staged sibling renamed into place.
+ * The rename is atomic on POSIX, but Windows refuses to replace a file another
+ * process has open — and the whole point of this marker is that something else
+ * polls it (a jump-host `cat` in a loop), so the "atomic" version stops updating
+ * exactly while it is being read. The cost of the plain write is a window
+ * between the create and the first byte where a reader sees an empty file; the
+ * marker is rewritten on every change, so that window is what a consumer has to
+ * tolerate rather than something the writer can hide.
+ * @param question - the question that just started waiting.
+ * @param dshHome - the harness home; defaults to the process one.
+ * @returns whether the marker is on disk.
+ */
+export declare function writeWaitingMarker(question: WaitingQuestion, dshHome?: string): Promise<boolean>;
+/**
+ * Remove the marker. Missing is fine: the question may have been answered, or
+ * the marker may never have been written.
+ * @param sessionId - the session whose wait ended.
+ * @param dshHome - the harness home; defaults to the process one.
+ */
+export declare function clearWaitingMarker(sessionId: string, dshHome?: string): Promise<void>;
+/**
+ * The command to run when a question starts waiting, if the user configured one.
+ *
+ * The environment wins over settings, the same order `/disconnect` uses, so a
+ * one-off invocation can point somewhere else without editing the profile.
+ * Empty and whitespace are "not configured".
+ * @param env - the process environment.
+ * @param saved - the `ssh-tui.notify` value, when settings has one.
+ * @returns the command, or undefined when notifications are off.
+ */
+export declare function notifyCommand(env?: NodeJS.ProcessEnv, saved?: string): string | undefined;
+/** What one notification knows about the question it is announcing. */
+export interface NotifyContext {
+    sessionId: string;
+    /** How many questions are waiting. */
+    count: number;
+    /** The question text. */
+    question: string;
+    /** Milliseconds the question has already been waiting. */
+    waitedMs: number;
+    /** A command that reattaches to the session. */
+    resumeCommand: string;
+    /** SMTP username, present only for an authenticated server. */
+    smtpUser?: string;
+    /** SMTP password, present only for an authenticated server. */
+    smtpPassword?: string;
+}
+/**
+ * One notify target, as `/notify` parsed it.
+ *
+ * `off` clears the command. `mail` is the local mailer. `smtp` is a submission
+ * to a server, authenticated when a password is given. `local` is the machine's
+ * own SMTP listener, which needs no account.
+ */
+export type NotifyTarget = {
+    kind: 'off';
+} | {
+    kind: 'mail';
+    address: string;
+} | {
+    kind: 'smtp';
+    host: string;
+    port: number;
+    from: string;
+    to: string;
+    user?: string;
+    password?: string;
+} | {
+    kind: 'local';
+    port: number;
+    from: string;
+    to: string;
+};
+/**
+ * Parse one `/notify` argument into a target.
+ *
+ * Four shapes, deliberately small:
+ *
+ * - empty, `off`, `none` — turn it off;
+ * - `mail you@example.com` — the local mailer;
+ * - `smtp host[:port] from to [user [password]]` — an SMTP server, port 587
+ *   when omitted, authenticated only when a user is given;
+ * - `local [port] from to` — the machine's own mailer on 25, or another port.
+ *
+ * @param raw - everything after `/notify`.
+ * @returns the target, or undefined when the shape is not one of those.
+ */
+export declare function parseNotifyTarget(raw: string): NotifyTarget | undefined;
+/**
+ * The shell command one target runs.
+ *
+ * SMTP and the local mailer both go through Python's stdlib `smtplib`, which
+ * is present on every jump host this plugin runs on (Node itself is). The
+ * password, when there is one, is read from `DSH_TUI_NOTIFY_SMTP_PASSWORD` at
+ * send time rather than written into the command, so it never lands in the
+ * settings file or the process list. The message text arrives on stdin.
+ * @param target - a parsed target other than `off`.
+ * @returns the command `/notify` stores.
+ */
+/**
+ * What `/notify` confirms back: the target in the user's own words, without the
+ * password.
+ * @param target - a parsed target other than `off`.
+ * @returns a short label.
+ */
+export declare function notifyTargetLabel(target: Exclude<NotifyTarget, {
+    kind: 'off';
+}>): string;
+export declare function notifyTargetCommand(target: Exclude<NotifyTarget, {
+    kind: 'off';
+}>): string;
+/**
+ * A mail command for an address, using whichever sender the host has.
+ *
+ * `mail` (or `mailx`) is on most jump hosts and speaks SMTP for them; no
+ * provider, token, or library joins this plugin. The body arrives on stdin, so
+ * the question text is never a shell argument.
+ * @param address - where the mail goes.
+ * @returns the command.
+ */
+export declare function mailNotifyCommand(address: string): string;
+/**
+ * A WeCom group-robot command for one webhook key.
+ *
+ * The payload is assembled by the caller and sent with `curl`, which a jump
+ * host already has. The key is the only secret, and it stays in the command the
+ * user configured rather than in this repo.
+ * @param key - the robot's webhook key.
+ * @returns the command.
+ */
+export declare function wecomNotifyCommand(key: string): string;
+/**
+ * The text a notification shows. Short on purpose: a mail subject and a WeCom
+ * message both get truncated by their carrier, so the resume command has to fit.
+ * @param context - the question being announced.
+ * @returns the message, one fact per line.
+ */
+export declare function notifyMessage(context: NotifyContext): string;
+/**
+ * The body a WeCom robot expects: a text message whose content is the notice.
+ * @param context - the question being announced.
+ * @returns JSON.
+ */
+export declare function wecomPayload(context: NotifyContext): string;
+/**
+ * Run the user's notify command once.
+ *
+ * The message goes to stdin and the facts go to the environment, so a command
+ * can be either `mail` (reads stdin) or anything that reads the variables. The
+ * command runs through a shell because it is a shell command by nature — the
+ * user wrote it as one — and the platform's own shell, so a Windows host uses
+ * `cmd`. Nothing it prints or fails with comes back: a notification that errors
+ * must not surface in the transcript or delay the question.
+ * @param command - the configured command.
+ * @param context - the question being announced.
+ * @param deps - injectable process spawn and clock, for tests.
+ * @returns once the command has exited, timed out, or failed to start.
+ */
+export declare function runNotify(command: string, context: NotifyContext, deps?: {
+    spawnFn?: typeof spawn;
+    platform?: NodeJS.Platform;
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * The shell that runs a notify command, and the flag that precedes it.
+ *
+ * A jump host means `sh -c`. Windows has no `sh` on PATH as a rule, so there
+ * the command runs under `cmd /c` and the user writes it for `cmd`.
+ * @param platform - injectable so the Windows shape is testable from POSIX.
+ * @returns the executable and its command flag.
+ */
+export declare function notifyShell(platform?: NodeJS.Platform): {
+    command: string;
+    flag: string;
+};

package/lib/types/selection.d.ts

@@ -9,10 +9,10 @@
  * OSC 52 (the channel `/copy` already uses).
  *
  * Only **model replies** are freely selectable. Everything here is pure: the
- * caller passes the painted lines (plain text plus whether each one came from a
- * reply) and gets back the ordered selection, the cell spans to paint in
- * reverse video, and the text to copy. The IO — mouse reports, OSC 52, notices —
- * stays in `tui.ts`.
+ * caller passes the painted lines (plain text, whether each one came from a
+ * reply, and how many leading cells are chrome) and gets back the ordered
+ * selection, the cell spans to paint in reverse video, and the text to copy.
+ * The IO — mouse reports, OSC 52, notices — stays in `tui.ts`.
  *
  * Columns are **cells**, not characters: a CJK glyph is two cells wide, and a
  * selection that touches either half includes the whole glyph. Surrogate pairs
@@ -24,6 +24,14 @@ export interface SelectableLine {
     text: string;
     /** True when this line came from a model reply, the only freely copyable kind. */
     copyable: boolean;
+    /**
+     * Cells at the start of the line that are chrome, not content.
+     *
+     * The focused card or reply carries a `▶ ` marker, and a reply's lines are
+     * copyable, so without this the marker was part of the text a drag copied off
+     * its first line. Only the first line of the focused row carries one.
+     */
+    gutter?: number;
 }
 /** A point in the transcript: `line` indexes the painted lines, `column` is a cell. */
 export interface SelectionPoint {

package/lib/types/settings-routes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Loader row that carries the `/model` route memory as a settings form.
+ *
+ * On the 0.1.5 line `route-memory.ts` registers this namespace itself through
+ * `installSettingsSection`; from 0.1.7 a settings form is projected out of a
+ * loader entry's own `Config` schema, so the same schema is mounted as a row.
+ * The row id (`ssh-tui-routes`, see `cordis.patch.yml`) is the namespace every
+ * read goes through, and it is also the id the host's legacy `settings.yaml`
+ * import lands on, so an existing `ssh-tui-routes` section keeps its routes.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "ssh-tui-settings-routes";
+/** The route-memory section, as the 0.1.7 settings service wants to see it. */
+export declare const Config: import("@deepseek-ai/schemastery").default<import("./route-memory.js").RouteMemorySettings>;
+/** Nothing to mount: the TUI owns every read and write of this section. */
+export declare function apply(_ctx: Context): void;

package/lib/types/settings-subagent.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Loader row that carries the subagent model selection as a settings form.
+ *
+ * On the 0.1.5 line `subagent-model.ts` registers this namespace itself through
+ * `installSettingsSection`; from 0.1.7 a settings form is projected out of a
+ * loader entry's own `Config` schema, so the same schema is mounted as a row.
+ * The row id (`ssh-tui-subagent`, see `cordis.patch.yml`) is the namespace
+ * every read and write goes through, and the id the host's legacy
+ * `settings.yaml` import lands on, so an existing `/submodel` pin survives.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "ssh-tui-settings-subagent";
+/** The subagent selection, as the 0.1.7 settings service wants to see it. */
+export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+    provider: import("@deepseek-ai/schemastery").default<string>;
+    model: import("@deepseek-ai/schemastery").default<string>;
+    reasoningEffort: import("@deepseek-ai/schemastery").default<string>;
+}>>, Schemastery.ObjectT<NoInfer<{
+    provider: import("@deepseek-ai/schemastery").default<string>;
+    model: import("@deepseek-ai/schemastery").default<string>;
+    reasoningEffort: import("@deepseek-ai/schemastery").default<string>;
+}>>, "plain">;
+/** Nothing to mount: the TUI owns every read and write of this section. */
+export declare function apply(_ctx: Context): void;

package/lib/types/subagent-model.d.ts

@@ -129,16 +129,16 @@ export declare function adoptSessionSubagentSelection(ref: SubagentSelectionRef,
  * the built-in default instead.
  */
 export declare function releaseSessionSubagentSelection(ref: SubagentSelectionRef, settingsValue: unknown): void;
-/** Settings schema for `$DSH_HOME/settings.yaml`. */
-export declare const SUBAGENT_SETTINGS_SCHEMA: z<Schemastery.ObjectS<{
-    provider: z<string, string>;
-    model: z<string, string>;
-    reasoningEffort: z<string, string>;
-}>, Schemastery.ObjectT<{
-    provider: z<string, string>;
-    model: z<string, string>;
-    reasoningEffort: z<string, string>;
-}>>;
+/** Settings schema for the subagent selection; every field is form-writable. */
+export declare const SUBAGENT_SETTINGS_SCHEMA: z<Schemastery.ObjectS<NoInfer<{
+    provider: z<string>;
+    model: z<string>;
+    reasoningEffort: z<string>;
+}>>, Schemastery.ObjectT<NoInfer<{
+    provider: z<string>;
+    model: z<string>;
+    reasoningEffort: z<string>;
+}>>, "plain">;
 /** Normalize a raw settings section into a live typed selection. */
 export declare function normalizeSubagentSelection(value: unknown): SubagentSelection;
 /**

package/lib/types/term-text.d.ts

@@ -38,6 +38,20 @@ export declare function waitCardCopy(input: {
  * end the last one with an ellipsis when the text does not fit.
  */
 export declare function wrapWaitDetails(detail: string, width: number, maxLines?: number): string[];
+/** Forget the cached decision, so the next read re-consults the environment. */
+export declare function resetAsciiChrome(): void;
+/**
+ * Rewrite one string's chrome into ASCII when the terminal cannot decode UTF-8.
+ *
+ * Only the glyphs in {@link ASCII_CHROME} move; CJK text is left byte for byte,
+ * because there is no ASCII for it and a Chinese locale on a non-UTF-8 console
+ * needs `/language en`, not a mangled translation. Widths are preserved for the
+ * two-cell marks, so a row measured either side of this call occupies the same
+ * number of cells.
+ * @param text - one row, possibly with ANSI sequences in it.
+ * @returns the row unchanged when UTF-8 chrome is safe.
+ */
+export declare function mapAsciiChrome(text: string): string;
 /**
  * Terminal cell width for one string.
  *

package/lib/types/terminal-caps.d.ts

@@ -0,0 +1,105 @@
+/**
+ * What the terminal in front of us can actually do.
+ *
+ * `color-depth.ts` answers the palette question; this answers the rest of the
+ * ones that change what we may safely emit: mouse reporting, bracketed paste,
+ * the alternate screen, clipboard writes (OSC 52) and hyperlinks (OSC 8), plus
+ * which family of terminal we are talking to.
+ *
+ * Why it is a module and not a few `if`s: these decisions are made from
+ * environment variables that nobody on the team can test by hand for every
+ * desktop — GNOME Terminal, XFCE Terminal, Konsole, xterm, tmux, the Linux
+ * virtual console, Windows Terminal, a legacy Windows console. So the input is
+ * a parameter, the table is data, and `tests/terminal-caps.test.mjs` pins one
+ * fixture per family on any platform.
+ *
+ * The bias is **not** "assume the best". A capability we claim but the terminal
+ * lacks costs the user something real: `?1000h` on a console that cannot report
+ * SGR coordinates swallows its mouse; OSC 52 where nothing reads it makes
+ * `/copy` look like it worked; the alternate screen on a serial console loses
+ * the scrollback. Where a terminal is known to be marginal, the answer is no,
+ * and `DSH_TUI_TERM_CAPS` is the escape hatch for the user who knows better.
+ *
+ * @module dsh-ssh-tui/terminal-caps
+ */
+import { type ColorDepth } from './color-depth.js';
+/** Which terminal implementation is on the other end. */
+export type TerminalFamily = 'windows-terminal' | 'windows-console' | 'vte' | 'konsole' | 'xterm' | 'tmux' | 'screen' | 'linux-console' | 'dumb' | 'unknown';
+/** One terminal's answer to every question this TUI asks of it. */
+export interface TerminalCapabilities {
+    family: TerminalFamily;
+    /** A human name for diagnostics (`/diag`), e.g. `GNOME Terminal (VTE 7000)`. */
+    label: string;
+    colors: ColorDepth;
+    /** Report mouse events at all (`?1000h`). */
+    mouse: boolean;
+    /** Report them as SGR (`?1006h`) instead of the 32-column X10 encoding. */
+    mouseSgr: boolean;
+    /** Report motion while a button is held (`?1002h`), which a drag needs. */
+    mouseDrag: boolean;
+    /** `?2004h`: paste arrives wrapped, so a multi-line paste is one event. */
+    bracketedPaste: boolean;
+    /** `?1049h`: the TUI gets its own screen and restores the scrollback on exit. */
+    alternateScreen: boolean;
+    /** OSC 52 clipboard writes reach the user's own machine. */
+    osc52: boolean;
+    /** OSC 8 hyperlinks are clickable rather than noise. */
+    osc8: boolean;
+    /** OSC 0/2 window-title updates are honoured. */
+    title: boolean;
+    /** `DSH_TUI_TERM_CAPS` tokens that were rejected, for `/diag` to report. */
+    ignoredOverrides: readonly string[];
+}
+/** Everything the classifier reads. `platform` and `env` are injectable. */
+export interface TerminalProbe {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}
+/** Capability names a user may force on or off through `DSH_TUI_TERM_CAPS`. */
+declare const TOGGLEABLE: readonly ["mouse", "mouseSgr", "mouseDrag", "bracketedPaste", "alternateScreen", "osc52", "osc8", "title"];
+/**
+ * Parse `DSH_TUI_TERM_CAPS`.
+ *
+ * `no-mouse`, `mouse`, `mouse=false` and `mouse = false` all mean what they
+ * look like: the `=` binds first, so the spaced spelling cannot silently invert
+ * into the opposite answer (it did, and `osc52 = false` then *re-enabled* the
+ * clipboard promise). A value outside the two vocabularies, an unknown name or a
+ * bare `no-` is rejected rather than guessed, and the rejects are returned so
+ * `/diag` can show them — this variable is the only feedback channel a user has
+ * when an override does not appear to work.
+ */
+export declare function parseCapsOverrideReport(raw: string): {
+    overrides: Partial<Record<(typeof TOGGLEABLE)[number], boolean>>;
+    ignored: string[];
+};
+/** The overrides alone, for callers that do not report. */
+export declare function parseCapsOverride(raw: string): Partial<Record<(typeof TOGGLEABLE)[number], boolean>>;
+/**
+ * Classify the terminal from the environment.
+ *
+ * Detection is by the markers terminals actually set: Windows Terminal exports
+ * `WT_SESSION`; the VTE family (GNOME Terminal, XFCE Terminal, MATE, Tilix,
+ * Terminator, Guake) exports `VTE_VERSION`; Konsole exports `KONSOLE_VERSION`;
+ * tmux and screen export `TMUX` / `STY` and set a `tmux*` / `screen*` TERM.
+ * Everything else falls back to the TERM name.
+ */
+export declare function detectTerminalFamily(probe?: TerminalProbe): {
+    family: TerminalFamily;
+    label: string;
+};
+/**
+ * Every capability for the terminal in front of us.
+ *
+ * `DSH_TUI_TERM_CAPS` overrides individual answers (`no-mouse`, `osc52=false`);
+ * `DSH_TUI_NO_ALT_SCREEN` and `DSH_TUI_OSC8` keep working because they came
+ * first and are documented.
+ */
+export declare function terminalCapabilities(probe?: TerminalProbe): TerminalCapabilities;
+/** Mouse-tracking sequences to enable, in one write. Empty when unsupported. */
+export declare function mouseEnableSequence(caps: TerminalCapabilities): string;
+/** Mouse-tracking sequences to disable. Always safe to emit: `l` on a mode the
+ *  terminal never enabled is ignored, and leaving a mode on is not. */
+export declare function mouseDisableSequence(): string;
+/** Bracketed-paste enable/disable, or empty when the terminal lacks it. */
+export declare function bracketedPasteSequence(caps: TerminalCapabilities, on: boolean): string;
+export {};

package/lib/types/terminal-input.d.ts

@@ -133,6 +133,16 @@ export declare class TerminalInputPump {
      * and 0 ms, two "agreeing" samples, early stop, chip frozen on a wrong value).
      */
     private quietMs;
+    /**
+     * One request, one window: what a display-liveness check needs.
+     *
+     * `measure()` deliberately is not this. It waits out its whole budget between
+     * attempts so a late answer cannot be read as a fast one, and a check that
+     * costs seconds per question is a picker that hangs. Reading a late answer as
+     * this window's is the harmless direction here: it reports "the terminal is
+     * there", which is the conservative answer for every caller.
+     */
+    measureOnce(timeoutMs?: number): Promise<boolean>;
     /**
      * Wait until the line has been quiet for a full window, measured from the
      * later of the last answer and the last request. An answer to a request we

package/lib/types/transcript-types.d.ts

@@ -142,6 +142,26 @@ export type Row = {
     text: string;
     plugin?: string;
     expanded: boolean;
+} | {
+    /**
+     * Files one turn changed, from the Host's `workspaceChanges` service.
+     * Display only: the summary is not in the session log, and a restarted
+     * Host cannot reopen it, so the card is never rebuilt from history.
+     */
+    kind: 'changes';
+    /** The turn the summary describes. A later event for it replaces this card. */
+    turn: number;
+    /** Sequence of the `workspace/changes` event the summary was read from. */
+    seq: number;
+    /** Session the summary belongs to; `diff` is served per session. */
+    sessionId: string;
+    /** Header text, rendered once so the card does not recompute it per frame. */
+    header: string;
+    /** One line per listed file, in the service's own order. */
+    files: string[];
+    /** Files the service's cap left off the list, appended after `files`. */
+    more?: string;
+    expanded: boolean;
 } | {
     kind: 'system';
     text: string;
@@ -171,6 +191,8 @@ export type CollapsibleBlock = Extract<Row, {
     kind: 'compaction';
 } | {
     kind: 'prompt';
+} | {
+    kind: 'changes';
 }> | {
     kind: 'streaming-reasoning';
     expanded: boolean;