dsh-diff-approval 0.29.1 → 0.31.0

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

@@ -0,0 +1,131 @@
+/**
+ * Where a comment's quote sits in a file's CURRENT content: the rule that turns the lines a comment
+ * was WRITTEN on into the lines it is about now.
+ *
+ * Pure and free of both Node and the DOM, so the two halves of the plugin import the very same rule:
+ * the host resolves each comment against the entry content it hangs off and ships the figures on the
+ * list read, and the browser half draws them. The panel's own row-level re-anchor
+ * (`src/client/discussion.ts`) is this same rule seen through the diff's rows — with one row per
+ * line, a removed line among them, and the quote's context taken from the rows — and it stays the
+ * browser's business: where a card is DRAWN is a layout fact. What a reader is TOLD (the list's
+ * label, the card's own chip, the jump's target line) comes from here, once, so two panes cannot
+ * name two lines for one comment.
+ *
+ * The two models can disagree in one situation, and it is worth knowing which: the host has the
+ * file's own lines, while the client's rows also carry the lines this file DELETED. A quote whose
+ * recorded `quoteContext` was captured across a deleted row therefore matches a context window the
+ * host cannot reproduce, and the host answers `undefined` where the client would re-anchor. The
+ * caller then falls back to `record.anchor` — the line the comment was written on — which is what an
+ * outdated thread shows anyway: the number stays honest rather than drifting.
+ *
+ * What the two may NOT disagree about is how far a match is allowed to be from the stored line: a
+ * look-alike elsewhere in the file is refused by both, through the one bound they share
+ * (`REANCHOR_MAX_LINES`), so the list's figure, the card's chip and the card's place cannot name two
+ * different lines for one comment.
+ * @module dsh-diff-approval/comment-lines
+ */
+/** The new-file lines one comment's quote settles on now (1-based, inclusive). */
+export interface CommentLineRange {
+    /** First new-file line the quote occupies in this content. */
+    start: number;
+    /** Last one. A one-line quote has `end === start`. */
+    end: number;
+}
+/**
+ * The record fields resolution reads: everything a re-anchor needs and nothing else.
+ *
+ * Structurally satisfied by `CommentRecord`, so a caller passes the record itself. The reader's own
+ * words, the questions asked and the timestamps play no part in where the code is.
+ */
+export interface CommentLineSource {
+    /** The lines the annotation was made on, as new-file numbers. */
+    anchor: {
+        startLine: number;
+        endLine: number;
+    };
+    /** The anchored lines as they read when the comment was written. */
+    quote: string;
+    /**
+     * `quote` with one line of context on each side, as it read then, when the record kept one. It is
+     * what tells a genuine move of the quoted code from another line elsewhere in the file that
+     * happens to read the same — without it a comment on a blank line or a closing brace followed that
+     * line wherever it appeared.
+     */
+    quoteContext?: string | undefined;
+}
+/**
+ * One file's content lines, numbered exactly as the diff numbers them.
+ *
+ * Both line endings are normalized first (`\r\n` and a lone `\r` become `\n`), and a single trailing
+ * newline is a line TERMINATOR rather than an extra empty line — the same convention the browser
+ * half's whole-file diff splits on (its `contentLines`), so line 1 here is the line the diff calls
+ * line 1 and the two cannot drift by a trailing newline.
+ *
+ * @param text - the file's content.
+ * @returns its lines, without the terminating newline; an empty file has none.
+ */
+export declare function commentFileLines(text: string): string[];
+/**
+ * How far a comment's quoted code may sit from the line the comment was written on and still count as
+ * that code having MOVED, in lines.
+ *
+ * A comment is re-anchored by its quote, and a quote is not unique: two declarations in one file can
+ * read exactly alike. The recorded context tells such places apart only as far as it reaches — one
+ * line each side — which two identically-shaped fields (`UPROPERTY` line, field, blank line) defeat
+ * completely. Distance is the other half of the answer, and the half that does not depend on what the
+ * record happened to keep: this code MOVING is a shift of a few lines, the insert or delete directly
+ * above it that every edit produces, while a match tens or hundreds of lines away is another place in
+ * the file that reads the same. The report's two cases bracket the number: the same declaration moved
+ * four lines when four lines above it were deleted, and a declaration that had been DELETED matched an
+ * identically-shaped one 74 lines below. Thirty keeps the first and refuses the second.
+ *
+ * Thirty is a screenful of code rather than a fact about the code: farther than that the reader is
+ * looking at another part of the file, and following it is a teleport rather than a correction — the
+ * comment ends up shown against code it was never written about, which is the bug this bound fixes.
+ * Any bound between the two real cases separates them; this one leaves a genuine shift of a
+ * function-sized block room to be followed, and nothing more.
+ *
+ * Both halves compare against this one number: the host in the file's own lines, the browser half in
+ * the rows of its diff model (a row is a line, or a line the file no longer has). A row distance is
+ * never smaller than the line distance it stands for, so a match the browser half refuses is one the
+ * host refused too, and the two panes cannot name a line the other will not draw.
+ */
+export declare const REANCHOR_MAX_LINES = 30;
+/**
+ * Whether a match that far from where the comment was written is that code having moved.
+ *
+ * The rule the two halves share, so neither can widen or narrow the bound on its own (see
+ * `REANCHOR_MAX_LINES` for the number and for what it separates). The bound is inclusive: at exactly
+ * the limit the code is taken to have moved.
+ *
+ * @param stored - the line (the host's content) or row (the browser half's model) the comment names.
+ * @param found - the line or row the quote was found on.
+ * @returns whether that match is close enough to be the same code.
+ */
+export declare function reanchorWithinLimit(stored: number, found: number): boolean;
+/**
+ * Where one comment's quote sits in a file's current content, or `undefined` when it is nowhere.
+ *
+ * The rule, in the order it is applied — the same order the browser half's `remapDiscussion` applies
+ * it in, so the same file and the same record produce the same number in both halves:
+ *
+ * 1. The lines the comment names have to exist in this file at all. When even the anchor's first
+ *    line is past the end, nothing here can be re-anchored: `undefined`.
+ * 2. The anchor's own line still reads the quote: the comment has not moved. The stored range is the
+ *    answer, `endLine` included — a range whose quote covers a different number of lines (a removed
+ *    row was quoted among them) still belongs to the reader's own numbers.
+ * 3. Otherwise the quote is followed: every window of as many lines as the quote has is compared to
+ *    it, the recorded context has to agree where the record carries one, and the occurrence CLOSEST
+ *    to the stored anchor wins — that is where the reader last saw the code. An equal distance keeps
+ *    the earlier occurrence, which is the first window an ascending scan meets.
+ * 4. The occurrence also has to be NEAR the stored anchor (see `REANCHOR_MAX_LINES`): a window
+ *    farther than that from the line the comment was written on is not this code having moved but
+ *    another place in the file that reads the same — however exactly its recorded context agrees.
+ * 5. Nothing matched: `undefined`. The caller falls back to `record.anchor`, the line the comment was
+ *    written on — the same answer the code view gives an outdated thread.
+ *
+ * @param text - the entry's current content (the file as it reads now).
+ * @param comment - the stored comment's anchor and quote.
+ * @returns the new-file line range the quote occupies now, or `undefined` when it is gone.
+ */
+export declare function resolveCommentLines(text: string, comment: CommentLineSource): CommentLineRange | undefined;

package/lib/types/comments.d.ts

@@ -0,0 +1,465 @@
+/**
+ * Durable comment threads, one JSON file per session under
+ * `<commentsDir>/<sessionId>.json`, beside the pending-entry storage but never in
+ * the same file: a comment that outlived its entry is exactly the leak this
+ * module exists to prevent, so a pending write that fails must not be able to
+ * take comments with it (or the other way round).
+ *
+ * A comment belongs to ONE pending entry (`entryId`, which is the entry's path —
+ * the store's global identity) and to ONE session. It carries the annotation and
+ * the identity of the turn that answered it (`messageId`, `turn`); it does NOT
+ * carry the answer's text, because the session transcript stays the single source
+ * of truth for what the agent said — a client reads the answer out of the
+ * transcript by that id. Saves rewrite the whole session file, staged as a sibling
+ * temp file and atomically renamed, so a crash leaves either the old or the new
+ * file. A missing file reads as empty; unknown versions and non-JSON content throw.
+ * @module dsh-diff-approval/src/comments
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { CommentAsk, CommentRecord } from './types.ts';
+import type { AskRead } from './comment-ask.ts';
+/**
+ * The comment directory that belongs to a pending-storage root.
+ *
+ * The plugin's own state directory is `<dshHome>/diff-approval`, and inside it the
+ * pending file lives in `workspaces/` and comments in `comments/` — siblings, so a
+ * write that fails on one side cannot take the other with it. Any OTHER root is a
+ * self-contained state directory (a deployment's chosen location, a test's temp
+ * dir) and keeps its comments INSIDE it: the sibling of an arbitrary directory can
+ * be shared by two instances that were each pointed somewhere different, and two
+ * instances writing one comment file is a leak rather than a layout choice.
+ *
+ * @param storageRoot - the resolved pending-storage root.
+ * @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.
+ *
+ * The store reads and writes plain JSON files and owns no logger, so both halves are
+ * callbacks: the host wires them to `ctx.logger` and to the list read the panel draws,
+ * which is what turns "the write failed" from a fact only the filesystem knew into
+ * something the reader is told (and something a test can assert without a disk).
+ */
+export interface CommentStoreOptions {
+    /**
+     * One session's comments could not be read, and that file was skipped. Called once per
+     * skipped file, with the file's path, because the caller's warning has to name it.
+     */
+    onLoadSkipped?: (file: string, error: unknown) => void;
+    /**
+     * A save failed (`message` is the reason) or a session's failure cleared (`undefined`).
+     * Called only when the report CHANGES, so a writer retrying every second cannot bury
+     * the log; the same value also rides the list read as `persistError()`. One session's
+     * healthy write does not clear another's failure — see `persistError`.
+     */
+    onPersistError?: (message: string | undefined) => void;
+}
+/**
+ * File-backed comment threads, one file per session.
+ *
+ * Every mutation is applied to memory synchronously and schedules that session's
+ * file write on its own chain, so a caller removing an entry can drop its comments
+ * in the same tick as the entry itself without awaiting anything — the same
+ * fire-and-forget persistence the pending store uses.
+ */
+export declare class CommentStore {
+    private readonly root;
+    private readonly options;
+    private readonly byId;
+    private readonly tails;
+    private revision;
+    /** Files `loadAll` could not read, in the order it met them (see `skippedFiles`). */
+    private readonly skipped;
+    /**
+     * The save failure of every session that has one, keyed by that session's file and in the
+     * order the failures happened (see `persistError`). Empty while every write works.
+     */
+    private readonly persistFailures;
+    /**
+     * Sessions whose unreadable file could not even be moved aside, keyed by that file: the
+     * reason their writes are refused rather than allowed to truncate the bytes (see `save`).
+     */
+    private readonly unmovable;
+    /**
+     * @param root - directory holding one `<sessionId>.json` per session.
+     * @param options - the error seam (see {@link CommentStoreOptions}).
+     */
+    constructor(root: string, options?: CommentStoreOptions);
+    /**
+     * Load every session's comments. A malformed row is skipped rather than
+     * failing the load: one bad comment must not cost the whole workspace's
+     * comments (or the plugin's activation).
+     *
+     * A file that cannot be READ is skipped the same way, because the alternative is
+     * worse in both directions: the old all-or-nothing load threw, the caller logged
+     * once and carried on with an EMPTY store, and the next save then wrote that
+     * emptiness back over every good file. One unreadable file therefore cost every
+     * session's comments. Skipping keeps the other sessions' threads, and the skipped
+     * file is moved aside (`.corrupt`) rather than dropped: it is not deleted — the
+     * bytes may be the only copy — but it is also not left where the next save for
+     * that session would silently overwrite it, which would destroy them for good.
+     *
+     * When even that fails — the file cannot be moved aside — that session's writes are
+     * refused from then on (see `save`) rather than allowed to truncate the only copy.
+     * "Skipped but still writable" is exactly the shape that turns a read failure into
+     * data loss: the store would answer "added", write the memory-only view over bytes
+     * nobody could read, and lose what the skip had just refused to guess at.
+     * @returns how many comments were loaded.
+     */
+    loadAll(): Promise<number>;
+    /**
+     * The files a load skipped, so the caller can say what went missing instead of
+     * reporting a session whose comments silently vanished.
+     * @returns the skipped files' paths, in load order.
+     */
+    skippedFiles(): string[];
+    /**
+     * The failure the reader has to be told about, or `undefined` while every write works.
+     * This is what rides the list read so the panel can say the threads are memory-only;
+     * a later successful save retracts it, mirroring the pending half's own report.
+     *
+     * Per SESSION, not one global slot: a deployment where one session's file cannot be
+     * written and another's can is the ordinary case (a locked file, a full quota, a
+     * directory that vanished), and letting the healthy write retract the broken one's
+     * report would say the threads are safe while that session's live in memory only —
+     * the same "a failure that looks like a success" trap, one session over. A session's
+     * own success is what retracts its own entry (see `reportPersist`).
+     * @returns the most recent outstanding failure's message, or undefined.
+     */
+    persistError(): string | undefined;
+    /**
+     * Record a skipped file: keep it for the caller, name it, and move it aside so a later
+     * save for that session writes a fresh file rather than overwriting the unreadable
+     * bytes. A quarantine that itself fails is still a skip — the store must not be the
+     * reason a single bad file takes the whole load down — but that session's file is then
+     * the only copy of its threads, so its writes are refused (see `save`) instead of being
+     * allowed to truncate it.
+     * @param file - the file that could not be read.
+     * @param error - why it could not be read.
+     */
+    private skip;
+    /**
+     * 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;
+    /**
+     * A counter bumped on every change, so a poller can tell "nothing new" from
+     * "re-read": the list endpoint ships the session's comments anyway, and this is
+     * 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.
+     *
+     * Writing a comment that is already here is the SAME comment written again — a client
+     * retrying a request whose response was dropped, or a second client sending the id it
+     * was handed — so the questions already asked in it are kept and only the annotation's
+     * own fields move. Overwriting the whole record would erase the identity of a question
+     * that is in flight, and its answer could then never be matched back to this thread;
+     * `createdAt` is kept for the same reason, since it is what a list read orders by.
+     *
+     * @param record - the comment to store.
+     * @returns the stored comment, which is the existing one when the id was already here.
+     */
+    add(record: CommentRecord): CommentRecord;
+    /**
+     * Record several annotations at once, as ONE write per affected session.
+     *
+     * This is what putting a batch of restored comments back needs and what a loop of `add` calls
+     * cannot give it: each `add` saves its session's file, so an undo that restored ten threads wrote
+     * that file ten times — ten chances for a transient failure to leave the store and the disk
+     * disagreeing about an action the reader already watched happen. The records are stored by the SAME
+     * rule as `add` (a new id verbatim, an existing one merged with its `createdAt` and its questions
+     * kept), which is what lets a restore be an ordinary write rather than a special case: a snapshot
+     * that came back as a new comment, with a fresh id and no questions, would be a look-alike of the
+     * reader's thread.
+     *
+     * A batch that carries nothing changes nothing, so a no-op restore does not rewrite a file.
+     *
+     * @param records - the comments to store, in the caller's order.
+     * @returns the stored record for each input, index-aligned: what landed, which is not always what
+     *   was handed over (a merge keeps the fields the existing comment owns). A count would drop that,
+     *   and a caller needing it would have to `get` each id back and race a later change.
+     */
+    addMany(records: readonly CommentRecord[]): CommentRecord[];
+    /**
+     * The record as the store keeps it: a new id VERBATIM, an id already here merged.
+     *
+     * The one place the merge rule lives, so `add` and `addMany` cannot drift: writing a comment that
+     * is already here is the same comment written again — a client retrying a request whose response
+     * was dropped, or a second client sending the id it was handed — so the questions already asked in
+     * it are kept and only the annotation's own fields move. Overwriting the whole record would erase
+     * the identity of a question that is in flight, and its answer could then never be matched back to
+     * this thread; `createdAt` is kept for the same reason, since it is what a list read orders by.
+     * @param record - the comment as the caller wrote it.
+     * @returns the record to store under its id.
+     */
+    private mergeOf;
+    /**
+     * 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 was in scope).
+     */
+    remove(scope: CommentScope, id: string): boolean;
+    /**
+     * 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 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 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 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(scope: CommentScope, ids: readonly string[]): string[];
+    /**
+     * Every comment one pending entry carries, oldest first.
+     *
+     * The read half of `removeForEntry` and kept beside it, because they are two answers about the same
+     * fact: which comments an entry owns. A caller that is about to drop the entry asks this first, so
+     * the undo pair can carry them back; the two must agree on that set, or a restore would put back
+     * fewer (or more) threads than the drop took.
+     * @param entryId - the entry id (= path).
+     * @returns that entry's comments, in list order.
+     */
+    forEntry(entryId: string): CommentRecord[];
+    /**
+     * Drop every comment of one pending entry. This is what "a comment dies with
+     * its entry" means, and the entry knows nothing about comments, so the caller
+     * runs it beside the entry's own removal.
+     * @param entryId - the entry id (= path) that left the list.
+     * @returns how many comments went with it.
+     */
+    removeForEntry(entryId: string): number;
+    /**
+     * 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 comments the view dropped.
+     */
+    retain(entryIds: ReadonlySet<string>): number;
+    /**
+     * Record one question asked in a thread. The answer itself is never stored, and the
+     * request id is minted by the caller before it submits, so this runs as part of the
+     * ask rather than waiting for the session to answer. A thread keeps its questions in
+     * order: the first is the annotation's own, and each follow-up appends.
+     *
+     * The reader's own words are stored WITH the question (`text`), because they exist
+     * nowhere else: the transcript holds the prompt, which is those words wrapped in the
+     * marker, the reference and the rules, and a thread that showed the prompt would show
+     * the scaffolding rather than the question.
+     *
+     * 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.
+     * @param text - the reader's own words, without the prompt's wrapper.
+     * @returns whether the comment existed.
+     */
+    recordAsk(sessionId: SessionId, id: string, requestId: string, turn: number | undefined, text: string): boolean;
+    /**
+     * 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.
+     *
+     * 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(requestId: string, turn: number): number;
+    /**
+     * Record that a session dropped one question before a turn claimed it: nothing is
+     * coming, and the reader is told rather than left waiting.
+     *
+     * 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(requestId: string): number;
+    /**
+     * Record that a turn is over, so the questions it claimed stop looking pending.
+     *
+     * The turn number is the only handle the stopping event carries — no message, no
+     * request id — so the questions that were claimed by that turn are the ones patched
+     * (see `recordTurnForRequest`, which wrote the number down when the inbox claimed
+     * them). A question whose turn is over and that the transcript shows no answer for
+     * was cut off; the client says so instead of waiting forever. Nothing here decides
+     * 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.
+     *
+     * 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.
+     */
+    markTurnEnded(sessionId: SessionId, turn: number): number;
+    /**
+     * Apply one patch to every comment it matches, and schedule the affected sessions'
+     * writes. The one mutation seam, so no caller has to remember to bump the revision
+     * or to save: a patch that matches nothing changes nothing.
+     * @param match - which comments to patch.
+     * @param patch - the change to apply.
+     * @returns how many comments changed.
+     */
+    private patch;
+    /**
+     * Wait for every scheduled write to settle.
+     *
+     * The mutators return as soon as a change is in memory — that is what lets an
+     * entry's removal take its comments with it in the same tick — so this is how a
+     * caller that must not lose the write (a dispose path, a test asserting the file)
+     * waits for the disk.
+     * @returns resolution after every session file's write chain has drained.
+     */
+    settled(): Promise<void>;
+    /**
+     * Write one session's comments, serialized against that file's own writes.
+     *
+     * A rejected write is reported, not swallowed: the mutation already answered
+     * "added" and the panel is drawing the thread from memory, so a silent failure means
+     * the reader keeps writing into a thread that a restart will erase. The report rides
+     * the list read (`persistError`) and the caller's logger, and a later write that works
+     * retracts it the way the pending half retracts its own.
+     *
+     * A session whose file could not be read at load AND could not be moved aside is not
+     * written at all: the only copy of that session's threads is the bytes the load could
+     * not parse, and the store's memory holds just what has been added since. Writing the
+     * 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.
+     *
+     * 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;
+    /**
+     * Publish the write state of one session's file, once per distinct report. Kept as its own
+     * step so both the success and the failure of the chain above land in one place — the
+     * retraction is what arms a later failure to be reported again.
+     *
+     * Keyed per file, so a healthy session's write cannot retract a broken one's report (see
+     * `persistError`); the callback sees the aggregate, which is what rides the list read.
+     * @param file - the session file the write was for.
+     * @param message - the failure's text, or undefined when the write worked.
+     */
+    private reportPersist;
+}

package/lib/types/index.d.ts

@@ -35,9 +35,11 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import type { DiffApprovalOpenAction } from './types.ts';
-export type { DiffApprovalActionOutcome, DiffApprovalActionValue, DiffApprovalBlockRange, DiffApprovalBlockTarget, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalRefreshOutcome, DiffApprovalRefreshValue, 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';
+export { CommentAsker, answerForRequest } from './comment-ask.ts';
 export { defaultOpenPath } from './open.ts';
 /** Stable Cordis plugin name. */
 export declare const name = "diff-approval";
@@ -45,7 +47,10 @@ export declare const name = "diff-approval";
  * Services required before the review surface activates. `webServer` rides with
  * `connection` (both come from the web bundle), and is named explicitly because
  * the channel's owner context must be able to resolve it — see
- * `ConnectionServiceSurface`.
+ * `ConnectionServiceSurface`. `sessionController` and `agents` are what a comment is
+ * asked through and what reports the turn that claimed it: both come from the same
+ * base composition this plugin already requires for `sessions`, so a host that could
+ * list pending changes at all has them.
  */
 export declare const inject: string[];
 /** The connection RPC channel this plugin serves. */