dsh-code 1.0.2 → 1.0.3

package/lib/types/app.d.ts

@@ -163,6 +163,8 @@ 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 completion candidate row. */
 interface CompletionCandidate {

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/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/lines.d.ts

@@ -39,3 +39,28 @@ export declare function reasoningLines(text: string, columns: number): readonly
 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).

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

@@ -0,0 +1,33 @@
+/**
+ * Serialized, crash-atomic persistence for the small user-level JSON files
+ * under the DSH home (statusline.json, theme.json). Two guarantees the bare
+ * floating `writeFile` path could not give:
+ *
+ * 1. Every save is appended to ONE chain, so rapid consecutive edits land
+ *    in submission order and the last snapshot is the one on disk (parallel
+ *    floating writes let an older snapshot finish last and win).
+ * 2. Each write goes to a sibling temp file first and is renamed into
+ *    place, so a crash mid-write can never leave a half-written JSON
+ *    document behind.
+ *
+ * The chain itself never rejects: a failed write is reported to that
+ * save's caller while later saves keep their turn.
+ *
+ * @module @deepseek-ai/dsh-code/settings-file
+ */
+/** The serialized persistence surface; flush() is handed to the quit sequence. */
+export interface UserSettingsPersistence {
+    /**
+     * Queue one file snapshot. Resolves when the chain reaches (and renames)
+     * it; rejects only to THIS caller when its own write failed.
+     */
+    save(path: string, text: string): Promise<void>;
+    /** Wait for every queued write; safe to call repeatedly. */
+    flush(): Promise<void>;
+}
+/**
+ * Create the shared settings-write chain. One instance per process keeps
+ * every user-level JSON file mutually serialized.
+ * @returns the persistence handle.
+ */
+export declare function createUserSettingsPersistence(): UserSettingsPersistence;

package/lib/types/store.d.ts

@@ -3,6 +3,16 @@
  * and notifies subscribers. The renderer subscribes through
  * `useSyncExternalStore`; the runner owns event feeding.
  *
+ * Folding runs on the same mutable replay accumulator the persisted-log
+ * path uses (`replayProjectEvent`: id-indexed row updates, in-place
+ * appends), so a live structural event costs O(1) entry work regardless of
+ * transcript length — the copy-on-write fold rebuilt the whole entries
+ * array per event, making a growing session quadratic. An immutable
+ * `TranscriptView` snapshot is materialized only when a changed view is
+ * READ (once per rendered frame under the notification throttle, never per
+ * event), and every snapshot copies its arrays, so a view already handed
+ * out never observes later folds.
+ *
  * Notification coalescing: the fold stays synchronous — `getView()` always
  * returns the latest state the moment `apply` returns — but listener
  * notification is frame-throttled (~16ms) and deduplicated. The zai/GLM

package/lib/types/subagents.d.ts

@@ -7,8 +7,13 @@
  *
  * This is NOT a second transcript: each child folds to ONE row (label,
  * running state, bounded last-activity text), capped at
- * {@link MAX_SUBAGENT_ROWS}. Rows are advisory display state, rebuilt from
- * live events; nothing here persists or replays. Notification is coalesced
+ * {@link MAX_SUBAGENT_ROWS}. The cap is a display budget, not a fan-out
+ * limit: a new running child evicts the OLDEST settled row when one
+ * exists, and while every row is busy the newcomer waits off-screen — but
+ * the observed-session total (getTotalSeen) keeps counting, so status
+ * totals never under-report the fan-out. Rows are advisory display
+ * state, rebuilt from live events; nothing here persists or replays.
+ * Notification is coalesced
  * by the same ~16ms frame throttle as the transcript store (per-burst
  * microtask notify chained SyncLane rerenders past React's nested update
  * limit; a bare macrotask merge repaints a whole turn's bursts at once).
@@ -16,7 +21,7 @@
  * @module @deepseek-ai/dsh-code/subagents
  */
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-/** Hard row cap: a fan-out larger than this stays summarized by the head. */
+/** Hard row cap: overflow evicts the oldest settled row; a fully busy feed waits. */
 export declare const MAX_SUBAGENT_ROWS = 8;
 /** One live subagent row in the feed. */
 export interface SubagentRow {
@@ -37,6 +42,11 @@ export interface SubagentFeedView {
     subscribe(listener: () => void): () => void;
     /** Read the current rows (identity-stable between changes). */
     getSnapshot(): readonly SubagentRow[];
+    /**
+     * Distinct child sessions observed since the last reset. The row cap is
+     * a display budget, not a count of the fan-out; totals surface this.
+     */
+    getTotalSeen(): number;
 }
 /**
  * Fold one child-session event into its feed row (pure).