dsh-rewind-plugin 0.6.2 → 0.7.0

package/lib/index.js

@@ -1,7 +1,8 @@
 // src/index.ts
 import { createAssistantMessage } from "@deepseek-ai/dsh-llm";
-import { unlink } from "node:fs/promises";
-import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { unlink as unlink2 } from "node:fs/promises";
+import * as dshSettings from "@deepseek-ai/dsh-settings";
+import "@deepseek-ai/schemastery";
 
 // src/locales.ts
 var en = {
@@ -33,11 +34,9 @@ var en = {
   "command.description": "Rewind the conversation back to an earlier user message (optionally restoring files)",
   "cleanup.description": "Manage automatic cleanup of session snapshot backups",
   "cleanup.inputHint": "on | off | max-age <days> | run [--apply] [--current]",
-  "cleanup.status": "Auto-cleanup: {state}. Max age: {days} day(s). Config: {path} ({present}).",
+  "cleanup.status": "Auto-cleanup: {state}. Max age: {days} day(s).",
   "cleanup.enabled": "enabled",
   "cleanup.disabled": "disabled",
-  "cleanup.present": "file present",
-  "cleanup.absent": "no file \u2014 defaults",
   "cleanup.onOk": "Auto-cleanup enabled.",
   "cleanup.offOk": "Auto-cleanup disabled \u2014 all snapshots kept.",
   "cleanup.maxAgeOk": "Auto-cleanup max age set to {days} day(s).",
@@ -83,11 +82,9 @@ var zh = {
   "command.description": "\u5728\u540C\u7A97\u53E3\u5185\u5C06\u5BF9\u8BDD\u56DE\u9000\u5230\u66F4\u65E9\u7684\u7528\u6237\u6D88\u606F\uFF08\u53EF\u540C\u65F6\u8FD8\u539F\u6587\u4EF6\uFF09",
   "cleanup.description": "\u7BA1\u7406\u4F1A\u8BDD\u5FEB\u7167\u5907\u4EFD\u7684\u81EA\u52A8\u6E05\u7406",
   "cleanup.inputHint": "on | off | max-age <\u5929\u6570> | run [--apply] [--current]",
-  "cleanup.status": "\u81EA\u52A8\u6E05\u7406\uFF1A{state}\u3002\u6700\u5927\u4FDD\u7559\u5929\u6570\uFF1A{days} \u5929\u3002\u914D\u7F6E\uFF1A{path}\uFF08{present}\uFF09\u3002",
+  "cleanup.status": "\u81EA\u52A8\u6E05\u7406\uFF1A{state}\u3002\u6700\u5927\u4FDD\u7559\u5929\u6570\uFF1A{days} \u5929\u3002",
   "cleanup.enabled": "\u5DF2\u5F00\u542F",
   "cleanup.disabled": "\u5DF2\u5173\u95ED",
-  "cleanup.present": "\u5B58\u5728\u914D\u7F6E\u6587\u4EF6",
-  "cleanup.absent": "\u65E0\u6587\u4EF6\u2014\u2014\u4F7F\u7528\u9ED8\u8BA4\u503C",
   "cleanup.onOk": "\u5DF2\u5F00\u542F\u81EA\u52A8\u6E05\u7406\u3002",
   "cleanup.offOk": "\u5DF2\u5173\u95ED\u81EA\u52A8\u6E05\u7406\u2014\u2014\u4FDD\u7559\u5168\u90E8\u5FEB\u7167\u3002",
   "cleanup.maxAgeOk": "\u5DF2\u5C06\u81EA\u52A8\u6E05\u7406\u7684\u6700\u5927\u4FDD\u7559\u5929\u6570\u8BBE\u4E3A {days} \u5929\u3002",
@@ -114,6 +111,12 @@ function translate(lang, key, params = {}) {
   return text;
 }
 
+// src/settings-locale.ts
+function readSettingsSection(provider, ns, brand) {
+  const key = brand?.(ns) ?? ns;
+  return provider.get(key);
+}
+
 // src/rewind.ts
 var RewindError = class extends Error {
   constructor(code, message) {
@@ -1325,16 +1328,49 @@ async function reconcileTracked(store, sessionId, anchorSeq, tracked, probe = de
 }
 
 // src/snapshot-cleanup.ts
-import { mkdir as mkdir2, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, readFile as readFile2, rename as rename2, unlink, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname2, join as join2 } from "node:path";
 import { resolveDshHome as resolveDshHome2 } from "@deepseek-ai/dsh-home-paths";
+import z from "@deepseek-ai/schemastery";
 var CLEANUP_CONFIG_FILENAME = "snapshot-cleanup.json";
-var CLEANUP_CONFIG_ENV = "DSH_SNAPSHOT_CLEANUP_CONFIG";
 var DEFAULT_MAX_AGE_DAYS = 30;
 var DEFAULT_CLEANUP_CONFIG = { enabled: false, maxAgeDays: DEFAULT_MAX_AGE_DAYS };
+var CLEANUP_SETTINGS_NAMESPACE = "dsh-rewind-snapshot-cleanup";
+var CleanupConfigSchema = z.object({
+  enabled: z.boolean().default(DEFAULT_CLEANUP_CONFIG.enabled),
+  maxAgeDays: z.number().step(1).min(1).default(DEFAULT_CLEANUP_CONFIG.maxAgeDays)
+});
+function settingsCleanupStore(scope) {
+  return {
+    load: () => scope.get(),
+    save: async (next) => {
+      const parsed = parseCleanupConfig({ enabled: next.enabled, maxAgeDays: next.maxAgeDays });
+      if (!parsed.ok) throw new RangeError(parsed.error);
+      await scope.update({ enabled: parsed.config.enabled, maxAgeDays: parsed.config.maxAgeDays });
+    }
+  };
+}
+async function migrateLegacyCleanupConfig(legacyPath, scope, log) {
+  const loaded = await loadCleanupConfig(legacyPath);
+  if (!loaded.ok) {
+    log(`[dsh-rewind] legacy snapshot-cleanup config invalid, migrating defaults and removing: ${loaded.error}`);
+    await scope.update({ enabled: false, maxAgeDays: DEFAULT_MAX_AGE_DAYS });
+    await unlink(legacyPath).catch(() => void 0);
+    return true;
+  }
+  if (!loaded.fromFile) return false;
+  if (loaded.config.enabled === DEFAULT_CLEANUP_CONFIG.enabled && loaded.config.maxAgeDays === DEFAULT_CLEANUP_CONFIG.maxAgeDays) {
+    await unlink(legacyPath).catch(() => void 0);
+    return true;
+  }
+  await scope.update({ enabled: loaded.config.enabled, maxAgeDays: loaded.config.maxAgeDays });
+  await unlink(legacyPath).catch(() => void 0);
+  log(`[dsh-rewind] migrated legacy snapshot-cleanup config (enabled=${String(loaded.config.enabled)}, maxAgeDays=${String(loaded.config.maxAgeDays)})`);
+  return true;
+}
 var AUTO_SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 function resolveCleanupConfigPath(dshHome) {
-  return process.env[CLEANUP_CONFIG_ENV] ?? join2(resolveDshHome2(dshHome), CLEANUP_CONFIG_FILENAME);
+  return join2(resolveDshHome2(dshHome), CLEANUP_CONFIG_FILENAME);
 }
 var STATE_FILENAME = "snapshot-cleanup-last-sweep.json";
 function resolveCleanupStatePath(dshHome) {
@@ -1357,7 +1393,7 @@ async function saveLastSweepAt(path, ms) {
 }
 async function runAutoCleanupCheck(deps, sessionId) {
   try {
-    const loaded = await loadCleanupConfig(deps.configPath);
+    const loaded = await deps.readConfig();
     if (!loaded.ok) {
       deps.log(`[dsh-rewind] snapshot cleanup config invalid; auto-cleanup skipped: ${loaded.error}`);
       return;
@@ -1410,15 +1446,6 @@ async function loadCleanupConfig(path) {
   if (!parsed.ok) return { ok: false, error: parsed.error };
   return { ok: true, config: parsed.config, fromFile: true };
 }
-async function saveCleanupConfig(path, config) {
-  if (typeof config.enabled !== "boolean" || !Number.isInteger(config.maxAgeDays) || config.maxAgeDays <= 0) {
-    throw new RangeError("invalid cleanup config: enabled must be a boolean and maxAgeDays a positive integer");
-  }
-  const tmp = `${path}.tmp`;
-  await mkdir2(dirname2(path), { recursive: true });
-  await writeFile2(tmp, JSON.stringify(config, null, 2), "utf8");
-  await rename2(tmp, path);
-}
 function parseCleanupCommand(rawInput) {
   const parts = rawInput.trim().split(/\s+/).filter(Boolean);
   if (parts.length === 0) return { action: "status" };
@@ -1465,6 +1492,7 @@ var inject = ["commands", "tools"];
 var TRACKED_TOOLS = /* @__PURE__ */ new Set(["write", "edit", "str_replace_editor"]);
 var MUTATING_EDITOR_COMMANDS = /* @__PURE__ */ new Set(["create", "str_replace", "insert"]);
 var activeLocale = "en";
+var cleanupStore;
 function t(key, params) {
   return translate(activeLocale, key, params);
 }
@@ -1694,7 +1722,7 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
     }
     let restore = "";
     if (mode === "both") {
-      const outcome = await store.restoreAfter(agent.session.id, plan.targetSeq, (path) => unlink(path));
+      const outcome = await store.restoreAfter(agent.session.id, plan.targetSeq, (path) => unlink2(path));
       await syncRestoreObservations(ctx, fs, agent, outcome);
       const parts = [];
       if (outcome.restored.length > 0) parts.push(t("restore.count", { count: outcome.restored.length }));
@@ -1772,11 +1800,21 @@ async function maybeRunAutoCleanup(ctx, store, sessionId, dshHome) {
   autoSweepChecked = true;
   await runAutoCleanupCheck({
     pruner: store,
-    configPath: resolveCleanupConfigPath(dshHome),
+    readConfig: () => readCleanupPolicy(),
     statePath: resolveCleanupStatePath(dshHome),
     log: (msg) => ctx.logger.warn(msg)
   }, sessionId);
 }
+async function readCleanupPolicy() {
+  if (cleanupStore === void 0) {
+    return { ok: false, error: "settings service unavailable; snapshot cleanup policy cannot be read" };
+  }
+  return { ok: true, config: cleanupStore.load() };
+}
+async function writeCleanupPolicy(next) {
+  if (cleanupStore === void 0) throw new Error("settings service unavailable; snapshot cleanup policy cannot be written");
+  await cleanupStore.save(next);
+}
 function formatCleanupReport(report) {
   const key = report.dryRun ? "cleanup.runDry" : "cleanup.runApply";
   const text = t(key, {
@@ -1791,37 +1829,34 @@ ${t("cleanup.skipped", { skipped: report.skippedActive })}` : text;
 async function handleSnapshotCleanup(store, invocation, dshHome, trackedBySession) {
   const parsed = parseCleanupCommand(invocation.rawInput);
   if ("error" in parsed) return { kind: "error", text: t("cleanup.usage") };
-  const configPath = resolveCleanupConfigPath(dshHome);
   switch (parsed.action) {
     case "status": {
-      const loaded = await loadCleanupConfig(configPath);
+      const loaded = await readCleanupPolicy();
       if (!loaded.ok) return { kind: "error", text: t("cleanup.cfgInvalid", { detail: loaded.error }) };
       return {
         kind: "success",
         text: t("cleanup.status", {
           state: t(loaded.config.enabled ? "cleanup.enabled" : "cleanup.disabled"),
-          days: loaded.config.maxAgeDays,
-          path: configPath,
-          present: t(loaded.fromFile ? "cleanup.present" : "cleanup.absent")
+          days: loaded.config.maxAgeDays
         })
       };
     }
     case "on":
     case "off": {
-      const loaded = await loadCleanupConfig(configPath);
+      const loaded = await readCleanupPolicy();
       const next = { ...loaded.ok ? loaded.config : DEFAULT_CLEANUP_CONFIG, enabled: parsed.action === "on" };
       try {
-        await saveCleanupConfig(configPath, next);
+        await writeCleanupPolicy(next);
       } catch (error) {
         return { kind: "error", text: t("cleanup.saveFailed", { detail: error instanceof Error ? error.message : String(error) }) };
       }
       return { kind: "success", text: t(parsed.action === "on" ? "cleanup.onOk" : "cleanup.offOk") };
     }
     case "max-age": {
-      const loaded = await loadCleanupConfig(configPath);
+      const loaded = await readCleanupPolicy();
       const next = { ...loaded.ok ? loaded.config : DEFAULT_CLEANUP_CONFIG, maxAgeDays: parsed.value };
       try {
-        await saveCleanupConfig(configPath, next);
+        await writeCleanupPolicy(next);
       } catch (error) {
         return { kind: "error", text: t("cleanup.saveFailed", { detail: error instanceof Error ? error.message : String(error) }) };
       }
@@ -1832,7 +1867,7 @@ async function handleSnapshotCleanup(store, invocation, dshHome, trackedBySessio
       if (parsed.target === "current") {
         return handleClearCurrent(store, invocation, apply2, trackedBySession);
       }
-      const loaded = await loadCleanupConfig(configPath);
+      const loaded = await readCleanupPolicy();
       if (!loaded.ok) return { kind: "error", text: t("cleanup.cfgInvalid", { detail: loaded.error }) };
       try {
         const report = await store.pruneStale({
@@ -1887,10 +1922,23 @@ function apply(ctx, config) {
   const trackedBySession = /* @__PURE__ */ new Map();
   let fsService;
   ctx.inject(["settings"], (settingsCtx) => {
-    const section = settingsCtx.settings.get(settingsNamespace("locale"));
+    const section = readSettingsSection(
+      settingsCtx.settings,
+      "locale",
+      dshSettings.settingsNamespace
+    );
     if (section?.preference === "zh" || section?.preference === "en") {
       activeLocale = section.preference;
     }
+    const cleanupScope = settingsCtx.settings.register(CLEANUP_SETTINGS_NAMESPACE, CleanupConfigSchema, { base: DEFAULT_CLEANUP_CONFIG });
+    cleanupStore = settingsCleanupStore(cleanupScope);
+    void migrateLegacyCleanupConfig(
+      resolveCleanupConfigPath(dshHome),
+      cleanupScope,
+      (msg) => ctx.logger.warn(msg)
+    ).catch((error) => {
+      ctx.logger.warn(`[dsh-rewind] snapshot cleanup migration failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
   });
   ctx.effect(function* () {
     const rewindHandler = (invocation) => handleRewind(ctx, store, fsService, invocation, inflight);

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

@@ -41,6 +41,16 @@ export declare function chatSnapshotOf(face: {
 } | undefined, chatView: {
     getSnapshot(): unknown;
 } | undefined): HiddenChat | undefined;
+/**
+ * The plain text of the human message at `seq` in the chat snapshot, for
+ * filling the composer after a withdraw. Accepts BOTH `user` and `steering`
+ * nodes: a plan-mode (`/plan <text>`) input is delivered through the agent
+ * inbox next-step and claimed, so it renders as `steering`, and its text must
+ * still return to the composer (`portals.tsx` `runRewindAndFill`) — the old
+ * `user`-only read silently left it empty. State absent → undefined; a message
+ * with no text blocks → ''. Same text-blocks join the candidate side uses.
+ */
+export declare function messageTextAt(chat: HiddenChat | undefined, seq: number): string | 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

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

@@ -25,6 +25,23 @@ export declare const zh: {
     'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
+    'cleanup.title': string;
+    'cleanup.desc': string;
+    'cleanup.expand': string;
+    'cleanup.collapse': string;
+    'cleanup.unsaved': string;
+    'cleanup.auto': string;
+    'cleanup.auto.on': string;
+    'cleanup.auto.off': string;
+    'cleanup.maxAge': string;
+    'cleanup.maxAge.hint': string;
+    'cleanup.invalid': string;
+    'cleanup.discard': string;
+    'cleanup.save': string;
+    'cleanup.saving': string;
+    'cleanup.saved': string;
+    'cleanup.saveFailed': string;
+    'cleanup.readonly': string;
 };
 /** The rewind namespace key union. */
 export type RewindKey = keyof typeof zh;
@@ -60,4 +77,21 @@ export declare const en: {
     'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
+    'cleanup.title': string;
+    'cleanup.desc': string;
+    'cleanup.expand': string;
+    'cleanup.collapse': string;
+    'cleanup.unsaved': string;
+    'cleanup.auto': string;
+    'cleanup.auto.on': string;
+    'cleanup.auto.off': string;
+    'cleanup.maxAge': string;
+    'cleanup.maxAge.hint': string;
+    'cleanup.invalid': string;
+    'cleanup.discard': string;
+    'cleanup.save': string;
+    'cleanup.saving': string;
+    'cleanup.saved': string;
+    'cleanup.saveFailed': string;
+    'cleanup.readonly': string;
 };

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

@@ -72,14 +72,16 @@ export interface RewindBridgeDeps {
 /** Structural face of the runtime slot service (see the module doc). */
 export interface SlotsLike {
     inject(key: string, install: () => () => void): () => void;
-    register(entry: {
+    register<P>(entry: {
         readonly name: string;
-        readonly id: string;
-        readonly order: number;
-    }, component: (props: {
-        readonly sessionId: string;
-    }) => ReactNode): () => void;
+        readonly id?: string;
+        readonly order?: number;
+        readonly key?: string;
+        readonly locale?: string;
+        readonly inject?: () => P;
+    }, component: (props: P) => ReactNode): () => void;
 }
+/** Join the text blocks of a user message into one plain preview. */
 /**
  * The alpha.1+ session input facade's write face (structural, so the plugin
  * never imports the conversation UI package). `setDraft` replaces the whole

package/lib/types/client/settings-card.d.ts

@@ -0,0 +1,76 @@
+/**
+ * dsh-rewind client settings card: the "Snapshot cleanup" module under
+ * Settings > Plugins > Plugin configuration, drawn as one `settings.plugin.item`
+ * card (keyed by the host-registered settings namespace).
+ *
+ * The card edits exactly two knobs — `enabled` (auto-cleanup switch) and
+ * `maxAgeDays` (idle cutoff, a positive integer) — and stages them exactly like
+ * the host-side /snapshot-auto-cleanup command does, so the GUI and the command
+ * can never disagree. The switch collapses/expands the max-age editor; a
+ * non-positive/non-integer draft blocks save (the same single validator the
+ * host schema enforces). "Discard changes" restores the last-read baseline.
+ *
+ * It neither imports the client settings typed contract nor depends on the
+ * alpha-only `mutate` write API: it reads `getSnapshot().value` and writes via
+ * the `set(field, value)` method present on both rc.2 and alpha, and the card
+ * receives a tiny structural `CleanupCardApi` supplied by `src/client/index.ts`
+ * so the component stays harness-agnostic and unit-testable in isolation.
+ *
+ * @module dsh-rewind/client/settings-card
+ */
+/**
+ * The dsh-settings namespace the card binds to. Duplicated here (not imported
+ * from the host module) because the client build must stay free of host/node
+ * imports; a cross-config test pins it equal to the host's constant. The
+ * settings grammar forbids dots, so this is hyphenated.
+ */
+export declare const CLEANUP_SETTINGS_NAMESPACE = "dsh-rewind-snapshot-cleanup";
+/** The defaults the host uses; shown as the field placeholder until a draft. */
+export declare const DEFAULT_MAX_AGE_DAYS = 30;
+/** The two editable knobs, exactly as the host policy exposes them. */
+export interface CleanupPolicy {
+    readonly enabled: boolean;
+    readonly maxAgeDays: number;
+}
+/** A staged draft: the switch state and the raw (unparsed) max-age text. */
+export interface CleanupDraft {
+    readonly enabled: boolean;
+    readonly maxAgeDays: string;
+}
+/** The structural api the card reads/saves through (supplied by the client). */
+export interface CleanupCardApi {
+    /** Read the resolved policy; `undefined` while the describe mirror loads. */
+    read(): CleanupPolicy | undefined;
+    /** Whether the settings source accepts writes (false = read-only card). */
+    writable(): boolean;
+    /** Persist a validated policy; rejects on failure. */
+    save(next: CleanupPolicy): Promise<void>;
+    /** Optional change subscription (returns the disposer). */
+    subscribe(cb: () => void): () => void;
+}
+/** Translate one client dictionary key (the card's `t`). */
+export type CardTranslate = (key: string, params?: Record<string, string | number>) => string;
+/** Load a draft from a policy (defaults when the view has not loaded). */
+export declare function draftFrom(policy: CleanupPolicy | undefined): CleanupDraft;
+/** Parse the max-age text: a strict positive integer, else `null`. */
+export declare function maxAgeOf(text: string): number | null;
+/**
+ * The policy a draft resolves to, or `null` when the max-age draft is invalid
+ * (which blocks save). `enabled` is always a boolean from the switch, and
+ * `maxAgeDays` comes from the validated draft.
+ */
+export declare function configOf(draft: CleanupDraft): CleanupPolicy | null;
+/** True when the draft differs from the baseline (an unsaved edit). */
+export declare function dirtyOf(base: CleanupDraft, draft: CleanupDraft): boolean;
+/**
+ * The card body. Draws the switch (+ collapse), the max-age editor, and the
+ * discard/save actions. Pure of host wiring: everything goes through the
+ * supplied {@link CleanupCardApi}.
+ * @param api - the read/write transport.
+ * @param t - the client dictionary translator.
+ * @returns the card element.
+ */
+export declare function SettingsCleanupCard({ api, t }: {
+    api: CleanupCardApi;
+    t: CardTranslate;
+}): import("react").JSX.Element;

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

@@ -23,4 +23,4 @@ export declare const CLASS: {
 /** The ↶ glyph, drawn inline so the bundle stays dependency-free. */
 export declare const REWIND_ICON_SVG: string;
 /** One injected stylesheet (scoped under `.dsh-rewind-*`). */
-export declare const STYLE = "\n.dsh-rewind-btn {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  padding: 6px;\n  border: none;\n  border-radius: 28px;\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n.dsh-rewind-btn:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-secondary);\n}\n\n.dsh-rewind-popover {\n  position: fixed;\n  z-index: 1000;\n  width: 288px;\n  padding: 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 12px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 14px;\n  line-height: 20px;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-popover-title {\n  font-size: 14px;\n  font-weight: 600;\n  line-height: 20px;\n}\n.dsh-rewind-popover-target {\n  margin: 4px 0 10px;\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n  word-break: break-all;\n}\n.dsh-rewind-popover-option {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  width: 100%;\n  margin: 0 0 6px;\n  padding: 8px 10px;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  text-align: left;\n  cursor: pointer;\n}\n.dsh-rewind-popover-option:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n.dsh-rewind-popover-option:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-option-label {\n  font-weight: 500;\n}\n.dsh-rewind-popover-option-hint {\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-popover-impact {\n  margin: 4px 0 10px;\n  padding: 8px 10px;\n  border-radius: 8px;\n  background: var(--dsw-alias-interactive-bg-hover);\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-secondary);\n  white-space: pre-wrap;\n  max-height: 160px;\n  overflow: auto;\n}\n.dsh-rewind-popover-actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n}\n.dsh-rewind-popover-primary,\n.dsh-rewind-popover-ghost {\n  padding: 5px 12px;\n  border: none;\n  border-radius: 8px;\n  font: inherit;\n  font-size: 13px;\n  line-height: 18px;\n  cursor: pointer;\n}\n.dsh-rewind-popover-primary {\n  background: var(--dsw-alias-button-primary-fill);\n  color: var(--dsw-alias-label-primary-foreground);\n}\n.dsh-rewind-popover-primary:hover:not(:disabled) {\n  background: var(--dsw-alias-button-primary-hover);\n}\n.dsh-rewind-popover-primary:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-ghost {\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n}\n.dsh-rewind-popover-ghost:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n.dsh-rewind-guard-hint {\n  position: fixed;\n  z-index: 1000;\n  max-width: min(440px, calc(100vw - 24px));\n  padding: 8px 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 10px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 13px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n  pointer-events: none;\n}\n";
+export declare const STYLE = "\n.dsh-rewind-btn {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  padding: 6px;\n  border: none;\n  border-radius: 28px;\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n.dsh-rewind-btn:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-secondary);\n}\n\n.dsh-rewind-popover {\n  position: fixed;\n  z-index: 1000;\n  width: 288px;\n  padding: 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 12px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 14px;\n  line-height: 20px;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-popover-title {\n  font-size: 14px;\n  font-weight: 600;\n  line-height: 20px;\n}\n.dsh-rewind-popover-target {\n  margin: 4px 0 10px;\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n  word-break: break-all;\n}\n.dsh-rewind-popover-option {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  width: 100%;\n  margin: 0 0 6px;\n  padding: 8px 10px;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  text-align: left;\n  cursor: pointer;\n}\n.dsh-rewind-popover-option:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n.dsh-rewind-popover-option:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-option-label {\n  font-weight: 500;\n}\n.dsh-rewind-popover-option-hint {\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-popover-impact {\n  margin: 4px 0 10px;\n  padding: 8px 10px;\n  border-radius: 8px;\n  background: var(--dsw-alias-interactive-bg-hover);\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-secondary);\n  white-space: pre-wrap;\n  max-height: 160px;\n  overflow: auto;\n}\n.dsh-rewind-popover-actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n}\n.dsh-rewind-popover-primary,\n.dsh-rewind-popover-ghost {\n  padding: 5px 12px;\n  border: none;\n  border-radius: 8px;\n  font: inherit;\n  font-size: 13px;\n  line-height: 18px;\n  cursor: pointer;\n}\n.dsh-rewind-popover-primary {\n  background: var(--dsw-alias-button-primary-fill);\n  color: var(--dsw-alias-label-primary-foreground);\n}\n.dsh-rewind-popover-primary:hover:not(:disabled) {\n  background: var(--dsw-alias-button-primary-hover);\n}\n.dsh-rewind-popover-primary:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-ghost {\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n}\n.dsh-rewind-popover-ghost:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n.dsh-rewind-guard-hint {\n  position: fixed;\n  z-index: 1000;\n  max-width: min(440px, calc(100vw - 24px));\n  padding: 8px 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 10px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 13px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n  pointer-events: none;\n}\n\n/* ---- Snapshot-cleanup settings card (mirrors the harness PluginCard look) ---- */\n.dsh-rewind-cleanup-card {\n  list-style: none;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 12px;\n  background: var(--dsw-alias-bg-layer-3);\n  transition: border-color .16s, background .16s;\n}\n.dsh-rewind-cleanup-card:hover {\n  border-color: var(--dsw-alias-label-dimmed);\n}\n.dsh-rewind-cleanup-card-open {\n  background: var(--dsw-alias-bg-layer-2);\n  border-color: var(--dsw-alias-label-dimmed);\n}\n.dsh-rewind-cleanup-header {\n  width: 100%;\n  appearance: none;\n  border: 0;\n  background: none;\n  font: inherit;\n  color: inherit;\n  text-align: left;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 14px 16px;\n  border-radius: 12px;\n}\n.dsh-rewind-cleanup-header:focus-visible {\n  outline: 2px solid var(--dsw-alias-brand-primary);\n  outline-offset: -2px;\n}\n.dsh-rewind-cleanup-head-text {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n}\n.dsh-rewind-cleanup-name {\n  font-size: 15px;\n  font-weight: 600;\n  line-height: 1.4;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-cleanup-desc {\n  font-size: 13px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-cleanup-chevron {\n  flex: none;\n  color: var(--dsw-alias-label-tertiary);\n  transition: transform .16s;\n}\n.dsh-rewind-cleanup-chevron-open {\n  transform: rotate(180deg);\n}\n.dsh-rewind-cleanup-pending {\n  flex: none;\n  border-radius: 999px;\n  padding: 1px 8px;\n  font-size: 11px;\n  line-height: 17px;\n  font-weight: 500;\n  white-space: nowrap;\n  background: var(--dsw-alias-bg-module-platform);\n  color: var(--dsw-alias-label-secondary);\n}\n.dsh-rewind-cleanup-body {\n  border-top: 1px solid var(--dsw-alias-border-l2);\n  margin: 0 16px;\n  padding: 4px 0 8px;\n}\n.dsh-rewind-cleanup-readonly {\n  margin: 12px 0 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-cleanup-permission {\n  display: grid;\n  gap: 6px;\n  padding: 12px 0;\n}\n.dsh-rewind-cleanup-field {\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n  padding: 12px 0;\n}\n.dsh-rewind-cleanup-field + .dsh-rewind-cleanup-field {\n  border-top: 1px solid var(--dsw-alias-border-l2);\n}\n.dsh-rewind-cleanup-head {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n}\n.dsh-rewind-cleanup-label {\n  flex: 1;\n  min-width: 0;\n  font-size: 13px;\n  font-weight: 500;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-cleanup-hint {\n  margin: 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-cleanup-error {\n  margin: 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-error);\n}\n/* Switch row: label left, role=switch button right, hint below (Subagent module). */\n.dsh-rewind-cleanup-toggle-row {\n  display: flex;\n  align-items: flex-start;\n  justify-content: space-between;\n  gap: 16px;\n  font-size: 13px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-cleanup-toggle-label {\n  flex: 1;\n  min-width: 0;\n}\n.dsh-rewind-cleanup-switch {\n  box-sizing: border-box;\n  position: relative;\n  flex: 0 0 auto;\n  width: 36px;\n  height: 20px;\n  padding: 2px;\n  border: 0;\n  border-radius: 10px;\n  background: var(--dsw-alias-border-l3);\n  cursor: pointer;\n}\n.dsh-rewind-cleanup-switch-on {\n  background: var(--dsw-alias-brand-primary);\n}\n.dsh-rewind-cleanup-switch:disabled {\n  cursor: default;\n  opacity: 0.5;\n}\n.dsh-rewind-cleanup-switch:focus-visible {\n  outline: 2px solid var(--dsw-alias-brand-primary);\n  outline-offset: 2px;\n}\n.dsh-rewind-cleanup-thumb {\n  display: block;\n  width: 16px;\n  height: 16px;\n  border-radius: 50%;\n  background: var(--dsw-alias-label-primary-foreground);\n  transition: transform 120ms ease;\n}\n.dsh-rewind-cleanup-switch-on .dsh-rewind-cleanup-thumb {\n  transform: translateX(16px);\n}\n.dsh-rewind-cleanup-input {\n  box-sizing: border-box;\n  height: 34px;\n  padding: 0 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 8px;\n  background: var(--dsw-alias-bg-layer-3);\n  font: inherit;\n  font-size: 13px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-cleanup-input:focus-visible {\n  outline: none;\n  border-color: var(--dsw-alias-brand-primary);\n}\n.dsh-rewind-cleanup-input:disabled {\n  color: var(--dsw-alias-label-tertiary);\n  cursor: default;\n}\n.dsh-rewind-cleanup-input-invalid {\n  border-color: var(--dsw-alias-label-error);\n}\n.dsh-rewind-cleanup-footer {\n  display: flex;\n  align-items: center;\n  justify-content: flex-end;\n  gap: 8px;\n  padding: 12px 0 4px;\n  border-top: 1px solid var(--dsw-alias-border-l2);\n}\n.dsh-rewind-cleanup-failed {\n  flex: 1;\n  min-width: 0;\n  margin: 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-error);\n}\n.dsh-rewind-cleanup-discard,\n.dsh-rewind-cleanup-save {\n  appearance: none;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  padding: 5px 14px;\n  font: inherit;\n  font-size: 13px;\n  line-height: 1.5;\n  cursor: pointer;\n}\n.dsh-rewind-cleanup-discard {\n  border-color: var(--dsw-alias-border-l2);\n  background: none;\n  color: var(--dsw-alias-label-secondary);\n}\n.dsh-rewind-cleanup-discard:hover:not(:disabled) {\n  color: var(--dsw-alias-label-primary);\n  border-color: var(--dsw-alias-label-dimmed);\n}\n.dsh-rewind-cleanup-save {\n  background: var(--dsw-alias-label-primary);\n  color: var(--dsw-alias-bg-layer-3);\n}\n.dsh-rewind-cleanup-discard:disabled,\n.dsh-rewind-cleanup-save:disabled {\n  opacity: 0.4;\n  cursor: default;\n}\n.dsh-rewind-cleanup-discard:focus-visible,\n.dsh-rewind-cleanup-save:focus-visible {\n  outline: 2px solid var(--dsw-alias-brand-primary);\n  outline-offset: 1px;\n}\n";

package/lib/types/locales.d.ts

@@ -54,8 +54,6 @@ export declare const en: {
     'cleanup.status': string;
     'cleanup.enabled': string;
     'cleanup.disabled': string;
-    'cleanup.present': string;
-    'cleanup.absent': string;
     'cleanup.onOk': string;
     'cleanup.offOk': string;
     'cleanup.maxAgeOk': string;

package/lib/types/settings-locale.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Version-neutral settings-namespace reading for the host half.
+ *
+ * DSH rc.2 exposes a `settingsNamespace(value)` brand helper, and `settings.get`
+ * is typed to require a branded `SettingsNamespace`. DSH 0.1.2-alpha.2 removed
+ * that helper (the `SettingsNamespace` *type* remains) and `settings.get`
+ * accepts the raw namespace string. This module collapses both into one runtime
+ * call: on rc.2 the brand is a compile-time marker erased at runtime (so
+ * `settingsNamespace(ns)` returns `ns`), on 0.1.2-alpha.2 the brand helper is
+ * absent and the raw `ns` string is used directly. That is what lets a single
+ * compiled host bundle link and run on both harness generations.
+ *
+ * @module dsh-rewind/settings-locale
+ */
+/** Minimal structural face of the settings provider the host reads from. */
+export interface SettingsProviderLike {
+    /**
+     * Read one registered settings section by namespace. Accepts whatever the
+     * running DSH generation passes: a branded `SettingsNamespace` (rc.2, brand
+     * erased) or the raw namespace string (0.1.2-alpha.2).
+     */
+    get(ns: string): unknown;
+}
+/** The `settingsNamespace(ns)` brand helper, or `undefined` when removed (0.1.2-alpha.2). */
+export type SettingsNamespaceBrand = ((value: string) => string) | undefined;
+/**
+ * Read one settings section keyed by `ns`, tolerant of the settings-namespace
+ * brand across DSH generations. Pass the brand helper when available (the rc.2
+ * path); it is `undefined` on 0.1.2-alpha.2, where the raw `ns` string is used
+ * directly. Never throws: an absent section simply returns `undefined`.
+ */
+export declare function readSettingsSection(provider: SettingsProviderLike, ns: string, brand: SettingsNamespaceBrand): unknown;

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

@@ -18,25 +18,79 @@
  *
  * @module dsh-rewind/snapshot-cleanup
  */
+import z from '@deepseek-ai/schemastery';
 /** 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;
+/**
+ * The dsh-settings namespace that backs the cleanup policy after migration.
+ * Namespaces must match the settings provider's `^[a-z][a-z0-9-]*$` grammar (no
+ * dots), so this is hyphenated, not dotted.
+ */
+export declare const CLEANUP_SETTINGS_NAMESPACE = "dsh-rewind-snapshot-cleanup";
+/**
+ * The schemastery schema that persists + validates the cleanup policy in the
+ * dsh-settings document. This is the SINGLE storage validator: the `maxAgeDays`
+ * rule is enforced by `.step(1).min(1)` (positive integer) and the defaults by
+ * `.default(...)`, so the resolved value is always a valid {@link CleanupConfig}
+ * and a bad stored/user value cannot steer the sweep into deleting everything.
+ */
+export declare const CleanupConfigSchema: z<CleanupConfig>;
+/**
+ * Structural face of the settings scope the host needs for the policy: a
+ * resolved read and a validated write. Kept local (never imports the settings
+ * contract) so the host bundle links on both rc.2 and alpha — the settings
+ * API drift (alpha adds `mutate`, rd2 does not) is confined to the seam the
+ * host passes in, never to this module.
+ */
+export interface CleanupSettingsScope {
+    /** The resolved policy: schema defaults, then base, then the user layer. */
+    get(): CleanupConfig;
+    /** Merge a partial patch into the user layer (validated by the schema). */
+    update(patch: {
+        enabled?: boolean;
+        maxAgeDays?: number;
+    }): Promise<void>;
+}
+/** A validated policy read/write port the command + auto-sweep use. */
+export interface CleanupConfigStore {
+    /** The resolved policy (always schema-valid, fail-closes when unavailable). */
+    load(): CleanupConfig;
+    /** Persist a validated policy, throwing when invalid or unavailable. */
+    save(next: CleanupConfig): Promise<void>;
+}
+/**
+ * Adapter that turns a {@link CleanupSettingsScope} into a
+ * {@link CleanupConfigStore}. Reads come straight from the resolved scope; a
+ * write validates via `parseCleanupConfig` before touching the scope, so a bad
+ * value can never reach the document (defense-in-depth below the schema).
+ */
+export declare function settingsCleanupStore(scope: CleanupSettingsScope): CleanupConfigStore;
+/**
+ * One-time migration of the pre-GUI cleanup policy file into the settings
+ * document. Idempotent and cheap: it is called on every startup but only does
+ * work once — a present-and-parsed legacy file is written into the scope and
+ * then deleted, after which the read is an ENOENT no-op. A missing file is a
+ * no-op; an invalid file writes the safe default (deleting nothing) and logs.
+ * This is the ONLY consumption of {@link loadCleanupConfig} after migration.
+ * @returns whether a legacy file was actually migrated.
+ */
+export declare function migrateLegacyCleanupConfig(legacyPath: string, scope: CleanupSettingsScope, log: (msg: string) => void): Promise<boolean>;
 /** 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`.
+ * Resolve the LEGACY pre-migration config file path (the only remaining use of
+ * the file store): `<harness home>/snapshot-cleanup.json`, derived from
+ * `dshHome` (config.dshHome > `$DSH_HOME` > `~/.dsh`) so the migration follows
+ * the harness home instead of hardcoding `~/.dsh`. The `DSH_SNAPSHOT_CLEANUP_CONFIG`
+ * env override was removed when the policy moved into the dsh-settings document.
  */
 export declare function resolveCleanupConfigPath(dshHome?: string): string;
 /** The state file that records the last automatic-sweep wall-clock time. */
@@ -74,7 +128,13 @@ export interface AutoCleanupPruner {
  */
 export declare function runAutoCleanupCheck(deps: {
     pruner: AutoCleanupPruner;
-    configPath: string;
+    readConfig: () => Promise<{
+        ok: true;
+        config: CleanupConfig;
+    } | {
+        ok: false;
+        error: string;
+    }>;
     statePath: string;
     log: (msg: string) => void;
 }, sessionId: string | undefined): Promise<void>;