dsh-rewind-plugin 0.4.2 → 0.6.0

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

@@ -1,7 +1,7 @@
 /**
- * dsh-rewind client half: the `/rewind` command decoration, the
- * parameterized-input guard, the locale registration, and the session-scoped
- * portal bridge that renders the per-message ↶ rewind button (see
+ * dsh-rewind client half: the `/rewind` command decoration, the locale
+ * registration, and the session-scoped portal bridge that renders the
+ * per-message ↶ rewind button (see
  * `portals.tsx` for the button itself).
  *
  * The button is NOT injected by hand into the DOM anymore: the plugin
@@ -14,15 +14,15 @@
  * drift.
  *
  * The text-driven flow is the harness's STANDARD command decoration
- * (`ctx.commandUi.decorate`): a bare `/rewind` — picked from the slash-menu
- * completion, or typed in full and Entered — opens the harness's own
- * popupSelect shell (search, ↑↓/Enter, Esc) listing the rewind candidates
- * instead of executing the command. Picking one continues the SAME flow as
- * the ↶ button: the mode popover, both-impact confirmation, execution, row
- * hiding and the composer refill (`runRewindAndFill`). The parameterized
- * forms (`/rewind @<seq> chat|both`, `/rewind preview …`) stay internal
- * channels the ↶ button and the popover drive through `session.command`; a
- * hand-typed parameterized line is stopped with a hint.
+ * (`ctx.commandUi.decorate`): a bare `/rewind` (or its alias `/undo`) —
+ * picked from the slash-menu completion, or typed in full and Entered —
+ * opens the harness's own popupSelect shell (search, ↑↓/Enter, Esc) listing
+ * the rewind candidates instead of executing the command. Picking one
+ * continues the SAME flow as the ↶ button: the mode popover, both-impact
+ * confirmation, execution, row hiding and the composer refill
+ * (`runRewindAndFill`). The parameterized forms (`/rewind @<seq> chat|both`,
+ * `/rewind preview …`) stay internal channels the ↶ button and the popover
+ * drive through `session.command`.
  *
  * @module dsh-rewind/client
  */
@@ -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/client/locales.d.ts

@@ -25,7 +25,6 @@ export declare const zh: {
     'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
-    'guard.hint': string;
 };
 /** The rewind namespace key union. */
 export type RewindKey = keyof typeof zh;
@@ -61,5 +60,4 @@ export declare const en: {
     'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
-    'guard.hint': string;
 };

package/lib/types/index.d.ts

@@ -26,13 +26,17 @@
  */
 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. */
+/** Plugin config. */
 export interface RewindConfig {
-    /** Checkpoint store root (defaults to `~/.dsh/rewind-snapshots`). */
+    /** Checkpoint store root (exact path; beats `DSH_REWIND_SNAPSHOT_DIR` and the harness-home default). */
     readonly snapshotDir?: string;
+    /** Harness home override (`config.dshHome` > `$DSH_HOME` > `~/.dsh`); feeds the default snapshot/cleanup paths. */
+    readonly dshHome?: string;
+    /** In-place content dedup (identical before-content → link). Default `true`. */
+    readonly dedup?: boolean;
 }
 /**
  * Register the `/rewind` command and the checkpoint pipeline (before-capture
@@ -53,6 +57,7 @@ export interface RewindConfig {
  * disk at `tools/post-execute` under the turn's anchor message seq.
  *
  * @param ctx - context carrying `commands`, `tools`, and an optional `fs`.
- * @param config - optional override of the checkpoint store root.
+ * @param config - optional plugin config: `snapshotDir` (exact store-root override),
+ *  `dshHome` (harness-home override feeding the default paths), `dedup`.
  */
 export declare function apply(ctx: Context, config?: RewindConfig): void;

package/lib/types/locales.d.ts

@@ -49,6 +49,28 @@ 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.clearDry': string;
+    'cleanup.clearApply': string;
+    'cleanup.clearActive': string;
+    'cleanup.clearCancelled': string;
+    'cleanup.clearFailed': 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,145 @@
+/**
+ * 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 (highest first): the `DSH_SNAPSHOT_CLEANUP_CONFIG`
+ * env override, else `<harness home>/snapshot-cleanup.json` — derived from
+ * `dshHome` (config.dshHome > `$DSH_HOME` > `~/.dsh`) so the plugin follows the
+ * harness home instead of hardcoding `~/.dsh`.
+ */
+export declare function resolveCleanupConfigPath(dshHome?: string): 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(dshHome?: string): 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';
+/** A parsed `/snapshot-auto-cleanup` command (excludes the error branch). */
+export type CleanupCommand = {
+    action: 'status' | 'on' | 'off';
+} | {
+    action: 'max-age';
+    value: number;
+} | {
+    action: 'run';
+    target: 'rules' | 'current';
+    apply: boolean;
+};
+/**
+ * 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.
+ *
+ * The `run` verb is the single manual-cleanup action. `--apply` is the ONLY
+ * execute-vs-dry-run switch (position-independent): without it the action is a
+ * dry-run preview. `--current` re-targets the action to the ACTIVE session's
+ * snapshots (the manual "clear this session now"); without it, `run` keeps its
+ * age-based stale-session sweep semantics. The old `run-apply` abbreviation is
+ * gone — use `run --apply`.
+ */
+export declare function parseCleanupCommand(rawInput: string): CleanupCommand | {
+    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

@@ -20,6 +20,11 @@
  *   kept), and restores read/write the real file system with plain `node:fs`
  *   — independent of the fs service.
  *
+ * Security note: this `node:fs` authority is the DSH host authority every host
+ * plugin holds — the model-facing fences constrain the model's tools, not this
+ * code. The store stays bounded to the model-touched paths, so excluding a
+ * file (e.g. `.env`) is a model-permission concern (see `SECURITY.md`).
+ *
  * Crash safety (this module's own engineering asset):
  *  - Checkpoint commits are ATOMIC: the entry JSON is written to a sibling
  *    temp file and renamed over the target, so a host crash mid-write can
@@ -48,7 +53,12 @@
  *
  * @module dsh-rewind/snapshot
  */
-/** Default store root: the dsh data directory. */
+/**
+ * Default store root: `<harness home>/rewind-snapshots`. Resolved through
+ * {@link resolveDshHome} so the plugin follows `$DSH_HOME` (or a configured
+ * harness home) rather than hardcoding `~/.dsh` — matching the other
+ * first-party DSH packages. See `SECURITY.md` "Sensitive files".
+ */
 export declare const DEFAULT_SNAPSHOT_ROOT: string;
 /** Environment variable overriding the store root (tests, exotic homes). */
 export declare const SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
@@ -66,6 +76,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,12 +233,60 @@ 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;
+}
+/**
+ * Result of a manual whole-session clear ({@link SnapshotStore.clearSession}).
+ *
+ * Unlike the age-based sweep, a clear removes EVERY snapshot of ONE session
+ * (all anchor groups, all checkpoint entries, all restore journals) on demand —
+ * the active session the user is driving, to drop the rewind overhead or to
+ * archive a conversation immediately. `dryRun` reports what would be removed
+ * without touching disk or memory.
+ */
+export interface ClearSessionReport {
+    /** The session whose records were (or would be) cleared. */
+    readonly sessionId: string;
+    /** Number of anchor-group (user-message) directories present. */
+    readonly anchorGroups: number;
+    /** Number of committed checkpoint entries (full backups + dedup links). */
+    readonly entries: number;
+    /** Number of restore-journal files (terminal + pending). */
+    readonly journals: number;
+    /** Bytes occupied by the session directory (the amount freed). */
+    readonly bytes: number;
+    /** Whether nothing was really removed (the clear 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.
  */
 export declare class SnapshotStore {
-    readonly root: string;
     /** Debounce window for the per-commit prune (keeps the readdir+sort off the hot path). */
     private static readonly PRUNE_INTERVAL_MS;
     private lastPruneAt;
@@ -221,15 +303,59 @@ 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;
+    /** Resolved checkpoint store root (absolute); see the constructor's fallback. */
+    readonly root: string;
+    /**
+     * 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;
+        readonly dshHome?: string;
+    });
     /** 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 +363,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 +395,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 +510,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 +538,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
@@ -404,6 +572,49 @@ export declare class SnapshotStore {
      * entries so no extra persistence is needed.
      */
     trackedPaths(sessionId: string): Promise<Set<string>>;
+    /**
+     * Summarize a session's on-disk footprint for a clear dry-run: anchor-group
+     * count, committed checkpoint-entry count, restore-journal count, and total
+     * bytes. Walks with `lstat` (never follows a symlink, so a hostile symlink
+     * cannot escape the store root or inflate the measurement) and skips
+     * dot-prefixed temp leftovers and non-`.json` members — they are never
+     * checkpoint entries.
+     */
+    private sessionStats;
+    /**
+     * Remove a session's ENTIRE snapshot directory — every anchor group, every
+     * checkpoint entry, and every restore journal — and reset the store's
+     * in-memory dedup state so the session starts recording fresh from the
+     * current workspace state. This is the manual "get rid of this session's
+     * records NOW" action on the ACTIVE session the user is driving (it is never
+     * targetable by id; that is a directory-manipulation concern the user can do
+     * directly).
+     *
+     * SEMANTICS — clearing is an explicit abandonment: issuing the command means
+     * the user accepts that this session's snapshot archive goes away. It is
+     * therefore NOT gated on the state of any restore journal. A clear and a
+     * restore are both slash commands the host runs to completion for an agent,
+     * so they never interleave — any non-terminal journal present on disk is a
+     * stale orphan from a previous (crashed) process, and discarding it is the
+     * correct, safe resolution of that abandoned restore.
+     *
+     * SAFETY (this module's real concern is the plugin's ongoing BEHAVIOR, not
+     * losing snapshots):
+     *  - Only the session dir is removed; dedup refs are session-relative, so
+     *    there is no cross-session dangling to materialize (the same rationale as
+     *    {@link pruneStale}'s whole-dir removal).
+     *  - The in-memory dedup state (`lastEntry` / `seededSessions`) is ALWAYS
+     *    reset on an apply — even when the dir was already empty. A stale
+     *    in-memory entry (e.g. a session whose dir was removed out-of-band) would
+     *    otherwise link a later `recordEntry` to a deleted prior entry, leaving a
+     *    dangling ref that breaks restore resolution. This is the primary
+     *    correctness guarantee.
+     *
+     * `dryRun` computes the report without touching disk or memory.
+     */
+    clearSession(sessionId: string, opts?: {
+        readonly dryRun?: boolean;
+    }): Promise<ClearSessionReport>;
 }
 /**
  * Re-check every tracked file at a user-message boundary and record the
@@ -418,10 +629,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 +645,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.6.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": {
@@ -75,6 +78,7 @@
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.1.1-rc.2",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.6 || ^0.1.1-rc.2",
     "@deepseek-ai/dsh-fs": "^0.1.0-rc.6 || ^0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6 || ^0.1.1-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.1.1-rc.2",
     "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6 || ^0.1.1-rc.2",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-rc.2",
@@ -103,6 +107,9 @@
     "@deepseek-ai/dsh-fs": {
       "optional": true
     },
+    "@deepseek-ai/dsh-home-paths": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-llm": {
       "optional": true
     },
@@ -133,6 +140,7 @@
     "@deepseek-ai/dsh-compaction-basic": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-fs": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-goal": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-sandbox": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-session": "^0.1.1-rc.2",