dsh-ssh-tui 0.7.3 → 0.7.4

package/lib/types/attach.d.ts

@@ -48,6 +48,12 @@ export interface LiveHost {
     kind: 'attachable' | 'zombie';
     sock: string;
     pid: number;
+    /**
+     * The lock's own view of the session: `attached` while a display relay is
+     * connected, `paused` / `running-detached` once its window is gone. Absent on
+     * a lock written before the field existed, which must not read as "in use".
+     */
+    state?: string;
     exitWatch?: {
         dispose(): void;
         exited: Promise<number | null>;
@@ -97,6 +103,8 @@ export interface AttacherDeps {
         replaced(sessionId: string): string;
         flapping(sessionId: string): string;
         zombie(sessionId: string, pid: number): string;
+        /** Refused: a window is on this session right now (see `attachOrSpawn`). */
+        attached(sessionId: string, pid: number): string;
     };
     locksDisabled?(): boolean;
     now?(): number;

package/lib/types/commands.d.ts

@@ -39,6 +39,9 @@ export declare const LOCAL_COMMANDS: readonly [{
 }, {
     readonly name: "disconnect";
     readonly key: "cmd.disconnect";
+}, {
+    readonly name: "notify";
+    readonly key: "cmd.notify";
 }, {
     readonly name: "approval";
     readonly key: "cmd.approval";

package/lib/types/diag.d.ts

@@ -38,6 +38,8 @@ export interface DiagSnapshot {
         title: boolean;
         /** `DSH_TUI_TERM_CAPS` tokens that were rejected (typos), for the row. */
         ignoredOverrides: readonly string[];
+        /** Chrome is being drawn in ASCII because the console cannot decode UTF-8. */
+        ascii: boolean;
     };
     /**
      * What the palette resolved to and which hints decided it. A "no colour on

package/lib/types/dialogs.d.ts

@@ -55,6 +55,22 @@ export interface InspectDialog {
     subagentSessionId?: string;
     /** `/find` already scrolled to its hit here; later repaints keep the offset. */
     searchRevealed?: boolean;
+    /**
+     * What the copy key takes while this overlay is up.
+     *
+     * The reader asked to see this body full-screen, so the body is what they
+     * mean by "copy this" — the overlay has no input line, and `/copy` typed at
+     * the prompt is covered by it. Undefined falls back to whatever is selected
+     * behind the overlay, which is the card the reader opened to get here.
+     */
+    copyText?: string;
+    /**
+     * Confirmation line shown in place of the key hint after an in-overlay copy.
+     *
+     * The notice row the copy also pushes is behind this screen, and silence after
+     * a clipboard write is the one thing that reads as a failure.
+     */
+    notice?: string;
 }
 export type Dialog = ConfirmDialog | QuestionDialog | OnboardingDialog | InspectDialog;
 export interface DialogAnswer {

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

@@ -5,6 +5,29 @@ export declare const FRAME_HELLO = 4;
 export declare const FRAME_GOODBYE = 5;
 export declare const FRAME_RTT = 6;
 export declare const FRAME_REPLACED = 7;
+/** Host → relay: round-trip your terminal now and say what it answered. */
+export declare const FRAME_PROBE = 8;
+/** Relay → Host: the answer to {@link FRAME_PROBE}. */
+export declare const FRAME_PROBE_REPLY = 9;
+/** A prober → Host: is a window *really* on this session? Does not claim it. */
+export declare const FRAME_QUERY = 10;
+/** Host → prober: the answer to {@link FRAME_QUERY}. */
+export declare const FRAME_QUERY_REPLY = 11;
+/**
+ * What a relay's own terminal round trip said.
+ *
+ * `live` — the terminal answered just now, so somebody has a screen in front of
+ *   them. `silent` — it answered when this relay attached and does not answer
+ *   now: that window is gone. The distinction is the whole point: a cut SSH link
+ *   leaves the launcher *connected* (it sees no hangup until sshd does, which
+ *   can be hours with TCP keepalive), so the socket alone cannot tell a live
+ *   window from a dead one — only the far end can. `unknown` — it never answered
+ *   (a pipe, a dumb terminal, or a link that was already dead at attach), and
+ *   silence must not be read as an answer.
+ */
+export type TerminalVerdict = 'live' | 'silent' | 'unknown';
+/** What a Host tells a prober about the window on its session. */
+export type AttachmentVerdict = 'attached' | 'detached' | 'unknown';
 /**
  * Drop launcher SIGTERM/SIGINT/SIGHUP so closing SSH cannot dispose the tree
  * before hangup handling. Leaving the session with setsid() is best-effort:
@@ -89,6 +112,12 @@ export declare function decodeResize(payload: Buffer): {
 } | undefined;
 export declare function encodeRtt(rttMs: number | undefined): Buffer;
 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;
+export declare function encodeQuery(): Buffer;
+export declare function encodeQueryReply(verdict: AttachmentVerdict): Buffer;
+export declare function decodeQueryReply(payload: Buffer): AttachmentVerdict;
 /** Incremental decoder for one socket. */
 export declare class FrameReader {
     private buffer;
@@ -113,19 +142,45 @@ export interface DisplayHostHandlers {
 export declare class DisplayHost {
     readonly path: string;
     private readonly handlers;
-    /** Test seam: how long a silent connection may wait for its HELLO. */
+    /** Test seams: how long a silent connection may wait for its HELLO, and
+     *  how long a relay may take to report its terminal round trip. */
     private readonly options;
     private server;
     private socket;
     private reader;
     attached: boolean;
+    /** Set while a {@link FRAME_PROBE} round trip is waiting for its answer. */
+    private probeSettle;
+    private probeInFlight;
     constructor(path: string, handlers: DisplayHostHandlers, 
-    /** Test seam: how long a silent connection may wait for its HELLO. */
+    /** Test seams: how long a silent connection may wait for its HELLO, and
+     *  how long a relay may take to report its terminal round trip. */
     options?: {
         helloGraceMs?: number;
+        probeTimeoutMs?: number;
     });
     listen(): Promise<void>;
     private accept;
+    /**
+     * Whether a window is really on this session — asked of the window itself.
+     *
+     * "The socket answers" is not evidence. A relay whose SSH link was cut stays
+     * connected (its launcher sees no hangup until sshd does), and the Host then
+     * truthfully reports a display that no longer has a screen behind it. Only the
+     * far end can settle it, so this round-trips the terminal through the relay.
+     */
+    attachmentVerdict(): Promise<AttachmentVerdict>;
+    /** One answer to one prober; never claims the display, never throws. */
+    private answerQuery;
+    /**
+     * Ask the claimed relay to round-trip its terminal, with a deadline.
+     *
+     * Sharing one in-flight round trip matters: a second question while the first
+     * is unanswered would be settled by the first reply, and two windows asking at
+     * once is a normal resume, not an error.
+     */
+    private probeTerminal;
+    private settleProbe;
     sendStdout(bytes: Buffer | string): boolean;
     sendGoodbye(): void;
     close(): Promise<void>;
@@ -142,6 +197,24 @@ export declare class DisplayHost {
  * it without stealing the display.
  */
 export declare function displaySockExists(path: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * How long a prober waits for the Host's answer to {@link FRAME_QUERY}.
+ *
+ * It has to cover the relay's own two probe windows (see
+ * {@link DISPLAY_PROBE_TIMEOUT_MS}) plus the hop; the answer only takes this
+ * long when the display really is silent.
+ */
+export declare const DISPLAY_QUERY_TIMEOUT_MS = 4000;
+/**
+ * Ask a live Host whether a window is really on its session.
+ *
+ * `undefined` means the Host did not answer — an older Host that does not know
+ * the frame, or one whose event loop is stuck. Every caller must read that as
+ * "cannot tell" and never as "free": the cost of the doubt is one confirmation
+ * prompt, and the cost of guessing wrong is taking a session away from a window
+ * somebody is still typing in.
+ */
+export declare function queryDisplayAttachment(path: string, timeoutMs?: number): Promise<AttachmentVerdict | undefined>;
 /** Watches a freshly spawned Host so a crash is reported immediately. */
 export interface HostExitWatch {
     /** Resolves with the exit code (or null when killed) once the Host exits. */
@@ -271,6 +344,9 @@ export interface DisplayRelayOptions {
     signals?: Pick<NodeJS.Process, 'on' | 'off' | 'removeListener'>;
     /** Link kind for the RTT probe; defaults to this process's SSH env. */
     ssh?: boolean;
+    /** Re-measure cadences (tests); defaults to {@link RTT_RECHECK_FIRST_MS} / {@link RTT_RECHECK_MS}. */
+    rttFirstRecheckMs?: number;
+    rttRecheckMs?: number;
     /** Typing captured before this relay existed; sent to the Host after HELLO. */
     seed?: string;
     /**

package/lib/types/dsh-compat.d.ts

@@ -14,23 +14,55 @@ import type { ContextFormed } from '@deepseek-ai/dsh-llm';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import type z from '@deepseek-ai/schemastery';
+/**
+ * The source kind this plugin declares for the messages it commits itself: the
+ * plan-close nudge and the approval-denied steering notice.
+ *
+ * These used to ride the released catch-all wrapper —
+ * `<kind: 'plugin', plugin: 'dsh-ssh-tui'>` — which 0.1.5 shipped as a member and
+ * 0.1.7 deleted ("each producer declares its own `kind` in its own module; there
+ * is no shared catch-all `plugin` kind"). Worse than missing on 0.1.7: its V4
+ * native admission *refuses* the wrapper outright, so an append under that
+ * spelling throws "format v4 message requires a producer-owned source kind" and
+ * takes the whole turn down with it — which is what the plan nudge and the
+ * approval-denied notice did to any turn they fired in on a V4 session.
+ *
+ * The producer-owned spelling is the one shape both supported lines admit: the
+ * wrapper was only ever mandatory for `system/message` (`SystemMessage['source']`
+ * is the `plugin` member on 0.1.5), while user-role messages have always carried
+ * a producer's own kind — the 0.1.5 line's own `goal`, `webhook`, and
+ * `agent-instructions` producers all commit `kind: '<their name>'`.
+ */
+export declare const TUI_SOURCE_KIND = "dsh-ssh-tui";
 declare module '@deepseek-ai/dsh-llm' {
-    /**
-     * The TUI's own notice/steering messages, which it commits to the durable log
-     * with `source.kind === 'plugin'`.
-     *
-     * 0.1.5 shipped this member; 0.1.7 removed the catch-all and documents the
-     * intended pattern instead — "each producer declares its own `kind` in its
-     * own module". This is that declaration, and it keeps the committed log shape
-     * identical on both lines.
-     */
     interface MessageSourceMap {
-        plugin: {
-            kind: 'plugin';
-            plugin: string;
+        'dsh-ssh-tui': {
+            kind: 'dsh-ssh-tui';
         } & ContextFormed;
     }
 }
+/**
+ * The kind the V3-to-V4 lane gives the same messages in a converted log.
+ *
+ * The conversion lifts a released plugin wrapper to the producer's kind when it
+ * knows the plugin, and falls back to `plugin:<name>` when it does not — which is
+ * this plugin's case, so a resumed V3 session carries the prefixed spelling.
+ */
+export declare const TUI_CONVERTED_SOURCE_KIND = "plugin:dsh-ssh-tui";
+/**
+ * Whether a durable message source came from this plugin.
+ *
+ * Three spellings reach a reader: the producer-owned kind written now, the
+ * `plugin:`-prefixed compatibility kind the V3-to-V4 conversion assigns, and the
+ * original wrapper (`kind: 'plugin'` + `plugin: 'dsh-ssh-tui'`) that a log
+ * committed before this change — or an unconverted V3 file read on the 0.1.5
+ * line — still carries.
+ *
+ * @param kind - the source's `kind`, when it has one.
+ * @param plugin - the source's legacy `plugin` field, when it carries the wrapper.
+ * @returns whether this plugin produced the message.
+ */
+export declare function isTuiMessageSource(kind: unknown, plugin?: unknown): boolean;
 /**
  * Settings namespaces are branded strings at the type level on both supported
  * lines; this cast supplies the brand from a plain literal.

package/lib/types/i18n/index.d.ts

@@ -16,7 +16,7 @@ export declare const UI_LOCALE_NAMESPACE: import("@deepseek-ai/dsh-settings").Se
  * Every field is live: on 0.1.7 the section *is* this form, and only volatile
  * paths may be written (see {@link liveField}).
  */
-export declare const UI_LOCALE_SCHEMA: z<Schemastery.ObjectS<{
+export declare const UI_LOCALE_SCHEMA: z<Schemastery.ObjectS<NoInfer<{
     language: z<string>;
     skipUpdate: z<string>;
     view: z<string>;
@@ -24,7 +24,12 @@ export declare const UI_LOCALE_SCHEMA: z<Schemastery.ObjectS<{
     autoApproval: z<string>;
     /** Milliseconds a leftover, finished Host waits before exiting; 0 = never. */
     idleExit: z<number>;
-}>, Schemastery.ObjectT<{
+    /**
+     * Command run once when a question starts waiting and nobody is attached.
+     * Empty means off. See `question-wait.ts` for the environment it receives.
+     */
+    notify: z<string>;
+}>>, Schemastery.ObjectT<NoInfer<{
     language: z<string>;
     skipUpdate: z<string>;
     view: z<string>;
@@ -32,7 +37,12 @@ export declare const UI_LOCALE_SCHEMA: z<Schemastery.ObjectS<{
     autoApproval: z<string>;
     /** Milliseconds a leftover, finished Host waits before exiting; 0 = never. */
     idleExit: z<number>;
-}>>;
+    /**
+     * Command run once when a question starts waiting and nobody is attached.
+     * Empty means off. See `question-wait.ts` for the environment it receives.
+     */
+    notify: z<string>;
+}>>, "plain">;
 export declare function localeFromTag(tag: string): Locale | undefined;
 /** Pick zh/en from env, optionally after a saved settings value. */
 export declare function resolveLocale(env?: NodeJS.ProcessEnv, saved?: string): Locale;

package/lib/types/paint.d.ts

@@ -37,6 +37,27 @@ export declare function ignoreFurtherHangupSignals(): void;
 export declare function waitUntilIdleOrTimeout(isIdle: () => boolean, timeoutMs: number, now?: () => number, wait?: (ms: number) => Promise<void>): Promise<'idle' | 'timeout'>;
 /** Map a CSI-6n round-trip to a paint cadence. Unknown RTT uses the SSH default. */
 export declare function paintIntervalForRtt(rttMs: number | undefined): number;
+/**
+ * How many measurements the link's reported round-trip is taken over.
+ *
+ * Three is the smallest window where one outlier cannot move the answer and two
+ * agreeing measurements can.
+ */
+export declare const RTT_HISTORY = 3;
+/**
+ * The link's current round-trip, from the last few measurements.
+ *
+ * The median — not the latest, not the mean. The probe shares the wire with the
+ * paint it is measuring, so a single burst can read like an overloaded link, and
+ * because the cadence *and* the per-frame byte budget follow this number, one
+ * bad measurement used to sit on the footer chip (and in the paint budget) for
+ * the rest of the session. A median ignores one outlier, follows a real change
+ * as soon as two measurements agree, and averages the pair in between so the
+ * chip does not jump.
+ * @param samples - measured round-trips, oldest first; non-finite ones ignored.
+ * @returns the median in whole milliseconds, or undefined with nothing to go on.
+ */
+export declare function medianRtt(samples: readonly number[]): number | undefined;
 export declare function paintLinkLabel(kind: PaintLinkKind, intervalMs: number, probed: boolean): string;
 export type LinkQuality = 'local' | 'good' | 'ok' | 'slow' | 'poor' | 'unknown';
 /** Signal-bar quality from a measured SSH round-trip, or local TTY. */

package/lib/types/picker.d.ts

@@ -44,6 +44,18 @@ export interface SessionPickerState {
     loading?: boolean;
     /** Sessions in history that have not been read yet. */
     more?: number;
+    /**
+     * A row whose session another window is attached to, waiting for the user to
+     * confirm. Submitting such a row does not attach on its own: the lock says a
+     * window is on that session, and attaching kicks that window. The note under
+     * the row cannot prove the window is still alive, so the picker asks once
+     * instead of either refusing forever or silently stealing the session.
+     */
+    confirmTakeover?: {
+        id: string;
+        sock: string;
+        pid: number;
+    };
 }
 /** One key / control action against {@link SessionPickerState}. */
 export type SessionPickerAction = {
@@ -89,6 +101,16 @@ export type SessionPickerStep = {
 export declare function sessionSearchHaystack(session: ResumableSession): string;
 /** Whether one session matches a whitespace-separated query (every token). */
 export declare function sessionMatchesQuery(session: ResumableSession, query: string): boolean;
+/**
+ * Whether a live Host is holding this session in a window *right now*.
+ *
+ * The lock's `state` is written by the Host: `attached` while a display relay is
+ * connected, `paused` / `running-detached` once the window is gone (a dropped
+ * link, a closed window) and the Host stayed behind. Only an explicit
+ * `attached` counts — a lock from before the field existed has no state, and
+ * treating "unknown" as "in use" would block a resume that used to work.
+ */
+export declare function sessionAttachedElsewhere(session: ResumableSession): boolean;
 /** Sessions still visible under the current filter, in list order. */
 export declare function filterResumableSessions(sessions: readonly ResumableSession[], query: string): ResumableSession[];
 /** Keep `cursor` inside `[0, total)`. Empty lists pin to 0. */

package/lib/types/platform.d.ts

@@ -213,3 +213,25 @@ export declare function restrictPathToUserSync(path: string, options?: {
     mode: number;
     directory?: boolean;
 } & RestrictDeps): boolean;
+/**
+ * Whether the terminal in front of us can paint UTF-8 at all.
+ *
+ * The chrome this TUI draws — rules, status dots, the warning glyph — is
+ * Unicode. A console whose output code page is not UTF-8 (a legacy Windows
+ * console left on CP936 or CP437) and a POSIX locale that is not UTF-8 both
+ * render those bytes as mojibake, which is worse than plain ASCII: the frame
+ * still has to line up. This answers only "can it decode UTF-8", never "which
+ * terminal", so the capability table stays where it is.
+ *
+ * The decision is read from the environment, which is all a portable test can
+ * assert: `DSH_TUI_ASCII=1` forces the fallback and `=0` forbids it; otherwise
+ * a locale naming a non-UTF-8 charset (or the bare `C` / `POSIX`) opts in,
+ * and so does a Windows console whose output code page is recorded as anything
+ * but 65001. An unset locale is left alone — a UTF-8 SSH session often exports
+ * nothing, and guessing "ASCII" there would strip the chrome from the audience
+ * this TUI is built for.
+ * @param env - the environment to read (tests pass their own).
+ * @param platform - the platform the decision is for.
+ * @returns true when chrome must be drawn in ASCII.
+ */
+export declare function asciiFallbackEnabled(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;

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)
@@ -42,11 +42,15 @@ export declare const ROSTER_ROWS: readonly RosterRow[];
  * 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. What the base does *not* mount are the three rows the
- * shipped standard preset owns beyond it — the persona prompt, and the
- * `ask_user_question` / `present` tools — so those are what a TUI profile adds.
- * Written verbatim as upstream's own `dsh-web-app/presets/standard.patch.yml`
- * declares them, minus the rows the base already carries.
+ * 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. */
@@ -56,11 +60,15 @@ 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";
 /** 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 every row the standard preset\n# needs except these three: the persona prompt and the ask_user_question /\n# present tools. The profile's user layer owns them.\n";
+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;
-/** One top-level `- insert:` entry mounting exactly these rows. */
-export declare function rosterInsertEntry(rows: readonly RosterRow[]): 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

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;
+};