dsh-rewind-plugin 0.4.2 → 0.5.0

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

@@ -37,6 +37,6 @@ export declare const inject: string[];
 export declare function apply(ctx: ClientContext): void;
 /**
  * Public contract — rewind visibility. Stable, semver-protected; the rest of
- * this module is internal. See `docs/client-contract.md`.
+ * this module is internal. See `docs/contract/client-contract.md`.
  */
 export { hiddenSeqsOf, targetSeqOfArgs, type HiddenChat } from './hidden.ts';

package/lib/types/index.d.ts

@@ -26,13 +26,15 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 export { SnapshotStore } from './snapshot.ts';
-export type { CheckpointEntry, FileImpact, RestoreOutcome, RestoreJournal, RestoreJournalState, RestoreReconcileReport } from './snapshot.ts';
+export type { CheckpointEntry, FileImpact, PruneStaleReport, RestoreOutcome, RestoreJournal, RestoreJournalState, RestoreReconcileReport } from './snapshot.ts';
 export declare const name = "dsh-rewind";
 export declare const inject: string[];
 /** Plugin config: optional override of the checkpoint store root. */
 export interface RewindConfig {
     /** Checkpoint store root (defaults to `~/.dsh/rewind-snapshots`). */
     readonly snapshotDir?: string;
+    /** In-place content dedup (identical before-content → link). Default `true`. */
+    readonly dedup?: boolean;
 }
 /**
  * Register the `/rewind` command and the checkpoint pipeline (before-capture

package/lib/types/locales.d.ts

@@ -49,6 +49,23 @@ export declare const en: {
     noUserMessages: string;
     chooseMode: string;
     'command.description': string;
+    'cleanup.description': string;
+    'cleanup.inputHint': string;
+    'cleanup.status': string;
+    'cleanup.enabled': string;
+    'cleanup.disabled': string;
+    'cleanup.present': string;
+    'cleanup.absent': string;
+    'cleanup.onOk': string;
+    'cleanup.offOk': string;
+    'cleanup.maxAgeOk': string;
+    'cleanup.cfgInvalid': string;
+    'cleanup.saveFailed': string;
+    'cleanup.runDry': string;
+    'cleanup.runApply': string;
+    'cleanup.runFailed': string;
+    'cleanup.skipped': string;
+    'cleanup.usage': string;
 };
 /** The host rewind dictionary key union. */
 export type HostKey = keyof typeof en;

package/lib/types/snapshot-cleanup.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Snapshot cleanup policy: the persisted config file, its validation, the
+ * `/snapshot-auto-cleanup` command's argument grammar, and the auto-sweep
+ * throttle. Kept free of host wiring so the policy and the parser are
+ * unit-testable in isolation; `src/index.ts` is the only consumer.
+ *
+ * Semantics (the "cleanup" vocabulary deliberately avoids "retention"):
+ * - `enabled` toggles the AUTOMATIC (24h) sweep. `false` (the default) keeps
+ *   every snapshot — the pre-feature behavior — and never writes a file.
+ * - `maxAgeDays` is the only "keep" knob: a finished session dir whose newest
+ *   member stamp is older than this many days of idle is removed by a sweep.
+ *   `0`/negative/non-integer are rejected, so a broken file can never steer
+ *   the sweep into deleting everything.
+ * - The config file is created ONLY by an explicit `/snapshot-auto-cleanup`
+ *   write. An absent file reads as the safe default (off); an unreadable or
+ *   invalid file reports `ok:false` so a sweep fail-closes (deletes nothing)
+ *   instead of guessing.
+ *
+ * @module dsh-rewind/snapshot-cleanup
+ */
+/** The cleanup policy, as persisted under `~/.dsh/snapshot-cleanup.json`. */
+export interface CleanupConfig {
+    readonly enabled: boolean;
+    readonly maxAgeDays: number;
+}
+export declare const CLEANUP_CONFIG_FILENAME = "snapshot-cleanup.json";
+/** Environment variable overriding the config file path. */
+export declare const CLEANUP_CONFIG_ENV = "DSH_SNAPSHOT_CLEANUP_CONFIG";
+/** The default keep threshold: finished sessions idle > 30 days are pruned. */
+export declare const DEFAULT_MAX_AGE_DAYS = 30;
+/** The safe default policy (off) — a missing/corrupt file behaves like this. */
+export declare const DEFAULT_CLEANUP_CONFIG: CleanupConfig;
+/** Auto-sweep cadence (the user's hardcoded 24h rhythm — not user-set). */
+export declare const AUTO_SWEEP_INTERVAL_MS: number;
+/** Resolve the config file path: env override, else `~/.dsh/snapshot-cleanup.json`. */
+export declare function resolveCleanupConfigPath(): string;
+/** The state file that records the last automatic-sweep wall-clock time. */
+export declare const STATE_FILENAME = "snapshot-cleanup-last-sweep.json";
+/**
+ * Resolve the last-sweep state path. It sits beside the config file so the
+ * 24h cadence SURVIVES a host restart (a real deployment is rarely up 24/7,
+ * so an in-memory timestamp would reset on every boot and re-sweep too often).
+ */
+export declare function resolveCleanupStatePath(): string;
+/**
+ * Read the persisted last-sweep time (epoch ms). A missing or corrupt file
+ * reads as `0` ("never swept"), so the next activity runs the sweep — which is
+ * safe because the sweep is idempotent and never deletes the active session.
+ */
+export declare function loadLastSweepAt(path: string): Promise<number>;
+/** Persist the last-sweep time, atomically (temp + rename). */
+export declare function saveLastSweepAt(path: string, ms: number): Promise<void>;
+/** The slice of a store `runAutoCleanupCheck` needs (pruneStale). */
+export interface AutoCleanupPruner {
+    pruneStale(opts: {
+        keepActiveId?: string;
+        maxAgeDays: number;
+        dryRun?: boolean;
+    }): Promise<unknown>;
+}
+/**
+ * The one-shot auto-cleanup check. Loads the policy + persisted last-sweep time
+ * and, only when enabled AND >=24h since the last sweep, runs the sweep and
+ * re-anchors the window on disk. Dependencies (store, paths, logger) are
+ * injected so the composition is unit-testable without a host. Never rejects:
+ * a corrupt config fail-closes (no deletion) and logs, a prune failure logs.
+ *
+ * `sessionId` is the active session directory that must never be pruned.
+ */
+export declare function runAutoCleanupCheck(deps: {
+    pruner: AutoCleanupPruner;
+    configPath: string;
+    statePath: string;
+    log: (msg: string) => void;
+}, sessionId: string | undefined): Promise<void>;
+/**
+ * Validate one parsed JSON value into a {@link CleanupConfig}. Tolerates
+ * unknown extra keys; rejects a present-but-wrong-typed known key. Missing
+ * known keys fall back to the safe default.
+ */
+export declare function parseCleanupConfig(raw: unknown): {
+    ok: true;
+    config: CleanupConfig;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Load and validate the config file. A missing file is NOT an error: it reads
+ * as the safe default (off, `fromFile:false`). An unreadable, non-JSON, or
+ * structurally-invalid file is `ok:false` so a sweep fail-closes.
+ */
+export declare function loadCleanupConfig(path: string): Promise<{
+    ok: true;
+    config: CleanupConfig;
+    fromFile: boolean;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * Persist a validated {@link CleanupConfig}, atomically (temp + rename). Any
+ * invalid value throws before the file is touched, so the command can never
+ * write a broken policy.
+ */
+export declare function saveCleanupConfig(path: string, config: CleanupConfig): Promise<void>;
+/** The `/snapshot-auto-cleanup` sub-command the parser can resolve to. */
+export type CleanupCommandAction = 'status' | 'on' | 'off' | 'max-age' | 'run' | 'run-apply';
+/**
+ * Parse the free-form text after `/snapshot-auto-cleanup`. Pure so it is
+ * unit-testable; `src/index.ts` maps the resolved action onto the store / the
+ * config file. `max-age` returns the validated positive day count.
+ */
+export declare function parseCleanupCommand(rawInput: string): {
+    action: CleanupCommandAction;
+    value?: number;
+} | {
+    error: string;
+};
+/**
+ * The 24h auto-sweep throttle. `lastAtMs` of `0` means "never ran" (a fresh
+ * process), so the first call always sweeps; after that a call within 24h is
+ * a no-op, matching the "every machine at most once per day" model.
+ */
+export declare function shouldRunAutoSweep(lastAtMs: number, nowMs: number): boolean;

package/lib/types/snapshot.d.ts

@@ -66,6 +66,30 @@ export interface CheckpointEntry {
     /** Epoch ms the entry was committed (stable ordering within a group). */
     readonly time: number;
 }
+/**
+ * One in-place dedup link, keyed by tool call. When a tracked file is
+ * recorded with a `before` content identical to the immediately-prior entry
+ * for that path, the entry is stored as a LINK instead of a full copy: it
+ * carries no `before`, only a `ref` naming the prior entry file
+ * (`<anchorSeq>/<callId>.json`). The linear (predecessor-chained) ref makes
+ * restore resolution and prune materialization rewrite-free.
+ *
+ * The real-entry format ({@link CheckpointEntry}) is unchanged so existing
+ * data reads identically; links are a NEW entry kind only the current build
+ * understands (old-build reads of links are explicitly out of scope).
+ */
+export interface LinkEntry {
+    readonly callId: string;
+    readonly anchorSeq: number;
+    readonly path: string;
+    /** `<anchorSeq>/<callId>.json` of the immediately-prior entry for the path. */
+    readonly ref: string;
+    readonly time: number;
+}
+/** Any on-disk entry: a full before-backup or an in-place dedup link. */
+export type StoredEntry = CheckpointEntry | LinkEntry;
+/** True when an entry is a dedup link (carries `ref`, not `before`). */
+export declare function isLinkEntry(entry: StoredEntry): entry is LinkEntry;
 /** Per-file restore impact preview (`/rewind preview @seq both`). */
 export interface FileImpact {
     readonly path: string;
@@ -199,6 +223,32 @@ export type PlannedAction = {
 };
 /** Production probe: real reads via node:fs, links detected by lstat + nlink. */
 export declare const defaultProbe: DiskProbe;
+/**
+ * Result of a stale-session cleanup sweep ({@link SnapshotStore.pruneStale}).
+ *
+ * The sweep is ANTI-DELETE: it only ever removes WHOLE session directories
+ * that have been idle past `maxAgeDays`. `scanned` counts every session dir
+ * evaluated; `kept` + `skippedActive` + `deleted` sum to it. `remainingBytes`
+ * is the total of directories that SURVIVE the policy (when `dryRun` it is the
+ * would-be total, not the current on-disk total), so it is comparable across
+ * dry and real runs.
+ */
+export interface PruneStaleReport {
+    /** Number of session directories evaluated. */
+    readonly scanned: number;
+    /** Session directories removed (would-be count when `dryRun`). */
+    readonly deleted: number;
+    /** Bytes reclaimed (would-be bytes when `dryRun`). */
+    readonly freedBytes: number;
+    /** Session directories retained (not past the cutoff, not the active one). */
+    readonly kept: number;
+    /** Bytes across the retained + skipped-active directories. */
+    readonly remainingBytes: number;
+    /** Directories skipped because they are the active session. */
+    readonly skippedActive: number;
+    /** Whether nothing was really removed (the sweep only reported). */
+    readonly dryRun: boolean;
+}
 /**
  * On-disk checkpoint store. Every write goes straight through `node:fs`, so a
  * restore reliably lands on the real file system.
@@ -221,15 +271,56 @@ export declare class SnapshotStore {
      * it, and even then the in-process order still holds.
      */
     private lastEntryTime;
-    constructor(root?: string);
+    /** Store options; `dedup` toggles in-place content dedup (default on). */
+    private readonly dedup;
+    /**
+     * In-memory per-path "most recent entry" for content dedup, keyed by
+     * `<sessionId>\0<path>`. Each value holds the entry's effective `before`
+     * content and its own file ref, so a new record with the same content links
+     * to the immediately-prior entry (linear chain). Seeded lazily per session
+     * from the bounded on-disk window, so dedup survives a host restart.
+     */
+    private readonly lastEntry;
+    /** Sessions whose dedup state has been seeded from disk this process. */
+    private readonly seededSessions;
+    constructor(root?: string, opts?: {
+        readonly dedup?: boolean;
+    });
     /** Absolute path of one session's snapshot directory (id sanitized). */
     sessionDir(sessionId: string): string;
     /** Absolute path of one anchor group directory. */
     anchorDir(sessionId: string, anchorSeq: number): string;
-    /** Commit one before-backup under its turn's anchor group (atomic write). */
+    /** Absolute file ref (relative to the session dir) of an entry. */
+    private entryRefOf;
+    /**
+     * Seed a session's dedup state from the existing (bounded) on-disk window:
+     * scan entries newest-first and record the most recent entry per path. This
+     * makes content dedup survive a host restart within the session window. A
+     * no-op after the first seed (or when `dedup` is disabled).
+     */
+    private ensureDedupSeeded;
+    /**
+     * Resolve an entry's effective `before` content, following a link chain to
+     * its terminal real snapshot. Refs are strictly backward in
+     * `(anchorSeq, time)`, so the chain is acyclic and finite. A dangling or
+     * cyclic link throws — callers fail per-file (never silently dropping the
+     * path from a restore).
+     */
+    private resolveBefore;
+    /** Commit one before-backup (or an in-place dedup link) under its anchor. */
     recordEntry(sessionId: string, entry: Omit<CheckpointEntry, 'time'>, opts?: {
+        readonly dedup?: boolean;
         readonly crash?: (point: CrashPoint) => void;
     }): Promise<void>;
+    /**
+     * The effective content recorded by the path's MOST RECENT entry, or
+     * undefined when the path has never been recorded (a fresh tracking sight).
+     * This is the single in-memory "last known state" the boundary uses to
+     * decide whether a tracked file changed — the same source `recordEntry`
+     * dedups against, so there is one content copy and one comparison per
+     * decision, not two. Seeding is idempotent (once per session from disk).
+     */
+    lastKnownContent(sessionId: string, path: string): Promise<string | null | undefined>;
     /**
      * All committed entries anchored at or after `targetSeq`, newest first (for
      * preview ordering). The boundary is inclusive: rewinding to a message also
@@ -237,7 +328,7 @@ export declare class SnapshotStore {
      * turn's assistant response and tool calls), so only entries anchored at
      * earlier messages survive.
      */
-    entriesAfter(sessionId: string, targetSeq: number): Promise<CheckpointEntry[]>;
+    entriesAfter(sessionId: string, targetSeq: number): Promise<StoredEntry[]>;
     /**
      * Per-path EARLIEST committed entry anchored at or after the target — the
      * single source of truth for both restore and impact preview.
@@ -269,7 +360,7 @@ export declare class SnapshotStore {
      * @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.
+     * @returns the planned actions, the link paths skipped, and per-file failures.
      */
     private planRestore;
     /** Per-file restore impact: only actions that would actually change the disk. */
@@ -384,8 +475,23 @@ export declare class SnapshotStore {
      * recycles terminal restore journals (see {@link pruneTerminalJournals}),
      * so the per-commit cap bounds BOTH the checkpoint entries and the journal
      * accumulation.
+     *
+     * Because dedup links reference prior entries, eviction is LINK-AWARE: before
+     * deleting the oldest groups, any SURVIVING (kept-group) link whose `ref`
+     * lands on a real snapshot inside a doomed group is MATERIALIZED (rewritten
+     * as a real snapshot carrying the resolved content), so no kept link is left
+     * dangling. Links form a linear predecessor chain, so materializing the first
+     * link after each doomed real is enough — later links already point at that
+     * materialized entry (or at other kept links), requiring no rewrite.
+     *
+     * `opts.crash` is the test-only seam: a crash fired inside a materialization
+     * write (between its temp write and rename) leaves ONLY a `.tmp` — the doomed
+     * real is still on disk and the kept link still resolves, so nothing dangles
+     * and a later prune simply re-materializes.
      */
-    prune(sessionId: string, keep?: number): Promise<void>;
+    prune(sessionId: string, keep?: number, opts?: {
+        readonly crash?: (point: CrashPoint) => void;
+    }): Promise<void>;
     /**
      * Recycle terminal restore journals (`completed` / `rolled-back`): once an
      * op finished, its journal's before + rescue content is dead weight that
@@ -397,6 +503,33 @@ export declare class SnapshotStore {
     private pruneTerminalJournals;
     /** True when a path exists on disk (used by tests and diagnostics). */
     exists(path: string): Promise<boolean>;
+    /**
+     * Cross-session retention sweep: remove WHOLE session directories whose
+     * newest member stamp is older than `maxAgeDays` days of idle, keeping the
+     * active session (`keepActiveId`) untouched. This is the anti-growth policy
+     * for finished sessions (rewind only ever reads the active session, so a
+     * finished session's backups are provably dead weight).
+     *
+     * SAFETY:
+     *  - Only whole session directories are removed (dedup refs are
+     *    session-relative, so there is no cross-session dangling to materialize);
+     *  - the active session is never targeted (`keepActiveId`), and everything
+     *    else is protected by its own mtime — a session that is still written to
+     *    keeps scrolling its newest member stamp forward, so it is never old
+     *    enough to be pruned;
+     *  - a non-positive `maxAgeDays` throws instead of degenerating into a
+     *    mass-destructive `cutoff` in the far future;
+     *  - the walk uses `lstat` (no symlink following) and skips dot-prefixed
+     *    temp left overs, so measurement stays inside the store root.
+     *
+     * `dryRun` computes and reports exactly what would be removed without
+     * deleting anything — the `/snapshot-auto-cleanup run` preview.
+     */
+    pruneStale(opts: {
+        readonly keepActiveId?: string;
+        readonly maxAgeDays: number;
+        readonly dryRun?: boolean;
+    }): Promise<PruneStaleReport>;
     /**
      * All distinct paths ever recorded for a session — the "tracked files"
      * set. Mirrors Claude Code's global `trackedFiles` collection (files stay
@@ -418,10 +551,13 @@ export declare class SnapshotStore {
  * 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).
+ * from the path's most-recent recorded content (`lastKnownContent`); a fresh
+ * sighting (never recorded) always records. The state is compared against the
+ * SAME single in-memory source `recordEntry` dedups against, so there is one
+ * content copy and one comparison — not the two (a boundary map plus the
+ * dedup map) the previous model held. Only CHANGED files are recorded, and
+ * each is a full snapshot (`dedup: false`): a changed state always differs
+ * from the recent record, so the link decision would never apply there.
  *
  * 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
@@ -431,8 +567,7 @@ export declare class SnapshotStore {
  * @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>;
+export declare function reconcileTracked(store: SnapshotStore, sessionId: string, anchorSeq: number, tracked: ReadonlySet<string>, probe?: DiskProbe): Promise<number>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "DSH 插件：真正便捷无感的同窗口内对话回退，从不新建分支；自带轻量工作区备份，可一并还原文件（完整 Claude Code /rewind 语义）。 · DSH plugin: genuinely effortless in-window conversation rewind — never forking a new session; ships a lightweight workspace backup that restores files together with the rewind (full Claude Code /rewind semantics).",
   "keywords": [
     "deepseek-harness",
@@ -39,6 +39,8 @@
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
     "docs",
     "assets",
     "LICENSE"
@@ -62,6 +64,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json && tsc --noEmit -p tsconfig.client-test.json",
     "test": "vitest run",
     "verify:host": "node scripts/verify-host.mjs",
+    "check": "npm run typecheck && npm test && npm run build && node scripts/verify-host.mjs && npm pack --dry-run",
     "prepare": "npm run build"
   },
   "publishConfig": {

package/docs/troubleshooting.md

@@ -1,44 +0,0 @@
-# Troubleshooting
-
-[简体中文](troubleshooting.zh.md)
-
-## History load failure: `…turn-tail… received an update before its start Match`
-
-Rewinds from `≤ 0.2.4` collided with the next real turn's `turn/start`, so reopening the session showed
-
-```
-Failed to load history: conversation Context …:turn-tail… received an update before its start Match (internal)
-```
-
-and the history vanished. Rewinds from `0.2.5` on no longer collide; already-corrupted sessions need an offline repair (the log is append-only). The repair tool (`dsh-rewind-repair`) is no longer shipped from v0.4.0 — install a pre-v0.4.0 release to get it (fully quit dsh web / host first, then):
-
-```sh
-npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair
-npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-run  # preview only
-```
-
-It only rewrites the marker events' `data.turn` (seqs, order, and zstd frame structure intact) and backs up the original file before writing — safe to run repeatedly. From a source checkout of a pre-v0.4.0 tag: `node scripts/repair-markers.mjs` (identical flags).
-
-## Known compatibility boundaries
-
-Behavioral notes verified by the compatibility probe suites
-([compat-audit.md](compat-audit.md)) — none of these is a crash:
-
-- **Session stats / telemetry do not roll back**: whole-log folds count the
-  withdrawn turns, and telemetry records the rewind's marker and ghost-step
-  frame under the reused turn. Expected whole-log semantics.
-- **Withdrawn messages stay searchable and exported**: rewind cuts only the
-  model-visible surface; full-text search and `/export` still see the raw log.
-- **Session titles may regenerate** after a rewind (title derives from the
-  current surface).
-- **Files written by a cancelled tool call** (write happened, no result, no
-  snapshot commit) cannot be restored by "conversation and code".
-
-**R-OPENSTEP** (harness-side, plugin does not guard): a session log carrying
-an *unclosed* `step/start` (a crash before the agent loop's `finally` closed
-the step) makes any later step activity break token-meter replay (and
-`/compact`). Harness `0.1.1-rc.2` fixes the crash path on load
-(`interruptedTurnClosers` closes leftover step/turn boundaries). A plugin-side
-up-front rejection was implemented and **reverted** (false positives broke the
-rewind feature on real session logs, `177ec14`); the residual runtime-produced
-risk is accepted. Tracked in the compat-audit.