dsh-diff-approval 0.29.1 → 0.31.0

package/lib/types/pending.d.ts

@@ -18,6 +18,29 @@ import type { PendingEntry } from './types.ts';
  */
 export declare class PendingDiffStore {
     private readonly entries;
+    /**
+     * The content version of each entry: bumped whenever its tracked `newText` moves, and never for a
+     * change that leaves the content alone (a block keep advances `oldText` only).
+     *
+     * It is what lets derived, content-dependent state — the lines a comment's quote resolves to, read
+     * off `newText` — be cached and refreshed when the content moved rather than recomputed on every
+     * read. The versions come from one monotonic counter and are never reused, so an entry that leaves
+     * the list and comes back cannot hand back the number a stale cache was keyed to.
+     */
+    private readonly contentVersions;
+    /** The last version handed out; only ever climbs (see `contentVersions`). */
+    private contentVersionCounter;
+    /** Note that one path's tracked content moved, and give it a fresh version. */
+    private bumpContent;
+    /**
+     * The version of one path's tracked content, or 0 while it has none.
+     *
+     * Two calls that return the same number describe the same `newText`: a caller caching something
+     * derived from that content may serve its copy until the number changes.
+     * @param path - the file path (the global entry key).
+     * @returns the path's content version.
+     */
+    contentVersion(path: string): number;
     /**
      * Merge one captured operation into its file's entry. A no-op (equal before
      * and after) folds nothing.
@@ -28,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;
     /**
@@ -59,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.
@@ -67,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

@@ -4,6 +4,27 @@
  * @module dsh-diff-approval/types
  */
 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
@@ -16,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. */
@@ -28,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.
@@ -72,6 +153,83 @@ export interface DiffApprovalListValue {
      * told about it simply finds the list gone later, with nothing to explain it (issue #6).
      */
     persistError?: string | undefined;
+    /**
+     * The last failure to write a COMMENT file, or absent while those writes are working.
+     * Separate from `persistError` because the two live in different files and one may be
+     * writable while the other is not; a comment that only exists in memory is erased by a
+     * restart exactly like an unpersisted list, and the panel says so once.
+     */
+    commentPersistError?: string | undefined;
+    /**
+     * The requested session's comment threads, oldest first. They ride the list read
+     * so a poll sees the entries and the comments that hang off them in one
+     * consistent snapshot — a comment list that arrived on its own channel could
+     * name an entry the same read had already dropped.
+     */
+    comments: CommentRecord[];
+    /**
+     * The new-file lines each comment sits on NOW, keyed by comment id — where its quote was found in
+     * the entry's current content (see `resolveCommentLines`, which both halves import).
+     *
+     * DERIVED on every read and never persisted: a resolved line written to the comment file would
+     * outlive the content it was true of, and a stale stored figure is worse than none. A comment the
+     * host cannot place — its quote is gone from the content — is simply ABSENT here, and a caller
+     * then falls back to `record.anchor`: the line the comment was WRITTEN on, which is what an
+     * outdated thread shows anyway. Both panes draw this one map, so the list and the open card
+     * cannot name two lines for one comment (issue: one comment read `[382]` in the list while its
+     * card read 378, because only the open file's pane had resolved it).
+     */
+    commentLines: Record<string, CommentLineRange>;
+    /** Bumped on every comment change, so a poller can tell "nothing new" from "re-read". */
+    commentsRevision: number;
+    /**
+     * The answer text for the questions the session has answered, keyed by the
+     * question's `requestId` (see `CommentAsk`). DERIVED on every read from the
+     * session's own transcript and never stored: the transcript is the one source of
+     * truth for what the agent said, so a stored copy could only ever disagree with it.
+     */
+    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';
@@ -223,3 +381,197 @@ export interface DiffApprovalAddValue {
     /** Failure detail for `outcome: 'failed'`. */
     message?: string | undefined;
 }
+/** The rows a comment was written about, as new-file line numbers. */
+export interface CommentAnchor {
+    /** First new-file line of the annotation. */
+    startLine: number;
+    /** Last new-file line of the annotation. */
+    endLine: number;
+}
+/** The gutter pair of one quoted line, kept so an outdated thread can lay its quote out. */
+export interface CommentQuoteLine {
+    /** Old-file number, absent on a row the old side does not have (an added line). */
+    old?: number | undefined;
+    /** New-file number — the second gutter — absent on a removed line. */
+    new?: number | undefined;
+    /** Which side of the change the row was on when the thread quoted it. */
+    kind?: 'add' | 'del' | 'context' | undefined;
+}
+/** One question asked inside a comment thread, and what became of it. */
+export interface CommentAsk {
+    /**
+     * The identity of the prompt request this question was submitted as. The session
+     * persists it on the exact user message it accepted (`source.rpcId`), so it is the
+     * join key between the question and its message in the transcript — and it is the
+     * idempotency key: a request carrying it again is the same submission, not a second
+     * one. Minted by this plugin, so a question knows its own message before the session
+     * 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
+     * prompt. The prompt is what the agent is asked; this is what the thread shows, so a
+     * follow-up is drawn as the words that were written. Set for every question asked
+     * now; absent only on a record written before this field existed, whose words are
+     * not recoverable from anywhere.
+     */
+    text?: string | undefined;
+    /** The turn that claimed the message, when the session reported one. */
+    turn?: number | undefined;
+    /**
+     * The session discarded the message before any turn claimed it (a stopped turn, a
+     * cancelled queue). Nothing is coming, and the reader is told so rather than left
+     * waiting — this is what the client used to infer from its own queue snapshot.
+     */
+    dropped?: boolean | undefined;
+    /**
+     * The turn that claimed this question has stopped. A question whose turn is over and
+     * that the transcript shows no answer for was cut off: the reader is told that and
+     * offered another try, instead of a block that waits forever on a turn that ended.
+     * Only ever set when true.
+     */
+    ended?: boolean | undefined;
+}
+/**
+ * One comment thread's durable record: the annotation, where it was written, and the
+ * questions asked inside it.
+ *
+ * The ANSWER's text is deliberately absent: `asks[].requestId` names each question's
+ * message, and the session transcript stays the one source of truth for what the agent
+ * said — a client renders an answer by reading the transcript at that id, and the list
+ * read carries the derived text keyed by the same id. Row indices are absent too: they
+ * are model-relative and meaningless after a reload, so the record keeps new-file LINE
+ * numbers plus the quote the reader was looking at, which is what a re-anchor needs.
+ */
+export interface CommentRecord {
+    /** Stable comment id, minted by the host when the annotation is written. */
+    id: string;
+    /** The session the comment belongs to: comments never cross sessions. */
+    sessionId: SessionId;
+    /** The pending entry the comment hangs off (its id, which is its path). */
+    entryId: string;
+    /** The entry's display path when the comment was written. */
+    path: string;
+    /** The lines the annotation was made on, as NEW-file line numbers: the numbers every label,
+     *  jump and reference shows, and the ones the host resolves the quote against. */
+    anchor: CommentAnchor;
+    /** The anchored lines as they read then (the re-anchor fingerprint). */
+    quote: string;
+    /** `quote` with one row of context on each side, as it read then. */
+    quoteContext?: string | undefined;
+    /** The gutter numbers of `quote`'s lines, in the same order. */
+    quoteLines?: CommentQuoteLine[] | undefined;
+    /** The annotation itself: what the reader wrote. */
+    text: string;
+    /**
+     * Who wrote `text`, when it was not the reader.
+     *
+     * The panel draws a thread's first turn as the reader's own words, which is what it is for every
+     * comment the reader makes. An AGENT-authored annotation is the other direction (see
+     * `annotate-tool.ts`): the panel is showing the agent's explanation on those lines, and drawing it as
+     * 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 {
+    /**
+     * What the request did. `missing` means the named entry is not in the session's
+     * list — a comment on a file that has left it is refused rather than stored,
+     * which is the first of the two guards against a comment outliving its entry.
+     */
+    outcome: 'added' | 'missing';
+    /** The stored comment; present only when `outcome` is `added`. */
+    comment?: CommentRecord | undefined;
+}
+/** Value returned by the channel's comment-remove endpoint. */
+export interface DiffApprovalCommentRemoveValue {
+    /** What the request did; `missing` means no such comment in that session. */
+    outcome: 'removed' | 'missing';
+}
+/** Value returned by the channel's comment-remove-many endpoint. */
+export interface DiffApprovalCommentRemoveManyValue {
+    /**
+     * How many of the named comments the request dropped.
+     *
+     * The ids that were not there are not named back: the reader asked for those comments to be
+     * gone, and one that another client already ended is gone. What is left to say is how many
+     * the request itself did, which is what a test and a log can hold on to.
+     */
+    removed: number;
+}
+/** Value returned by the channel's comment-ask endpoint. */
+export interface DiffApprovalCommentAskValue {
+    /**
+     * What the request did. `missing` means no such comment in that session;
+     * `no-agent` means the session has no live agent to ask (it ended, or this host
+     * drives no agent for it), and `failed` carries `message`.
+     */
+    outcome: 'asked' | 'missing' | 'no-agent' | 'failed';
+    /** The request identity the comment now carries (present when `outcome` is `asked`). */
+    requestId?: string | undefined;
+    /** Failure detail for `outcome: 'failed'`. */
+    message?: string | undefined;
+}

package/lib/types/vcs.d.ts

@@ -9,13 +9,17 @@
  * directory.
  *
  * Scope of one import (mirrors the panel's preferences):
- * - modified files (git: working tree vs index — "仅未暂存"; svn: vs BASE;
- *   p4: opened edits), imported as `edit` (old = baseline, new = working);
+ * - modified files, imported as `edit` (old = baseline, new = working). The GIT baseline is the
+ *   last commit, not the index: this list answers "what is not committed yet", so a change the
+ *   reader already `git add`ed is as much a review item as one they have not — staging is a step
+ *   towards a commit, not a decision this panel records (`git diff HEAD` semantics). svn compares
+ *   against BASE and p4 against `#have`, which are their "last commit" already;
  * - deleted files, imported as `edit` with an empty new side (revert restores);
- * - new/untracked files (git `??`, svn `?`, p4 not-yet-opened files), imported
- *   as `create` ONLY when the untracked preference is on. For p4 that means a
- *   full workspace scan (`p4 status`, which can be slow); with the preference
- *   off only already-opened files are read.
+ * - new/untracked files, imported as `create` ONLY when the untracked preference is on: git `??`
+ *   (never added), svn unversioned, p4 not-yet-opened. For p4 that means a full workspace scan
+ *   (`p4 status`, which can be slow); with the preference off only already-opened files are read.
+ *   A file that is new but already under version control (git `A`, svn `added`) needs no
+ *   preference: it is an uncommitted change like any other.
  * @module dsh-diff-approval/vcs
  */
 /** The version-control systems this integration knows. */
@@ -30,32 +34,54 @@ 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. */
     newText: string;
 }
-/** The subset of `ctx.shell`'s executor this module calls (kept structural so
- * the module stays dependency-light and testable with a fake). */
+/**
+ * The subset of `ctx.shell`'s executor this module calls — for BOTH eras of that seam.
+ *
+ * Kept structural so the module stays dependency-light and testable with a fake, and both eras are here
+ * because the seam changed under this plugin. Up to 0.1.6 the executor was `resolve(request)` +
+ * `run(spec)`, and 0.1.7 replaced `run` with `execute(spec)`, which resolves to a PROCESS HANDLE whose
+ * foreground projection is `result()` (measured in `@deepseek-ai/dsh-shell`: `abstract resolve`,
+ * `abstract execute`, `ShellExecution.result(): Promise<ShellRunResult>`). On 0.1.7 the old shape failed
+ * with `shell.run is not a function` — the whole text the import button could show — so both are
+ * accepted, and an executor offering neither is reported by the methods it does have.
+ */
 export interface ShellExecutorLike {
-    resolve(request: {
-        command: string;
-        workdir?: string | undefined;
-        timeoutMs?: number | undefined;
-        signal?: AbortSignal | undefined;
-        /** Foreground stdout capture budget in bytes; absent uses the executor's cap. */
-        stdoutMaxBytes?: number | undefined;
-    }): unknown;
-    run(spec: unknown): Promise<{
-        exitCode: number | null;
-        stdout: {
-            text: string;
-        };
-        stderr: {
-            text: string;
-        };
-    }>;
+    /** 0.1.7: apply the implementation's defaults and caps before execution. */
+    resolve?(request: ShellExecRequestLike): unknown;
+    /** 0.1.7: prepare and spawn; the returned handle carries `result()`. */
+    execute?(spec: unknown): Promise<ShellExecutionLike>;
+    /** Up to 0.1.6: resolve and run in one call. */
+    run?(spec: unknown): Promise<ShellRunResultLike>;
+}
+/** One command, as the seam's request takes it (`workdir`/`timeoutMs` are required only on the spec). */
+interface ShellExecRequestLike {
+    command: string;
+    workdir: string;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    /** Foreground stdout capture budget in bytes; absent uses the executor's cap. */
+    stdoutMaxBytes?: number | undefined;
+}
+/** 0.1.7's execution handle, reduced to the part this module reads. */
+interface ShellExecutionLike {
+    result?: (() => Promise<ShellRunResultLike>) | undefined;
+}
+/** The outcome this module reads, in the shape both eras report it. */
+interface ShellRunResultLike {
+    exitCode: number | null;
+    stdout: {
+        text: string;
+    };
+    stderr: {
+        text: string;
+    };
 }
 /** Reads one file's working content; undefined when the file is absent. */
 export type VcsFileReader = (absolutePath: string) => Promise<string | undefined>;
@@ -95,3 +121,4 @@ 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[]>;
+export {};