dsh-code 0.6.1 → 0.8.0

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

@@ -0,0 +1,144 @@
+/**
+ * Provider settings adapter for the TUI `/model` provider-management panel:
+ * the same-process equivalent of the web host's Models page join
+ * (`packages/client/ui-settings-models`), reading the advisory `ctx.llm`
+ * registry, the redacted `ctx.settings` descriptors, and the value-free
+ * `ctx.credentials` facts directly. Secrets never cross this module: settings
+ * are read with `redactSecrets: true`, credentials are only ever described
+ * (never resolved), and every message is single-line without embedding key
+ * data.
+ *
+ * @module @deepseek-ai/dsh-tui/provider-settings
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * The conventional credential reference for a provider route: `<ROUTE>_API_KEY`
+ * with the route uppercased and every non-alphanumeric run collapsed to one
+ * underscore — the exact derivation the official Models page uses
+ * (`deriveKeyRef` in `ui-settings-models`), so a key saved here is found there.
+ * @param provider - provider route id (e.g. `pi-ai`, `minimax-cn`).
+ * @returns the derived reference name (e.g. `PI_AI_API_KEY`).
+ */
+export declare function deriveCredentialRef(provider: string): string;
+/** Value-free facts about one credential reference — never the value. */
+export interface ProviderCredentialFacts {
+    /** Whether the reference currently resolves to a stored value. */
+    readonly configured: boolean;
+    /** Source layer supplying the value; absent while unconfigured. */
+    readonly source?: string;
+    /** Whether a write through this panel would currently succeed. */
+    readonly writable: boolean;
+}
+/**
+ * One row's credential state: value-free facts once the reference was
+ * described, a bounded error when that describe failed (the row itself is
+ * never dropped), or `undefined` when the row names no reference to describe —
+ * an unmanaged active provider, a dormant route, or a profile authenticating
+ * through the provider's own path.
+ */
+export type ProviderCredentialView = ({
+    readonly kind: 'facts';
+} & ProviderCredentialFacts) | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/**
+ * One provider row in the TUI provider-management panel: the configurable
+ * directory entry joined with its settings profile and credential facts.
+ * Every mutation below addresses this row, and the caller passes the row back
+ * after re-loading so the revision/ref facts are current.
+ */
+export interface ProviderTargetView {
+    /** Provider route id (`GenerateOptions.provider`). */
+    readonly provider: string;
+    /** Human-readable provider name. */
+    readonly displayName: string;
+    /** Whether an adapter currently serves this route. */
+    readonly active: boolean;
+    /** User-settings namespace whose section configures this provider; '' when unmanaged. */
+    readonly settingsNs: string;
+    /** Path from that section's root to this provider's profile; [] when the whole section is the profile. */
+    readonly settingsPath: readonly string[];
+    /** Revision of the owning settings section at load (0 when no namespace resolved). */
+    readonly settingsRevision: number;
+    /** Whether the resolved profile exists (the whole section, or at `settingsPath`). */
+    readonly configured: boolean;
+    /** Whether only the user settings layer carries the profile, so removal restores the base. */
+    readonly removable: boolean;
+    /** The credential reference the resolved profile names, when one does. */
+    readonly credentialRef?: string;
+    /** The conventional reference a save uses for a dormant or ref-less profile. */
+    readonly suggestedRef: string;
+    /** Credential facts, a bounded describe error, or undefined when there is no ref to describe. */
+    readonly credential: ProviderCredentialView | undefined;
+    /** The owning adapter reports this route as hand-declared (absent when it draws no distinction). */
+    readonly declared?: boolean;
+}
+/** The resolved provider/settings/credential join. */
+export interface ProviderSettingsDirectory {
+    /** Provider rows: configurable-directory order first, active-unmanaged rows after. */
+    readonly rows: readonly ProviderTargetView[];
+    /** Whether the settings provider accepts writes (mirrors the web page's flag). */
+    readonly writable: boolean;
+    /** Non-fatal join failures (settings/directory reads), for a degradation notice. */
+    readonly failures: readonly string[];
+}
+/** Subscribe to the same provider-directory invalidations as the official Web Models page. */
+export declare function subscribeProviderSettings(ctx: Context, listener: () => void): () => void;
+/** A single-line, bounded error from the provider-management adapter. */
+export declare class ProviderSettingsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Join the configurable-provider directory, the redacted settings
+ * namespaces, and the referenced credentials into panel rows, web-parity:
+ * - directory entries merge with `listProviders()` to mark each live or
+ *   dormant, and routes registered without a directory declaration appear as
+ *   read-only/unmanaged rows (no settings address);
+ * - a whole-section entry is configured whenever its namespace resolves;
+ *   a path-addressed one only when the profile resolves there;
+ * - a row is removable when the user layer alone carries its profile;
+ * - only refs named by resolved profiles are described, and a per-ref failure
+ *   degrades to that row's bounded error instead of losing it.
+ * Absent `settings`/`credentials` services are tolerated the same way.
+ * @param ctx - context carrying the `llm` service (settings/credentials optional).
+ * @returns the resolved directory; empty rows when `llm` is unavailable.
+ */
+export declare function loadProviderSettings(ctx: Context): Promise<ProviderSettingsDirectory>;
+/**
+ * Store a provider API key, web-parity: validate with `normalizeApiKey`
+ * (single-line, actionable errors that never echo the key), materialize the
+ * profile/`apiKeyEnv` through `settings.mutate` first when the resolved
+ * profile names no reference (dormant route or ref-less profile), then store
+ * under the trusted named ref or the derived conventional ref. An existing
+ * whole-section DeepSeek whose resolved profile already names
+ * `DEEPSEEK_API_KEY` needs no settings mutation. Env-supplied read-only keys
+ * are refused before any service call.
+ * @param ctx - context carrying `settings` (when materializing) and `credentials`.
+ * @param target - the joined row to write through.
+ * @param rawKey - the key exactly as typed; surrounding whitespace is trimmed.
+ * @throws {@link ProviderSettingsError} with a single-line, key-free message.
+ */
+export declare function saveProviderCredential(ctx: Context, target: ProviderTargetView, rawKey: string): Promise<void>;
+/**
+ * Remove the currently named credential without touching the provider
+ * profile. Only the resolved profile's own reference is unset; a dormant or
+ * ref-less row (nothing to remove), an already-absent key, and an
+ * env-supplied read-only key are rejected safely before any service call.
+ * @param ctx - context carrying the `credentials` service.
+ * @param target - the joined row whose named credential to unset.
+ * @throws {@link ProviderSettingsError} with a single-line, key-free message.
+ */
+export declare function unsetProviderCredential(ctx: Context, target: ProviderTargetView): Promise<void>;
+/**
+ * Remove a user-added provider profile, web-parity: only `removable` rows may
+ * be removed; a page-managed credential — the derived ref, configured and
+ * writable — is unset first (so a second-step failure leaves the row visible
+ * and the operation retryable), then `settings.mutate` unsets
+ * `target.settingsPath`. Both steps are idempotent. A hand-named credential
+ * ref may be shared elsewhere and is left alone.
+ * @param ctx - context carrying `credentials` and `settings`.
+ * @param target - the joined row to remove.
+ * @throws {@link ProviderSettingsError} with a single-line, key-free message.
+ */
+export declare function removeProviderSettings(ctx: Context, target: ProviderTargetView): Promise<void>;

package/lib/types/questions.d.ts

@@ -22,6 +22,8 @@ export interface PendingQuestion {
     resolve(answers: AskUserQuestionAnswer): void;
     /** Reject the provider promise as aborted (also used for Esc cancel). */
     reject(error: Error): void;
+    /** Detach the request's abort listener once the question settles (internal). */
+    detachAbort?(): void;
 }
 /** The pending-question snapshot the renderer subscribes to. */
 export interface QuestionSnapshot {

package/lib/types/render/animations.d.ts

@@ -3,11 +3,20 @@
  * the StateDot "ongoing" pixel chase (3×3 ring, 125ms flat-hold brightness
  * steps, 1s cycle) becomes the single-cell stepped pulse below and the
  * full-ring clockwise braille chase in {@link BUSY_CHASE_FRAMES}, and the
- * streaming caret blink is the Claude-Code convention. Pure functions only —
- * the Ink layer owns timers and colors.
+ * streaming caret blink is the Claude-Code convention.
+ *
+ * The DeepSeek model-switch easter egg ports Codex's effort-ignition "Wave"
+ * style (`codex-rs/tui/src/bottom_pane/effort_ignition_styles.rs`): switching
+ * INTO an official DeepSeek route sweeps a blue wave across the composer's
+ * input row — one column per cell, `backgroundColor` = the sampled wave
+ * color — then, on the deepseek (Ultra-equivalent) tier, drops the `· ✦ ✧`
+ * sparkle sequence into the rightmost blank cell before fading. The prompt
+ * marker keeps the tier accent afterwards (persistent, like Codex's prompt
+ * charge). Pure functions only — the Ink layer owns timers and colors.
  *
  * @module @deepseek-ai/dsh-code/render/animations
  */
+import type { RgbTriple } from '../theme.ts';
 /** Single-cell stepped pulse: flat holds mirroring the web's 125ms keyframes. */
 export declare const PULSE_FRAMES: readonly ["█", "█", "▆", "▃", "▁", "▃", "▆", "█"];
 /** Pulse frame for a monotonic tick. */
@@ -22,3 +31,169 @@ export declare const BUSY_CHASE_FRAMES: readonly ["⣾", "⣽", "⣻", "⢿", "
 export declare function busyChaseFrame(tick: number): string;
 /** Caret visibility: half the ticks on, half off (530ms blink). */
 export declare function caretVisible(tick: number): boolean;
+/**
+ * The one-shot DeepSeek model-switch easter egg: when the status bar model
+ * label switches to an official DeepSeek route, the composer's input row
+ * plays Codex's effort-ignition "Wave" — a blue crest sweeping the content
+ * row column by column (background tint ≤ 0.55 under the draft), plus the
+ * Ultra-style `· ✦ ✧` sparkles on the deepseek tier — and the prompt marker
+ * keeps the tier accent afterwards. The Ink layer owns the timer and reads
+ * the ACTIVE palette anchors (`getPalette`); everything below is pure
+ * interpolation over the colors it is given.
+ */
+/** Frame cadence of the DeepSeek wave: Codex's IGNITION_FRAME_TICK (33ms ≈ 30fps). */
+export declare const DEEPSEEK_WAVE_TICK_MS = 33;
+/**
+ * The two DeepSeek wave tiers. The concept maps Codex's reasoning tiers to
+ * model ids: `flash` runs the Max parameters, `deepseek` (pro models) runs
+ * the Ultra parameters (dual band + tail sparkles on the Wave style).
+ */
+export type DeepseekWaveTier = 'flash' | 'deepseek';
+/**
+ * The three ignition styles — Codex `IgnitionStyle`: a traveling crest
+ * (Wave), a drifting multi-hue band (Aurora), and an expanding ring (Pulse).
+ * One style is picked at random per trigger and never repeats the previous.
+ */
+export type DeepseekWaveStyle = 'wave' | 'aurora' | 'pulse';
+/** All styles in canonical order, for random selection and tests. */
+export declare const DEEPSEEK_WAVE_STYLES: readonly DeepseekWaveStyle[];
+/** Wave half-width in columns — Codex WAVE_HALF_WIDTH (9). */
+export declare const WAVE_HALF_WIDTH = 9;
+/** Pulse ring half-width in columns — Codex PULSE_HALF_WIDTH (4.5). */
+export declare const PULSE_HALF_WIDTH = 4.5;
+/** Sparkle start and frame cadence — Codex SPARK_START / SPARK_FRAME. */
+export declare const SPARK_START_MS = 900;
+export declare const SPARK_FRAME_MS = 100;
+/** Sparkle glyphs in frame order — Codex SPARK_GLYPHS (`· ✦ ✧`). */
+export declare const SPARK_GLYPHS: readonly ["·", "✦", "✧"];
+/**
+ * Band tables — Codex `bands(style, tier)`. Each entry is a triple whose
+ * meaning depends on the style: Wave/Pulse use `(launch, travel, strength)`;
+ * Aurora uses `(speed, phase, hueIndex)`.
+ */
+export type DeepseekWaveBand = readonly [number, number, number];
+export declare const DEEPSEEK_WAVE_BANDS: Readonly<Record<DeepseekWaveStyle, Readonly<Record<DeepseekWaveTier, readonly DeepseekWaveBand[]>>>>;
+/** Extra display time applied to every Codex ignition style. */
+export declare const DEEPSEEK_WAVE_DURATION_EXTENSION_MS = 200;
+/**
+ * Total visible duration: the Codex ignition duration plus 200ms so its motion
+ * remains readable in a busy terminal.
+ * @param tier - the active wave tier.
+ * @param style - the active ignition style.
+ * @returns the duration in milliseconds.
+ */
+export declare function deepseekWaveDuration(tier: DeepseekWaveTier, style?: DeepseekWaveStyle): number;
+/**
+ * Pick one ignition style at random, never repeating the previous one —
+ * Codex `IgnitionStyle::random`. Falls back to the remaining styles.
+ * @param previous - the style of the last trigger, if any.
+ * @returns a style different from `previous`.
+ */
+export declare function deepseekWaveStyleRandom(previous: DeepseekWaveStyle | undefined): DeepseekWaveStyle;
+/**
+ * Blank-cell background the wave tint blends toward — fixed approximations
+ * of the terminal's default background, mirroring Codex's
+ * `user_message_bg_rgb` (which derives a near-black / near-white bubble tint
+ * from the terminal background). The Ink layer picks the active theme's one.
+ */
+export declare const WAVE_BASE_DARK: RgbTriple;
+export declare const WAVE_BASE_LIGHT: RgbTriple;
+/**
+ * Tier for a `provider/model` label: a model id containing `flash` runs the
+ * single-band flash tier; everything else (pro/reasoner/chat) runs the
+ * dual-band deepseek tier. Mirrors Codex's Max→Ultra mapping.
+ * @param model - the `provider/model` label of the applied model.
+ * @returns the wave tier for that model.
+ */
+export declare function deepseekWaveTier(model: string): DeepseekWaveTier;
+/**
+ * Cosine window — Codex `crest`: 1 exactly under the wave center, 0 from
+ * one half-width away.
+ * @param distance - distance from the crest center in half-widths.
+ * @returns the crest strength in 0..1.
+ */
+export declare function crest(distance: number): number;
+/**
+ * Cubic ease-in-out — Codex `ease_in_out`: flat at both ends, steepest in
+ * the middle, so the crest accelerates and eases instead of sliding linearly.
+ * @param progress - raw progress (clamped to 0..1).
+ * @returns the eased progress in 0..1.
+ */
+export declare function easeInOut(progress: number): number;
+/**
+ * Fade-in/fade-out envelope — Codex `envelope`: linear ramp over `fadeIn`
+ * at the start and `fadeOut` at the end, plateau at 1 between, 0 outside the
+ * total. The Wave style keeps the envelope at 1 (Codex paints Wave without
+ * an envelope); exported for the Aurora-style fades and for tests.
+ * @param elapsed - seconds since the animation started.
+ * @param total - total duration in seconds.
+ * @param fadeIn - seconds of fade-in.
+ * @param fadeOut - seconds of fade-out.
+ * @returns the envelope value in 0..1.
+ */
+export declare function envelope(elapsed: number, total: number, fadeIn: number, fadeOut: number): number;
+/**
+ * The background color for one composer-row column at a tick — Codex
+ * `paint_bands` + `Canvas::tint` for all three styles. Bands overlap with a
+ * max for Wave/Pulse and a SUM for Aurora (Codex differs by style), the
+ * weighted hues mix per column (Wave/Pulse always end on hue 0), the tint
+ * blends the mixed hue toward the blank-cell base at the style's alpha cap,
+ * and Aurora applies its own fade envelope. Returns `null` when the column
+ * should stay transparent, so the row returns to no `backgroundColor` on
+ * both ends.
+ * @param tick - wave frame (0, 1, … at DEEPSEEK_WAVE_TICK_MS).
+ * @param column - column index in the content row (0..width-1).
+ * @param width - content-row width in columns.
+ * @param tier - the wave tier (flash = Max, deepseek = Ultra parameters).
+ * @param style - the ignition style.
+ * @param hues - the tier's three hues.
+ * @param base - the blank-cell base color the tint blends toward.
+ * @returns the blended RGB background, or null for transparent.
+ */
+export declare function deepseekWaveColumnBg(tick: number, column: number, width: number, tier: DeepseekWaveTier, style: DeepseekWaveStyle, hues: readonly [RgbTriple, RgbTriple, RgbTriple], base: RgbTriple): RgbTriple | null;
+/**
+ * The sparkle glyph for a tick — Codex `spark_frame`, sampled on the same
+ * proportionally slowed DeepSeek Wave timeline as the composer background.
+ * The Ink layer still must skip occupied cells.
+ * @param tick - wave frame at DEEPSEEK_WAVE_TICK_MS.
+ * @returns the sparkle glyph, or null outside the stretched tail window.
+ */
+export declare function deepseekWaveSpark(tick: number): string | null;
+/**
+ * The composer BORDER color at a tick: the frame breathes with the wave —
+ * the palette's static dim blends toward the tier accent as the crest is
+ * alive and back, so the frame glows up while the wave sweeps and settles to
+ * dim on both ends (first==last frame==dim, no hard jump).
+ * @param tick - wave frame at DEEPSEEK_WAVE_TICK_MS.
+ * @param tier - the wave tier.
+ * @param hues - the tier's three hues; the border blends toward hues[0].
+ * @param dim - the palette's static dim RGB (the resting border color).
+ * @returns the blended border RGB.
+ */
+export declare function deepseekWaveBorderColor(tick: number, tier: DeepseekWaveTier, style: DeepseekWaveStyle, hues: readonly [RgbTriple, RgbTriple, RgbTriple], dim: RgbTriple): RgbTriple;
+/**
+ * Whether the `deepseek` wordmark rides the wave at this tick: it fades in
+ * shortly after the first crest launches and out before the wave settles,
+ * so the brand name surfaces through the sweep's middle. The Ink layer
+ * places it in the row's blank mid-section (never over real draft text).
+ * @param tick - wave frame at DEEPSEEK_WAVE_TICK_MS.
+ * @param tier - the wave tier.
+ * @returns true while the wordmark should be visible.
+ */
+export declare function deepseekWaveWordVisible(tick: number, tier: DeepseekWaveTier, style?: DeepseekWaveStyle): boolean;
+/**
+ * The per-character color for the `deepseek` wordmark: the tier's hues
+ * cycled per character (d→hue0, e→hue1, e→hue2, …), a brand-gradient text.
+ * @param index - character index in the wordmark.
+ * @param hues - the tier's three hues.
+ * @returns the hue for that character.
+ */
+export declare function deepseekWaveWordHue(index: number, hues: readonly [RgbTriple, RgbTriple, RgbTriple]): RgbTriple;
+/**
+ * True when a `provider/model` status label addresses the official DeepSeek
+ * route: either segment contains `deepseek` (case-insensitive), covering the
+ * `deepseek-official` provider route and its `deepseek-*` model ids.
+ * @param label - the status bar model label (`provider/model`).
+ * @returns whether the label names an official DeepSeek model.
+ */
+export declare function isOfficialDeepSeekLabel(label: string): boolean;

package/lib/types/render/lines.d.ts

@@ -24,6 +24,12 @@ export declare function styledLines(segments: readonly StyledSegment[], columns:
 export declare function textLines(text: string, columns: number, style?: LineStyle): readonly StyledLine[];
 /** Markdown rows re-hardened so a single long word cannot escape the budget. */
 export declare function markdownLines(text: string, columns: number): readonly StyledLine[];
+/**
+ * Codex-style reasoning rows: the marker occupies the reply gutter and every
+ * wrapped or explicit continuation starts with the same two-column indent, so
+ * reasoning content and assistant Markdown share one left edge.
+ */
+export declare function reasoningLines(text: string, columns: number): readonly StyledLine[];
 /**
  * Convert one durable transcript entry to its complete scrollable row model.
  * The source entry stays intact; only the caller's visible slice is rendered.

package/lib/types/render/markdown.d.ts

@@ -3,13 +3,13 @@
  * block/inline parser producing styled line segments the Ink renderer maps
  * to colored text. No ANSI here — the app owns color mapping, tests own the
  * structure. The subset mirrors what agent replies actually emit: headings,
- * emphasis, inline/fenced code, flat lists, blockquotes, links, rules, and
- * wrapped paragraphs. Unknown syntax degrades to plain text (never throws).
+ * emphasis, inline/fenced code, flat lists, blockquotes, links, rules, GFM
+ * tables, and wrapped paragraphs. Unknown syntax degrades to plain text.
  *
  * @module @deepseek-ai/dsh-code/render/markdown
  */
 /** Style classes the renderer emits; the app maps them to colors/props. */
-export type MdStyle = 'plain' | 'bold' | 'italic' | 'boldItalic' | 'code' | 'accent' | 'dim' | 'strike';
+export type MdStyle = 'plain' | 'bold' | 'italic' | 'boldItalic' | 'code' | 'accent' | 'accentBold' | 'dim' | 'strike';
 /** One styled run of text. */
 export interface MdSegment {
     /** Visible text (no ANSI). */

package/lib/types/render/projection.d.ts

@@ -138,6 +138,24 @@ export interface UsageTotals {
     /** Cache-read tokens over the whole log (0 when the adapter reports none). */
     cacheReadTokens: number;
 }
+/**
+ * Estimated used tokens per context content type, folded from transcript
+ * events via {@link estimateTokens}. The segmented context bar's composition
+ * source: proportions across types are meaningful, absolute values are not
+ * (they never touch billing or the reported `lastPromptTokens`).
+ */
+export interface ContextSegments {
+    /** Rendered system-prompt text (latest `request/header`) plus injected-context notices. */
+    system: number;
+    /** Direct human prompts (durable `user/message` rows). */
+    prompt: number;
+    /** Assistant text blocks (visible replies). */
+    assistant: number;
+    /** Assistant reasoning blocks (hidden thinking). */
+    thinking: number;
+    /** Tool call arguments plus result text. */
+    tools: number;
+}
 /** Window-scoped figures the status line shows; timing uses event timestamps. */
 export interface TranscriptStats {
     /** Durable turns opened (`turn/start` events). */
@@ -154,6 +172,8 @@ export interface TranscriptStats {
     lastPromptTokens: number;
     /** Newest advertised route capacity, 0 when no adapter ever advertised one. */
     contextWindow: number;
+    /** Estimated used tokens per content type (the segmented bar's composition). */
+    contextSegments: ContextSegments;
     /** Summed first-token waits: `step/start` → first non-empty chunk, in ms. */
     ttftMs: number;
     /** Steps that produced a first chunk (the TTFT average's denominator). */
@@ -162,6 +182,14 @@ export interface TranscriptStats {
     decodeMs: number;
     /** Completion tokens over timed decode spans (the tok/s numerator). */
     decodeTokens: number;
+    /**
+     * Adapter-owned reasoning effort of the latest `request/header` config —
+     * the EFFECTIVE effort the session actually uses (a materialized model
+     * default is included, exactly as the adapter resolved it). Empty when the
+     * header carried none (provider-default behavior). The status line appends
+     * it to the model segment as `provider/model@effort`.
+     */
+    reasoningEffort: string;
 }
 /** The complete TUI transcript view for one session. */
 export interface TranscriptView {
@@ -208,7 +236,10 @@ export interface TranscriptView {
     /**
      * Fold-internal timing anchors, never rendered: open step and tool-call
      * start timestamps the next `assistant/message` / `tool/result` resolves
-     * against. Keyed `turn:step` and by call id.
+     * against. Keyed `turn:step` and by call id. `turnSteps`/`turnTools`
+     * track which step/tool anchors still belong to the open turn so
+     * `turn/end` (and a superseding `step/start`) can sweep anchors an
+     * interruption left behind; `turnFiles` keys mutated paths by turn.
      */
     readonly anchors: {
         stepStart: Map<string, number>;
@@ -217,6 +248,8 @@ export interface TranscriptView {
         compactionTokens: Map<string, number>;
         lastPruneTokens: number;
         turnFiles: Map<number, Set<string>>;
+        turnSteps: Map<number, string>;
+        turnTools: Map<number, Set<string>>;
     };
 }
 /** A fresh, empty transcript view. */
@@ -228,8 +261,92 @@ export declare function createTranscriptView(): TranscriptView;
  * @returns the view after the event; the input view is never mutated.
  */
 export declare function projectEvent(view: TranscriptView, event: SessionEvent): TranscriptView;
+/**
+ * Mutable replay accumulator: folds a persisted log into the identical view
+ * `projectEvent` would produce, but in near-linear time. Where `projectEvent`
+ * is copy-on-write — every append/scan rebuilds the whole `entries` array, so
+ * folding a full log costs O(N²) — the accumulator appends by push, resolves
+ * id-keyed updates (tool/result, command/done, retry-started) through index
+ * maps, and tombstones retired pending rows, so the whole log folds in O(N)
+ * plus one compaction pass when tombstones exist.
+ *
+ * Index maps never delete: every appended row registers its index, so an id
+ * lookup miss provably means no matching row exists and the update is an O(1)
+ * no-op (a malicious/orphan-heavy log cannot force per-orphan full-array
+ * scans). Each id maps to ALL of its indices, so a duplicate id updates every
+ * matching row exactly like the copy-on-write reducer.
+ *
+ * @internal Exported only so tests can (a) prove replay ≡ sequential
+ * `projectEvent` folds and (b) assert the linear complexity deterministically
+ * via {@link ReplayAccumulator.ops}, which counts entry-level container work
+ * instead of relying on wall-clock thresholds. No public consumer.
+ */
+export interface ReplayAccumulator {
+    /** Working entry list; `undefined` marks a retired pending row (tombstone). */
+    entries: (TranscriptEntry | undefined)[];
+    /** callId → every index into `entries` holding a `tool` row with that id. */
+    toolIndex: Map<string, number[]>;
+    /** commandId → every index into `entries` holding a `command` row with that id. */
+    commandIndex: Map<string, number[]>;
+    /** retryId → every index into `entries` holding a `retry` row with that id. */
+    retryIndex: Map<string, number[]>;
+    /** messageId → every index into `entries` holding a `pending` row with that id. */
+    pendingIndex: Map<string, number[]>;
+    /** Tombstone count; zero means `entries` is already the final array. */
+    removedCount: number;
+    /** Mutable inbox id lists, mirroring `view.pending` order per target. */
+    pendingTurn: string[];
+    pendingStep: string[];
+    streaming: string;
+    streamingReasoning: string;
+    todos: readonly TodoItem[];
+    busy: boolean;
+    busySince: number;
+    model: string;
+    plan: boolean;
+    permission: string;
+    title: string;
+    sandbox: string;
+    goal: GoalFold | undefined;
+    stats: TranscriptStats;
+    stepStart: Map<string, number>;
+    toolStart: Map<string, number>;
+    firstChunkAt: Map<string, number>;
+    compactionTokens: Map<string, number>;
+    lastPruneTokens: number;
+    turnFiles: Map<number, Set<string>>;
+    turnSteps: Map<number, string>;
+    turnTools: Map<number, Set<string>>;
+    /** Entry-level container operations performed so far (test instrumentation). */
+    ops: number;
+}
+/** @internal A fresh replay accumulator whose state mirrors `createTranscriptView()`. */
+export declare function createReplayAccumulator(): ReplayAccumulator;
+/**
+ * Fold one session event into a replay accumulator. This mirrors
+ * {@link projectEvent} case for case — same stats arithmetic, same anchor
+ * set/delete behavior, same entry shapes — so the finished view is identical
+ * to a sequential fold; only the `entries` container operations are mutable.
+ *
+ * @internal Test-instrumentation path; `projectEvents` is the public entry.
+ */
+export declare function replayProjectEvent(acc: ReplayAccumulator, event: SessionEvent): void;
+/**
+ * Materialize the accumulated fold as a `TranscriptView`, compacting any
+ * retired tombstones. The anchors maps are handed through as-is (their
+ * content is identical to a sequential fold's).
+ *
+ * @internal Test-instrumentation path; `projectEvents` is the public entry.
+ */
+export declare function finishReplay(acc: ReplayAccumulator): TranscriptView;
 /**
  * Fold a replayed event history into one view.
+ *
+ * Folding is near-linear in the log size: the mutable replay accumulator
+ * appends in place and resolves id-keyed updates through index maps, so a
+ * long persisted session replays without the O(N²) copy-on-write rebuilds a
+ * naive sequential fold would incur. The result is identical to folding
+ * {@link projectEvent} per event in order.
  * @param events - events in `seq` order.
  * @returns the folded view.
  */
@@ -243,8 +360,11 @@ export declare function projectEvents(events: readonly SessionEvent[]): Transcri
  * the inbox claims or cancels them durably (`agent/inbox/spliced` removals,
  * `user/message` retirement), and an append-only `<Static>` flush cannot
  * erase a row that vanishes from the view — the retired row would ghost on
- * screen until the next source-backed replay. Everything else (including a
- * completed tail) is final: later events only APPEND new rows.
+ * screen until the next source-backed replay. Running commands join the
+ * mutable boundary for the same reason in reverse: `command/done` mutates the
+ * row's state/summary, so a flushed row would keep its stale running mark
+ * until a resize-triggered replay. Everything else (including a completed
+ * tail) is final: later events only APPEND new rows.
  * @param entries - the view's transcript entries in order.
  * @returns the count of entries safe to flush (0 for an empty transcript).
  */