dsh-diff-approval 0.30.1 → 0.32.0

package/lib/types/client/settings.d.ts

@@ -204,32 +204,58 @@ export declare function setSplitMode(value: boolean): void;
 export declare function mdPreviewEnabled(): boolean;
 /** Persist the Markdown-preview default preference. */
 export declare function setMdPreviewEnabled(value: boolean): void;
+/**
+ * Whether this plugin MOUNTS its own file menu at all — the press bridge that takes over a file press in
+ * the shell's lists, a file link in a message, and a relative link in the Markdown preview.
+ *
+ * Default ON, and the default is the interesting half: only an explicit `'0'` turns it off, so a reader who
+ * never touches the setting keeps the menu they have always had (and a storage that cannot be read — a
+ * privacy mode, a cleared profile — leaves the plugin working rather than silently disabled).
+ *
+ * Off means the bridge does not take the press over AT ALL: no menu, and the shell's own behaviour runs
+ * exactly as if this plugin were not installed. That includes this plugin's own preview, where a relative
+ * link therefore goes back to the browser's own navigation — which is the honest consequence of asking this
+ * plugin to keep its hands off, not a bug to special-case.
+ *
+ * @returns whether the file menu is enabled.
+ */
+export declare function chipMenuEnabled(): boolean;
+/** Persist the file-menu preference (see {@link chipMenuEnabled}). */
+export declare function setChipMenuEnabled(value: boolean): void;
 /**
  * Whether commenting on a diff range is offered: the selection frame's comment button,
- * and the chord that stands for it. Defaults to off while the mode is a preview (see
- * {@link COMMENT_MODE_PREVIEW_KEY}); only an explicit `'1'` enables it. This gates
- * STARTING a thread, not the threads themselves — one already written keeps rendering,
- * so turning the mode off never hides work or interrupts an answer on its way back.
+ * and the chord that stands for it. **Defaults to ON** — comment mode is the mode now,
+ * not a preview — so only an explicit `'0'` turns it off (the `chipMenuEnabled` idiom a
+ * few lines up), and an absent field means on for every profile that predates the flip.
+ * This gates STARTING a thread, not the threads themselves — one already written keeps
+ * rendering, so turning the mode off never hides work or interrupts an answer on its way
+ * back.
  * @returns whether comment mode is on.
  */
 export declare function commentModeEnabled(): boolean;
-/** Window event: comment mode was toggled (see {@link setCommentModeEnabled}). */
-export declare const COMMENT_MODE_CHANGED_EVENT = "diff-approval:comment-mode";
-/** Persist the comment-mode preference. */
+/** Window event: comment mode was toggled (see {@link setCommentModeEnabled}). A DIFFERENT string from
+ *  {@link COMMENT_MODE_KEY} on purpose: a key literal and an event literal that read the same make every
+ *  grep a guess (the hazard this file already names for the file-menu key at the top). */
+export declare const COMMENT_MODE_CHANGED_EVENT = "diff-approval:comment-mode-changed";
+/** Persist the comment-mode preference (`'1'` on, `'0'` off — see {@link commentModeEnabled}). */
 export declare function setCommentModeEnabled(value: boolean): void;
 /**
  * Whether the diff's code uses the font this plugin bundles.
  *
- * Defaults to **off**: the bundled face is JetBrains Maple Mono subset and
- * sliced into 138 woff2 files, and a page pulls the slices its characters land
- * in — tens of kilobytes for a comment, up to ~120 KB for a rare character. That
- * is real traffic, so it is the reader's decision, not a default they discover.
- * Only an explicit `'1'` enables it.
+ * **Defaults to ON**, like comment mode: absent means on, and only an explicit `'0'` turns
+ * it off. The old field's answer is deliberately NOT carried over (see the constant): a
+ * reader who had turned the bundled face off before this change comes back with it on, which
+ * is the one behaviour the reader asked for. The cost is real and worth naming where the
+ * switch is: the face is a JetBrains Maple Mono subset sliced into 138 woff2 files, and a
+ * page pulls only the slices its characters land in — tens of kilobytes for a comment, up to
+ * ~120 KB for a rare character — downloaded on demand rather than shipped.
  * @returns whether the bundled code font is enabled.
  */
 export declare function codeFontEnabled(): boolean;
-/** Window event: the bundled code font was turned on or off (see {@link setCodeFontEnabled}). */
-export declare const CODE_FONT_CHANGED_EVENT = "diff-approval:code-font";
+/** Window event: the bundled code font was turned on or off (see {@link setCodeFontEnabled}). A DIFFERENT
+ *  string from {@link CODE_FONT_KEY} on purpose — they used to be the same literal, which made a grep for
+ *  either one a guess (the hazard this file names for the file-menu key at the top). */
+export declare const CODE_FONT_CHANGED_EVENT = "diff-approval:code-font-changed";
 /** Persist the bundled-code-font preference. */
 export declare function setCodeFontEnabled(value: boolean): void;
 /**

package/lib/types/client/slots.d.ts

@@ -4,7 +4,7 @@ import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
 import type { DockSnapshot } from './dock.tsx';
 import type { CommentDraft } from './port.ts';
 import type { CommentLineRange } from '../comment-lines.ts';
-import type { CommentRecord, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalCommentAddValue, DiffApprovalCommentAskValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, DiffApprovalOpenAction, DiffApprovalRefreshValue, PendingFileDiff, VcsImportValue } from '../types.ts';
+import type { CommentRecord, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalCommentAddValue, DiffApprovalCommentAskValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, DiffApprovalOpenAction, DiffApprovalRefreshValue, DiffApprovalUpdateValue, PendingFileDiff, VcsImportValue } from '../types.ts';
 /** What the panel reads and drives: the pending list plus in-flight entries. */
 export interface PendingDiffSnapshot {
     /** Whether a list read has completed at least once. */
@@ -32,6 +32,21 @@ export interface PendingDiffSnapshot {
     commentAnswers: Record<string, string>;
     /** A read failure's message; absent while the latest read succeeded. */
     error?: string;
+    /**
+     * How many rows the host says this session has, from the LIGHT read (`list-count`) — the badge's
+     * question, answered without shipping any file content.
+     *
+     * It is the number a full read would have carried, but it is a separate fact with a separate age: a
+     * count lands on ticks that ask only for a count (when nothing is showing), and a FULL read clears it,
+     * because that read carries the same fact in `files` and is newer. So a reader's rule is
+     * `count ?? files.length` — the fallback covers both "no count has arrived" and "the list is fresher",
+     * and a count that FAILED leaves the previous number in place rather than showing zero.
+     *
+     * Absent on a host that predates the endpoint: there the store keeps doing full reads, the value stays
+     * absent, and every reader stays on the fallback — today's behaviour, at today's cost (see
+     * `PendingDiffStore.refreshCount`).
+     */
+    count?: number | undefined;
     /** Entry ids whose keep/revert is in flight; their controls are disabled. */
     busy: ReadonlySet<string>;
     /** Entry ids whose last keep/revert failed, mapped to the error message; the panel surfaces these inline (row tag + detail banner) instead of hiding the list. */
@@ -69,8 +84,81 @@ export interface PendingDiffSnapshot {
      * panel is closed) via a bottom-right notice. */
     redoCleared?: boolean;
 }
+/** One filter over one session's view of the pending list; the shape every view hook takes. */
+export type PendingViewSelector<T> = (view: PendingDiffSnapshot) => T;
+/**
+ * The number a badge, a header entry or a dock chip shows for one session: the light count when one has
+ * arrived, else the length of the list that read carried.
+ *
+ * The fallback is not a nicety — it is the whole older-host story and the state before the first count
+ * lands. `count` is absent when no count has arrived (the page just loaded, or the host predates the
+ * endpoint, where the store keeps doing full reads) and it is cleared by every full read, whose `files`
+ * are the same fact and newer. So `count` is only ever shown while it is the FRESHEST number the client
+ * has; otherwise the list speaks. See `PendingDiffSnapshot.count`.
+ * @param view - one session's view.
+ * @returns how many rows it holds.
+ */
+export declare function countOf(view: PendingDiffSnapshot): number;
+/**
+ * The view a seat draws when it has NO reviewable session: a session that is absent, or one the shell has
+ * told us is blank — a brand-new session with nothing said in it yet.
+ *
+ * This exists because the page-wide fallback is the wrong answer for such a seat. `viewFor(undefined)`
+ * and `getSnapshot()` deliberately answer the newest session read on the page (the whole-page contract the
+ * remap follows), and with the store's slots keyed only by session id and no workspace comparison anywhere
+ * in this client, "the newest read" can be another session's list — even another workspace's. A seat that
+ * has nothing of its own to show must draw NOTHING, and this is the nothing: no rows (so `countOf` is 0),
+ * no comments, no workspace, and `read: false` because nothing has been read FOR this seat.
+ *
+ * Shared rather than re-spelled per seat: the panel's badge and body, the header entry's count and the
+ * dock chip all have to agree that "no reviewable session" means zero, and a second literal here is how
+ * they would drift. Frozen because it is handed to readers as a snapshot: nothing may write through it.
+ */
+export declare const EMPTY_PENDING_VIEW: PendingDiffSnapshot;
+/**
+ * The view a seat DRAWS when there is nothing to review: the same emptiness as {@link EMPTY_PENDING_VIEW},
+ * but READ.
+ *
+ * The difference is what the panel draws: an unread view is a session whose list is still coming, so it
+ * shows the loading state, while this one says "no pending changes" — the truth for a session that is
+ * absent or blank. Using the unread view here would leave a docked panel spinning forever behind an entry
+ * that is disabled and can never be opened.
+ */
+export declare const NOTHING_TO_REVIEW_VIEW: PendingDiffSnapshot;
+/** Function shape of {@link PendingViewHooks.pendingView}; named so a seat can call it directly. */
+export type PendingViewReader = <T>(sessionId: SessionId | undefined, select: PendingViewSelector<T>) => T;
+/**
+ * How a seat reads pending state for the session it is actually about.
+ *
+ * The page runs several seats at once — the sidebar footer's badge, the Session header's entry, the
+ * docked tab's chip and body — and they can belong to different sessions. Reading the ONE page-wide
+ * snapshot is what let a badge show another session's count, so a seat that knows its session reads
+ * that session's own view through {@link PendingViewHooks.pendingView} and nothing else.
+ *
+ * This lives BESIDE the face's `hooks`, not inside it: that compartment is a map of observables
+ * (`HooksSources`), and the framework binds each one onto the component props as a `use<Name>` selector
+ * hook. Folding a non-observable in there would stop the whole compartment from matching, and the panel
+ * would lose `usePending` and `useDock` with it. `pendingView` is a read, not an observable: the panel's
+ * `usePending` subscription is what re-renders it.
+ *
+ * The hook is optional because the shapes are read structurally: a host (or a test) that offers only
+ * `pending` still renders, with the panel falling back to the page-wide snapshot.
+ */
+export interface PendingViewHooks {
+    /**
+     * Read one session's own view, with `select` applied inside the subscription.
+     *
+     * `sessionId === undefined` means "I have no session of my own": the answer is then the page-wide
+     * view (the newest session read), which is what a whole-page caller wants. A session that has never
+     * been read answers an unread empty view — never another session's list.
+     * @param sessionId - the session whose view to read.
+     * @param select - what to take out of that view.
+     * @returns the selected value.
+     */
+    pendingView?: PendingViewReader | undefined;
+}
 /** The injected face the panel component receives from the plugin body. */
-export interface PendingPanelFace {
+export interface PendingPanelFace extends PendingViewHooks {
     hooks: {
         /** Live pending-diff snapshot for the current page. */
         pending: HostObservable<PendingDiffSnapshot>;
@@ -91,8 +179,26 @@ export interface PendingPanelFace {
     /** Close the docked tab now, when one exists (the quick-summon chord's job
      *  while the panel lives in the sidebar). */
     closeDock?: (() => void) | undefined;
+    /**
+     * Ask the host whether a newer release of this plugin is published.
+     *
+     * Optional, and deliberately so: a seat that is not given one (an older shell wiring, or a
+     * harness that does not stage it) simply draws no update chip. The panel calls it ONCE, after
+     * mount, and never waits on it — a host that cannot answer, or has no answer to give, leaves the
+     * chip's site exactly as it was. The answer is drawn in ONE place (the open file's status bar, at
+     * the panel's bottom edge) out of one piece of panel state.
+     */
+    onCheckUpdate?: (() => Promise<DiffApprovalUpdateValue>) | undefined;
     /** Read the pending list for the current session into the snapshot. */
     onRefresh: (sessionId: SessionId | undefined) => void;
+    /**
+     * The badge's tick, for a seat with nothing on screen: ask how many rows the session has, with no file
+     * content on the wire. Optional so a face built against an older shape still renders — the panel then
+     * keeps the full read, which is what such a page did before the verb existed.
+     */
+    onRefreshCount?: ((sessionId: SessionId | undefined) => void) | undefined;
+    /** The reader is looking at this file now: its row's unseen dot goes out. */
+    onMarkSeen?: ((sessionId: SessionId | undefined, id: string) => void) | undefined;
     /** Keep one operation. `keepListed` leaves the resolved entry in the list. */
     onKeep: (sessionId: SessionId, id: string, keepListed?: boolean) => Promise<void>;
     /** Revert one operation (restore its prior content, or remove a created file).
@@ -149,7 +255,7 @@ export interface PendingPanelFace {
     /**
      * Drop several annotations in one host call. Ending a pick of comments is one action the reader
      * asked for, so it goes to the host as one request and comes back as one read — see
-     * `DiffApprovalStore.commentRemoveMany`.
+     * `PendingDiffStore.commentRemoveMany`.
      */
     onCommentRemoveMany: (sessionId: SessionId, ids: readonly string[]) => Promise<DiffApprovalCommentRemoveManyValue>;
     /**
@@ -159,6 +265,12 @@ export interface PendingPanelFace {
      * question so the thread can draw what was written.
      */
     onCommentAsk: (sessionId: SessionId, id: string, prompt: string, text: string) => Promise<DiffApprovalCommentAskValue>;
+    /**
+     * The reader has this comment's card in view: its unseen dot goes out, and the answers on it become
+     * the baseline a later rewrite is measured against. A reader action, so it is its own call rather
+     * than something a read does — a read that cleared attention would make the dot impossible to see.
+     */
+    onCommentSeen?: ((sessionId: SessionId, id: string) => void) | undefined;
     /** Acknowledge the redo-cleared notice so it is only surfaced once. */
     onAckRedoCleared: () => void;
     /** Acknowledge a refused-undo notice once the panel has said it (see `undoNotice`). */

package/lib/types/client/store.d.ts

@@ -12,8 +12,51 @@ import type { PendingDiffSnapshot } from './slots.ts';
 import type { CommentDraft, DiffApprovalPort } from './port.ts';
 /** The observable the panel reads and the plugin body drives. */
 export interface PendingDiffStore extends HostObservable<PendingDiffSnapshot> {
+    /**
+     * One session's own view of the pending list.
+     *
+     * The page runs several mounts of the panel at once — the footer entry, the Session header entry and
+     * the docked tab — and they can be about DIFFERENT sessions (the reader is in one, while the docked
+     * tab was opened from another). One page-wide snapshot made every badge read whichever session's read
+     * landed last, which is the cross-talk the reader reported: a badge showing another session's count,
+     * and a session with a real list showing zero. So each session's read publishes only into its own
+     * slot, and every consumer takes its own slot, by the session it is actually about.
+     *
+     * A session that has never been read answers an unread empty view — never another session's list.
+     * `sessionId === undefined` answers the most recently published view — exactly what
+     * {@link PendingDiffStore.getSnapshot} answers — because that is what a caller with no session of its
+     * own (a whole-page concern) is asking for.
+     * @param sessionId - the session whose view to read.
+     * @returns that session's snapshot, identity-stable until it is next published.
+     */
+    viewFor: (sessionId: SessionId | undefined) => PendingDiffSnapshot;
+    /**
+     * Every session's view this page is HOLDING, one per session it has read.
+     *
+     * This is the reader a press needs (see `produced-diff.ts`): a shell press names a file and asks whether
+     * ANY session this page has read holds it, and the press cannot wait for a poll. The slots are where the
+     * fresh paths live — the light read's `paths` and the last full read's `files` — so answering from the
+     * slots is what keeps a file edited since the last full read from being a press nothing recognises.
+     * @returns the held views; a session never read contributes nothing (it has no slot).
+     */
+    views: () => readonly PendingDiffSnapshot[];
     /** Re-read one session's pending list (an absent session empties the view). */
     refresh: (sessionId: SessionId | undefined) => Promise<void>;
+    /**
+     * Ask how many rows this session has, THE LIGHT WAY: one number, no file content.
+     *
+     * This is what a seat polls while it is showing nothing but its badge. It publishes into the same
+     * per-session slot as `refresh` — as `count`, never as `files` — so a badge keeps reading the view it
+     * already subscribes to, and it deliberately does NOT set `read` (a count is not a list: a session
+     * whose list has never been read stays unread, and its list stays empty rather than looking loaded).
+     *
+     * Failure keeps the LAST GOOD number: a count that failed knows nothing, and showing 0 or a blank
+     * badge for a list that may well be full is worse than showing the previous figure. A host that
+     * predates the endpoint (`unknown endpoint "list-count"`) is detected here ONCE and then this call
+     * degrades to `refresh`, which is exactly the old behaviour at exactly the old cost — one full read
+     * per tick — and an absent session has no count to ask for, so it returns without a call.
+     */
+    refreshCount: (sessionId: SessionId | undefined) => Promise<void>;
     /** Keep one operation. `keepListed` leaves the resolved entry in the list. */
     keep: (sessionId: SessionId, id: string, keepListed?: boolean) => Promise<void>;
     /** Revert one operation. `keepListed` leaves the resolved entry in the list. */
@@ -35,6 +78,11 @@ export interface PendingDiffStore extends HostObservable<PendingDiffSnapshot> {
     browse: (sessionId: SessionId, path?: string) => Promise<DiffApprovalBrowseValue>;
     /** Add one named path to the list, then refresh; resolves to what the scan did. */
     addPath: (sessionId: SessionId, path: string, includeUnchanged: boolean, exact?: boolean) => Promise<DiffApprovalAddValue>;
+    /**
+     * The reader is looking at this file now: its row's unseen dot goes out. Deliberately NOT followed by a
+     * re-read — see the note at the implementation.
+     */
+    markSeen: (sessionId: SessionId, id: string) => Promise<void>;
     /** Open one file with its default application or reveal it in the folder. */
     open: (sessionId: SessionId, id: string, action: DiffApprovalOpenAction) => Promise<void>;
     /** Keep every pending entry of one session in a single host call, then refresh. */
@@ -70,6 +118,8 @@ export interface PendingDiffStore extends HostObservable<PendingDiffSnapshot> {
     commentRemoveMany: (sessionId: SessionId, ids: readonly string[]) => Promise<DiffApprovalCommentRemoveManyValue>;
     /** Ask one stored comment as its own turn, then refresh (the answer is derived on read). */
     commentAsk: (sessionId: SessionId, id: string, prompt: string, text: string) => Promise<DiffApprovalCommentAskValue>;
+    /** The reader is looking at a comment: its card's dot goes out, then the list is re-read. */
+    commentSeen: (sessionId: SessionId, id: string) => Promise<void>;
     /** Drop every local fact (used on connection reset). */
     reset: () => void;
     /** Acknowledge a redo-cleared notice so the panel surfaces it only once. */

package/lib/types/client/whole-file-diff.d.ts

@@ -33,6 +33,21 @@ export interface ChangeBlock {
 }
 /** Split a row list into maximal runs of non-context rows. */
 export declare function changeBlocksOf(diff: WholeFileDiff): ChangeBlock[];
+/**
+ * The change region a row range sits in, widened to whole runs: from the first row of the run `start`
+ * belongs to, to the last row of the run `end` belongs to. A row range that names one side of a change —
+ * one line of a replacement, or the additions alone — grows to cover that change's removals as well, which
+ * is what a reader pointing at it means. Rows that are context stand alone (a run is a maximal non-context
+ * run), so a range that touches no change is returned as it is.
+ * @param rows - the whole-file diff rows.
+ * @param start - the range's first row.
+ * @param end - the range's last row.
+ * @returns the widened row range.
+ */
+export declare function changeRunSpanOf(rows: readonly WholeFileDiffRow[], start: number, end: number): {
+    start: number;
+    end: number;
+};
 /**
  * One diff block's old/new line ranges, 1-based inclusive, for block-level
  * keep/revert. A side with no lines (a pure addition or deletion) is empty; its
@@ -46,6 +61,33 @@ export declare function changeBlocksOf(diff: WholeFileDiff): ChangeBlock[];
  * @returns the old and new line ranges.
  */
 export declare function blockRangesOf(rows: readonly WholeFileDiffRow[], block: ChangeBlock): DiffApprovalBlockRange;
+/** One side-by-side pair: the whole-file row index each side holds, when it has one. */
+export interface DiffPairRows {
+    old?: number;
+    new?: number;
+}
+/**
+ * One side-by-side pair's old/new line ranges, 1-based inclusive, for pair-level keep/revert. A pair is
+ * one old line against one new line, so each side contributes a single line; a side the pair does not
+ * have (an unpaired insertion or removal) is the empty range at that side's insertion point, read off the
+ * row before the pair — the same rule `blockRangesOf` applies to a side with no lines at all.
+ * @param rows - the whole-file diff rows.
+ * @param pair - the rows the pair holds.
+ * @returns the old and new line ranges, or undefined for a pair that holds no row.
+ */
+export declare function pairRangeOf(rows: readonly WholeFileDiffRow[], pair: DiffPairRows): DiffApprovalBlockRange | undefined;
+/**
+ * The old/new ranges keep/revert act on for the pairs a side-by-side selection names, in the order they
+ * must be sent. Pairs of context rows are dropped (nothing to act on). When the changed pairs occupy one
+ * contiguous span of the row list with no other changed row inside it, ONE range covers them all: one
+ * host call, one undo step, and the same range a whole-block action would send. Otherwise each pair gets
+ * its own range, ordered from the BOTTOM of the file up, so a splice never moves the line numbers of a
+ * pair still to be applied.
+ * @param rows - the whole-file diff rows.
+ * @param pairs - the pairs the selection names, in row order.
+ * @returns one range, several, or none when the selection carries no change.
+ */
+export declare function pairsRangeOf(rows: readonly WholeFileDiffRow[], pairs: readonly DiffPairRows[]): DiffApprovalBlockRange[];
 /**
  * Compute the whole-file view between two contents. The context budget is the
  * side lengths, so every hunk covers the file and unchanged lines survive as

package/lib/types/comment-ask.d.ts

@@ -19,8 +19,8 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { SessionId } from '@deepseek-ai/dsh-session';
-import type { DiffApprovalCommentAskValue } from './types.ts';
-import type { CommentStore } from './comments.ts';
+import type { DiffApprovalCommentAskValue, CommentRecord } from './types.ts';
+import type { CommentScope, CommentStore } from './comments.ts';
 /** One derived transcript message, narrowed to what answering a comment needs. */
 interface DerivedMessage {
     role?: unknown;
@@ -75,6 +75,14 @@ export interface AskRead {
     /** The claiming turn is over (`turn/end` in the log), whatever it did or did not write. */
     ended: boolean;
 }
+/**
+ * One request's already-read transcripts, keyed by the session read.
+ *
+ * `undefined` is cached as a value (hence `has`, not a truthy check): a session whose log cannot be
+ * read must not be asked for again within the same read, or a folded-over lineage would pay for the
+ * same failure once per transcript.
+ */
+export type TranscriptCache = Map<SessionId, readonly LogEvent[] | undefined>;
 /**
  * The answer to one submitted comment, read from the session's own event log.
  *
@@ -99,13 +107,6 @@ export interface AskRead {
  * @returns the claiming turn, its answer text, and whether the turn is over.
  */
 export declare function answerForRequest(events: readonly LogEvent[], requestId: string): AskRead;
-/**
- * Read every question one session has asked, keyed by its request id.
- * @param events - the session's event log, in sequence order.
- * @param requestIds - the questions' request ids.
- * @returns the read per request id; a question the log holds nothing for reads as nothing.
- */
-export declare function answersIn(events: readonly LogEvent[], requestIds: readonly string[]): Record<string, AskRead>;
 /**
  * Submits comments as turns of their session, and reads their answers back.
  *
@@ -140,24 +141,44 @@ export declare class CommentAsker {
      * arrives while the submission is still in flight already finds its comment. A
      * submission that rejects is marked dropped rather than left looking pending.
      *
-     * @param sessionId - the session the comment belongs to.
+     * @param sessionId - the session the question is asked FROM: the prompt goes into it, so its
+     *   transcript is where the answer will appear.
      * @param commentId - the comment to ask.
      * @param prompt - the prompt text to send verbatim.
      * @param text - the reader's own words, which the prompt wraps: the thread keeps these.
      * @param signal - aborts the submission.
+     * @param inScope - which comment authors the caller's lineage covers, so a thread another seat
+     *   wrote can be asked from this one.
      * @returns what the request did.
      */
-    ask(sessionId: SessionId, commentId: string, prompt: string, text: string, signal: AbortSignal): Promise<DiffApprovalCommentAskValue>;
+    ask(sessionId: SessionId, commentId: string, prompt: string, text: string, signal: AbortSignal, inScope: CommentScope): Promise<DiffApprovalCommentAskValue>;
+    /**
+     * One scope's questions, grouped by THE TRANSCRIPT each was submitted into.
+     *
+     * A lineage's threads may hold questions asked from several seats, and an answer lives in the
+     * transcript of the session that was asked — so the read is per transcript, not per thread. Grouping
+     * here (rather than reading each thread separately) is what keeps a poll to ONE log walk per
+     * transcript, however many threads asked there.
+     *
+     * The legacy case is why `askTranscript` exists: a question asked before the asking session was
+     * recorded has only the comment's own session to go on, which is where it went.
+     * @param visible - the comments this read may see (already scoped by the caller).
+     * @returns the request ids per transcript; empty when nothing was ever asked.
+     */
+    answerGroups(visible: readonly CommentRecord[]): Map<SessionId, string[]>;
     /**
-     * Every question of one session and what the transcript says about it, keyed by the
+     * Every question submitted into ONE transcript and what it says about them, keyed by the
      * question's request id (which is what `CommentAsk` records and what a client matches
-     * against). Derived from the session's own event log on every call and never stored:
-     * the log is the one source of truth for what the agent said, so a stored copy could
-     * only ever disagree with it.
-     * @param sessionId - the session whose comments to read.
+     * against). Derived from that session's event log on every call and never stored: the log
+     * is the one source of truth for what the agent said, so a stored copy could only ever
+     * disagree with it.
+     * @param sessionId - the transcript to read.
+     * @param requestIds - the questions that were submitted into it.
+     * @param cache - this request's already-read logs, so the answer fold and the turn-end read
+     *   below share ONE walk of a log that can hold >100k events.
      * @returns the read per question; empty when the session holds no questions.
      */
-    answers(sessionId: SessionId): Record<string, AskRead>;
+    answersFor(sessionId: SessionId, requestIds: readonly string[], cache?: TranscriptCache): Record<string, AskRead>;
     /**
      * The turns the session's log shows as over, for the questions it holds.
      *
@@ -167,10 +188,11 @@ export declare class CommentAsker {
      * a client that connected afterwards, a deployment whose agent events cannot be
      * subscribed at all — because `turn/end` is durable and the event is not.
      *
-     * @param sessionId - the session whose turns to check.
+     * @param sessionId - the transcript whose turns to check.
+     * @param cache - this request's already-read logs (see `answersFor`).
      * @returns the turns the log closed, or empty when the log cannot be read.
      */
-    endedTurns(sessionId: SessionId): number[];
+    endedTurns(sessionId: SessionId, cache?: TranscriptCache): number[];
     /**
      * One session's event log, as the reads above take it.
      *
@@ -180,7 +202,12 @@ export declare class CommentAsker {
      * and `snapshotEvents` hands back a frozen, sequence-ordered copy of it, so walking it
      * is a plain read that cannot disturb the session.
      *
+     * The cache is per REQUEST, not per session: one list read asks this twice for every transcript
+     * (the answer fold and the turn-end read), and the copy is the expensive part of a long session's
+     * log. `has` rather than a truthy check, so "cannot be read" is cached as such instead of being
+     * asked again.
      * @param sessionId - the session to read.
+     * @param cache - this request's already-read logs, when the caller is doing several reads.
      * @returns its events, or undefined when no live session can be read.
      */
     private sessionEvents;
@@ -200,7 +227,7 @@ export declare class CommentAsker {
      * released first, so re-arming is not a leak: one set of handlers per live agent,
      * not one more per identity change.
      *
-     * Called on every ask AND on every poll read (`answers`), because the agent can be
+     * Called on every ask AND on every poll read (`answersFor`), because the agent can be
      * replaced while a question is still pending — the case where nothing asks again.
      * @param sessionId - the session whose agent to watch.
      */