dsh-rewind-plugin 0.3.0 → 0.3.2

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

@@ -13,8 +13,12 @@ export interface HiddenChat {
         get(key: string): ChatConversationViewNode | undefined;
     };
 }
-/** Extract the rewind target from a command outcome text ("已撤回 seq N..."). */
-export declare function targetOfOutcome(text: string | undefined): number | undefined;
+/**
+ * Extract the rewind target seq from a `/rewind` command's structured `args`
+ * (e.g. `@5 chat`, `preview @5 both`). Locale-independent — never parses the
+ * host's human outcome copy.
+ */
+export declare function targetSeqOfArgs(args: string | null | undefined): number | undefined;
 /**
  * True when a `/rewind` command node is an EXECUTED rewind for `seq` — the
  * admission form the popover drives (`@<seq> chat` / `both`) that settled
@@ -28,12 +32,19 @@ export declare function isExecutedRewindCommand(node: CommandNode, seq: number):
  * of the "rewind conversation and code" option (Claude Code hides the
  * code-restore options when the checkpoint has no tracked changes).
  *
- * Prefers the machine-readable `impact=<n>` trailer the current host appends
- * to preview text. Older host output (or a history-loaded preview row from
- * before the trailer existed) has none, so it falls back to the human copy
- * ("将影响 …") to keep mixed-version deployments correct.
+ * Reads ONLY the machine-readable `impact=<n>` trailer the host appends to
+ * preview text. Older host output without the trailer is treated as having no
+ * changes (never guesses from human copy). Unknown/absent text degrades to
+ * always-show so a working option is never hidden on a failed probe.
  */
 export declare function hasFileImpact(text: string | undefined): boolean;
+/**
+ * True when a `/rewind` command node is the internal candidate-list probe
+ * (`/rewind __candidates`) the popupSelect runs to fetch the FULL candidate
+ * list from the host. Like previews, its flow node never surfaces in the
+ * transcript — it only feeds the popup — so it is hidden in every state.
+ */
+export declare function isCandidateCommand(command: CommandNode): boolean;
 /**
  * Anchor seqs that must be hidden from the rendered transcript so the user
  * sees the conversation as the agent sees it: every impact-preview flow node

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

@@ -15,6 +15,8 @@ export declare const zh: {
     'popover.impact.loading': string;
     'popover.impact.failed': string;
     'popover.impact.none': string;
+    'popover.impact.restore': string;
+    'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
     'guard.hint': string;
@@ -43,6 +45,8 @@ export declare const en: {
     'popover.impact.loading': string;
     'popover.impact.failed': string;
     'popover.impact.none': string;
+    'popover.impact.restore': string;
+    'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
     'guard.hint': string;

package/lib/types/locales.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Host-side localization for dsh-rewind's `/rewind` command output and command
+ * description.
+ *
+ * Architecture (matches the dsh ecosystem): the HOST half of a dual-face
+ * plugin has no locale service — only the browser client carries one. The host
+ * therefore renders its command-adjacent copy from a durable user preference
+ * (`ctx.settings` → `locale.preference`, registered by dsh-client-locale),
+ * defaulting to English — the ecosystem's neutral default language (the harness
+ * `FALLBACK_LOCALE` and the language dsh's own host commands use, e.g.
+ * dsh-plan-mode). See packages/client/locale in deepseek-harness.
+ *
+ * The client half (`src/client/locales.ts`) owns all interactive UI copy via
+ * `ctx.locale` + `t()`; the host's human text is a machine channel the client
+ * renders through machine tokens (`impact=<n>`, `args` @seq), never by parsing
+ * host prose.
+ *
+ * English is the key-set source of truth; zh is checked complete against it.
+ *
+ * @module dsh-rewind/locales
+ */
+/** Host-side supported locale ids, mirroring the harness's shipped locales. */
+export type HostLocaleId = 'zh' | 'en';
+/** English dictionary — the key-set source of truth (neutral default). */
+export declare const en: {
+    'usage.title': string;
+    'usage.noArgs': string;
+    'usage.seq': string;
+    'usage.blocked': string;
+    'describeTarget.seq': string;
+    'describeTarget.index': string;
+    'plan.rewinding': string;
+    'plan.affects': string;
+    'plan.restore': string;
+    'plan.delete': string;
+    'plan.noChanges': string;
+    'error.invalidTarget': string;
+    'failures.suffix': string;
+    'failures.item': string;
+    inflight: string;
+    stopFailed: string;
+    cancelled: string;
+    failed: string;
+    'restore.count': string;
+    'delete.count': string;
+    'skip.count': string;
+    noRestorable: string;
+    success: string;
+    noUserMessages: string;
+    chooseMode: string;
+    'command.description': string;
+};
+/** The host rewind dictionary key union. */
+export type HostKey = keyof typeof en;
+/** Chinese dictionary, checked complete against the en key set. */
+export declare const zh: Record<HostKey, string>;
+/** The host dictionaries keyed by locale id. */
+export declare const HOST_DICTS: Record<HostLocaleId, Record<HostKey, string>>;
+/**
+ * Render one dictionary key with `{name}` template interpolation. Unknown
+ * params are ignored; a missing key falls back to the raw key so a dictionary
+ * gap is visible instead of blank.
+ * @param lang - the active locale.
+ * @param key - the dictionary key.
+ * @param params - `{name}` substitution values.
+ */
+export declare function translate(lang: HostLocaleId, key: HostKey, params?: Record<string, string | number>): string;

package/lib/types/rewind.d.ts

@@ -60,6 +60,12 @@ export interface RewindPlan {
 }
 /** Preview length cap for candidate listings. */
 export declare const CANDIDATE_PREVIEW_CHARS = 80;
+/**
+ * Default cap on how many user messages a candidate listing returns (newest
+ * kept). Raised from 10 so long sessions don't look incomplete; callers can
+ * still pass an explicit `limit`.
+ */
+export declare const DEFAULT_CANDIDATE_LIMIT = 50;
 /**
  * Turn number for the rewind marker.
  *
@@ -85,6 +91,18 @@ export declare const CANDIDATE_PREVIEW_CHARS = 80;
 export declare function markerTurnOf(events: readonly SessionEvent[]): number;
 /** Narrow an event to a user message. */
 export declare function isUserMessageEvent(event: SessionEvent): event is SessionEvent<'user/message'>;
+/**
+ * True for a HUMAN user message event — one whose `source.kind` is `'user'`.
+ *
+ * The surface can carry `user/message` events whose source is NOT the user:
+ * plugin/system context injection (including compaction checkpoints) and
+ * tool-result backfill all arrive as `user/message` with a non-`'user'`
+ * source, and the client renders those as `context` nodes, never as a user
+ * bubble. Only genuine user messages (and user steering during a running
+ * turn, which keeps `source.kind: 'user'`) are valid rewind targets — a
+ * rewind boundary must land on a human prompt, not on injected context.
+ */
+export declare function isHumanUserMessageEvent(event: SessionEvent): event is SessionEvent<'user/message'>;
 /** Join the text blocks of a message into one plain string. */
 export declare function messagePreview(message: UserMessage): string;
 /**
@@ -104,6 +122,23 @@ export declare function parseRewindTarget(raw: string): RewindTarget | undefined
  * @returns candidates numbered 1..N by recency.
  */
 export declare function listRewindCandidates(events: readonly SessionEvent[], surface: readonly number[], limit?: number): RewindCandidate[];
+/** Header line of the machine-readable candidate list (locale-independent). */
+export declare const CANDIDATE_LIST_HEADER = "candidates=";
+/**
+ * Encode a candidate list as the host→client machine channel (the same
+ * trailer pattern `formatPlan` uses for `impact=`). The client popupSelect
+ * parses this instead of reading the windowed chat snapshot, so the candidate
+ * list reflects the FULL host surface — not just the already-loaded history.
+ *
+ * Lines (each preview is already whitespace-collapsed and tab-free by
+ * `messagePreview`):
+ *   candidates=<n>
+ *   <seq>\t<time>\t<preview>
+ *   … (one line per candidate, newest first, matching `listRewindCandidates`)
+ *
+ * A list with no candidates is just `candidates=0`.
+ */
+export declare function formatCandidateList(candidates: readonly RewindCandidate[]): string;
 /**
  * Resolve a target against the session log and surface into a validated plan.
  * @param events - the full session event log.

package/lib/types/snapshot.d.ts

@@ -65,6 +65,34 @@ export interface RestoreOutcome {
 }
 /** Deletes one file by its real path (node:fs, bypassing the fs service). */
 export type DeleteFile = (path: string) => Promise<void>;
+/**
+ * Current-on-disk state probe used by restore planning. Injected so the plan
+ * logic runs against a fake FS in tests; the production default reads the
+ * real file system with plain `node:fs` (see {@link defaultProbe}).
+ */
+export interface DiskProbe {
+    /**
+     * Full text of the file, or undefined when the file does not exist.
+     * Any thrown error is treated as a probe failure: restore planning then
+     * conservatively treats the file as DIFFERING from its record (a restore
+     * still attempts the write / a delete still attempts the unlink), so an
+     * unreadable file is never silently skipped.
+     */
+    readText(path: string): Promise<string | undefined>;
+    /** True when the path is a symlink or a hard link (never planned/restored). */
+    isLink(path: string): Promise<boolean>;
+}
+/** One restore action the planner derived from record + disk reconciliation. */
+export type PlannedAction = {
+    readonly path: string;
+    readonly action: 'restore';
+    readonly before: string;
+} | {
+    readonly path: string;
+    readonly action: 'delete';
+};
+/** Production probe: real reads via node:fs, links detected by lstat + nlink. */
+export declare const defaultProbe: DiskProbe;
 /**
  * On-disk checkpoint store. Every write goes straight through `node:fs`, so a
  * restore reliably lands on the real file system.
@@ -94,18 +122,49 @@ export declare class SnapshotStore {
      * single source of truth for both restore and impact preview.
      */
     private earliestEntries;
-    /** Per-file restore impact for the earliest entry at/after the target. */
-    impactsAfter(sessionId: string, targetSeq: number): Promise<FileImpact[]>;
     /**
-     * Restore the workspace to the target message's checkpoint: for every path
-     * with entries anchored at or after it, apply the EARLIEST entry — write the
-     * before content back, or delete the file when it was created after the
-     * target. Symlinked and hard-linked paths are skipped (reported, never
-     * written through); a restored file's parent directory is created when it
-     * was deleted after the backup. Failures are per-file and never abort the
-     * pass.
+     * The single source of truth for BOTH the impact preview and the restore
+     * pass: reconcile the earliest recorded entry per path (at/after the
+     * target) against the CURRENT on-disk state, and plan only the actions
+     * that would actually change the disk. This is the Claude Code model —
+     * `fileHistoryGetDiffStats` / `applySnapshot` both compare against the
+     * live filesystem (`checkOriginFileChanged`) and count only real
+     * differences, so a rewind whose target state already matches the disk is
+     * a no-op with zero impact.
+     *
+     * - `before === null` (the file did not exist at the target) plans a
+     *   `delete` ONLY when the file currently exists; an already-absent file
+     *   is a no-op — this kills the "ghost impact" of replaying an entry a
+     *   previous rewind already consumed.
+     * - `before === 'X'` plans a `restore` ONLY when the current content
+     *   differs from X (or the file is missing); identical content is a no-op
+     *   — this keeps repeated rewinds idempotent.
+     * - Symlinked / hard-linked paths are never planned (they are reported as
+     *   skipped by the restore pass, never written through).
+     * - A probe failure (e.g. a permission error reading the file) plans the
+     *   action conservatively as if the file differed, so an unreadable file
+     *   is never silently dropped from the restore.
+     *
+     * @param sessionId - session whose snapshot store to plan against.
+     * @param targetSeq - rewind target; entries anchored at/after it apply.
+     * @param probe - current-disk state probe (defaults to the real FS).
+     * @returns the planned actions plus the link paths that were skipped.
+     */
+    private planRestore;
+    /** Per-file restore impact: only actions that would actually change the disk. */
+    impactsAfter(sessionId: string, targetSeq: number, probe?: DiskProbe): Promise<FileImpact[]>;
+    /**
+     * Restore the workspace to the target message's checkpoint: execute exactly
+     * the actions {@link planRestore} derived from the record + current disk
+     * reconciliation — write the before content back, or delete the file when
+     * it was created after the target and still exists. Symlinked and
+     * hard-linked paths are skipped (reported, never written through); a
+     * restored file's parent directory is created when it was deleted after
+     * the backup; a delete whose file is ALREADY absent is a silent no-op (not
+     * a failure — the target state is already reached). Failures are per-file
+     * and never abort the pass.
      */
-    restoreAfter(sessionId: string, targetSeq: number, deleteFile: DeleteFile): Promise<RestoreOutcome>;
+    restoreAfter(sessionId: string, targetSeq: number, deleteFile: DeleteFile, probe?: DiskProbe): Promise<RestoreOutcome>;
     /**
      * Drop the session's oldest anchor groups beyond `keep` (default
      * {@link MAX_ANCHOR_GROUPS}), deleting their whole directories.
@@ -113,4 +172,42 @@ export declare class SnapshotStore {
     prune(sessionId: string, keep?: number): Promise<void>;
     /** True when a path exists on disk (used by tests and diagnostics). */
     exists(path: string): Promise<boolean>;
+    /**
+     * All distinct paths ever recorded for a session — the "tracked files"
+     * set. Mirrors Claude Code's global `trackedFiles` collection (files stay
+     * tracked once a write-class tool touched them), derived from the disk
+     * entries so no extra persistence is needed.
+     */
+    trackedPaths(sessionId: string): Promise<Set<string>>;
 }
+/**
+ * Re-check every tracked file at a user-message boundary and record the
+ * current on-disk state for any file whose state changed since it was last
+ * seen — Claude Code's `fileHistoryMakeSnapshot` re-stats every tracked file
+ * at each user message and snapshots the new state (changed files get a new
+ * backup version, deleted files a null marker). Here the "new version" is a
+ * plain before-backup entry anchored at the boundary message, so an EXTERNAL
+ * edit or deletion (never seen by the write-class tool capture) enters the
+ * record and can be restored by a later rewind.
+ *
+ * Semantics: the recorded `before` is the file's state at the boundary —
+ * the state the boundary message's turn starts from, exactly like the
+ * tool-captured entries. An entry is written only when the state differs
+ * from the last-seen state (`states`); the FIRST sighting of a path always
+ * records (a restart leaves `states` empty, so the first boundary after a
+ * restart unconditionally records the current state — redundant but correct,
+ * mirroring Claude's resume-then-re-stat behavior).
+ *
+ * Symlinked / hard-linked paths are never re-checked (restores skip them).
+ * A probe failure skips the file with a warning-level no-op; it never
+ * aborts the boundary pass.
+ *
+ * @param store - the session's snapshot store.
+ * @param sessionId - session whose tracked files to re-check.
+ * @param anchorSeq - the boundary user-message seq (entry anchor).
+ * @param tracked - the session's tracked path set (read-only here).
+ * @param states - per-path last-seen state (path → content, null = absent).
+ * @param probe - current-disk state probe (defaults to the real FS).
+ * @returns the number of entries recorded.
+ */
+export declare function reconcileTracked(store: SnapshotStore, sessionId: string, anchorSeq: number, tracked: ReadonlySet<string>, states: Map<string, string | null>, probe?: DiskProbe): Promise<number>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "DeepSeek Harness plugin: in-place conversation rewind in the same session window (Claude Code /rewind semantics) with optional workspace file restore",
   "keywords": [
     "deepseek-harness",
@@ -82,6 +82,7 @@
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
   },
   "peerDependenciesMeta": {
@@ -115,6 +116,9 @@
     "@deepseek-ai/dsh-session": {
       "optional": true
     },
+    "@deepseek-ai/dsh-settings": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-tools": {
       "optional": true
     }
@@ -132,6 +136,7 @@
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
     "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.7",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
     "@types/node": "^24.0.0",
     "@types/react": "^18.3.31",