dsh-ssh-tui 0.8.1 → 0.8.2

package/lib/types/footer.d.ts

@@ -1,276 +1,26 @@
 /**
- * Footer stats, status identity, context-pressure chips, and `/status` report.
- */
-import { type ColorDepth } from './color-depth.js';
-import { type QuotaPeriod, type QuotaSnapshot, type QuotaSource } from './quota.js';
-import type { DisconnectPolicyName } from './transcript-types.js';
-export declare const WAIT_INDICATOR_MS = 8000;
-/** Compact token count, matching the web stats line (517 / 12.2K / 1.2M). */
-export declare function formatTokens(n: number): string;
-/**
- * Prompt occupancy of the next request, from DSH `contextPressure`.
- * Provider-agnostic: uses the routed model's advertised window, not a
- * hardcoded xAI size. Compaction-basic still owns in-turn pressure at 80%.
- */
-export declare const CONTEXT_PRESSURE_WARN_RATIO = 0.8;
-export declare const CONTEXT_PRESSURE_DANGER_RATIO = 0.95;
-/** Idle auto-compact starts here so recovery finishes before the 80% in-turn trigger. */
-export declare const CONTEXT_IDLE_COMPACT_RATIO = 0.72;
-export interface ContextPressureSample {
-    usedTokens: number;
-    contextWindow: number;
-}
-export interface ContextPressureView {
-    usedTokens: number;
-    contextWindow: number;
-    percent: number;
-    level: 'ok' | 'warn' | 'danger';
-}
-/** Prompt-side occupancy of one usage sample: uncached input plus cache traffic. */
-export declare function promptPressureTokens(usage: {
-    inputTokens: number;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-}): number;
-/** Prefer the next-request projection; fall back to last-request pressure. */
-export declare function contextPressureUsedTokens(pressure: {
-    projectedTokens?: number;
-    pressureTokens?: number;
-} | undefined): number | undefined;
-export declare function parseContextPressure(value: unknown): ContextPressureSample | undefined;
-export declare function contextPressureView(sample: ContextPressureSample): ContextPressureView;
-/**
- * 8-segment Braille ring. Empty `⣀`; full `⣿`. Width is always 1 cell.
- * Index is `ceil(percent / 12.5)` clamped to 0..8.
- */
-export declare const CONTEXT_RING_EMPTY = "\u28C0";
-export declare const CONTEXT_RING_SEGMENTS: readonly ["⣀", "⠉", "⠋", "⠛", "⠞", "⠟", "⠿", "⡿", "⣿"];
-/** The full cell of the same Braille family, for bars built like the ring. */
-export declare const CONTEXT_RING_FULL = "\u28FF";
-export declare function formatContextPressureRing(percent: number): string;
-export declare function contextPressureRingColor(level: ContextPressureView['level']): string;
-export declare function formatContextPressureChip(view: ContextPressureView, color?: boolean): string;
-export declare function formatContextPressureStatusLine(view: ContextPressureView | undefined): string;
-export declare function contextPressureAlertText(view: ContextPressureView): string;
-export declare function shouldIdleAutoCompact(view: ContextPressureView | undefined): boolean;
-/** Compact duration, matching the web stats line (45.2s / 2m42s). */
-export declare function formatDuration(ms: number): string;
-export declare function formatTokensPerSecond(tokensPerSecond: number): string;
-export declare function providerShortCode(provider: string): string;
-export interface FooterStatsInput {
-    turns: number;
-    steps: number;
-    llmMs: number;
-    toolMs: number;
-    ttftMs: number;
-    ttftSteps: number;
-    decodeMs: number;
-    decodeTokens: number;
-    inputTokens: number;
-    outputTokens: number;
-    cacheReadTokens: number;
-    cacheWriteTokens: number;
-}
-/** Stats groups in drop order (last is dropped first when the row is too wide). */
-export declare function footerStatsGroups(stats: FooterStatsInput): string[];
-/**
- * One group in the status strip, with the graphic-only form a narrow terminal
- * keeps. `priority` orders the losses: 0 is the last thing to go.
- */
-export interface FooterChip {
-    id: string;
-    /** Glyph plus text: what a wide terminal shows. */
-    long: string;
-    /** Glyph only, or `''` for a group that is pure text. */
-    short: string;
-    priority: number;
-}
-/**
- * Fit an ordered strip into `width` cells, losing text before graphics.
+ * The footer, in four parts — and the module every caller has always imported.
  *
- * The old fitter dropped whole groups from the end, so a narrow terminal lost
- * the ⚠ and the context ring — the two signals that say something is wrong —
- * while keeping long numeric groups. Two passes now: every chip trades its text
- * for its glyph in reverse priority order, and only then do whole groups go,
- * again lowest priority first. The result never exceeds the width.
+ * `tui.ts` paints from here, `/status` reports from here, and a dozen tests
+ * reach in through this path. The pass that turned the strip into a status row
+ * split the file along the four responsibilities that had grown together inside
+ * it; this module stays as the barrel so that split cost no call site:
  *
- * Chips may carry SGR accents (the link pips, the ⚠) and the caller may pass a
- * styled separator, so both the measurement and the final cut are ANSI-aware:
- * feeding styled text to a plain-text truncator strips the accent's `ESC` and
- * leaves its `[32m` body on the grid.
- */
-export declare function fitFooterChips(chips: readonly FooterChip[], width: number, separator?: string): string;
-/**
- * The roster's health as a chip: absent means `/mode` cannot switch presets and
- * the preset-owned tools are missing. It leads the strip and keeps its glyph
- * longest, because it is the one group that reports a broken install.
- */
-export declare function footerHealthChip(missing: boolean, color?: boolean, 
-/** Which rows are missing: the 0.1.5 roster, or the 0.1.7 agent plane. */
-kind?: 'roster' | 'agent-plane'): FooterChip | undefined;
-export declare function fitFooterStatsLine(chip: string, groups: readonly string[], width: number): string;
-export type FooterActivityKind = 'plan-review' | 'waiting' | 'compacting' | 'retry' | 'subagents' | 'tools' | 'plan-open' | 'plan-pending' | 'goal' | 'waiting-llm' | 'idle';
-export interface FooterStatusInput {
-    running: boolean;
-    planReview: boolean;
-    waitingQuestion: boolean;
-    compacting: boolean;
-    retry?: {
-        retry: number;
-        maxRetries: number;
-    };
-    subagents: number;
-    tools: number;
-    planLeftOpen: boolean;
-    planPending: boolean;
-    planActive: boolean;
-    goalPhase?: 'active' | 'paused' | 'blocked';
-    idleMs: number;
-    model: string;
-    effort?: string;
-    preset?: string;
-    provider: string;
-    parentModel: string;
-    subModel: string;
-    /** Explicit `/submodel` provider override; undefined means "inherit parent". */
-    subProvider?: string;
-    /** Explicit `/subeffort` override for subagent children. */
-    subEffort?: string;
-    quotaCode?: string;
-    quotaPercent?: number;
-    /** Which rolling window `quotaPercent` belongs to: tagged `5Hr`/`1Wk`/`1Mo`. */
-    quotaPeriod?: QuotaPeriod;
-    /** The provider has a quota surface but no reading yet: paint `░░░░░░░░ ?%`. */
-    quotaUnknown?: boolean;
-    contextChip?: string;
-    balanceText?: string;
-    search?: {
-        index: number;
-        total: number;
-    };
-    foldedInput: boolean;
-    multiLineInput: boolean;
-    queued: number;
-    cwdLabel?: string;
-    compactView?: boolean;
-}
-export declare function footerActivity(input: FooterStatusInput): {
-    kind: FooterActivityKind;
-    text: string;
-};
-/** Short remaining-quota bar: 8 pips, filled from the left. */
-export declare function formatQuotaBar(remainingPercent: number, width?: number): string;
-/**
- * `sub:<model>` chip for the identity row: `sub:grok-4.5`, or
- * `sub:grok-4.5(xhigh)` when an explicit `/subeffort` is set.
+ * - `footer-format.ts`      — a value in, text out (and the pressure reading).
+ * - `footer-meters.ts`      — the three meter primitives.
+ * - `footer-budget.ts`      — the responsive degradation ladder and the row.
+ * - `footer-layout.ts`      — the two chrome rows, and `/status`.
  *
- * It shows the model name only, like the parent's own chip, unless `/submodel`
- * pinned a different provider — then `sub:xai/grok-4.5` so the foreign route
- * is visible on the identity row as well as the recolored chip.
- */
-export declare function subagentRouteLabel(model: string, provider?: string, effort?: string): string;
-/**
- * Paint the `sub:` chip on an otherwise muted status line.
+ * The one helper they all share — `accent`, the "paint this run in this role's
+ * colour" primitive — lives in `color-depth.ts` beside `downgradeSgr`, which is
+ * where "what can this terminal take" is already answered.
  *
- * Only a *foreign* route is accented: cyan when `/submodel` pinned a supplier
- * the parent is not on. A child that follows the parent (or that was pinned
- * back onto the parent's own provider) keeps the identity row's mute — the
- * accent means "this route is not your parent's", and spending it on every
- * child made the following case look pinned.
- *
- * The mute (`90`) is reopened after the chip so the rest of the identity row
- * stays dim.
- */
-export declare function paintFooterSubagentChip(line: string, chip: string, foreign: boolean, muteSgr?: string, depth?: ColorDepth, identitySgr?: string): string;
-export declare function footerSubagentForeign(input: Pick<FooterStatusInput, 'provider' | 'subProvider'>): boolean;
-/**
- * The model as the footer shows it: the model's own name, without a
- * `provider/model` route prefix.
- *
- * Some providers carry the vendor in the model id (`xai/grok-4.6`,
- * `deepseek-official/deepseek-v4-flash`). The route is worth a row in the header
- * and in `/status`; in the status line it spent cells on something the reader
- * already knows, and it pushed the quota badge towards the drop edge.
- * `sub:` routes keep their provider on purpose — that is a *different* route
- * from the parent's, and hiding it would make the two indistinguishable.
- */
-export declare function shortModelName(model: string): string;
-export declare function footerIdentityParts(input: FooterStatusInput): string[];
-/**
- * `SuperGrok 5Hr ███████░ 82%` — short plan badge, the window the number belongs
- * to, then the bar.
- *
- * The tags are fixed technical labels (`5Hr` / `1Wk` / `1Mo`) rather than
- * localized words: they sit in a footer that is already fighting for cells, and
- * a window tag that changes with the locale would be unreadable in a screenshot
- * or a bug report. Everything else about the window (label, reset time, detail)
- * stays in `/quota`.
- */
-export declare function formatFooterQuota(percent: number, code?: string, period?: QuotaPeriod): string;
-/**
- * The quota widget before the first reading arrives, or while the provider
- * cannot be reached: an empty bar and a question mark.
- *
- * Deliberately not `0%`: an unreachable quota API is not a used-up quota, and a
- * number the footer cannot back up is worse than no number. The bar is there
- * from the first frame so the row does not jump when the reading lands.
- */
-export declare function formatQuotaUnknown(): string;
-/** Fixed-width tag for the window a footer quota number belongs to. */
-export declare function quotaWindowTag(period: QuotaPeriod | undefined): string;
-/**
- * The badge the footer shows instead of the billing plan's own label:
- * `SuperGrok`, `OC·GO` (OpenCode Go), `CC·GOAT` (Command Code Goat).
- *
- * The long names live in `/quota`; this one has to survive next to a model id.
- * Without a `source` (a hand-built snapshot) the plan label is matched instead,
- * so old callers and tests keep a sensible badge.
- */
-export declare function shortQuotaPlanName(snapshot: {
-    plan: string;
-    source?: QuotaSource;
-}): string;
-/**
- * Drop the Go / SuperGrok plan name from a quota identity part, keeping the
- * remaining-percent bar. Returns true when a part was rewritten.
- */
-export declare function dropFooterQuotaPlanName(parts: string[]): boolean;
-export declare function fitFooterStatusLine(activity: string, identity: readonly string[], width: number): string;
-export interface StatusReportInput {
-    sessionId: string;
-    pluginVersion: string;
-    provider: string;
-    model: string;
-    effort?: string;
-    agentStatus: string;
-    preset: string;
-    activeSubagents: number;
-    plan: 'off' | 'pending' | 'on';
-    paint: string;
-    disconnect?: DisconnectPolicyName;
-    waitingQuestions: number;
-    quota?: QuotaSnapshot;
-    context?: ContextPressureView;
-    parentModel?: string;
-    subProvider?: string;
-    subModel: string;
-    cwd?: string;
-}
-/** Lines printed by `/status` — SSH first-boot diagnostics, no extra command. */
-export declare function formatStatusReport(input: StatusReportInput): string[];
-/** Human-facing kind for a live LLM route. */
-export declare function describeProviderRoute(provider: string): {
-    kind: string;
-    short: string;
-};
-/** Routes that authenticate without a harness API-key credential. */
-export declare function providerUsesLocalOAuth(provider: string): boolean;
-/**
- * Whether a provider has a quota surface at all, without asking it.
+ * Import from here unless you are inside the footer; the four modules import
+ * each other in exactly that order and never back.
  *
- * The footer paints a quota widget from the first frame — an empty bar and `?%`
- * until a reading arrives — so it needs to tell "this provider will have one"
- * from "this provider reports a balance instead" (DeepSeek) or nothing at all.
- * Every branch is a synchronous settings read, so a repaint never does IO.
+ * @module dsh-ssh-tui/footer
  */
-export declare function providerHasQuotaSurface(provider: string, llmPiAiSection: unknown): boolean;
+export * from './footer-format.js';
+export * from './footer-meters.js';
+export * from './footer-budget.js';
+export * from './footer-layout.js';

package/lib/types/paint.d.ts

@@ -37,6 +37,35 @@ 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;
+/**
+ * Where the paint cadence came from: a measured round trip, an explicit
+ * `DSH_TUI_PAINT_MS`, a local TTY's constant, or a probe that never answered.
+ */
+export type PaintCadenceSource = 'measured' | 'configured' | 'local' | 'unprobed';
+/** The redraw budget a drag assumes on a link whose round trip was never measured. */
+export declare const RESIZE_UNKNOWN_LINK_BUDGET_MS = 200;
+/**
+ * How long one frame takes to reach the terminal, for pacing a drag.
+ *
+ * Two of the four sources are an *answer*: `paintIntervalForRtt` already turned a
+ * measured round trip into a cadence, and an explicit `DSH_TUI_PAINT_MS` is the
+ * user's own. The other two are not, and they are not the same kind of guess:
+ *
+ * - a local TTY's cadence is a constant about a link that is not a link, so it is
+ *   used as it stands;
+ * - an **unprobed** link's interval is the SSH default — a number nobody measured
+ *   — and pacing frames by it composes them faster than the link can deliver them,
+ *   which queues stale geometries behind each other and reads as a drag that
+ *   freezes and jumps. That case gets a deliberately slow budget instead.
+ *
+ * Nothing here claims a round trip: the status row keeps painting `SSH ○○○○ 160ms`
+ * when the probe never answered, and this budget stays an internal pacing floor.
+ * @param link - which kind of link the session is on.
+ * @param source - where the cadence came from.
+ * @param intervalMs - the cadence in force.
+ * @returns milliseconds one frame needs, at least.
+ */
+export declare function linkRedrawBudgetMs(link: PaintLinkKind, source: PaintCadenceSource, intervalMs: number): number;
 /**
  * How many measurements the link's reported round-trip is taken over.
  *
@@ -104,6 +133,25 @@ export interface PaintOptions {
     cursorColumn: number;
     /** Keep the cursor hidden (session picker). Default shows it on the input. */
     hideCursor?: boolean;
+    /**
+     * Never touch a row above this index, even when the size changed.
+     *
+     * A window drag repaints the whole screen on every event, and a frame's size is
+     * proportional to the width, so the *growing* direction is the expensive one:
+     * each frame is bigger than the last while the terminal drains at a fixed rate,
+     * the backlog compounds, and the screen keeps moving after the pointer has
+     * stopped (measured against a byte-rate-limited consumer: 30–44 ms of leftover
+     * drain growing, against 0–10 ms shrinking). The transcript is not what that
+     * frame is needed for — the terminal reflows the grid it already holds — so a
+     * drag paints the chrome and leaves the transcript to the terminal: a frame
+     * about 1/6 the size, flat in the column count. `paintTailBudget` already
+     * decides when the transcript may be left behind; this is the frame's half of
+     * the same decision.
+     *
+     * A frame with `dirtyFrom` never clears the screen: `\x1b[H\x1b[J` is precisely
+     * what it must not do.
+     */
+    dirtyFrom?: number;
 }
 export interface PaintFrame {
     /** The single stdout write for this frame. */

package/lib/types/plan-projection.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The plan artifact, projected from durable session events (B2.5).
+ *
+ * A plan is an **artifact**, not a row: it has an identity that outlives the card
+ * drawn for it, a revision history, and a state that comes from the session log
+ * rather than from whatever the renderer last painted. Everything here is a pure
+ * fold over events, so a replay produces exactly the artifacts a live session did —
+ * the same ids, the same revisions, the same states. That is the whole point of the
+ * module: the transcript, the dock and the review Surface read *this*, and none of
+ * them keeps plan state of its own (AD-15).
+ *
+ * What is durable (measured; see `docs/plans/b2-5-plan-artifact-audit.md`):
+ *
+ *   `plan/mode { active }`              — plan mode entered / left (plan-mode service)
+ *   `todo/write { todos }`              — a whole-list snapshot (the `todo_write` tool)
+ *   `exit_plan_mode` `tool/call`        — `arguments.plan` is the plan body; the call is
+ *                                         the review's identity
+ *   `exit_plan_mode` `tool/result`      — success = approved; the harness's own refusal
+ *                                         sentences = rejected / dismissed
+ *   `command/run` + `command/done`      — a `/plan` switch that is queued for the next step
+ *
+ * What is **not** durable, and therefore is never claimed here:
+ *
+ *   - the plan-review *question*: `dsh-plan-mode` asks through
+ *     `ctx.get('userQuestions').ask(...)`, which appends nothing. The tool call is the
+ *     review's only durable trace — which is also enough to recognise it on replay,
+ *     something B2.4 could not do from the question alone;
+ *   - any plan name or id: derived below, deterministically, from event order;
+ *   - "completed" and "abandoned": no event says either. They are folded from the last
+ *     snapshot (every step completed) and from the mode switch, and they carry
+ *     {@link PlanProvenance} `inferred` so a reader is never told them as fact.
+ *
+ * @module dsh-ssh-tui/plan-projection
+ */
+import type { PlanTodoItem } from './transcript-types.js';
+/** How the artifact's state is known. `durable` = an event says it; `inferred` = a reading. */
+export type PlanProvenance = 'durable' | 'inferred';
+/** What the artifact is doing. `unknown` is a real answer, not a placeholder. */
+export type PlanState = 'draft' | 'reviewing' | 'approved' | 'rejected' | 'executing' | 'completed' | 'abandoned' | 'unknown';
+/** One whole-list snapshot, with the durable sequence that produced it. */
+export interface PlanRevision {
+    /** `plan@<openSeq>#<writeSeq>` — deterministic, and unique within a session. */
+    id: string;
+    /** `seq` of the `todo/write` that produced this revision. */
+    seq: number;
+    steps: PlanTodoItem[];
+}
+/** The review a plan was put through, and what came back. */
+export interface PlanReview {
+    /** The `exit_plan_mode` call id: the review's identity, durable and replay-stable. */
+    id: string;
+    seq: number;
+    /** The plan body as it was reviewed (`arguments.plan`). */
+    body: string;
+    /**
+     * `pending` is a *live* state: a request is out and nobody has answered yet. A
+     * replayed log that ends here says `unknown` instead — the Host that asked is gone,
+     * and B2.4 set that precedent for approvals.
+     */
+    outcome: 'pending' | 'approved' | 'rejected' | 'dismissed' | 'unknown';
+    /** The reader's own words, when they refused with feedback. */
+    feedback?: string;
+}
+/** One plan, folded from the events that describe it. */
+export interface PlanArtifact {
+    /** `plan@<seq of the opening event>` — session-local, replay-stable. */
+    id: string;
+    /** What opened it: plan mode, or a standing todo list. */
+    openedBy: 'plan-mode' | 'todos';
+    openSeq: number;
+    state: PlanState;
+    provenance: PlanProvenance;
+    /** The plan body, when the session recorded one. */
+    body?: string;
+    /** The latest revision's steps. */
+    steps: PlanTodoItem[];
+    revisions: PlanRevision[];
+    review?: PlanReview;
+    /** Plan mode is on, as of the end of the fold. */
+    active: boolean;
+    /** A `/plan` switch is queued for the next step (derived, not read from the Host). */
+    pending: boolean;
+    /** `seq` of the event that closed the artifact, when one did. */
+    closedSeq?: number;
+}
+/** The slice of a session event this fold reads. */
+export interface PlanEvent {
+    type: string;
+    seq?: number;
+    /**
+     * Whether this event arrived from the running Host (as opposed to a log read).
+     *
+     * Only a live `exit_plan_mode` can be `reviewing`: a resumed process never carries
+     * on a review the Host that asked it did not finish, so a replayed unresolved call
+     * is `unknown`. Recorded per event because one log holds both.
+     */
+    live?: boolean;
+    data?: {
+        active?: unknown;
+        todos?: unknown;
+        name?: unknown;
+        args?: unknown;
+        commandId?: unknown;
+        kind?: unknown;
+        arguments?: unknown;
+        callId?: unknown;
+        message?: {
+            source?: {
+                callId?: unknown;
+            };
+            content?: unknown;
+            isError?: unknown;
+        };
+        error?: {
+            code?: unknown;
+            message?: unknown;
+        };
+    };
+}
+/**
+ * The harness's own refusal sentences for a plan review.
+ *
+ * Matched exactly, because they are the *only* durable evidence that a review was
+ * refused rather than never asked: `keep planning` (with or without feedback) and the
+ * dismissal that happens when the reader speaks instead of answering.
+ */
+export declare function reviewRefusal(text: string): {
+    outcome: 'rejected' | 'dismissed';
+    feedback?: string;
+} | undefined;
+/**
+ * Fold the durable events of one session into its plan artifacts.
+ *
+ * Deterministic by construction: ids are derived from event `seq` alone, and every
+ * decision reads only events that precede it. The same log (live or replayed) folds
+ * to the same list, which is what lets one artifact feed the transcript, the dock and
+ * the review Surface without any of them keeping state.
+ *
+ * @param events - the session's events, in order. Unknown types are ignored.
+ * @param options - `live` marks a fold whose last events come from a running Host, so
+ *   an unresolved review may be called `reviewing`; a replay leaves it `unknown`.
+ * @returns every artifact the session accounts for, oldest first.
+ */
+export declare function foldPlanArtifacts(events: readonly PlanEvent[], options?: {
+    live?: boolean;
+}): PlanArtifact[];
+/** The artifact a workspace should dock: the newest one that is still live. */
+export declare function livePlanArtifact(artifacts: readonly PlanArtifact[]): PlanArtifact | undefined;
+/**
+ * Whether the artifact still describes work in progress.
+ *
+ * The same question `planIsLive` asked of a row, asked of the projection instead:
+ * plan mode on, a switch queued, a step not finished, or a review awaiting its
+ * answer. Everything else is history, and history belongs in the transcript.
+ */
+export declare function artifactIsLive(artifact: PlanArtifact): boolean;
+/** `3/7`-style progress over the latest revision. */
+export declare function artifactProgress(artifact: PlanArtifact): {
+    done: number;
+    total: number;
+    current?: PlanTodoItem;
+};

package/lib/types/plan.d.ts

@@ -3,6 +3,7 @@
  */
 import { type Theme } from './theme.js';
 import { type TextSegment } from './term-text.js';
+import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions';
 import type { DiffDisplayLine, DisplayKind, PlanTodoItem, Row, SubagentLogEntry } from './transcript-types.js';
 export declare const MAX_SUBAGENT_LOGS = 80;
 export declare const TODO_STATUS_MARK: Record<PlanTodoItem['status'], string>;
@@ -80,6 +81,18 @@ export declare function parsePlanTodos(value: unknown): PlanTodoItem[];
 export declare function todoSummary(value: unknown): string;
 /** Compact ask_user_question summary from tool arguments. */
 export declare function askSummary(value: unknown): string;
+/**
+ * The questions one `ask_user_question` call recorded, for the durable fold.
+ *
+ * The Session's own reader (`questionsOf` in `@deepseek-ai/dsh-user-questions`)
+ * validates against the tool's schema and returns nothing when it does not match.
+ * This one only has to be faithful enough to draw a card from a log entry this
+ * process did not witness, so it takes the fields it can use and drops the rest
+ * rather than refusing the whole call.
+ * @param value - the tool call's arguments, raw JSON or already parsed.
+ * @returns the questions, or an empty list when the shape is unusable.
+ */
+export declare function askQuestions(value: unknown): readonly AskUserQuestionItem[];
 /** First non-empty line, collapsed to a single scan line. */
 export declare function firstDisplayLine(text: string): string;
 /** Collapse a child-session blob to one short chip/wait-card line. */

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

@@ -0,0 +1,96 @@
+/**
+ * The durable half of an ask-user question, as the Session reports it.
+ *
+ * A question used to exist only as a live request: the dialog the answerer opened
+ * and the row it pushed. Nothing rebuilt it from the log, so `--resume` showed the
+ * `ask_user_question` *tool* card and nothing that said what was asked or answered —
+ * the same session read differently depending on whether it was lived or replayed.
+ *
+ * The Session already records the truth: `tool/call` carries the questions and
+ * `tool/result` (or a late `user-question-reply` message) carries the answers, and
+ * `@deepseek-ai/dsh-user-questions` folds both into a projection every Client can
+ * read (`ctx.sessionProjections.stateOf(session, 'userQuestions')`). This module
+ * turns that view into the records the transcript paints, and it is deliberately
+ * pure: the caller supplies the questions, because the projection's *settled* half
+ * names only the call and the answers.
+ *
+ * Two limits are the Harness's, not this module's, and both are why the caller
+ * keeps its live path as well:
+ *
+ * - the projection tracks only **timed** `ask_user_question` calls — a call made
+ *   while the blocking legacy schema was in effect appears in neither half, so a
+ *   session that only ever used it folds to an empty view;
+ * - it needs the projection service to be registered at all, which a bare Context
+ *   in a test (or an embedder without `dsh-session-projection`) does not provide.
+ *
+ * @module dsh-ssh-tui/question-state
+ */
+import type { AskUserQuestionAnswerItem, AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions';
+/**
+ * The projection's two halves, declared here as the *shape this plugin reads*
+ * rather than imported by name.
+ *
+ * `PendingUserQuestion`, `SettledUserQuestion` and `UserQuestionProjectionView` are
+ * named exports of `dsh-user-questions` only from 0.2.0-rc.2 on: the same module on
+ * 0.1.7-rc.x and 0.2.0-rc.1 exports a different surface, and importing the names made
+ * the plugin fail to *compile* there — which is how three CI legs went red at 0.8.2's
+ * first push. Nothing here needs the host's names: every field below is already read
+ * defensively (`questionViewOf` takes `unknown` and parses it), and the two item types
+ * are exported by every line the plugin declares.
+ */
+export interface QuestionViewPending {
+    readonly callId: string;
+    readonly questions: readonly AskUserQuestionItem[];
+    /** `open` while the window is live, `continued` once it closed but still accepts. */
+    readonly state?: string;
+}
+export interface QuestionViewSettled {
+    readonly callId: string;
+    readonly answers?: readonly AskUserQuestionAnswerItem[];
+}
+/** Both halves of one Session's timed `ask_user_question` state. */
+export interface QuestionView {
+    readonly active: readonly QuestionViewPending[];
+    readonly settled: readonly QuestionViewSettled[];
+}
+/** One question as the transcript should show it, live or replayed. */
+export interface DurableQuestionRecord {
+    /** The `ask_user_question` call this question belongs to. */
+    callId: string;
+    question: AskUserQuestionItem;
+    /**
+     * `open` is a foreground wait nobody has answered yet; `continued` is one whose
+     * window closed but which the Session still accepts an answer for; the other two
+     * are terminal.
+     */
+    state: 'open' | 'continued' | 'answered' | 'cancelled';
+    /** What the human chose; empty while the question is unanswered. */
+    answers: readonly AskUserQuestionAnswerItem[];
+}
+/** The projection view, or the empty one when nothing is registered. */
+export declare function questionViewOf(value: unknown): QuestionView | undefined;
+/** Whether the projection has anything to say about this session's questions. */
+export declare function questionViewIsEmpty(view: QuestionView | undefined): boolean;
+/**
+ * Every question the Session log can still account for, in ask order then
+ * settlement order.
+ *
+ * A settled call names only its answers, so a call whose questions this process
+ * never saw (a resumed session whose `tool/call` predates the log window it read)
+ * contributes nothing rather than a half-record: an answer with no question is not
+ * something the transcript can draw.
+ * @param view - the projection view, or undefined when nothing is registered.
+ * @param questionsOf - the questions recorded for one call, when known.
+ * @returns one record per question, newest last.
+ */
+export declare function durableQuestionRecords(view: QuestionView | undefined, questionsOf: (callId: string) => readonly AskUserQuestionItem[] | undefined): DurableQuestionRecord[];
+/**
+ * How one answered question reads on its card.
+ *
+ * Mirrors what the live dialog writes when it settles a card, so a session that
+ * was replayed shows the same sentence as one that was lived: the typed answer
+ * when there was one, the chosen labels otherwise.
+ * @param answers - the recorded answers for this question.
+ * @returns the summary text.
+ */
+export declare function answerSummaryText(answers: readonly AskUserQuestionAnswerItem[]): string;