dsh-rewind-plugin 0.6.3 → 0.7.1

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 { 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,14 @@ function translate(lang, key, params = {}) {
   return text;
 }
 
+// src/session-events.ts
+function eventsOf(session) {
+  const s = session;
+  if (s.snapshotEvents !== void 0) return s.snapshotEvents();
+  if (s.events !== void 0) return s.events;
+  return [];
+}
+
 // src/settings-locale.ts
 function readSettingsSection(provider, ns, brand) {
   const key = brand?.(ns) ?? ns;
@@ -1331,16 +1336,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) {
@@ -1363,7 +1401,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;
@@ -1416,15 +1454,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" };
@@ -1471,6 +1500,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);
 }
@@ -1494,7 +1524,7 @@ function mutationPathOf(exec) {
   return void 0;
 }
 function anchorSeqOf(session, cache) {
-  const events = session.events;
+  const events = eventsOf(session);
   const cached = cache.get(session);
   if (cached !== void 0 && cached.eventsLength === events.length) return cached.anchor;
   let anchor = cached?.anchor;
@@ -1672,15 +1702,15 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
     }
     let plan;
     try {
-      plan = resolveOrError(agent.session.events, agent.session.surface.nodes, rawTarget);
+      plan = resolveOrError(eventsOf(agent.session), agent.session.surface.nodes, rawTarget);
     } catch (error) {
       return rewindErrorResult(error);
     }
     const marker = buildMarker();
     let event;
     try {
-      const turn = markerTurnOf(agent.session.events);
-      const step = markerStepOf(agent.session.events, turn);
+      const turn = markerTurnOf(eventsOf(agent.session));
+      const step = markerStepOf(eventsOf(agent.session), turn);
       agent.session.append("step/start", { turn, step });
       try {
         event = agent.session.append("assistant/message", { turn, step, message: marker }, {
@@ -1700,7 +1730,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 }));
@@ -1734,7 +1764,7 @@ async function handleRewind(ctx, store, fs, invocation, inflight) {
   const session = invocation.agent.session;
   const input = invocation.rawInput.trim();
   if (input === "") {
-    const candidates = listRewindCandidates(session.events, session.surface.nodes, 1);
+    const candidates = listRewindCandidates(eventsOf(session), session.surface.nodes, 1);
     if (candidates.length === 0) {
       return { kind: "error", text: t("noUserMessages") };
     }
@@ -1746,7 +1776,7 @@ async function handleRewind(ctx, store, fs, invocation, inflight) {
     if (target2 === void 0) return { kind: "error", text: usage() };
     let plan;
     try {
-      plan = resolveOrError(session.events, session.surface.nodes, target2);
+      plan = resolveOrError(eventsOf(session), session.surface.nodes, target2);
     } catch (error) {
       return rewindErrorResult(error);
     }
@@ -1754,7 +1784,7 @@ async function handleRewind(ctx, store, fs, invocation, inflight) {
     return { kind: "success", text: formatPlan(plan, impacts) };
   }
   if (parts[0] === "__candidates") {
-    const candidates = listRewindCandidates(session.events, session.surface.nodes);
+    const candidates = listRewindCandidates(eventsOf(session), session.surface.nodes);
     return { kind: "success", text: formatCandidateList(candidates) };
   }
   const target = parts[0];
@@ -1778,11 +1808,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, {
@@ -1797,37 +1837,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) }) };
       }
@@ -1838,7 +1875,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({
@@ -1901,6 +1938,15 @@ function apply(ctx, config) {
     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/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,13 +72,14 @@ 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. */
 /**
@@ -124,6 +125,28 @@ export declare function writeComposer(text: string, facade: ComposerDraftWriter
  * after switching sessions or restarting dsh.
  */
 export declare function runRewindAndFill(session: SessionFace, seq: number, mode: 'chat' | 'both', currentSessionId: () => string | undefined, chatOf: ChatOf, setComposerText: (sessionId: string, text: string) => boolean): Promise<void>;
+/**
+ * Locate the actions container of a user/steering seat row — the element the
+ * ↶ button portals into (the copy/branch IconActions row).
+ *
+ * Dual channel:
+ * - rc.2 (0.1.1-rc.2) / alpha.2+ (0.1.2-alpha.2): the hover-reveal root is
+ *   attribute-marked (`[data-time-hover-root]` ≤ rc.x, `[data-actions-reveal]`
+ *   alpha.2+) and mounts the actions row as its LAST child. A pending row IS
+ *   that root; a durable row CONTAINS it as a descendant.
+ * - alpha.4 (0.1.2-alpha.4): the marker was removed from user rows (it now
+ *   lives only on the per-turn tail footer, `TurnTailNodeView`), and the user
+ *   action row is revealed via CSS `:has()`. The container is instead located
+ *   structurally: the direct holder of the copy `<button>` (the
+ *   `MessageIconActions` container, which mounts that button as a direct
+ *   child — `MessageIconActions.tsx:83,86`).
+ *
+ * Returns undefined when no qualifying container is found; the caller refuses
+ * to portal (never a crash, never a wrong attachment). Exported as a test seam
+ * (see `collectTargets`) so the dual-channel finder is exercised directly for
+ * both durable and pending row shapes without a full React portal render.
+ */
+export declare function actionsContainerOf(row: HTMLElement | undefined): HTMLElement | undefined;
 /**
  * Collect the portal targets of one session: user rows × snapshot nodes.
  * Exported as a test seam — the DOM→targets pairing that drives the ↶ button

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  corner-shape: round;\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/session-events.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cross-channel session event-log reader.
+ *
+ * Harness 0.1.1-rc.2 exposes the full log as `Session.events`
+ * (`get events(): readonly SessionEvent[]`), while 0.1.2-alpha.4 removed that
+ * member and replaced it with the on-demand APIs `snapshotEvents(from?, to?)`
+ * (half-open range, internally cached), `eventAt(seq)`, `ownEvents()` and
+ * `seq`. This module reads the full log through whichever channel the host
+ * exposes, so the plugin keeps one code path across both.
+ *
+ * `snapshotEvents()` is deliberately preferred over `ownEvents()`:
+ * `snapshotEvents()` defaults to the whole log (including any fork-inherited
+ * prefix), which is exactly what `Session.events` returned on rc.2 — the
+ * rewind semantics are preserved for fork-seeded sessions. `ownEvents()`
+ * would drop the inherited prefix and change behaviour.
+ *
+ * @module dsh-rewind/session-events
+ */
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+/**
+ * Read the full event log of a session, transparently across harness channels:
+ * - 0.1.1-rc.2 (`Session.events`): the live immutable log array.
+ * - 0.1.2-alpha.4 (`Session.snapshotEvents()`): a deep-frozen snapshot, cached
+ *   by the session until the next append.
+ *
+ * Falls back to an empty log when the session exposes neither member (a future
+ * harness shape) rather than throwing — callers already treat the empty log as
+ * "no candidates".
+ *
+ * @param session - the session to read.
+ * @returns the full event log in log order (the same shape rc.2's `events`
+ *   returned, so existing consumers are unchanged).
+ */
+export declare function eventsOf(session: Session): readonly SessionEvent[];

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>;