dsh-rewind-plugin 0.5.0 → 0.6.0

package/lib/types/index.d.ts

@@ -29,10 +29,12 @@ export { SnapshotStore } 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;
 }
@@ -55,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

@@ -65,6 +65,11 @@ export declare const en: {
     '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. */

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

@@ -32,8 +32,13 @@ export declare const DEFAULT_MAX_AGE_DAYS = 30;
 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;
+/**
+ * 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";
 /**
@@ -41,7 +46,7 @@ export declare const STATE_FILENAME = "snapshot-cleanup-last-sweep.json";
  * 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;
+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
@@ -105,16 +110,31 @@ export declare function loadCleanupConfig(path: string): Promise<{
  */
 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';
+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): {
-    action: CleanupCommandAction;
-    value?: number;
-} | {
+export declare function parseCleanupCommand(rawInput: string): CleanupCommand | {
     error: string;
 };
 /**

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";
@@ -249,12 +259,34 @@ export interface PruneStaleReport {
     /** 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;
@@ -273,6 +305,8 @@ export declare class SnapshotStore {
     private lastEntryTime;
     /** 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`
@@ -285,6 +319,7 @@ export declare class SnapshotStore {
     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;
@@ -537,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.5.0",
+  "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",
@@ -78,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",
@@ -106,6 +107,9 @@
     "@deepseek-ai/dsh-fs": {
       "optional": true
     },
+    "@deepseek-ai/dsh-home-paths": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-llm": {
       "optional": true
     },
@@ -136,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",