dsh-diff-approval 0.30.1 → 0.32.0

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';

package/lib/types/pending.d.ts

@@ -51,10 +51,11 @@ export declare class PendingDiffStore {
     /** Fold a captured entry into the path's single global entry. */
     private merge;
     /**
-     * Combine a stored entry and a new capture. `oldText` comes from the earlier
-     * capture (the file's original basis), `newText` from the later (latest
-     * content), and the session set is the union — so the entry always spans the
-     * whole pending change regardless of which session contributed which part.
+     * Combine a stored entry and a new capture. `oldText` comes from the earlier capture (the file's
+     * original basis) — except where that capture was the file's creation and this one edits it, when
+     * the creation's own content becomes the basis — and `newText` from the later (latest content).
+     * The session set is the union, so the entry always spans the whole pending change regardless of
+     * which session contributed which part.
      */
     private mergeEntry;
     /**
@@ -82,6 +83,15 @@ export declare class PendingDiffStore {
     /**
      * Advance one entry's tracked content after a block-level keep/revert. The
      * entry keeps its path; only the given side's text and capture time move.
+     *
+     * A keep that advances `oldText` also ends the entry's life as a creation. `earlierVersion` is the fact
+     * "this file did not exist before", and once part of the file has been accepted there IS an earlier
+     * version to restore — what the reader kept. The whole-file action must therefore become 回退, not 删除:
+     * deleting would throw away the part they just accepted. (Leaving the field alone kept a partly-kept new
+     * file offering to delete itself, which is what sent the reader here.)
+     *
+     * Every caller of this is a reader action — a block keep or revert, a refresh from version control — so it
+     * also takes the unseen dot down: the reader has just handled this file.
      * @param path - the file path.
      * @param patch - the side to advance (`oldText` for keep, `newText` for revert).
      * @returns whether the entry changed.
@@ -90,6 +100,22 @@ export declare class PendingDiffStore {
         oldText?: string;
         newText?: string;
     }): boolean;
+    /**
+     * Mark paths the reader has now seen — the file was opened, or its row was acted on. The dot is about
+     * attention rather than content, so this and the entry leaving the list are the only ways it goes out, and
+     * nothing brings it back except a new capture.
+     * @param paths - one path, or several.
+     * @returns whether anything changed.
+     */
+    markSeen(paths: string | readonly string[]): boolean;
+    /**
+     * Raise the dot for paths whose content moved WITHOUT the reader asking — a writer outside the panel, a
+     * second process. The capture sites set the field on the entry they fold; this is for the changes the
+     * plugin notices by itself while refreshing, which do not come through a capture.
+     * @param paths - one path, or several.
+     * @returns whether anything changed.
+     */
+    markUnseen(paths: string | readonly string[]): boolean;
     /**
      * Restore one entry exactly as given (an undo/redo replays a snapshot). The
      * entry is inserted or replaced by path.

package/lib/types/types.d.ts

@@ -5,6 +5,26 @@
  */
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { CommentLineRange } from './comment-lines.ts';
+/**
+ * Where a session sits in the lineage a merged view groups by.
+ *
+ * Read off the session's own header when an entry is CAPTURED (`SessionHeader.parentSession`, `.origin`,
+ * `.delegationDepth`, `.cwd`) and carried on the entry, so a client can group without a second wire
+ * field. Every part is optional and absent when the header — or that one field of it — was not
+ * available: an ordinary root session has no parent by design, and a host older than these header
+ * fields reports none of them. An unknown lineage is recorded as unknown; guessing a root would file a
+ * session under the wrong one. Nothing reads this yet: the record is written for the merged view to use.
+ */
+export interface SessionLineage {
+    /** The session this one was forked from, or absent for an ordinary root. */
+    parentSessionId?: SessionId | undefined;
+    /** The header's coarse product classification — `'subagent'` for a subagent child. */
+    origin?: string | undefined;
+    /** How deep below its root the session was delegated, when the shell reports it. */
+    delegationDepth?: number | undefined;
+    /** The session's own working directory, when its header names one. */
+    cwd?: string | undefined;
+}
 /**
  * One file's pending entry, global and unique per `path`: the complete set of
  * unhandled changes folded into a single cumulative span across every session
@@ -17,8 +37,12 @@ export interface PendingEntry {
     id: string;
     /** Backend-resolved display path (the tool's output `path`). */
     path: string;
-    /** What the operation did: an in-place change or a file creation. */
-    kind: PendingEntryKind;
+    /**
+     * Whether there is an earlier version of the file to restore: `'file'` when
+     * the whole-file action writes the earlier text back, `'none'` when the file
+     * did not exist, so the whole-file action deletes it.
+     */
+    earlierVersion: PendingEntryKind;
     /** File content before the first captured operation (empty for a creation). */
     oldText: string;
     /** File content after the latest captured operation. */
@@ -29,14 +53,70 @@ export interface PendingEntry {
     sessionId: SessionId;
     /** Every session that touched the file (drives the per-session list filter). */
     sessionIds: SessionId[];
+    /**
+     * Where this entry's session sits in its lineage, as the shell reported it when the entry was
+     * CAPTURED — display-only data for a merged view. The entry keeps its real `sessionId`/`sessionIds`
+     * either way: grouping by lineage never rewrites who did the work. Absent on a record written before
+     * this field existed, on a session whose header carried none of it, and on an ordinary root (which
+     * has no parent by design) — so a reader must treat absent as "not known", never as "a root".
+     */
+    lineage?: SessionLineage | undefined;
+    /**
+     * Whether a change the reader has not looked at yet arrived on this path — the dot beside its row. Set
+     * when an agent operation (or an agent-side admission) changes the entry, cleared when the reader opens
+     * the file or acts on the row, and deliberately NOT part of an undo snapshot: a snapshot restores
+     * CONTENT, and having seen something is not content.
+     */
+    unseen?: boolean | undefined;
 }
-/** What one captured operation did to the file. */
-export type PendingEntryKind = 'edit' | 'create';
+/** Whether an entry has an earlier version of its file to restore. */
+export type PendingEntryKind = 'file' | 'none';
+/**
+ * Which way a row's other contributor sits relative to the session LISTING it, walked from the recorded
+ * subagent parent links (see `lineageView` on the host).
+ *
+ * `child` — the other session descends from the lister (the lister is on the other's upward chain).
+ * `parent` — the other session is ABOVE the lister (the lister descends from it). It means an ANCESTOR,
+ *   possibly more than one hop up, not only the direct parent: the Chinese 上级 says exactly that without
+ *   ambiguity, so the English copy and this name keep that meaning.
+ * `sibling` — same lineage root, neither is on the other's chain (two children of one parent, say).
+ * `mixed` — non-requester owners of DIFFERENT directions: never one of them, and never a guess at one.
+ */
+export type LineageDirection = 'child' | 'parent' | 'sibling' | 'mixed';
 /**
  * One listed pending entry: the stored operation plus the live file state the
  * list endpoint computes by reading the file's current content.
  */
 export interface PendingFileDiff extends PendingEntry {
+    /**
+     * Whether this row reached the list through the LINEAGE MERGE rather than because the LISTING session
+     * itself touched it. The HOST computes it per read (`listWithState`), because only the host can walk a
+     * lineage — the client cannot, and must not try: it is what lets the panel show a child session's row
+     * without re-deriving the merge in the browser. Absent on a host older than the merge and absent on a
+     * row this session touched, so a client that does not know the field behaves exactly as it did before.
+     */
+    viaLineage?: boolean | undefined;
+    /**
+     * Whether some session OTHER than the listing one — and inside the listing session's lineage — also
+     * contributed to this row, so a row the session touched itself still says a child had a hand in it. Kept
+     * apart from `viaLineage` on purpose: that one answers "why is this row here" (visibility), this one
+     * answers "whose change does it carry" (the mark). Only a session in the same lineage counts: entries are
+     * keyed by path globally, so an unrelated session's touch of the same file must never be called a child's
+     * work. Host-computed per read (`listWithState`), absent on a host older than the mark.
+     */
+    hasChildContribution?: boolean | undefined;
+    /**
+     * WHICH WAY the row's other contributor stands, so the marker's sentence tells the truth from the seat it
+     * is drawn in: the same row is a child's change in its parent's panel and a parent's change in its
+     * child's. Host-computed per read from the SAME recorded parent links the merge walks, and carried to the
+     * browser like `viaLineage` — the client never infers lineage.
+     *
+     * Absent whenever no mark applies (the lister is the only contributor), and absent on a host older than
+     * this field — in which case the client says the neutral sentence rather than picking a direction.
+     * `mixed` is likewise the honest answer when the row carries non-requester owners of different
+     * directions; it is never resolved to one of them.
+     */
+    lineageDirection?: LineageDirection | undefined;
     /**
      * Whether the file no longer exists (or cannot be resolved). Reverting a
      * missing entry restores its old content, which recreates the file.
@@ -110,6 +190,47 @@ export interface DiffApprovalListValue {
      */
     commentAnswers: Record<string, string>;
 }
+/**
+ * Value returned by the channel's `list-count` endpoint: how many rows a full `list` read for the same
+ * session would carry.
+ *
+ * The badge needs a number once a second, and a full read is enormously more than a number: it ships
+ * every visible entry's whole `oldText`+`newText` (measured at 6.77 MB across 302 stored entries, with
+ * single rows at 1.2-1.6 MB). So this is the LIGHT read — the same visibility rule (`lineageView().sees`
+ * for the requesting session) and the same `ensureLoaded` discipline as `list`, and nothing else.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: it reads no file content (`ctx.fs.readText` is never called), so it
+ * computes no diff, adopts no external change, creates no undo checkpoint, sweeps no comments and does not
+ * persist anything. It sends no texts, no comment records, no `commentLines`, no revision and no errors —
+ * `count` is the whole answer.
+ *
+ * WHAT THAT COSTS THE CALLER: a count is not a list. It asks `stat` about each visible row (the cheap
+ * liveness signal) and drops a row whose file is GONE, which is the one state `list` also drops without
+ * reading — but a file that is present and merely unreadable cannot be told from a readable one without
+ * reading it, so it is counted here and dropped by the next full read. The number can therefore be one
+ * poll stale, and the next full read is what corrects it; nothing else in this value is authoritative.
+ */
+export interface DiffApprovalListCountValue {
+    /** How many rows this session's next full `list` read would carry. */
+    count: number;
+}
+/**
+ * Value returned by the channel's `update-check` endpoint: whether a newer release of
+ * this package is published, and what changed since the installed one.
+ *
+ * The comparison itself is the HOST's (`src/version.ts`): it is the side that knows the
+ * installed version, and the only side that can reach the registry (the browser cannot —
+ * `registry.npmjs.org` sends no CORS header). `newer` is therefore an ANSWER, not a hint:
+ * the client never re-derives it, so exactly one rule decides "is this newer".
+ */
+export interface DiffApprovalUpdateValue {
+    /** The installed version as this host read it; empty when it could not be read at all. */
+    current: string;
+    /** The published version; absent when the registry was unreachable or answered nonsense. */
+    latest?: string | undefined;
+    /** Whether `latest` is STRICTLY newer than `current`; always false when either is unparsable. */
+    newer: boolean;
+}
 /** What the open endpoint asks the OS to do with a file. */
 export type DiffApprovalOpenAction = 'open' | 'reveal';
 /** Value returned by the channel's open endpoint. */
@@ -180,6 +301,9 @@ export type DiffApprovalRefreshOutcome =
  | 'unchanged'
 /** The file has no local VCS change (untracked-and-excluded, or already clean). */
  | 'no-change'
+/** The scan saw no change AND the file's content equals its VCS baseline: the change is
+ *  committed, so the entry's diff is a keep away from being out of date. */
+ | 'committed'
 /** No pending entry existed for the id. */
  | 'missing'
 /** The workspace is not inside a git/svn/p4 checkout. */
@@ -187,6 +311,9 @@ export type DiffApprovalRefreshOutcome =
 /** Value returned by the channel's vcs-refresh endpoint. */
 export interface DiffApprovalRefreshValue {
     outcome: DiffApprovalRefreshOutcome;
+    /** Set when the refresh already settled the entry (the `committed` outcome keeps it, with no
+     *  diff left); absent for every outcome that leaves the decision to the panel. */
+    resolved?: boolean | undefined;
 }
 /** Value returned by the channel's keep and revert endpoints. */
 export interface DiffApprovalActionValue {
@@ -287,6 +414,20 @@ export interface CommentAsk {
      * has admitted anything.
      */
     requestId: string;
+    /**
+     * The SESSION THIS QUESTION WAS SUBMITTED INTO — the transcript that will carry its answer.
+     *
+     * It is not always the comment's own `sessionId`: once a lineage reads every seat's threads (`list`
+     * fans the read out across the lineage root), any seat may ask a question on a thread another seat
+     * wrote, and the prompt goes into the seat the human is using. The answer fold then has to know which
+     * transcript to read for which question, and turn numbers are only unique WITHIN one session — so this
+     * is what `markTurnEnded` matches on as well.
+     *
+     * Absent on a question asked before this field existed, when the only session a question could have
+     * gone to was the comment's own: the fold reads the comment's `sessionId` for those (see
+     * `askTranscript` in the comment store), which is exactly where their answers already are.
+     */
+    sessionId?: SessionId | undefined;
     /**
      * The question's own words, as the reader typed them — without the marker, the
      * `(path:lines)` reference and the answer rules that wrap them in the submitted
@@ -352,12 +493,53 @@ export interface CommentRecord {
      * something the reader said would put words in their mouth. Absent means the reader.
      */
     author?: 'agent' | undefined;
+    /**
+     * Which CLASS of annotation this one belongs to, as the calling agent named it (see
+     * `annotate-tool.ts`'s `category` argument).
+     *
+     * The panel draws it as a coloured round dot on the comment list's row, so an agent that annotates
+     * several passes or topics can be told apart at a glance. OPAQUE to every reader of this record: the
+     * panel hashes the string to pick a colour and shows the string itself in the mark's own label, and
+     * nothing parses it, orders it or validates its shape. Absent means "no class, no dot" — which is
+     * every comment the reader writes themselves, and every annotation written before this field existed.
+     * Short by construction (the tool trims it and caps it at `MAX_ANNOTATION_CATEGORY_CHARS`).
+     */
+    category?: string | undefined;
     /** Epoch milliseconds the comment was written. */
     createdAt: number;
     /** Epoch milliseconds of the last change to this record. */
     updatedAt: number;
     /** The questions asked in this thread, oldest first; empty until one is asked. */
     asks?: CommentAsk[] | undefined;
+    /**
+     * Whether something the reader has not looked at yet arrived in this thread — the dot beside its
+     * card. Set when an agent-authored annotation is written or when an answer lands in the thread,
+     * cleared when the card comes into view, and deliberately NOT part of an undo snapshot: a snapshot
+     * restores CONTENT, and having seen something is not content.
+     */
+    unseen?: boolean | undefined;
+    /**
+     * The answer text the reader has already been told about, keyed by question id.
+     *
+     * The answer's text is deliberately absent from this record (see the doc above) — the transcript is
+     * the one source
+     * of truth for what the agent said — but "is this the answer I have already seen?" cannot be
+     * answered from the transcript alone, because a read has nothing to compare against. This is the
+     * baseline the comparison takes: the host writes the current answer here when the card goes out of
+     * the reader's way, and an answer whose text differs from this is news. Persisted rather than held
+     * in memory, so a restart does not light a dot the reader had already cleared.
+     */
+    answerSeen?: Record<string, string> | undefined;
+    /**
+     * The latest answer text the host has observed for each question, keyed by question id.
+     *
+     * The other half of the comparison above, and kept apart from it on purpose: this follows what the
+     * agent said, while `answerSeen` follows what the reader has looked at. An answer whose text differs
+     * from its stored `answerSeen` entry is what lights the dot — and an answer that disappears leaves
+     * this empty rather than looking like a change, so a transcript that cannot be read never re-lights
+     * a thread the reader already read.
+     */
+    answerNow?: Record<string, string> | undefined;
 }
 /** Value returned by the channel's comment-add endpoint. */
 export interface DiffApprovalCommentAddValue {

package/lib/types/vcs.d.ts

@@ -34,7 +34,8 @@ export interface VcsRoot {
 export interface VcsChange {
     /** Absolute path of the changed file (inside the workspace). */
     path: string;
-    kind: 'edit' | 'create';
+    /** Whether an earlier version of the file exists: `'file'` restores it, `'none'` deletes the file. */
+    earlierVersion: 'file' | 'none';
     /** Baseline (pre-change) content; empty for a brand-new file. */
     oldText: string;
     /** Working content; empty for a deleted file. */
@@ -104,6 +105,18 @@ export interface VcsImportInput {
     readText: VcsFileReader;
     signal?: AbortSignal | undefined;
 }
+/** What a revision has to say about one path: its content, or that the path has no version at all.
+ * A FAILED read is neither: it throws (see {@link readVcsBaseline}). */
+export type VcsBaseline = 
+/** The baseline carries this path; `text` is its content there. */
+{
+    state: 'file';
+    text: string;
+}
+/** The baseline has no version of this path (a creation — there is nothing to restore). */
+ | {
+    state: 'none';
+};
 /**
  * Find the VCS enclosing `start` by walking up the directory tree: the first
  * directory (deepest) holding a marker wins, with git > svn > p4 when several
@@ -120,4 +133,25 @@ export declare function detectVcsRoot(start: string): VcsRoot | undefined;
  * @returns the changes; an absent/unusable VCS surfaces as a thrown error.
  */
 export declare function listVcsChanges(input: VcsImportInput): Promise<VcsChange[]>;
+/**
+ * Read one file's BASELINE content — the version every branch above reads to build a change's
+ * `oldText`: git's last commit (`HEAD`, when the scan could not see the change), svn's `BASE`, p4's
+ * `#have`. The commands are the same ones those branches run, so a caller that needs one file's
+ * pre-change content outside a scan (the per-file refresh's "was this committed?" check) does not
+ * invent a second way to ask the same question — or a second set of failure modes to reason about.
+ *
+ * The two answers stay distinguishable, exactly as they do in a scan: a baseline that carries no
+ * version of the path is {@link VcsBaseline} `none` (git is the only branch that can report it,
+ * through {@link readGitBlob}'s own absence pattern), while a read that FAILED — a refused command,
+ * a timeout, a missing client — throws, because "could not read" is not "there is nothing there".
+ *
+ * @param kind - the VCS to read.
+ * @param root - the repository/checkout/client root, as {@link detectVcsRoot} found it.
+ * @param absolutePath - the file's absolute path (inside the root's tree).
+ * @param shell - the deployment's shell executor.
+ * @param signal - the caller's abort signal.
+ * @returns the baseline content, or `none` when the baseline has no version of the path.
+ * @throws when the baseline read failed for any other reason.
+ */
+export declare function readVcsBaseline(kind: VcsKind, root: string, absolutePath: string, shell: ShellExecutorLike, signal: AbortSignal | undefined): Promise<VcsBaseline>;
 export {};