dsh-diff-approval 0.30.1 → 0.31.0

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/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.
      */

package/lib/types/comments.d.ts

@@ -16,7 +16,8 @@
  * @module dsh-diff-approval/src/comments
  */
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
-import type { CommentRecord } from './types.ts';
+import type { CommentAsk, CommentRecord } from './types.ts';
+import type { AskRead } from './comment-ask.ts';
 /**
  * The comment directory that belongs to a pending-storage root.
  *
@@ -32,6 +33,28 @@ import type { CommentRecord } from './types.ts';
  * @returns the directory holding the comments that belong to that root.
  */
 export declare function commentsDirFor(storageRoot: string): string;
+/**
+ * The scope one request may act on: which comment AUTHORS its lineage covers.
+ *
+ * This module knows nothing about lineages — the host walks them — so the rule arrives as a predicate,
+ * built once per request from the lineage view the endpoint already has (`sameRoot`). Every read and
+ * every guard takes it, which is what lets the store answer for a whole lineage without a second
+ * lineage rule living down here beside the first.
+ */
+export type CommentScope = (author: SessionId) => boolean;
+/**
+ * The transcript one question's answer will be written in.
+ *
+ * `ask.sessionId` when the question recorded one — every question asked since a lineage could read more
+ * than one seat's threads does — otherwise the comment's own session, which is where a question asked
+ * before that field existed necessarily went: the only session that could ask it was the one that wrote
+ * the thread. ONE definition, shared by the answer fold, the turn-end match and the asker's grouping,
+ * so the three cannot disagree about which transcript a question belongs to.
+ * @param ask - the question.
+ * @param comment - the thread it was asked in.
+ * @returns the session whose transcript holds its answer.
+ */
+export declare function askTranscript(ask: CommentAsk, comment: CommentRecord): SessionId;
 /**
  * How a caller hears about the two ways a comment file can go wrong.
  *
@@ -138,8 +161,20 @@ export declare class CommentStore {
      * @param error - why it could not be read.
      */
     private skip;
-    /** One session's comments, oldest first (the order threads are read in). */
-    list(sessionId: SessionId): CommentRecord[];
+    /**
+     * The comments one SCOPE may read, oldest first (the order threads are read in).
+     *
+     * The scope is the caller's lineage rule (`CommentScope`), so a seat reads every thread of the seats
+     * it shares a lineage root with — not only the ones it wrote. The files do not move for that: each
+     * comment still lives in its author's file (see `save`), and the fan-out happens here, in memory,
+     * over the one map `loadAll` filled from every file. That is what keeps a teammate's already-written
+     * threads visible, with no migration.
+     * @param scope - which comment authors this caller may read.
+     * @returns the comments those authors wrote, oldest first.
+     */
+    list(scope: CommentScope): CommentRecord[];
+    /** One author's own comments, oldest first: the WRITE-SET of that author's file (see `save`). */
+    private authoredBy;
     /** A comment by id, whatever session it belongs to. */
     get(id: string): CommentRecord | undefined;
     /**
@@ -148,6 +183,42 @@ export declare class CommentStore {
      * what says whether anything moved since the last read.
      */
     commentsRevision(): number;
+    /**
+     * Fold what ONE transcript now says into the threads that asked there, so a thread whose answer has
+     * arrived (or been rewritten) wears the dot.
+     *
+     * The answers are DERIVED on every list read and never trusted from the file (see
+     * `CommentRecord.answerNow`): the read is the only moment the host knows what the agent has said, and
+     * the comparison it makes is against a baseline that survives a restart — a restart must not light a
+     * dot the reader already cleared, and a read that changed nothing must not light one at all. That is
+     * what `answerSeen` is, and why this writes a baseline only when the text actually moved.
+     *
+     * A question the transcript shows no answer for goes back to ABSENT rather than looking like an
+     * empty answer: a log this process cannot read (or a turn that has not written yet) then leaves the
+     * dot exactly as it was, instead of raising it on every poll.
+     *
+     * The patch's own key is the TRANSCRIPT, not the comment's author: a thread written in one seat can
+     * hold a question asked from another (see `askTranscript`), and this read is that other seat's log.
+     * Only the questions whose answer lives in `sessionId` are folded; a thread that also holds questions
+     * asked elsewhere keeps those exactly as that transcript's own fold left them.
+     *
+     * @param sessionId - the transcript being folded, which owns the questions it is handed.
+     * @param answers - the answer text per question id, as that transcript read it.
+     * @returns whether any thread changed.
+     */
+    syncAnswers(sessionId: SessionId, answers: Readonly<Record<string, AskRead>>): boolean;
+    /**
+     * Mark one comment as looked at: the dot goes out, and the answers it currently shows become the
+     * baseline a later rewrite is measured against — otherwise the next read would find the same answer
+     * "new" again and put the dot straight back up.
+     *
+     * Deliberately its own seam rather than something a read does: only a reader action (the card coming
+     * into view) may clear attention, and a read that cleared it would make the dot impossible to see.
+     *
+     * @param id - the comment the reader has in front of them.
+     * @returns whether the comment existed.
+     */
+    markSeen(id: string): boolean;
     /**
      * Record one annotation.
      *
@@ -196,30 +267,35 @@ export declare class CommentStore {
      */
     private mergeOf;
     /**
-     * Drop one comment.
-     * @param sessionId - the session the caller believes the comment belongs to.
+     * Drop one comment the caller's scope covers.
+     * @param scope - which comment authors the caller may act on.
      * @param id - the comment to drop.
-     * @returns whether it was there (and belonged to that session).
+     * @returns whether it was there (and was in scope).
      */
-    remove(sessionId: SessionId, id: string): boolean;
+    remove(scope: CommentScope, id: string): boolean;
     /**
-     * Drop several comments of one session in ONE write.
+     * Drop several comments in one write PER FILE that holds them.
      *
      * This is what a batch action needs and what a loop of `remove` calls cannot give it: each
-     * `remove` saves the session's file, so ending ten comments wrote that file ten times — ten
-     * chances for a transient failure to leave the store and the disk disagreeing about an action
-     * the reader asked for once. The save happens only when something was actually dropped, so a
-     * batch that matches nothing does not rewrite the file.
+     * `remove` saves the file, so ending ten comments wrote that file ten times — ten chances for a
+     * transient failure to leave the store and the disk disagreeing about an action the reader asked
+     * for once. The save happens only when something was actually dropped, so a batch that matches
+     * nothing does not rewrite a file.
+     *
+     * Each record is removed from the file that HOLDS it, which is its author's (`save`), not the
+     * caller's: once a lineage reads every seat's threads, a batch can name comments written by several
+     * seats, and routing them all to the caller's file would leave the real files holding records the
+     * store no longer has — the next load would resurrect every one of them.
      *
-     * An id of another session, or one that is not here at all, is skipped rather than refused:
+     * An id outside the scope, or one that is not here at all, is skipped rather than refused:
      * a batch is one request and the comments it names are the ones it can act on, and a comment
      * another client already ended is the state the caller was asking for anyway.
      *
-     * @param sessionId - the session the caller believes the comments belong to.
+     * @param scope - which comment authors the caller may act on.
      * @param ids - the comments to drop; a repeated id is one comment.
      * @returns the ids that were dropped, in the order given.
      */
-    removeMany(sessionId: SessionId, ids: readonly string[]): string[];
+    removeMany(scope: CommentScope, ids: readonly string[]): string[];
     /**
      * Every comment one pending entry carries, oldest first.
      *
@@ -240,17 +316,29 @@ export declare class CommentStore {
      */
     removeForEntry(entryId: string): number;
     /**
-     * The orphan sweep: drop every comment whose entry is not in `entryIds`.
-     *
-     * The explicit `removeForEntry` is the primary path; this is the backstop that
-     * catches a comment left behind by a crash between the two writes. Run it when
-     * the store loads and on every list read, and the one race it could lose — an
-     * entry re-added after its comments were already swept — cannot happen: entries
-     * only leave through this host, so an entry absent at load time was removed
-     * while the host was running, and the sweep at load runs before anything can
-     * add it back.
+     * The orphan sweep: prune every comment whose entry is not in `entryIds`, in MEMORY ONLY.
+     *
+     * The explicit `removeForEntry` is the primary path and the ONLY one that erases; this is the view
+     * filter that guarantees no read is ever handed a comment naming a file the list does not carry. Run it
+     * when the store loads and on every list read.
+     *
+     * WHY IT DOES NOT SAVE (2026-10-06, a data loss measured on the live host). The sweep used to write the
+     * pruned state to the files, on the assumption that an entry absent here had been removed while the host
+     * was running. That is only one of two ways an entry can be missing; the other is that its ADD never
+     * reached `pending.json` — a pending entry is folded in memory and persisted on a later flush — and then
+     * the sweep deleted the comments hanging on it AND saved the deletion. Three real annotations were gone
+     * from the disk after a restart, not merely hidden: the reader's cards were written first and their
+     * entries never landed. An entry that exists but is not on disk yet is not an orphan.
+     *
+     * A write would not even help the case it was added for. A second client must never be handed a comment
+     * naming a file the same read no longer lists — that is a VIEW requirement, and the prune satisfies it.
+     * Erasure belongs to the paths where a removal was actually ASKED FOR: `removeForEntry` (what the panel's
+     * own drop calls, and it removes the comments in the same tick), and `remove`/`removeMany` for one
+     * thread. A genuine orphan therefore stays on the disk, hidden, until the next boot that sees the entry
+     * again — a row nobody reads is a smaller price than a reader's annotation nobody can recover.
+     *
      * @param entryIds - every entry id the pending store currently holds.
-     * @returns how many orphaned comments were dropped.
+     * @returns how many comments the view dropped.
      */
     retain(entryIds: ReadonlySet<string>): number;
     /**
@@ -264,7 +352,14 @@ export declare class CommentStore {
      * marker, the reference and the rules, and a thread that showed the prompt would show
      * the scaffolding rather than the question.
      *
-     * @param sessionId - the session the comment belongs to.
+     * The ASKING session is recorded on the question, not taken from the comment: a thread another
+     * seat wrote can be asked from this one, and the prompt then goes into the seat the human is
+     * using, so that session's transcript is where the answer will appear (see `askTranscript`).
+     *
+     * Matched by comment ID alone: the request id is minted here and is globally unique, and the
+     * caller has already checked that the thread is in its scope.
+     *
+     * @param sessionId - the transcript the question was submitted into.
      * @param id - the comment that was asked in.
      * @param requestId - the identity the submission carries into the transcript.
      * @param turn - the turn that claimed it, when that is already known.
@@ -276,20 +371,24 @@ export declare class CommentStore {
      * Record the turn that claimed one question, as the agent's inbox reported it. Two
      * questions claimed by the same turn were answered together, which is a fact the
      * panel can state instead of guessing from transcript positions.
-     * @param sessionId - the session the submission belongs to.
+     *
+     * Matched by REQUEST ID alone: it is minted per submission and globally unique, so it names the
+     * question on its own — and a thread another seat wrote can hold a question asked from this seat,
+     * which the old `comment.sessionId === sessionId` guard would refuse to write down.
      * @param requestId - the request identity the inbox reported back.
      * @param turn - the turn that claimed it.
      * @returns how many threads the patch touched.
      */
-    recordTurnForRequest(sessionId: SessionId, requestId: string, turn: number): number;
+    recordTurnForRequest(requestId: string, turn: number): number;
     /**
-     * Record that the session dropped one question before a turn claimed it: nothing is
+     * Record that a session dropped one question before a turn claimed it: nothing is
      * coming, and the reader is told rather than left waiting.
-     * @param sessionId - the session the submission belongs to.
+     *
+     * Matched by REQUEST ID alone, for the same reason as `recordTurnForRequest`.
      * @param requestId - the request identity the inbox reported back.
      * @returns how many threads the patch touched.
      */
-    markDroppedForRequest(sessionId: SessionId, requestId: string): number;
+    markDroppedForRequest(requestId: string): number;
     /**
      * Record that a turn is over, so the questions it claimed stop looking pending.
      *
@@ -301,7 +400,11 @@ export declare class CommentStore {
      * that: whether an answer exists is read from the transcript on each list read, so a
      * turn that stopped AFTER writing its answer keeps showing the answer.
      *
-     * @param sessionId - the session whose turn ended.
+     * Matched by TURN **within one transcript** (`askTranscript`), never by the thread's author: turn
+     * numbers are only unique inside a session, so two sessions can both have a turn 7, and a thread that
+     * holds questions from both would otherwise have one session's ending mark the other's questions
+     * over — the reader would be told a question was cut off while its answer was still coming.
+     * @param sessionId - the transcript whose turn ended.
      * @param turn - the turn that stopped.
      * @returns how many threads the patch touched.
      */
@@ -340,7 +443,12 @@ export declare class CommentStore {
      * memory-only view would TRUNCATE that copy — turning a read failure into a permanent
      * loss — so the save is refused and reported instead, which is what tells the reader
      * those comments are memory-only.
-     * @param sessionId - the session whose file to rewrite.
+     *
+     * The write-set is the AUTHOR's own comments (`authoredBy`), never the wider read scope
+     * (`list`): a read spans the lineage, but a file must hold exactly the comments whose
+     * author it is named for — writing the scope's comments into one seat's file would
+     * duplicate every other seat's threads on disk and, on the next load, in memory.
+     * @param sessionId - the author whose file to rewrite.
      */
     private save;
     /**

package/lib/types/index.d.ts

@@ -35,7 +35,7 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import type { DiffApprovalOpenAction } from './types.ts';
-export type { DiffApprovalActionOutcome, DiffApprovalActionValue, DiffApprovalBlockRange, DiffApprovalBlockTarget, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalRefreshOutcome, DiffApprovalRefreshValue, CommentAnchor, CommentQuoteLine, CommentRecord, DiffApprovalCommentAddValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, PendingEntry, PendingEntryKind, PendingFileDiff, } from './types.ts';
+export type { DiffApprovalActionOutcome, DiffApprovalActionValue, DiffApprovalBlockRange, DiffApprovalBlockTarget, DiffApprovalListCountValue, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalRefreshOutcome, DiffApprovalRefreshValue, CommentAnchor, CommentQuoteLine, CommentRecord, DiffApprovalCommentAddValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, LineageDirection, PendingEntry, PendingEntryKind, PendingFileDiff, SessionLineage, } from './types.ts';
 export { PendingDiffStore } from './pending.ts';
 export { PendingPersistence, defaultStorageDir } from './persist.ts';
 export { CommentStore, commentsDirFor } from './comments.ts';