dsh-ssh-tui 0.7.3 → 0.8.0

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-subagent.d.ts

@@ -11,14 +11,14 @@
 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<{
+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<{
+}>>, 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

@@ -130,15 +130,15 @@ export declare function adoptSessionSubagentSelection(ref: SubagentSelectionRef,
  */
 export declare function releaseSessionSubagentSelection(ref: SubagentSelectionRef, settingsValue: unknown): void;
 /** Settings schema for the subagent selection; every field is form-writable. */
-export declare const SUBAGENT_SETTINGS_SCHEMA: z<Schemastery.ObjectS<{
+export declare const SUBAGENT_SETTINGS_SCHEMA: z<Schemastery.ObjectS<NoInfer<{
     provider: z<string>;
     model: z<string>;
     reasoningEffort: z<string>;
-}>, Schemastery.ObjectT<{
+}>>, 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-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;

package/lib/types/tui.d.ts

@@ -25,7 +25,7 @@ import { type SessionRoute } from './session-route.js';
 import { type SubagentSelectionRef } from './subagent-model.js';
 import { type AskUserQuestionAnswer, type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-questions';
 import type { ApprovalOutcome, ApprovalRequest } from '@deepseek-ai/dsh-user-approval';
-import type { CollapsibleBlock, DisconnectPolicyName } from './transcript-types.js';
+import type { CollapsibleBlock, DisconnectPolicyName, Row } from './transcript-types.js';
 import { paintedLinkHits } from './term-text.js';
 export type { CollapsibleBlock, DisplayKind, DisconnectPolicyName, PlanTodoItem, Row, SubagentLogEntry, ToolDiffHunk, } from './transcript-types.js';
 export { clipAnsiToWidth, cursorVisualPosition, displayWidth, foldInputView, hrefAtColumn, osc52Clipboard, osc8Enabled, paintedLinkHits, fmtElapsedCompact, padAnsiToWidth, padToWidth, renderMarkdownLines, repeatToWidth, shimmerText, truncateToWidth, visibleWidth, waitCardCopy, waitSummaryFromReasoning, wrapWaitDetails, } from './term-text.js';
@@ -107,6 +107,15 @@ export interface TuiConfig {
     onHangup?: () => void | Promise<void>;
     /** Called when a Display relay attaches after hangup. */
     onReattach?: () => void | Promise<void>;
+    /**
+     * The display just went away, before the Host has decided whether to stay.
+     *
+     * The lock stops saying `attached` from here: that field is what a resume (and
+     * the launch picker's list) reads to decide whether another window is on the
+     * session, and leaving it set for the whole cancel-and-flush below turned a
+     * reconnect in that window into "already attached to another window".
+     */
+    onDetach?: () => void | Promise<void>;
     /** Host process: no local TTY; paint only through the display socket. */
     headlessDisplay?: boolean;
     /** Append events as plain lines instead of painting (see `line-mode`). */
@@ -123,6 +132,16 @@ export interface TuiController {
     disconnectPolicy(): DisconnectPolicyName;
 }
 export type WorkspaceView = 'detailed' | 'compact';
+/**
+ * One row the card cursor can land on.
+ *
+ * Every collapsible card, plus the model replies. A reply has nothing to expand,
+ * which is why it used to be left out of the ring — and that is exactly what
+ * made `/copy` unreachable for it: `/copy` takes the focused row, so as soon as
+ * the reader selected any card the reply stopped being a copy target, and the
+ * newest reply survived only as the no-focus fallback.
+ */
+export type FocusTarget = Row | CollapsibleBlock;
 export declare function parseDisconnectPolicy(raw: string): DisconnectPolicyName | undefined;
 /**
  * The `reasoningEfforts` map `/setup` writes for a hand-declared
@@ -221,6 +240,7 @@ export declare class SshTui {
     private relayRows;
     private readonly onHangup;
     private readonly onReattach;
+    private readonly onDetach;
     private renderTimer;
     private readonly decoder;
     private readonly color;
@@ -254,6 +274,14 @@ export declare class SshTui {
     private commandSuggestions;
     private suggestionIndex;
     private focusedRow;
+    /**
+     * The text of the last prompt the user sent, kept so an opted-in retry can
+     * send the same thing again after a provider-side auth failure. Cleared when
+     * the retry fires, which is what bounds it to one attempt per user message.
+     */
+    private lastUserText;
+    /** Set on every turn/start; a retry consumes it. */
+    private authRetryArmed;
     private pendingMessages;
     private lastActivity;
     private lastIdleCtrlCAt;
@@ -317,6 +345,15 @@ export declare class SshTui {
     private readonly inputGuard;
     private thinkingStartedAt;
     private waitStartedAt;
+    /**
+     * Whether the running turn produced anything a person can read: reply text or
+     * a tool card. A turn that ends with thinking only is the upstream returning
+     * an empty stop, and painting 完成 for it reads as a finished answer — see
+     * the hint at `turn/end`.
+     */
+    private turnSawOutput;
+    /** Whether the turn produced thinking, which the empty-stop hint names. */
+    private turnSawReasoning;
     private completionSignaled;
     private replaying;
     /** Display-line budget for the first paint after resume; 0 = full transcript. */
@@ -370,10 +407,22 @@ export declare class SshTui {
     private detachedDeniedCount;
     /** Questions waiting for a display right now — their cards do not exist yet. */
     private queuedQuestions;
+    /** When the current detached wait began, so the reconnect can say how long. */
+    private questionWaitSince;
     private paintIntervalMs;
     private paintLink;
+    /**
+     * Whether this process runs inside an SSH session, from the sshd environment.
+     *
+     * Distinct from `paintLink`, which `applyProbedRtt` pins to `'ssh'` for any
+     * relayed frame — a local window included. Only this flag says the capability
+     * table described a remote tty rather than the terminal the bytes reach.
+     */
+    private sshSession;
     private paintProbed;
     private paintRttMs;
+    /** The last few measured round-trips; the chip and the budget use their median. */
+    private paintRttHistory;
     private sessionTitle;
     private llmRetry;
     private quotaSnapshot;
@@ -562,6 +611,8 @@ export declare class SshTui {
     /** Re-open DECSET and start painting to an attached Display relay. */
     attachRelayDisplay(): void;
     currentDisconnectPolicy(): DisconnectPolicyName;
+    /** The paint cadence in force right now: the link tier the footer shows. */
+    currentPaintIntervalMs(): number;
     applyProbedRtt(rttMs: number | undefined): void;
     private markDirty;
     private toolCardSummary;
@@ -576,6 +627,19 @@ export declare class SshTui {
     private flushLineMode;
     /** The transcript rows that support per-row expand/collapse. */
     private collapsibleRows;
+    /**
+     * Everything the card cursor walks, in transcript order: the collapsible
+     * cards plus the model replies.
+     *
+     * Built from the two lists rather than from the rows alone, because one of the
+     * collapsible entries is synthetic: the live thinking block exists only while a
+     * turn streams and is never a member of `this.rows`. Filtering the rows (the
+     * first version of this) silently dropped it out of the cursor walk — ↑ on a
+     * turn that had only streamed thinking did nothing, and Enter could no longer
+     * expand the card being written. It belongs at the end, which is where it is
+     * painted, so anything not in the rows is appended.
+     */
+    private focusRing;
     private spinnerFrame;
     /**
      * Codex wait card: shown while the turn is running. The live thinking
@@ -630,6 +694,16 @@ export declare class SshTui {
     private markSearchRow;
     private openToolInspect;
     private openSubagentInspect;
+    /**
+     * Read one reply full-screen.
+     *
+     * What Enter does on a selected reply: a reply has no body to fold away, and
+     * the transcript wraps it to the window — which for a long answer with tables
+     * or code blocks is not how it reads. The overlay is the same surface the tool
+     * cards use, and the copy key works inside it, so "read it, then copy it"
+     * needs no trip back through the timeline.
+     */
+    private openReplyInspect;
     /**
      * Line mode has no framed scroller, so an inspect body goes into the log.
      *
@@ -640,8 +714,18 @@ export declare class SshTui {
     private echoInspectToLog;
     closeInspect(): void;
     private paintCollapsibleHeader;
-    /** Move the expand/collapse focus among reasoning and tool rows. */
-    private moveCollapsibleFocus;
+    /**
+     * Which file line of an expanded changes card the screen cursor is on.
+     *
+     * The card paints its header, then one row per file, and `selectableLines`
+     * holds exactly the viewport. The cursor sits on the input row unless the
+     * reader scrolled, so the file is how many painted rows above the cursor the
+     * card's header is. A cursor on the header, the remainder line, or the prompt
+     * falls back to the first file, which is the only defensible guess.
+     */
+    private changesFileIndex;
+    /** Move the card cursor among the cards and the replies. */
+    private moveFocus;
     /** Toggle the focused block; without focus, toggle the most recent one. */
     toggleCollapsible(): void;
     /**
@@ -807,6 +891,27 @@ export declare class SshTui {
     private readonly handleInboxClaimed;
     private readonly handleInboxDiscarded;
     private readonly handleDisposed;
+    /**
+     * One `workspace/changes` event: the files a turn changed.
+     *
+     * The event carries only the turn number; the summary stays on the Host and
+     * is served by `workspaceChanges` for this event's own sequence, and only
+     * while the Session lives. A missing service (every 0.1.5 Host) or a summary
+     * that can no longer be opened (a log replayed after a restart) shows
+     * nothing — upstream's rule, so a card that cannot be read is never drawn.
+     * A later event for the same turn replaces the earlier summary in place.
+     */
+    private noteWorkspaceChanges;
+    /** Copy one summary onto its card. Shared by the first event and its replacements. */
+    private fillChangesCard;
+    /**
+     * Full view of one file on a changes card: its comparison, as the service
+     * computed it. Binary and oversized files have no lines, so the overlay
+     * carries the one-line explanation instead of an empty body.
+     */
+    private openChangesInspect;
+    /** Open (or replace) the changes overlay, or echo it to the log in line mode. */
+    private openChangesInspectLines;
     /** Plan-mode / command / team events that plugins merge into SessionEventMap. */
     private handleExtensionEvent;
     private findCompactionRow;
@@ -851,6 +956,19 @@ export declare class SshTui {
     /** Keep an open inspect overlay in sync with the live child log. */
     private refreshOpenSubagentInspect;
     private hasLiveDisplay;
+    /**
+     * Tell the absent user that a question is waiting.
+     *
+     * The marker file is the part that needs no configuration: it sits next to the
+     * session's stderr log, so logging back into the jump host shows it before the
+     * TUI is open. The command is whatever the user pointed `ssh-tui.notify` at,
+     * run once; it never blocks the wait and never reports its own failure.
+     */
+    private announceWaitingQuestion;
+    /** The SMTP account `/notify smtp` saved, when the target is authenticated. */
+    private readNotifySmtp;
+    /** `DSH_TUI_NOTIFY`, else the saved `ssh-tui.notify`. Empty means off. */
+    private readNotifyCommand;
     private waitForLiveDisplay;
     /**
      * Auto mode rides the approval waterfall: when the host approval policy is
@@ -884,6 +1002,10 @@ export declare class SshTui {
      * `the user rejected tool "bash"`. Steer a plugin notice with the real
      * classifier/reviewer reason. Summary matches the workspace decision row
      * so the handler does not paint the body twice.
+     *
+     * This notice is committed to the session, so it is exactly the injection a
+     * V4 log refuses when it wears the released `plugin` wrapper — see
+     * {@link TUI_SOURCE_KIND}.
      */
     private tellModelApprovalDenied;
     readonly handleApproval: (request: ApprovalRequest, _next: () => Promise<ApprovalOutcome>) => Promise<ApprovalOutcome>;
@@ -1092,7 +1214,31 @@ export declare class SshTui {
     private runLanguageCommand;
     /** /view: detailed (see the work) vs compact (Codex-like summary). */
     private runViewCommand;
+    /**
+     * /notify: where a question waiting on an absent user is announced.
+     *
+     * No argument shows what is configured. `off` clears it. `mail`, `smtp` and
+     * `local` store the command that target needs; the SMTP password is kept
+     * beside it and handed to the command through the environment, so it is never
+     * part of the command string.
+     */
+    private runNotifyCommand;
     /** /disconnect: pause (default) or continue the turn after SSH drop. */
+    /**
+     * Say where an auth failure came from, and retry it if the user asked for that.
+     *
+     * `code: "AUTH"` collapses two opposite situations (see `auth-failure.ts`), and
+     * the host does not retry either of them: a provider-side 401/403 that lasted
+     * 45 seconds killed two turns in a row on 2026-09-29 while the same key, model
+     * and route answered 200 straight afterwards. The hint costs nothing and the
+     * retry is opt-in, because resending a long session re-sends its whole context.
+     */
+    private reportAuthFailure;
+    private explainAuthFailure;
+    /** Whether the opt-in retry is on (`/retryauth`, the settings form, or the env). */
+    private retryProviderAuthEnabled;
+    /** `/retryauth [on|off]` — the setting that lets one provider 401/403 retry itself. */
+    private runRetryAuthCommand;
     private runDisconnectCommand;
     /** /mode: pick an agent preset (standard / minimal / ptc / cordis / routing-suite / ...). */
     private runModeCommand;

package/lib/types/update-check.d.ts

@@ -1,13 +1,28 @@
 /**
  * Best-effort npm latest check. Failures stay quiet. The TUI may offer to
- * run `dsh plugin --profile <name> add dsh-ssh-tui@latest` — pnpm otherwise
- * keeps the lockfile pin (e.g. 0.3.7) when the spec is a bare package name.
+ * install the version it just read, by number: `dsh plugin --profile <name>
+ * add dsh-ssh-tui@<version>`. A bare package name lets pnpm keep the lockfile
+ * pin (e.g. 0.3.7), and `@latest` is resolved a second time at install — under
+ * pnpm's `minimumReleaseAge` that second lookup can quietly land on yesterday's
+ * release while still exiting 0.
  */
 import { spawn } from 'node:child_process';
 export declare const PLUGIN_PACKAGE = "dsh-ssh-tui";
 export declare function compareSemver(a: string, b: string): number;
 export declare function resolvePluginProfileName(env?: NodeJS.ProcessEnv): string;
-export declare function pluginUpgradeCommand(profile?: string): string;
+/**
+ * The install command for one already-resolved version.
+ *
+ * The version is the number `checkForPluginUpdate` read from the registry, not
+ * the `latest` dist-tag: handing pnpm the tag makes it resolve the release a
+ * second time, and a release younger than `minimumReleaseAge` is then skipped
+ * without an error. A caller with no resolved version passes `@latest`, which
+ * is still better than a bare name.
+ * @param profile - the profile the plugin is installed into.
+ * @param version - the exact version to install.
+ * @returns the command, safe to show the user and to run.
+ */
+export declare function pluginUpgradeCommand(profile?: string, version?: string): string;
 export declare function formatUpdateNotice(current: string, latest: string, profile?: string): string;
 export declare function fetchLatestNpmVersion(fetchImpl?: typeof fetch): Promise<string | undefined>;
 export interface PluginUpdateInfo {
@@ -50,7 +65,7 @@ export declare function resolveDshInvocation(options?: {
  * hold the fallback together.
  */
 export declare function shellSafeProfile(profile: string): string;
-export declare function installPluginLatest(profile?: string, deps?: {
+export declare function installPluginLatest(profile?: string, version?: string, deps?: {
     invocation?: DshInvocation;
     spawnFn?: typeof spawn;
 }): Promise<{