dsh-code 1.0.1 → 1.0.3

package/lib/types/app.d.ts

@@ -26,7 +26,7 @@ import type { ModelDirectory, ModelRow } from './models.ts';
 import type { ProviderConfiguration, ProviderSettingsDirectory, ProviderTargetView } from './provider-settings.ts';
 import type { QuestionStore } from './questions.ts';
 import type { SkillsView, SkillRow } from './skills.ts';
-import type { MentionCandidate } from './mentions.ts';
+import { type MentionCandidate } from './mentions.ts';
 import type { SubagentFeedView } from './subagents.ts';
 import { type JobRow } from './kernel-panels.ts';
 import type { PresetRow } from './presets.ts';
@@ -85,7 +85,7 @@ export interface AppProps {
     /** Validate draft image paths without committing attachment objects. */
     inspectImages(paths: readonly string[]): Promise<readonly ImagePathInspection[]>;
     /** Validate, normalize and persist images immediately before submission. */
-    prepareImages(paths: readonly string[]): Promise<readonly ImageBlock[]>;
+    prepareImages(paths: readonly string[], signal?: AbortSignal): Promise<readonly ImageBlock[]>;
     /** Apply one /model selection (with an advertised reasoning effort, when picked); returns the display label. */
     selectModel(row: ModelRow, effortId?: string): string;
     /** The /subagent override label, '' when delegated agents follow the current model. */
@@ -163,18 +163,9 @@ export interface AppProps {
     recordHistory(text: string): void;
     /** Cancel one queued inbox message by identity (Delete on the empty composer). */
     cancelQueued(messageId: string): void;
+    /** Apply the Ctrl+R terminal passthrough to the detected editor (/vscode-keys); resolves to a one-line summary. */
+    applyEditorKeys(): Promise<string>;
 }
-/**
- * One-row editor window keeping the logical cursor visible in long drafts.
- * The caret and its surroundings slice at grapheme boundaries: splitting a
- * star-plane surrogate pair would render an isolated half under the block
- * caret with a width the terminal never draws.
- */
-export declare function editorWindow(value: string, cursor: number, columns: number): {
-    before: string;
-    caret: string;
-    after: string;
-};
 /** One completion candidate row. */
 interface CompletionCandidate {
     /** Insertion text for the command name (with leading slash). */

package/lib/types/attachments.d.ts

@@ -17,4 +17,4 @@ export declare function parsePastedImagePaths(input: string): readonly string[];
 /** Validate path, byte size and encoded signature without writing an attachment object. */
 export declare function inspectImagePaths(paths: readonly string[], attachments: AttachmentStore | undefined, cwd?: string): Promise<readonly ImagePathInspection[]>;
 /** Read, validate, and persist an ordered image path list as model content blocks. */
-export declare function saveImagePaths(paths: readonly string[], attachments: AttachmentStore | undefined): Promise<readonly ImageBlock[]>;
+export declare function saveImagePaths(paths: readonly string[], attachments: AttachmentStore | undefined, signal?: AbortSignal): Promise<readonly ImageBlock[]>;

package/lib/types/editor-keys.d.ts

@@ -0,0 +1,105 @@
+/**
+ * VS Code-family terminal keybinding repair. VS Code hands Ctrl+R to the
+ * workbench (Open Recent) even while an integrated terminal owns focus, so
+ * the reasoning-fold key never reaches the TUI. Workspace-scoped keybindings
+ * do not exist, so the fix is one user-level keybindings.json rule that
+ * forwards the raw Ctrl byte via sendSequence under terminalFocus. This
+ * module detects the hosting editor variant, resolves its user
+ * keybindings.json, and merges the rule idempotently; pure merge/detect
+ * helpers are separated from the fs orchestration so both stay testable.
+ * @module @deepseek-ai/dsh-code/editor-keys
+ */
+/** Integrated-terminal editor variants this module can repair. */
+export type EditorTerminalFamily = 'vscode' | 'cursor' | 'vscodium' | 'windsurf';
+/**
+ * Detect the editor hosting this integrated terminal.
+ * @param env - process environment (TERM_PROGRAM decides; case/whitespace tolerant).
+ * @returns the family, or undefined outside VS Code-family terminals.
+ */
+export declare function detectEditorTerminalFamily(env?: NodeJS.ProcessEnv): EditorTerminalFamily | undefined;
+/**
+ * Whether the pty is hosted away from the editor UI (ssh/container/tunnel).
+ * Keybindings live on the client machine, so a remote session must never
+ * write them server-side.
+ */
+export declare function isRemoteTerminalEnv(env?: NodeJS.ProcessEnv): boolean;
+/** Filesystem anchors used to resolve editor config paths (injectable for tests). */
+export interface EditorPathContext {
+    /** User home directory. */
+    homedir: string;
+    /** %APPDATA% on Windows; only read for win32 resolution. */
+    appdata?: string;
+    /** Node platform qualifier. */
+    platform: NodeJS.Platform;
+}
+/**
+ * Resolve the user keybindings.json candidates for one family, most likely
+ * install first. Only paths that exist on disk are repaired.
+ */
+export declare function editorKeybindingCandidates(family: EditorTerminalFamily, context: EditorPathContext): readonly string[];
+/** The one workbench rule that hands Ctrl+R to the focused terminal. */
+export declare const CTRL_R_PASSTHROUGH_RULE: {
+    readonly key: "ctrl+r";
+    readonly command: "workbench.action.terminal.sendSequence";
+    readonly args: {
+        readonly text: "\u0012";
+    };
+    readonly when: "terminalFocus";
+};
+/**
+ * Remove // and block comments from one JSONC document. Double-quoted strings
+ * survive untouched, so comment markers inside string values are preserved.
+ */
+export declare function stripJsoncComments(text: string): string;
+/** Parse one JSONC document; trailing commas are tolerated. */
+export declare function parseJsonc(text: string): unknown;
+/** Outcome of merging the passthrough rule into one keybindings document. */
+export type KeybindingsMerge = {
+    readonly status: 'present';
+} | {
+    readonly status: 'updated';
+    readonly text: string;
+} | {
+    readonly status: 'created';
+    readonly text: string;
+};
+/**
+ * Merge the Ctrl+R passthrough into one keybindings.json document. The raw
+ * text is preserved verbatim (comments included); the rule is inserted right
+ * after the array opener so it cannot be shadowed by later conflicting user
+ * rules. Missing files resolve to a fresh template.
+ * @throws when the document does not carry a rule array.
+ */
+export declare function mergeCtrlRPassthrough(raw: string | undefined): KeybindingsMerge;
+/** User-level marker file content: the startup hint fires at most once per install. */
+export interface EditorKeysFlag {
+    hintShownAt?: string;
+}
+/** Parse one flag file snapshot; missing or corrupt content degrades to unshown. */
+export declare function parseEditorKeysFlag(raw: string | undefined): EditorKeysFlag;
+/** Persist the shown marker; best-effort, the hint is cosmetic and never a gate. */
+export declare function markEditorKeysHintShown(path: string): Promise<void>;
+/** Inputs shared by the apply and startup-hint flows. */
+export interface EditorKeysEnv {
+    /** Process environment (TERM_PROGRAM / VSCODE_IPC_HOOK_CLI). */
+    env: NodeJS.ProcessEnv;
+    /** Filesystem anchors for editor config resolution. */
+    paths: EditorPathContext;
+    /** Absolute path of the one-shot hint marker under the DSH home. */
+    flagPath: string;
+}
+/**
+ * Apply the Ctrl+R passthrough to every local keybindings.json of the hosting
+ * editor and mark the startup hint shown. Existing files get a .dsh-bak
+ * backup before the first write.
+ * @returns a one-line user-facing summary.
+ * @throws with an actionable message when the environment cannot be repaired.
+ */
+export declare function applyCtrlRPassthrough({ env, paths, flagPath }: EditorKeysEnv): Promise<string>;
+/**
+ * Resolve the one-shot startup hint for VS Code-family terminals. Fires at
+ * most once per install (flag file), never when the passthrough rule is
+ * already present, and never in remote ptys where the repair cannot run.
+ * @returns the hint line, or undefined to stay silent.
+ */
+export declare function resolveEditorKeysStartupHint({ env, paths, flagPath }: EditorKeysEnv): Promise<string | undefined>;

package/lib/types/git-workflow.d.ts

@@ -17,7 +17,11 @@ export interface GitDiffView {
 export declare function parseGitDiffFiles(text: string): readonly GitDiffFile[];
 /** Parse the intentionally small, option-safe /diff argument vocabulary. */
 export declare function parseGitDiffSpec(argument: string): GitDiffSpec;
-/** Load one complete textual diff without invoking external diff drivers. */
-export declare function loadGitDiff(cwd: string, argument: string): Promise<GitDiffView>;
+/**
+ * Load one complete textual diff without invoking external diff drivers.
+ * @param signal - aborted by the caller on session switches/quit, killing the
+ * git subprocess instead of letting a stale repository's diff land later.
+ */
+export declare function loadGitDiff(cwd: string, argument: string, signal?: AbortSignal): Promise<GitDiffView>;
 /** Review prompt capped before it reaches a provider context window. */
 export declare function buildReviewPrompt(diff: string, label: string, maxChars?: number): string;

package/lib/types/keyboard.d.ts

@@ -19,10 +19,26 @@
 export declare const KEYBOARD_ENHANCE_ENABLE = "\u001B[>4;0m\u001B[>5u";
 /** Pop the enhancement stack and reset modifyOtherKeys (exit path). */
 export declare const KEYBOARD_ENHANCE_DISABLE = "\u001B[<u\u001B[>4;0m";
+/** Explicit environment overrides for terminal keyboard enhancement. */
+export declare const DSH_DISABLE_KEYBOARD_ENHANCEMENT = "DSH_DISABLE_KEYBOARD_ENHANCEMENT";
+export declare const DSH_ENABLE_KEYBOARD_ENHANCEMENT = "DSH_ENABLE_KEYBOARD_ENHANCEMENT";
+/** True when the process is running inside the VS Code integrated terminal. */
+export declare function isVsCodeTerminalEnv(env?: NodeJS.ProcessEnv): boolean;
+/** Whether to push Kitty keyboard enhancement for the current terminal. */
+export declare function shouldEnableKeyboardEnhancement(env?: NodeJS.ProcessEnv): boolean;
 /** Enable bracketed paste reporting. */
 export declare const BRACKETED_PASTE_ENABLE = "\u001B[?2004h";
 /** Disable bracketed paste reporting. */
 export declare const BRACKETED_PASTE_DISABLE = "\u001B[?2004l";
+/** Enable terminal focus-in/focus-out reporting (xterm focus protocol). */
+export declare const TERMINAL_FOCUS_REPORT_ENABLE = "\u001B[?1004h";
+/** Disable terminal focus-in/focus-out reporting. */
+export declare const TERMINAL_FOCUS_REPORT_DISABLE = "\u001B[?1004l";
+/**
+ * Remove xterm focus reports from one input chunk and update the caller's
+ * focus state. Focus reports are terminal protocol, not composer text.
+ */
+export declare function stripTerminalFocusEvents(chunk: string, onFocus: (focused: boolean) => void): string;
 /** Bracketed paste markers as Ink delivers them (it strips the leading ESC). */
 export declare const PASTE_START_MARKER = "[200~";
 export declare const PASTE_END_MARKER = "[201~";
@@ -39,3 +55,18 @@ export declare function stripPasteMarkers(text: string): string;
  * unaffected.
  */
 export declare function normalizeKeyboardChunk(chunk: string): string;
+/** Editor actions Ink cannot distinguish reliably when terminal bytes batch. */
+export type RawEditorToken = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'home' | 'end' | 'delete-backward' | 'delete-word-backward' | 'delete-forward' | 'delete-word-forward';
+};
+/**
+ * Tokenize a stdin chunk containing at least one editor-only key. Ink calls
+ * `useInput` once for a pasted/batched chunk, so preserving each action here
+ * prevents repeated Backspace/Home/End/Delete presses from collapsing into
+ * one blurred key event. Unknown escape sequences return undefined and stay
+ * under Ink's ownership.
+ */
+export declare function tokenizeRawEditorChunk(chunk: string): readonly RawEditorToken[] | undefined;

package/lib/types/mentions.d.ts

@@ -44,6 +44,8 @@ export interface PreparedMention {
     /** Aggregated snapshot for `agent.inject()`, undefined without references. */
     additionalContext?: import('@deepseek-ai/dsh-session').UserMessage;
 }
+/** Whether a mention token is already navigating a filesystem path. */
+export declare function isPathLikeMentionQuery(query: string): boolean;
 /** The mention API the input editor and the runner share. */
 export interface MentionsApi {
     /** Ranked menu candidates for the typed `@` query. */

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

@@ -0,0 +1,82 @@
+/**
+ * Same-id reasoning-capability inheritance for hand-declared pi-ai routes:
+ * the model catalog inherits capabilities by route key, not by model id, so a
+ * relay route listing `gpt-5.5` reads nothing from the installed `openai`
+ * catalog entry and materializes as `reasoning: false` until its settings
+ * entry declares `reasoningEfforts`. This adapter closes that gap without
+ * touching upstream: whenever a pi-ai profile's model entry carries no
+ * declaration and its live row advertises no efforts, but the same model id
+ * is declared (in a sibling settings entry) or advertised (on another route)
+ * elsewhere, the declaration is materialized into settings — verbatim from a
+ * sibling declaration when one exists, otherwise as an identity level map
+ * (`off` maps to null, every other level to its own name), which is the
+ * correct wire spelling for OpenAI-compatible relays. Writes ride the same
+ * `settings.mutate` path as the provider panel, so the upstream
+ * `assertServiceable` gate still rejects anything invalid atomically.
+ *
+ * @module @deepseek-ai/dsh-tui/model-capabilities
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ModelRow } from './models.ts';
+/** A notice sink structurally compatible with the app bridge's `notify`. */
+export type CapabilityNotice = (text: string, tone?: 'info' | 'warning' | 'error') => void;
+/** One pi-ai provider profile as stored in settings, addressed for mutation. */
+export interface CapabilityProfileSource {
+    /** Settings namespace owning the profile (`llm-pi-ai`). */
+    readonly settingsNs: string;
+    /** Path from the section root to this provider's profile. */
+    readonly settingsPath: readonly string[];
+    /** Revision of the owning section at read time. */
+    readonly revision: number;
+    /** Raw model entries, exactly as stored (declaration fields included). */
+    readonly models: readonly Record<string, unknown>[];
+}
+/** One planned per-provider models rewrite. */
+export interface CapabilitySyncPlan {
+    /** Provider route the plan targets. */
+    readonly provider: string;
+    /** Settings namespace owning the profile. */
+    readonly settingsNs: string;
+    /** Path from the section root to the provider profile. */
+    readonly settingsPath: readonly string[];
+    /** Raw model entries, exactly as stored (declaration fields included). */
+    readonly models: readonly Record<string, unknown>[];
+    /** Fingerprint of the source models array this plan was derived from. */
+    readonly sourceFingerprint: string;
+    /** Document revision of the owning section when the plan was derived. */
+    readonly sourceRevision: number;
+    /** Model ids that gained a declaration, notice-facing. */
+    readonly inherited: readonly string[];
+    /** `provider/model` labels the declarations came from, notice-facing. */
+    readonly sources: readonly string[];
+}
+/**
+ * Plan the reasoning declarations to materialize. A model entry inherits
+ * when it declares nothing (`reasoningEfforts` absent — a dict or `false` is
+ * an explicit choice and is never touched) and its live row advertises no
+ * efforts; the donor is the first sibling settings declaration for the same
+ * id, copied verbatim so dialect wire spellings survive, otherwise the first
+ * other-route row advertising efforts for that id, mapped by identity.
+ * Entries never lose fields and keep their key order; a provider appears in
+ * the result only when at least one entry changes.
+ * @param input - the live model rows and the raw pi-ai profiles from settings.
+ * @returns one plan per provider with at least one inheritance.
+ */
+export declare function planCapabilitySync(input: {
+    readonly rows: readonly ModelRow[];
+    readonly profiles: ReadonlyMap<string, CapabilityProfileSource>;
+}): readonly CapabilitySyncPlan[];
+/**
+ * Materialize same-id reasoning declarations once per provider. Reads the
+ * configurable directory, the redacted settings document, and the live model
+ * rows; plans; then writes each provider's merged models array through
+ * `settings.mutate` under a fresh revision (writes bump the section
+ * revision, so per-plan revisions are re-read). Every failure converges to a
+ * single-line notice — the caller's promise never rejects and the session
+ * keeps running on the previous configuration.
+ * @param ctx - context carrying the `llm` and `settings` services (optional).
+ * @param notify - the app bridge's notice sink, when one is live.
+ */
+export declare function syncModelCapabilities(ctx: Context, notify?: CapabilityNotice): Promise<void>;
+/** Test seam: forget the applied-write fingerprints. */
+export declare function resetCapabilitySyncState(): void;

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

@@ -48,6 +48,13 @@ export interface ProviderModelSettings {
     readonly name?: string;
     readonly contextWindow?: number;
     readonly maxTokens?: number;
+    /**
+     * Remaining entry fields the editor does not model (`reasoningEfforts`,
+     * `compat`, `input`, …), carried verbatim so a save preserves them.
+     * Populated by {@link loadProviderSettings}; never contains the four
+     * modelled keys.
+     */
+    readonly extras?: Readonly<Record<string, unknown>>;
 }
 /** The small, portable subset of a provider profile the terminal edits. */
 export interface ProviderConfiguration {

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

@@ -1,9 +1,8 @@
 /**
- * Terminal animation frame tables derived from the web design language:
- * the StateDot "ongoing" pixel chase (3×3 ring, 125ms flat-hold brightness
- * steps, 1s cycle) becomes the full-ring clockwise braille chase in
- * {@link BUSY_CHASE_FRAMES}, and the streaming caret blink is the
- * Claude-Code convention.
+ * Terminal animation helpers derived from the web design language:
+ * thinking uses Codex's slow shimmer sweep, the busy composer marker uses the
+ * original braille chase, and the 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
@@ -17,14 +16,31 @@
  * @module @deepseek-ai/dsh-code/render/animations
  */
 import type { RgbTriple } from '../theme.ts';
-/**
- * The web StateDot "ongoing" chase in terminal form: three cells of the 3×3
- * ring trail clockwise around the eight outer positions, one braille glyph
- * per step — 8 frames × 125ms = the web's 1s cycle.
- */
+/** Cadence for the original busy braille chase (8 frames × 125ms = 1s). */
+export declare const BUSY_CHASE_TICK_MS = 125;
+/** Original terminal StateDot chase frames. */
 export declare const BUSY_CHASE_FRAMES: readonly ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
-/** Chase frame for a monotonic tick (the busy composer/Deep-diving marker). */
+/** Chase frame for a monotonic tick. */
 export declare function busyChaseFrame(tick: number): string;
+/** Clock cadence for the Codex-style Deep diving shimmer. */
+export declare const DEEP_DIVING_SHIMMER_TICK_MS = 33;
+/** Codex shimmer timing and geometry. */
+export declare const DEEP_DIVING_SHIMMER_DURATION_MS = 2000;
+export declare const DEEP_DIVING_SHIMMER_PADDING = 10;
+export declare const DEEP_DIVING_SHIMMER_HALF_WIDTH = 5;
+export declare const DEEP_DIVING_SPARK_BREATH_DURATION_MS = 2000;
+/**
+ * Codex's 2-second shimmer sweep, expressed in terminal ticks. The sweep has
+ * ten virtual columns of padding on either side and a five-column cosine
+ * highlight band, so the text changes gently rather than cycling rapidly.
+ */
+export declare function deepDivingShimmerIntensity(index: number, tick: number, graphemeCount: number): number;
+/** Blue RGB color for one grapheme in the Codex-style shimmer. */
+export declare function deepDivingGradientColor(index: number, tick: number, graphemeCount: number, base: RgbTriple, highlight: RgbTriple): RgbTriple;
+/** Smooth breathing intensity for the always-visible Deep diving sparkle. */
+export declare function deepDivingSparkIntensity(tick: number): number;
+/** Blue RGB color for the breathing Deep diving sparkle. */
+export declare function deepDivingSparkColor(tick: number, base: RgbTriple, highlight: RgbTriple): RgbTriple;
 /** Caret visibility: half the ticks on, half off (530ms blink). */
 export declare function caretVisible(tick: number): boolean;
 /**

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

@@ -8,9 +8,8 @@
  * grapheme boundaries) so the React state stays two primitives
  * (value, cursor) and every operation here stays pure and testable.
  *
- * Word motion deviates from Codex's UAX#29 segmentation in one deliberate
- * way: a run of same-class characters is ONE piece, so a CJK run moves as a
- * single word (two hanzi are one Alt+B step, not two).
+ * Word motion follows Codex's piece semantics: whitespace separates runs,
+ * punctuation runs stay atomic, and each Han grapheme is its own boundary.
  *
  * @module @deepseek-ai/dsh-code/render/editor
  */
@@ -79,6 +78,15 @@ export interface CaretSite {
     row: number;
     column: number;
 }
+/** Text slices for rendering one physical row with at most one caret. */
+export interface EditorRowParts {
+    readonly before: string;
+    readonly caret: string;
+    readonly after: string;
+    readonly hasCaret: boolean;
+}
+/** Split one row around the authoritative caret; every other row stays whole. */
+export declare function editorRowParts(row: EditorRowModel, rowIndex: number, caretRow: number, cursor: number, caretEnabled?: boolean): EditorRowParts;
 /** Map a cursor offset to its caret site on the wrapped rows. */
 export declare function caretSite(model: EditorModel, offset: number): CaretSite;
 /**
@@ -123,6 +131,23 @@ export declare function killToLineStart(value: string, cursor: number): EditResu
 export declare function killToLineEnd(value: string, cursor: number): EditResult;
 /** Insert sanitized text at the cursor. */
 export declare function insertText(value: string, cursor: number, text: string): EditResult;
+/** Ctrl+A: current logical line start, then the previous line start on repeat. */
+export declare function moveToLineStart(value: string, cursor: number, crossOnRepeat: boolean): number;
+/** Ctrl+E: current logical line end, then the next line end on repeat. */
+export declare function moveToLineEnd(value: string, cursor: number, crossOnRepeat: boolean): number;
+/** One stable text range captured before an asynchronous draft operation. */
+export interface DraftRange {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Remap a captured range when all intervening edits are wholly before or
+ * wholly after it. An edit overlapping either boundary invalidates the
+ * anchor instead of guessing and inserting content at a surprising place.
+ */
+export declare function remapStableRange(original: string, current: string, range: DraftRange): DraftRange | undefined;
+/** Replace a current range while preserving a cursor moved after capture. */
+export declare function replaceRangePreservingCursor(value: string, cursor: number, range: DraftRange, replacement: string): EditResult;
 /**
  * Composer editor row budget: the editor itself never grows past this many
  * physical rows; deeper drafts scroll internally to keep the caret visible.
@@ -130,8 +155,8 @@ export declare function insertText(value: string, cursor: number, text: string):
  */
 export declare function composerMaxRows(terminalRows: number): number;
 /**
- * Codex `should_handle_navigation`: Up/Down walk history only from an empty
- * draft, or from a boundary of a draft that still exactly matches the last
- * recalled entry. Any interior cursor position keeps vertical caret movement.
+ * History navigation starts with Up on an empty draft, or after visual
+ * movement has reached the directional text edge of an unchanged recalled
+ * entry. Every other position remains under textarea movement.
  */
-export declare function shouldRecallNavigate(value: string, cursor: number, lastRecalled: string | null): boolean;
+export declare function shouldRecallNavigate(value: string, cursor: number, lastRecalled: string | null, direction: -1 | 1): boolean;

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

@@ -36,6 +36,31 @@ export declare function reasoningLines(text: string, columns: number): readonly
  * Wrapped continuations keep a hanging indent aligned under each row's
  * content (Codex history-cell alignment) instead of resetting to column 0.
  */
-export declare function transcriptEntryLines(entry: TranscriptEntry, columns: number, showReasoning?: boolean, reasoningToggleHint?: boolean): readonly StyledLine[];
+export declare function transcriptEntryLines(entry: TranscriptEntry, columns: number, showReasoning?: boolean, reasoningToggleHint?: boolean, showToolDetails?: boolean): readonly StyledLine[];
 /** Settled-history variant carrying the Ctrl+R reasoning fold. */
 export declare function settledEntryLines(entry: TranscriptEntry, columns: number, showReasoning: boolean): readonly StyledLine[];
+/** The flexible rows of the live region; chrome (composer/notice/status) is never reduced. */
+export interface LiveAllocation {
+    /** Settled tail rows currently rendered in the live tree. */
+    readonly live: number;
+    /** Rows reserved for the streaming reasoning tail or its marker. */
+    readonly reasoning: number;
+    /** Rows reserved for the streaming answer tail. */
+    readonly answer: number;
+}
+/** A clamped allocation plus the invariant-trip warning that triggered it. */
+export interface LiveAllocationAudit {
+    readonly allocation: LiveAllocation;
+    readonly warning?: string;
+}
+/**
+ * Clamp the live-region allocation so the flexible dynamic rows never exceed
+ * the post-chrome budget. By construction the caller derives these rows from
+ * the same budget; this is the runtime tripwire for a future edit that breaks
+ * that derivation. Reduction order: answer first (the freshest content is the
+ * live tail), then reasoning, then settled live rows; nothing goes negative.
+ * @param allocation - the intended row allocation.
+ * @param dynamicRows - the post-chrome row budget.
+ * @returns the clamped allocation and a warning string when clamping fired.
+ */
+export declare function clampLiveAllocation(allocation: LiveAllocation, dynamicRows: number): LiveAllocationAudit;

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

@@ -21,7 +21,7 @@ export interface MdSegment {
 export interface MdLine {
     segments: readonly MdSegment[];
 }
-/** Visible width of a run in columns (CJK counts double). */
+/** Visible width of a run in columns (grapheme-cluster and emoji aware). */
 export declare function visibleColumns(text: string): number;
 /** Render markdown text into styled lines of at most `width` columns. */
 export declare function renderMarkdown(text: string, width: number, options?: {

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

@@ -357,8 +357,11 @@ export declare function createReplayAccumulator(): ReplayAccumulator;
  * to a sequential fold; only the `entries` container operations are mutable.
  *
  * @internal Test-instrumentation path; `projectEvents` is the public entry.
+ * @returns whether the event changed the accumulated state — the live store
+ * stays silent and keeps its snapshot identity for ignored events, exactly
+ * like the copy-on-write reducer returning its input view unchanged.
  */
-export declare function replayProjectEvent(acc: ReplayAccumulator, event: SessionEvent): void;
+export declare function replayProjectEvent(acc: ReplayAccumulator, event: SessionEvent): boolean;
 /**
  * Materialize the accumulated fold as a `TranscriptView`, compacting any
  * retired tombstones. The anchors maps are handed through as-is (their
@@ -367,6 +370,17 @@ export declare function replayProjectEvent(acc: ReplayAccumulator, event: Sessio
  * @internal Test-instrumentation path; `projectEvents` is the public entry.
  */
 export declare function finishReplay(acc: ReplayAccumulator): TranscriptView;
+/**
+ * Materialize the accumulated fold as a fresh immutable snapshot for the
+ * live store. Unlike {@link finishReplay} — the one-shot replay entry, which
+ * hands the accumulator's own arrays through because the accumulator is
+ * discarded — every array a renderer can hold is copied here, so later
+ * folds never mutate a snapshot already handed out. Same fields, same
+ * tombstone compaction.
+ *
+ * @internal Live-store path; `projectEvents` is the public entry.
+ */
+export declare function snapshotReplayView(acc: ReplayAccumulator): TranscriptView;
 /**
  * Fold a replayed event history into one view.
  *

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

@@ -25,8 +25,8 @@ export declare function singleLineText(text: string): string;
 /**
  * Truncate one display-safe row without ever exceeding its physical-column
  * budget. The ellipsis is included inside the budget, matching Codex's popup
- * truncation contract; the previous app-local helper appended it after the
- * row was already full and could force an extra terminal wrap.
+ * truncation contract; the cut walks grapheme clusters so emoji and
+ * combining sequences never split mid-cluster.
  */
 export declare function truncateColumns(text: string, columns: number): string;
 /** A display-safe suffix bounded by terminal rows and columns. */
@@ -37,13 +37,19 @@ export interface DisplayTail {
     truncated: boolean;
 }
 /**
- * Keep only the newest display-safe text that fits a terminal rectangle.
- * The scan walks backward and stops as soon as the suffix is full, so a long
- * reasoning stream does not rescan its entire accumulated prefix per chunk.
- * Explicit newlines and terminal wrapping both consume rows; tabs expand to
- * two spaces so terminal tab stops (which render at contextual column 8
- * boundaries, not at the budgeted cell count) cannot inflate the physical
- * row count of the live region.
+ * Keep the newest display-safe text that fits a terminal rectangle, wrapping
+ * FORWARD from the start of the text and slicing the tail rows.
+ *
+ * Forward wrapping is what keeps a streaming tail calm: rows already produced
+ * never re-wrap as tokens append (a backward scan recomputes every wrap point
+ * per chunk and the whole visible block jumps), and the wrap rules match the
+ * settled text's renderer so the flush at turn end does not reflow the block
+ * a second time. CJK kinsoku applies at both edges: closing punctuation
+ * overhangs up to two cells onto the filled row instead of starting the next
+ * one (within the caret column the caller reserves), and opening punctuation
+ * moves down instead of dangling at a row end. Tabs expand to two spaces so
+ * terminal tab stops cannot inflate the physical row count; clusters carry
+ * emoji presentation and combining marks whole.
  * @param text - raw externally sourced text.
  * @param columns - available terminal columns.
  * @param rows - available terminal rows.

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

@@ -0,0 +1,29 @@
+/**
+ * Precise terminal-cell width measurement — the single authority every
+ * budget, wrap, and truncation path shares. The previous heuristic
+ * (`codePoint > 0x2e7f ? 2 : 1)) mis-sized Hangul Jamo (narrow), high
+ * non-CJK code points (wide), and emoji: text-default glyphs like ✳ ⚠ ❤
+ * counted 2 while terminals draw 1, and VS16 sequences counted 1 while
+ * terminals draw 2 — the exact drift class the community dsh-TUI string
+ * engine documents (a spinner glyph drifting one column per frame). This
+ * module adapts that engine's rules without its Ink-fork renderer: an ASCII
+ * fast path, grapheme-cluster iteration via Intl.Segmenter (code-point
+ * fallback), a merged East-Asian-Wide/Fullwidth + Emoji_Presentation range
+ * table, text-default emoji = 1, VS16 = 2, marks/selectors/ZWJ = 0.
+ * @module @deepseek-ai/dsh-code/render/width
+ */
+/** Split text into grapheme clusters (code points when Segmenter is absent). */
+export declare function splitGraphemes(text: string): string[];
+/** Terminal-cell width of one grapheme cluster. */
+export declare function graphemeWidth(cluster: string): number;
+/** Terminal-cell width of one code point (surrogate pairs must stay paired). */
+export declare function codePointWidth(char: string): number;
+/**
+ * Terminal-cell width of a string: an ASCII fast path avoids the segmenter
+ * for the overwhelmingly common case; everything else sums grapheme clusters.
+ * Control characters occupy no cells (display sanitization makes them
+ * visible escapes before they ever reach a budget).
+ * @param text - display-safe or raw text to measure.
+ * @returns the column count the terminal will draw.
+ */
+export declare function stringWidth(text: string): number;

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

@@ -102,6 +102,33 @@ export declare function sessionArtifactDirectory(artifact: string, id: string):
  * @returns the ids to delete, root first.
  */
 export declare function collectDeletionSubtree(records: readonly SessionRecord[], id: string): string[];
+/** One validated node of a deletion plan. */
+export interface DeletionPlanNode {
+    /** Session id to remove. */
+    readonly id: string;
+    /** Distance from the deletion root (0 for the root itself). */
+    readonly depth: number;
+}
+/** A fully preflighted subtree deletion, or the refusal that produced none. */
+export type SessionDeletionPlan = {
+    readonly ok: true;
+    readonly nodes: readonly DeletionPlanNode[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Plan one session-subtree deletion with NO filesystem side effects: collect
+ * the doomed lineage, refuse when the root or ANY member is live (a live
+ * child would outlive its deleted parent) or missing from the listing, and
+ * order the result children-first so the executor can never leave a deleted
+ * parent behind surviving children. Artifact-location guards stay at the
+ * call site; this is the pure preflight they complete.
+ * @param records - the full directory listing.
+ * @param id - the root session id to delete.
+ * @returns the ordered plan, or a user-facing refusal reason.
+ */
+export declare function planSessionDeletion(records: readonly SessionRecord[], id: string): SessionDeletionPlan;
 /**
  * Codex-style relative time for session rows ("now", "5m ago", "3h ago",
  * "2d ago"; older than a week falls back to the local date).