dsh-ssh-tui 0.8.0 → 0.8.2-rc.1

package/lib/types/screen.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The Screen contract: a whole-view surface with its own navigation state.
+ *
+ * A **Surface** (ask-user, a picker) borrows a few rows of the workspace and gives
+ * them back when the action is done: the transcript behind it never moves, and
+ * the reader returns to the same place. A **Screen** is the other thing entirely —
+ * it replaces the workspace, owns its own scrolling, and must be able to redraw
+ * itself from its state alone (a reattach after an SSH drop is a normal event, not
+ * an edge case). See `docs/decisions/b2-architecture-decisions.md` (AD-1 … AD-3).
+ *
+ * Depth is exactly one: a Screen may hold tabs, sections and detail modes of its
+ * own, but it never pushes another Screen. Nothing here allocates a stack, and
+ * nothing here renders — this module is the contract, `tui.ts` is the renderer.
+ */
+import type { Dialog, InspectDialog } from './dialogs.js';
+import type { DiffDisplayLine } from './tool-present.js';
+/**
+ * Which Screen is up. Adding one here is the only way to add one at all.
+ *
+ * `setup` is the odd one: it draws no body of its own — the wizard's rows are built
+ * from its state machine every frame — but it is a Screen in every other sense. It
+ * owns the whole view, it owns its input, it never enters the dialog queue, and it is
+ * rebuilt from state after a reattach (B2.6).
+ */
+export type ScreenKind = 'inspect' | 'report' | 'setup';
+/** The report a `report` Screen is showing. */
+export type ReportKind = 'status' | 'usage' | 'diag' | 'doctor' | 'help' | 'subagents';
+/**
+ * A Screen's whole state.
+ *
+ * Everything the renderer needs is here on purpose: nothing about the picture
+ * lives only in the paint loop, which is what makes a reattach able to rebuild the
+ * same screen, and what makes the screen testable without a terminal. `offset` is
+ * the first visible body row — the Screen's own scroll position, unrelated to the
+ * transcript's `scrollOffset` behind it.
+ */
+export interface ScreenState {
+    kind: ScreenKind;
+    /** Title row. */
+    title: string;
+    /** Body, already rendered for the width it will be shown at. */
+    lines: readonly DiffDisplayLine[];
+    /** First visible body row. */
+    offset: number;
+    /** Which report this is, when `kind === 'report'`. */
+    report?: ReportKind;
+    /** What the copy key takes while this screen is up. */
+    copyText?: string;
+    /**
+     * A confirmation line shown in place of the navigation hint.
+     *
+     * Used by an in-screen copy ("copied 412 chars") and by a Screen's own action
+     * (the doctor repair result): the row the action would otherwise push is behind
+     * this screen, and silence after an action reads as a failure.
+     */
+    notice?: string;
+    /** Child session whose live log refreshes this screen in place. */
+    subagentSessionId?: string;
+    /** `/find` already scrolled to its hit here; later repaints keep the offset. */
+    searchRevealed?: boolean;
+}
+/**
+ * The one judgement: is this dialog a Screen?
+ *
+ * A Screen is *not* a dialog — it never enters `dialogQueue`, is never replaced by
+ * a Surface and never blocks one. This function exists so that no future call site
+ * has to remember that: a screen-shaped dialog handed to the dialog path is
+ * converted here and handed to the Screen path instead, and a test pins it.
+ *
+ * Returns `undefined` for the surfaces that genuinely are dialogs (questions,
+ * confirms, the onboarding wizard).
+ */
+export declare function screenFromDialog(dialog: Dialog | InspectDialog): ScreenState | undefined;
+/**
+ * The row kind a report falls back to where there is no frame to draw on.
+ *
+ * Line mode has no Screen (and no way to dismiss one), so `/diag` and `/doctor`
+ * keep their own copyable `diag` rows there — which is also where they are read
+ * from in a transcript (`/copy error` looks for `error` or `diag`).
+ */
+export declare function reportRowKind(report: ReportKind): 'diag' | 'system';
+/** The rows a Screen lays out, top to bottom. */
+export interface ScreenLayout {
+    /** 1 when the title row is drawn. */
+    titleRows: number;
+    /** 1 when the rule under the title is drawn. */
+    dividerRows: number;
+    /** Rows available to the body; may be 0 on a terminal that short. */
+    bodyRows: number;
+    /** 1 when the navigation hint row is drawn. */
+    hintRows: number;
+    /** 1 when the compact runtime strip is drawn. */
+    stripRows: number;
+    /** 0-based index of the first body row in the painted frame. */
+    contentTop: number;
+    /** 0-based index of the hint row, or -1 when it is not drawn. */
+    hintTop: number;
+    /** 0-based index of the strip row, or -1 when it is not drawn. */
+    stripTop: number;
+}
+/**
+ * Lay a Screen out for the height the terminal has.
+ *
+ * The strip is the one row that never goes: a Screen is a place the reader can be
+ * *while the agent keeps working*, and "is it still running, is anything waiting,
+ * is the link alive" has to be answerable without leaving. After that the order
+ * gives up the least load-bearing row first — the rule under the title, then the
+ * title, then body rows — and the navigation hint goes only when there is nothing
+ * left to navigate. Measured at 8 / 12 / 20 rows in the Screen contract tests.
+ */
+export declare function screenLayout(height: number): ScreenLayout;
+/**
+ * Clamp a Screen's scroll offset to its body.
+ *
+ * The body can be shorter than the last offset the reader scrolled to (a resize, a
+ * shorter report, a live subagent log that was replaced), and an offset past the
+ * end paints an empty screen with a position readout that lies.
+ */
+export declare function clampScreenOffset(offset: number, lineCount: number, bodyRows: number): number;
+/**
+ * `1–18/64`, the position readout a Screen's footer shows.
+ *
+ * Zero lines reads `0/0` rather than `1–0/0`: the second looks like a bug in the
+ * readout instead of an empty report.
+ */
+export declare function screenPositionText(offset: number, lineCount: number, bodyRows: number): string;

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

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

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

@@ -4,6 +4,18 @@
  * labels, and ordering, so both surfaces offer the same sessions.
  */
 import { listAttachableHosts } from './session-lock.js';
+/** Delete one session's on-disk artifacts (log directory), best effort. */
+/**
+ * Delete one session's artifacts by id.
+ *
+ * `false` means the persistence layer could not locate it (already gone, or a
+ * service that does not expose `locate`) — never an error worth surfacing, since
+ * the only caller is tidying up on the way out.
+ * @param persistence - the session persistence service.
+ * @param id - the session id.
+ * @returns true when a directory was found and removed.
+ */
+export declare function pruneSessionById(persistence: object | undefined, id: string): Promise<boolean>;
 /** Last path segment for the footer chip (`\root\genshin\srv` → `srv`). */
 export declare function sessionCwdLabel(cwd: string): string;
 export declare function formatFooterCwd(cwd: string): string;
@@ -88,6 +100,28 @@ export declare function openResumableSessionPager(persistence: object, currentId
     listHosts?: typeof listAttachableHosts;
     indexPath?: string;
 }): Promise<ResumableSessionPager>;
+/**
+ * Delete every session that never saw user input, and report what happened.
+ *
+ * The picker prunes these as it resolves them, but only for the surface that
+ * looks at them: a launch that died before doing anything kept showing up in
+ * *other* profiles' menus (the web session list reads the same artifacts without
+ * this filter). So the same rule is offered as an explicit sweep, which is also
+ * what `/cleanup` runs.
+ * @param persistence - the session persistence service.
+ * @param currentId - the live session, never a candidate for deletion.
+ * @param options - `listHosts` for test injection.
+ * @returns how many were deleted, how many were kept, and how many could not be
+ *   read (an unreadable log is kept: it might be a live writer).
+ */
+export declare function pruneBlankSessions(persistence: object, currentId: string, options?: {
+    listHosts?: typeof listAttachableHosts;
+    dryRun?: boolean;
+}): Promise<{
+    pruned: number;
+    kept: number;
+    unreadable: number;
+}>;
 /**
  * List resumable top-level sessions, newest first.
  *

package/lib/types/startup.d.ts

@@ -6,6 +6,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { SessionId } from '@deepseek-ai/dsh-session';
+import { type DisplayMode } from './display-mode.js';
 /** Service key under which the parsed TUI launch options are provided. */
 export declare const SSH_TUI_STARTUP_SERVICE = "sshTuiStartup";
 /** Config `id` of the agent-loop entry the TUI drives. */
@@ -24,6 +25,11 @@ export interface SshTuiStartup {
     readonly provider?: string;
     /** ANSI color opt-out supplied at launch. */
     readonly noColor?: boolean;
+    /**
+     * Where the bytes go: `stdio` when the parent speaks the display protocol on
+     * stdin/stdout (a GUI, a web terminal, a harness) instead of owning a TTY.
+     */
+    readonly display?: DisplayMode;
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -32,6 +38,30 @@ declare module '@deepseek-ai/cordis' {
 }
 export declare const name = "ssh-tui-startup";
 export declare const inject: string[];
+/**
+ * Whether another application already owns this profile's command line.
+ *
+ * `@deepseek-ai/dsh-cmdline` has **no arbitration between apps**: every app plugin is
+ * handed the same argv and parses it with its own grammar, and an unknown flag is
+ * `program.error`, which exits the process. A profile that hosts two apps therefore
+ * requires the second one to understand the first one's flags — and the desktop
+ * application passes `--no-open` (the web app's own flag) to its host, so this row's
+ * grammar rejected it: the host exited 1, the application reported
+ * `dsh desktop host exited with 1: error: unknown option '--no-open'` and died. Only
+ * the *startup* row did that; the TUI row never ran, which is why 0.8.1's inert-when-
+ * headless fix could not have caught it.
+ *
+ * The signals are two, and they overlap on purpose:
+ *
+ * - the launcher facts (`desktopLauncher`): an Electron host, `DeepSeek Harness.exe`,
+ *   or `app.asar` in argv — true whatever the profile's row order is;
+ * - `webStartup`: the web app provides it as soon as it has parsed, and a `web`
+ *   profile is not a terminal profile in any case.
+ *
+ * Stepping aside is not a degraded mode: the TUI row `inject`s `sshTuiStartup`, so
+ * nothing of this plugin activates and the host keeps its own grammar and its own app.
+ */
+export declare function anotherAppOwnsCommandLine(ctx: Context): boolean;
 /**
  * Build the TUI command grammar and provide the session identity for the
  * agent-loop row plus the {@link SshTuiStartup} service. On `--help` or a

package/lib/types/stats.d.ts

@@ -14,12 +14,41 @@
  * - decode rate needs a finite, non-negative output token count.
  */
 import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import { type ThroughputView } from './throughput.js';
 export interface SessionUsage {
     inputTokens: number;
     outputTokens: number;
+    /** Sum of the full-call totals the harness itself reported, when it reported one. */
+    reportedTokens: number;
+    /** Steps whose usage carried a harness total. */
+    reportedSteps: number;
+    /** Steps whose usage carried none, so the billed parts had to stand in. */
+    unreportedSteps: number;
     cacheReadTokens: number;
     cacheWriteTokens: number;
 }
+/** The session-size number the second row shows, and how it was derived. */
+export interface SessionTokenTotal {
+    tokens: number;
+    /**
+     * `harness` when every usage sample carried the harness's own total; `sum`
+     * when some step's billed parts had to be added in instead.
+     */
+    basis: 'harness' | 'sum';
+}
+/**
+ * How many tokens this session has moved, on the accounting the harness
+ * published.
+ *
+ * The harness is the authority: a `totalTokens` it reports is a full-call total
+ * whose parts are defined provider by provider — pi-ai's own adapters build it
+ * as prompt + output + cache read + cache write — and re-deriving one from the
+ * three prompt counters plus output is exactly the arithmetic that
+ * double-counts on a provider that folds cache into its prompt count. So
+ * reported totals are summed, and only a step that reported none contributes
+ * its billed parts. The basis says which happened, and `/status` prints it.
+ */
+export declare function sessionTokenTotal(usage: SessionUsage): SessionTokenTotal | undefined;
 export interface SessionStatsSnapshot {
     turns: number;
     steps: number;
@@ -29,6 +58,12 @@ export interface SessionStatsSnapshot {
     ttftSteps: number;
     decodeMs: number;
     decodeTokens: number;
+    /** Tokens and milliseconds of the most recent settled step alone. */
+    lastDecodeMs: number;
+    lastDecodeTokens: number;
+    /** Decode totals excluding the step that is currently open. */
+    settledDecodeMs: number;
+    settledDecodeTokens: number;
     usage: SessionUsage;
 }
 /** Flat view of the same numbers, for the footer's stats line. */
@@ -45,6 +80,7 @@ export interface SessionStatsRow {
     outputTokens: number;
     cacheReadTokens: number;
     cacheWriteTokens: number;
+    totalTokens: number;
 }
 export interface OpenStep {
     turn: number;
@@ -52,7 +88,7 @@ export interface OpenStep {
 }
 export declare function emptySessionUsage(): SessionUsage;
 export declare function emptySessionStats(): SessionStatsSnapshot;
-/** Flatten a snapshot into the footer's row shape. */
+/** Flatten a snapshot into the legacy stats-row shape. */
 export declare function statsRowOf(stats: SessionStatsSnapshot): SessionStatsRow;
 /**
  * Accumulates the stats the footer and `/status` show as session events arrive.
@@ -65,10 +101,35 @@ export declare class SessionStatsTracker {
     private readonly usageByStep;
     private readonly pendingToolTimes;
     private lastTurn;
+    /** Live decode estimate for the step currently streaming. */
+    private readonly live;
     /** The step a live chunk belongs to when the host frame carried none. */
     currentStep(): OpenStep | undefined;
+    /**
+     * The open step's two clocks, for the status row's elapsed suffix.
+     *
+     * Both are host wall clocks, so a caller may subtract them from `Date.now()`
+     * without a translation. `firstTokenAt` is absent until the step's first
+     * delta, which is exactly the difference between "the request is out" and
+     * "the model is talking".
+     */
+    stepClocks(): {
+        startedAt?: number;
+        firstTokenAt?: number;
+    };
     /** `step/start`: opens the clock LLM time, TTFT and decode are measured from. */
     noteStepStart(turn: number, step: number, time: number): void;
+    /**
+     * A live fragment of model output, for the running throughput estimate.
+     *
+     * The text itself travels: the estimate is tokens per character, and how many
+     * tokens a character is worth depends on the script the fragment is written in.
+     * @param text - the fragment.
+     * @param time - wall clock the fragment arrived at.
+     */
+    noteDelta(text: string, time?: number): void;
+    /** The running throughput estimate, settled value included. */
+    throughput(now?: number): ThroughputView;
     /** The first token delta of the open step latches its TTFT clock. */
     noteFirstToken(turn: number, step: number, time: number): void;
     /** Replace one step's usage sample so a repeated report never double counts. */
@@ -87,6 +148,8 @@ export declare class SessionStatsTracker {
     }): void;
     /** `tool/call`: start the tool clock for this call. */
     noteToolStart(callId: string, time: number): void;
+    /** When a still-open tool call started, for the status row's elapsed suffix. */
+    toolStartedAt(callId: string): number | undefined;
     /** `tool/result`: add the elapsed tool time, once. */
     noteToolEnd(callId: string, time: number): void;
     /** `step/end`: count the step, and forget the step's usage dedupe key. */

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

@@ -44,13 +44,14 @@ export declare function canonicalProviderId(provider: string | undefined): strin
  */
 export declare function subagentProviderDiffers(parent: string | undefined, child: string | undefined): boolean;
 /**
- * Identity SGR for a subagent chip title. Same provider as the parent stays
- * the violet used since the courtesy-name work; a different provider uses
- * cyan so the foreign route is visible without a second color layer.
+ * Which identity role a subagent chip title wears.
+ *
+ * The colours themselves live in `theme.ts`: the same provider as the parent
+ * gets the identity role, a different provider gets the foreign one, and the
+ * palette decides what those look like (under `mono` they become an attribute,
+ * because the distinction has to survive a terminal without colour).
  */
-export declare const SUBAGENT_IDENTITY_SGR = "38;5;141";
-export declare const SUBAGENT_FOREIGN_SGR = "38;5;80";
-export declare function subagentIdentitySgr(foreign: boolean): typeof SUBAGENT_IDENTITY_SGR | typeof SUBAGENT_FOREIGN_SGR;
+export declare function subagentIdentityRole(foreign: boolean): 'subagent-self' | 'subagent-foreign';
 /**
  * True when the stored subagent model still belongs to the parent provider
  * family. An explicit leftover DeepSeek flash id after switching to xAI is

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

@@ -40,6 +40,16 @@ export declare function waitCardCopy(input: {
 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;
+/**
+ * Whether chrome is being drawn in ASCII, for renderers that pick the glyph run
+ * themselves.
+ *
+ * `pinEmojiCells` translates them anyway; asking is for the case where the
+ * *shape* differs rather than just the character — a metre whose filled cell is
+ * `#` reads as `##..`, not as `#..#`, so the renderer wants to know before it
+ * counts and pads.
+ */
+export declare function asciiChromeEnabled(): boolean;
 /**
  * Rewrite one string's chrome into ASCII when the terminal cannot decode UTF-8.
  *
@@ -53,25 +63,87 @@ export declare function resetAsciiChrome(): void;
  */
 export declare function mapAsciiChrome(text: string): string;
 /**
- * Terminal cell width for one string.
+ * Resolve the ambiguous-glyph policy for this process.
  *
- * Match glibc wcwidth / typical UTF-8 SSH terminals: CJK ideographs and
- * fullwidth forms occupy two cells; East-Asian Ambiguous box-drawing and
- * ornaments (`─`, `●`, `·`, `▸`, `❯`, Braille spinners) occupy one. Counting
- * those ambiguous glyphs as two made `repeatToWidth('─', cols)` paint a
- * half-width rule and parked the input cursor half a cell past the text.
+ * Cheap enough to call once per line (it compares one string) and far too
+ * expensive to call per character, which is the distinction that matters.
+ * @param env - the environment to read.
+ * @param onTerminal - whether the output is a terminal at all.
+ * @returns whether the glyphs are two cells wide, and whether the second cell is
+ *   ours to reserve.
+ */
+export declare function ambiguousPolicy(env?: NodeJS.ProcessEnv, onTerminal?: boolean): {
+    wide: boolean;
+    reserve: boolean;
+};
+/**
+ * Record what the terminal's own answer said about these glyphs.
  *
- * Emoji-bearing symbols are the exception: a terminal with an emoji font draws
- * a symbol the monospace font lacks with a colour glyph that is wider than the
- * cell it advances, so they are budgeted two cells. {@link pinEmojiCells} makes
- * the terminal actually spend both: VS15 asks for the narrow text form, and a
- * reserving space clears the second cell when the run does not already end in
- * one. Budgeting two cells without clearing the second is what left `✖`
- * overlapping the `|` beside it while every `▶` row came up a cell short.
+ * Called by the launcher after measuring; also the escape hatch for a caller
+ * that knows better than the locale (a relay that has already measured for its
+ * own accounting, or a test).
+ * @param wide - true when the terminal advances two cells, false for one, or
+ *   undefined to fall back to the locale.
+ */
+export declare function setAmbiguousWidthMeasured(wide: boolean | undefined): void;
+/**
+ * Force the reserve behaviour, for a caller that measured the same terminal for
+ * its own accounting (a relay) or a test.
+ * @param reserve - whether to spend a space after each ambiguous glyph.
+ */
+export declare function setAmbiguousWidthReserve(reserve: boolean): void;
+/** Whether the second cell is currently reserved with a space. */
+export declare function ambiguousWidthReserved(): boolean;
+/**
+ * Cells one character costs in this TUI's layout.
  *
- * Overflow into the input box is handled by clipping/padding painted rows to
- * the measured column count, not by inflating glyph width.
+ * The reserve case still costs two: the glyph advances one cell and the reserving
+ * space takes the next, so the layout must budget both or every row holding one
+ * comes up short. Non-ambiguous characters are unchanged.
+ * @param cp - the code point.
+ * @returns 0, 1 or 2 cells.
  */
+export declare function ambiguousCellCost(cp: number): number;
+/** What the last measurement decided, for diagnostics and tests. */
+export declare function ambiguousWidthMeasured(): boolean | undefined;
+/**
+ * Whether ambiguous glyphs in {@link AMBIGUOUS_WIDE_RANGES} are drawn two cells
+ * wide here.
+ *
+ * `DSH_TUI_AMBIGUOUS_WIDTH=1|2` answers outright. Otherwise the locale decides,
+ * and only when there really is a terminal: a zh/ja/ko locale means the terminal
+ * is very likely using a CJK font, where these glyphs are full width. The UI
+ * language is deliberately *not* consulted — a Chinese reader on a Western
+ * terminal has narrow glyphs, and typing in Chinese does not change the font
+ * metrics.
+ * @param env - the environment to read (tests pass their own).
+ * @param onTerminal - whether the output is a terminal at all; a pipe or a test
+ *   harness has no font metrics, so there the narrow default applies.
+ * @returns true when those glyphs should be budgeted two cells.
+ */
+export declare function ambiguousWidthIsTwo(env?: NodeJS.ProcessEnv, onTerminal?: boolean): boolean;
+/**
+ * Cells one *code unit* costs at its position, given a resolved policy.
+ *
+ * The per-character core of {@link displayWidth}, split out for the
+ * callers that walk a string themselves (clipping, truncation, wrapping): they
+ * resolve {@link ambiguousPolicy} once per string and then ask this per
+ * character, instead of paying `displayWidth`'s policy lookup and ASCII mapping
+ * for every character of every row. A profile of a window drag put 56% of the
+ * samples in that lookup, because the clipping loops are O(n²) in a way nothing
+ * about their shape advertises: `clipAnsiToWidth` calls this for each character,
+ * and `truncateToWidth` re-measures the whole remainder inside its loop.
+ *
+ * ASCII is answered from its code point before any table lookup: it is the
+ * overwhelming majority of every row, and it can never be ambiguous or wide.
+ * @param cp - the code point.
+ * @param policy - the resolved policy, as returned by {@link ambiguousPolicy}.
+ * @returns 0, 1 or 2 cells.
+ */
+export declare function charCellWidth(cp: number, policy: {
+    wide: boolean;
+    reserve: boolean;
+}): number;
 export declare function displayWidth(text: string): number;
 /**
  * Make a painted row spend the two cells {@link displayWidth} budgets for every
@@ -176,7 +248,19 @@ export declare function hrefAtColumn(hits: readonly PaintedLinkHit[], col: numbe
  * headings, quotes, lists, rules, links and inline spans keep their own ANSI.
  */
 export declare function renderMarkdownLines(text: string, width: number, color: boolean, hyperlinks?: boolean): string[];
-/** Cut one line to fit a width, appending an ellipsis when truncated. */
+/**
+ * Cut **one line** to fit a width, appending an ellipsis when truncated.
+ *
+ * A line break is not a character in a row: it moves the terminal to the next row,
+ * and a frame that addresses its rows absolutely (`ESC[row;1H`) then writes every
+ * following row one line off — content lands on the composer, on the footer, and on
+ * top of whatever was already there. `sanitizeTerminalText` keeps LF/CR on purpose
+ * (it also sanitizes multi-line bodies), so the collapse happens here, where the
+ * contract is "one row": each break becomes a single space, which keeps the string
+ * the same *length* — callers that pass this result into `paintSegmentedLine` rely
+ * on character offsets into the text they built, and a collapsing replacement would
+ * silently move every colour segment.
+ */
 export declare function truncateToWidth(text: string, width: number): string;
 /**
  * Clip an already-styled ANSI line to `width` terminal cells without dropping
@@ -201,14 +285,6 @@ export interface InputView {
     cursorOffset: number;
     folded: boolean;
 }
-/**
- * Fold a long input into one terminal row around the cursor.
- *
- * Newlines from a paste are display-only: they do not occupy cells, so a
- * naive `displayWidth(input)` under-counts a multi-line paste and parks the
- * caret in the middle of later text. Fold the *current line* (between the
- * surrounding newlines) and keep `\n` out of the visible slice.
- */
 export declare function foldInputView(input: string, cursor: number, maxWidth: number): InputView;
 /**
  * Map a character index in the input text to its visual (row, col) after the

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

@@ -28,6 +28,7 @@ export declare const RTT_OUTLIER_RATIO = 0.25;
 export declare function stripCursorReplies(text: string): {
     text: string;
     replies: number;
+    last?: string;
 };
 /**
  * Drop cursor replies from a byte stream that is otherwise user input.
@@ -38,6 +39,8 @@ export declare function stripCursorReplies(text: string): {
  */
 export declare class TerminalInputFilter {
     private held;
+    /** The most recent cursor reply this filter swallowed, if any. */
+    lastReply: string | undefined;
     push(text: string): {
         forward: string;
         replies: number;
@@ -103,10 +106,26 @@ export declare class TerminalInputPump {
     private slowestSampleMs;
     private holdTimer;
     private listening;
+    /** Set by {@link quiet}: the held tail is dropped instead of forwarded. */
+    private dropping;
     readonly ssh: boolean;
     constructor(options: TerminalInputPumpOptions);
     start(): void;
     stop(): void;
+    /**
+     * Wait one more round trip before letting go of the terminal.
+     *
+     * A cursor reply can still be on the wire when a relay stops. The terminal
+     * answers a Device Status Report after the round trip, so on a slow SSH link
+     * that is hundreds of milliseconds after the request; restoring cooked mode
+     * first lets the tty echo the answer as literal `^[[25;1R` text at the user's
+     * prompt, and leaves it in the tty queue for the shell to read as typing.
+     * Staying in raw mode for one round trip swallows it instead. Typing that
+     * lands in this window is forwarded as usual — the window exists to drop
+     * answers, not keystrokes.
+     * @param graceMs - how long the terminal may still owe us a reply.
+     */
+    handBack(graceMs?: number): Promise<void>;
     /**
      * Ask the terminal for its cursor a few times and report the round-trip that
      * best describes the link. `undefined` means the terminal never answered in
@@ -170,5 +189,23 @@ export declare class TerminalInputPump {
      * from being attributed to the next request.
      */
     private answer;
+    /**
+     * Ask the terminal for its cursor after printing `probe`, and report where it
+     * says the cursor ended up.
+     *
+     * This is the measurement half of the pump: `measure()` answers "how long did
+     * the round trip take", this answers "how far did the cursor move". Replies are
+     * swallowed by the same filter that swallows them for the timing probe — which
+     * matters, because a reply nobody consumes is echoed on screen as literal
+     * `^[[1;5R` text, and that is exactly what a hand-rolled version of this did.
+     * @param probe - the text to print before asking (cleared afterwards).
+     * @param timeoutMs - how long to wait for the answer.
+     * @returns the coordinates the terminal reported, or undefined when it stayed
+     *   silent.
+     */
+    askPosition(probe: string, timeoutMs?: number): Promise<{
+        row: number;
+        column: number;
+    } | undefined>;
     private scheduleHold;
 }