dsh-rewind-plugin 0.20.0 → 0.21.1

package/lib/types/client/rewind-flow.d.ts

@@ -0,0 +1,86 @@
+/**
+ * dsh-rewind flow half: the executed rewind command and its composer refill.
+ *
+ * This is the BEHAVIOR layer, deliberately free of any mounting decision. Both
+ * the `/rewind` text flow (command decoration → mode popover) and, in A2, the
+ * per-message action call {@link runRewindAndFill}; nothing here portals,
+ * observes rows, or knows where the trigger sits.
+ *
+ * The refill is event-driven: it runs only when THIS page performed the
+ * rewind (the user confirmed moments ago). It must NEVER scan loaded history
+ * for rewind commands — a session window opens with only the tail page, so
+ * "a command already in the snapshot" cannot be told apart from "executed in
+ * this page", and the old baseline heuristic refilled withdrawn text into the
+ * composer after switching sessions or restarting dsh.
+ *
+ * @module dsh-rewind/client/rewind-flow
+ */
+import type { SessionFace } from '@deepseek-ai/dsh-api-session-controller/client';
+import { type ChatOf, type ChatWatch, type MessageImageRef } from './hidden.ts';
+/**
+ * The session input facade's write face (structural, so the plugin
+ * never imports the conversation UI package). `setDraft` replaces the whole
+ * composer draft through the harness's own Lexical editor — the correct way
+ * to restore the withdrawn text.
+ */
+interface ComposerDraftWriter {
+    setDraft(text: string): void;
+    /**
+     * Return the keyboard to the composer with the caret it last held (the
+     * facade's own `focus`). Optional so the DOM fallback and older faces still
+     * restore the text.
+     */
+    focus?(): void;
+}
+/**
+ * Fill the dsh composer with `text` through the `contenteditable`
+ * DOM path. Used by `setComposerText` (the harness-facade-aware writer) as the
+ * last-resort and by `runRewindAndFill` to put the withdrawn target message
+ * back into the composer after a rewind. Best-effort — no composer match means
+ * false, never a throw.
+ */
+export declare function fillComposer(text: string): boolean;
+/**
+ * Composer write: prefer the harness facade's `setDraft` (correct whole-draft
+ * replace), then degrade to the DOM `fillComposer` (contenteditable). A facade
+ * that throws (session teardown) is treated as absent so the DOM path still
+ * restores the text. Never throws.
+ * @param text - the withdrawn target message text.
+ * @param facade - the session input draft writer, when reachable.
+ * @returns whether a channel applied the text.
+ */
+export declare function writeComposer(text: string, facade: ComposerDraftWriter | undefined): boolean;
+/**
+ * Execute one rewind and, when it settles successfully, put the withdrawn
+ * target message's text back into the composer so the user can edit and
+ * re-send.
+ */
+export declare function runRewindAndFill(session: SessionFace, seq: number, mode: 'chat' | 'both', isMainViewSession: (sessionId: string) => boolean, chatOf: ChatOf, watchChat: ChatWatch, setComposerText: (sessionId: string, text: string) => boolean, restoreImages?: (sessionId: string, images: readonly MessageImageRef[]) => Promise<void>): Promise<void>;
+/** The current composer draft: the contenteditable `textContent`.
+ * Empty when the composer is absent. Exported as a test seam (the
+ * empty-composer guard in `runRewindAndFill`). */
+export declare function composerText(): string;
+/**
+ * The session-kind slice the durable-target gate reads — the session
+ * snapshot's `subagent` cell, the Harness's own runtime signal for a
+ * direct-subagent (child) session. Typed structurally so the plugin never
+ * imports the session-controller snapshot contract.
+ */
+export interface SessionKindLike {
+    /** Non-null exactly while this Session is addressed as a subagent child. */
+    readonly subagent: unknown;
+}
+/**
+ * Whether a session is rewind-inert: a direct-subagent (child) session.
+ *
+ * The Harness refuses every generic Session RPC for a subagent-owned identity
+ * (`session/agent-busy`, "use subagent delivery for this child session"), so
+ * `/rewind` can never execute there — the command's own admission is the
+ * refusal, before any handler runs. A wired-up action in such a session would
+ * therefore be dead UI (SiriLee/dsh-rewind#26). This mirrors the Harness's own
+ * slash-command directory (which returns no commands for an addressed child)
+ * and the Host's `isSubagentSession` skips: a child session gets no rewind
+ * surface and records no snapshot.
+ */
+export declare function isRewindInertSession(snapshot: SessionKindLike): boolean;
+export {};

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

@@ -1,13 +1,14 @@
 /**
  * Client plugin styling: one injected `<style>` tag (scoped class names),
- * following the dsh design tokens (`--dsw-*`) so the button and popover blend
- * with the conversation chrome.
+ * following the dsh design tokens (`--dsw-*`) so the per-message action, the
+ * mode popover, the failure toast and the settings card blend with the
+ * conversation chrome.
  *
  * @module dsh-rewind/client/styles
  */
 /** Class names shared between the injected DOM and the stylesheet. */
 export declare const CLASS: {
-    readonly button: 'dsh-rewind-btn';
+    readonly action: 'dsh-rewind-action';
     readonly popover: 'dsh-rewind-popover';
     readonly popoverTitle: 'dsh-rewind-popover-title';
     readonly popoverTarget: 'dsh-rewind-popover-target';
@@ -21,15 +22,5 @@ export declare const CLASS: {
     readonly popoverGhost: 'dsh-rewind-popover-ghost';
     readonly guardHint: 'dsh-rewind-guard-hint';
 };
-/**
- * The ↶ glyph, drawn inline so the bundle stays dependency-free.
- *
- * Size follows the 0.1.7 product-icon set (15px, as the neighbouring copy/branch
- * actions in `MessageIconActions`). Stroke is 1.25 rather than upstream's
- * `Regular` 1: ↶ is a single open stroke next to a dense outline-plus-fill copy
- * glyph, so at 1 it reads thinned out. Rounded caps/joins stay — upstream keeps
- * them on curved artwork.
- */
-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  /* The neighbouring action buttons scale by this delta too. */\n  width: calc(28px + var(--dsh-content-font-delta, 0px));\n  height: calc(28px + var(--dsh-content-font-delta, 0px));\n  padding: 6px;\n  border: none;\n  border-radius: var(--dsw-radius-sm, 8px);\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n.dsh-rewind-btn svg {\n  width: calc(15px + var(--dsh-content-font-delta, 0px));\n  height: calc(15px + var(--dsh-content-font-delta, 0px));\n}\n@media (hover: hover) {\n  .dsh-rewind-btn:hover {\n    background: var(--dsw-alias-interactive-bg-hover);\n    color: var(--dsw-alias-label-secondary);\n  }\n}\n\n.dsh-rewind-popover {\n  position: fixed;\n  z-index: 1100;\n  box-sizing: border-box;\n  width: min(300px, calc(100vw - 24px));\n  padding: 16px;\n  border: 0;\n  border-radius: var(--dsw-radius-lg);\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  backdrop-filter: var(--dsw-menu-backdrop-filter);\n  isolation: isolate;\n  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);\n  /* Elevated surface: match the menu cards' l2 scrollbar tokens. */\n  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);\n  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);\n  box-shadow: var(--dsw-elevation-prominent);\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-popover-title {\n  font-size: 12px;\n  font-weight: 500;\n  line-height: 18px;\n}\n.dsh-rewind-popover-target {\n  margin: 2px 0 10px;\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-tertiary);\n  word-break: break-all;\n  /* The full message sits above the popover; two lines are enough context. */\n  display: -webkit-box;\n  -webkit-box-orient: vertical;\n  -webkit-line-clamp: 2;\n  overflow: hidden;\n}\n.dsh-rewind-popover-option {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  width: 100%;\n  margin: 0 0 2px;\n  padding: 6px 8px;\n  border: 0;\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/* Arrow navigation moves real focus, so the focused row carries the pointer's\n   fill and the browser ring is suppressed: in dark mode the UA two-tone ring\n   draws its dark half against the filled row and reads as a residue edge (the\n   harness Menu suppresses it the same way). */\n.dsh-rewind-popover-option:focus-visible:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover);\n  outline: none;\n}\n.dsh-rewind-popover-option:disabled {\n  opacity: 0.4;\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-note {\n  margin-top: 6px;\n  font-size: 11px;\n  line-height: 15px;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-popover-actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n  margin-top: 8px;\n}\n.dsh-rewind-popover-primary,\n.dsh-rewind-popover-ghost {\n  height: 28px;\n  padding: 0 10px;\n  border: none;\n  border-radius: 8px;\n  font: inherit;\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.4;\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.dsh-rewind-popover-ghost:active {\n  background: var(--dsw-alias-interactive-bg-active);\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: 0;\n  border-radius: var(--dsw-radius-md);\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  backdrop-filter: var(--dsw-menu-backdrop-filter);\n  isolation: isolate;\n  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);\n  box-shadow: var(--dsw-elevation-panel);\n  font-size: 13px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n  pointer-events: none;\n}\n\n/* ---- Plugin configuration form ---- */\n/* Only the card's own controls: the two switch rows, their hints, and the divider. */\n.dsh-rewind-settings-divider {\n  border-top: 1px solid var(--dsw-alias-border-l2);\n}\n.dsh-rewind-settings-section {\n  display: grid;\n  gap: 6px;\n  padding: 12px 0;\n}\n.dsh-rewind-settings-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-settings-toggle-label {\n  flex: 1;\n  min-width: 0;\n}\n.dsh-rewind-settings-hint {\n  margin: 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n";
+export declare const STYLE = "\n/* The official action chrome, value for value: the action is Copy's peer in the\n   same 28px row, so a different box, glyph scale, or resting tier would read as\n   a different kind of control. */\n.dsh-rewind-action {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: calc(28px + var(--dsh-content-font-delta, 0px));\n  height: calc(28px + var(--dsh-content-font-delta, 0px));\n  padding: 6px;\n  border: none;\n  border-radius: var(--dsw-radius-sm, 8px);\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n.dsh-rewind-action svg {\n  width: calc(15px + var(--dsh-content-font-delta, 0px));\n  height: calc(15px + var(--dsh-content-font-delta, 0px));\n}\n@media (hover: hover) {\n  .dsh-rewind-action:hover {\n    background: var(--dsw-alias-interactive-bg-hover);\n    color: var(--dsw-alias-label-secondary);\n  }\n}\n\n.dsh-rewind-popover {\n  position: fixed;\n  z-index: 1100;\n  box-sizing: border-box;\n  width: min(300px, calc(100vw - 24px));\n  padding: 16px;\n  border: 0;\n  border-radius: var(--dsw-radius-lg);\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  backdrop-filter: var(--dsw-menu-backdrop-filter);\n  isolation: isolate;\n  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);\n  /* Elevated surface: match the menu cards' l2 scrollbar tokens. */\n  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);\n  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);\n  box-shadow: var(--dsw-elevation-prominent);\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-popover-title {\n  font-size: 12px;\n  font-weight: 500;\n  line-height: 18px;\n}\n.dsh-rewind-popover-target {\n  margin: 2px 0 10px;\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-tertiary);\n  word-break: break-all;\n  /* The full message sits above the popover; two lines are enough context. */\n  display: -webkit-box;\n  -webkit-box-orient: vertical;\n  -webkit-line-clamp: 2;\n  overflow: hidden;\n}\n.dsh-rewind-popover-option {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  width: 100%;\n  margin: 0 0 2px;\n  padding: 6px 8px;\n  border: 0;\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/* Arrow navigation moves real focus, so the focused row carries the pointer's\n   fill and the browser ring is suppressed: in dark mode the UA two-tone ring\n   draws its dark half against the filled row and reads as a residue edge (the\n   harness Menu suppresses it the same way). */\n.dsh-rewind-popover-option:focus-visible:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover);\n  outline: none;\n}\n.dsh-rewind-popover-option:disabled {\n  opacity: 0.4;\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-note {\n  margin-top: 6px;\n  font-size: 11px;\n  line-height: 15px;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-popover-actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n  margin-top: 8px;\n}\n.dsh-rewind-popover-primary,\n.dsh-rewind-popover-ghost {\n  height: 28px;\n  padding: 0 10px;\n  border: none;\n  border-radius: 8px;\n  font: inherit;\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.4;\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.dsh-rewind-popover-ghost:active {\n  background: var(--dsw-alias-interactive-bg-active);\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: 0;\n  border-radius: var(--dsw-radius-md);\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  backdrop-filter: var(--dsw-menu-backdrop-filter);\n  isolation: isolate;\n  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);\n  box-shadow: var(--dsw-elevation-panel);\n  font-size: 13px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n  pointer-events: none;\n}\n\n/* ---- Plugin configuration form ---- */\n/* Only the card's own controls: the two switch rows, their hints, and the divider. */\n.dsh-rewind-settings-divider {\n  border-top: 1px solid var(--dsw-alias-border-l2);\n}\n.dsh-rewind-settings-section {\n  display: grid;\n  gap: 6px;\n  padding: 12px 0;\n}\n.dsh-rewind-settings-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-settings-toggle-label {\n  flex: 1;\n  min-width: 0;\n}\n.dsh-rewind-settings-hint {\n  margin: 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n";

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

@@ -0,0 +1,479 @@
+/**
+ * On-disk store format — the single source of truth for what a snapshot
+ * directory looks like.
+ *
+ * Everything here is stateless and independent of the file-system service:
+ * the naming functions, the entry/journal JSON codecs, and the ref validators
+ * that keep a hostile or corrupt record inside the store. The byte format
+ * itself is specified in `docs/format.md`; the fail-closed store-version
+ * contract is enforced by `readEntry` here and by
+ * `SnapshotStore.assertKnownStoreVersion` in `snapshot.ts`.
+ *
+ * @module dsh-rewind/snapshot-format
+ */
+/** Suffix of the raw byte copy holding one entry's before-content. */
+export declare const SIDECAR_SUFFIX = ".before";
+/** Session-dir sub-directory holding captures that are staged but not committed. */
+export declare const PENDING_DIR = ".pending";
+/** Session-dir sub-directory holding one pre-restore ("rescue") copy per op. */
+export declare const RESCUE_DIR = "rescue";
+/** Journal-file prefix of the current format. */
+export declare const JOURNAL_PREFIX = "journal-";
+/** Journal-file prefix written by the released v1 build (read-only compatibility). */
+export declare const LEGACY_JOURNAL_PREFIX = "restore-journal-";
+/**
+ * Current on-disk store format version (the session's `store` marker value and
+ * the `store` field of every entry this build writes). A value ABOVE this one
+ * means the snapshots were written by a NEWER build: readers must then fail
+ * closed (no file restore, nothing changed) instead of guessing what the extra
+ * fields mean. A missing marker (or `1`) means the released v1 string format,
+ * which is still read.
+ */
+export declare const CURRENT_STORE_VERSION = 2;
+/**
+ * Thrown when snapshots carry a store format newer than this build understands
+ * (ADR-10: whole-operation fail-closed — never a partial restore, never a
+ * clear). The session rewind itself does not depend on snapshots and still
+ * works.
+ */
+export declare class UnknownStoreVersionError extends Error {
+    /** The version found on disk. */
+    readonly version: number;
+    /** Where it was found (a marker or an entry file). */
+    readonly source: string;
+    constructor(
+    /** The version found on disk. */
+    version: number, 
+    /** Where it was found (a marker or an entry file). */
+    source: string);
+}
+/**
+ * Recorded before-content — always bytes, never a decoded string:
+ *
+ * - `blob`: a raw byte copy inside the store (the format every new write uses).
+ * - `text`: the exact UTF-8 bytes of a released-v1 string record (a v1 record
+ *   that was decoded from valid UTF-8 is byte-exact, so restoring it is safe).
+ * - `lossyText`: a released-v1 string record that contains U+FFFD, i.e. one
+ *   the v1 build produced by a LOSSY decode of non-UTF-8 bytes. The original
+ *   bytes are unknowable, so it can be compared against the disk but must
+ *   never be written back as a restore target (that would destroy live data).
+ */
+export type ByteSource = {
+    readonly kind: 'blob';
+    readonly path: string;
+} | {
+    readonly kind: 'text';
+    readonly bytes: Buffer;
+} | {
+    readonly kind: 'lossyText';
+    readonly text: string;
+};
+/** Classify a released-v1 string record (U+FFFD means the decode lost bytes). */
+export declare function textSourceOf(text: string): ByteSource;
+/** A staged raw byte copy waiting to be committed (`recordBackup`). */
+export interface PendingBackup {
+    /** Absolute path of the staged file (inside the session's `.pending/`). */
+    readonly file: string;
+    /** Byte size of the staged content. */
+    readonly size: number;
+    /**
+     * Permission bits of the source file (`stat().mode & 0o7777`), captured
+     * best-effort. Restored alongside the content — never on its own, and never
+     * as part of the change decision (ADR-9).
+     */
+    readonly mode?: number;
+}
+/** One committed before-backup, keyed by tool call. */
+export interface CheckpointEntry {
+    readonly callId: string;
+    /** Seq of the user message anchoring the turn in which the change happened. */
+    readonly anchorSeq: number;
+    /** Resolved display path (absolute) of the tracked file. */
+    readonly path: string;
+    /** Byte source of the content before the change; null when the file was created. */
+    readonly before: ByteSource | null;
+    /** Byte size of `before` (0 when the file was created). */
+    readonly size: number;
+    /**
+     * Checkpoint-time location pin: where `dirname(path)` resolved when the entry
+     * was captured — or, when that directory was already gone, where it would
+     * have resolved (nearest surviving ancestor plus the missing segments). A
+     * restore refuses the path when its parent directory no longer resolves there,
+     * because a repointed or moved ancestor would otherwise redirect the write
+     * (or the unlink) outside the recorded location; the path's FINAL component is
+     * checked separately (see {@link isUnsafeTarget}). Absent means "no pin": a
+     * released-v1 entry or a legacy v2 entry, whose restore falls back to the
+     * final-component check alone.
+     */
+    readonly parent?: string;
+    /**
+     * Permission bits recorded at capture time, when known. Applied only when
+     * the CONTENT is restored (a mode-only difference is never a reason to plan
+     * a restore); a missing value means "leave the live mode alone".
+     */
+    readonly mode?: number;
+    /**
+     * Set when this entry's sidecar holds re-encoded LOSSY text (a released-v1
+     * record that was decoded with replacement characters, e.g. after `prune`
+     * materialized its link). The bytes are comparable but must never be written
+     * back: a reader turns such an entry into a `lossyText` source again.
+     */
+    readonly lossy?: boolean;
+    /** Epoch ms the entry was committed (stable ordering within a group). */
+    readonly time: number;
+    /**
+     * Absolute file this entry was READ from (in-memory only, never serialized):
+     * a dedup reference must name the file that actually exists, which for an
+     * entry written by an older build is not necessarily the name the current
+     * naming function would produce.
+     */
+    readonly file?: string;
+}
+/**
+ * One in-place dedup link, keyed by tool call. When a tracked file is
+ * recorded with a `before` content identical to the immediately-prior entry
+ * for that path, the entry is stored as a LINK instead of a full copy: it
+ * carries no content, only a `ref` naming the prior entry file
+ * (`<anchorSeq>/<callId>.json`). The linear (predecessor-chained) ref makes
+ * restore resolution and prune materialization rewrite-free.
+ */
+export interface LinkEntry {
+    readonly callId: string;
+    readonly anchorSeq: number;
+    readonly path: string;
+    /** `<anchorSeq>/<callId>.json` of the immediately-prior entry for the path. */
+    readonly ref: string;
+    /**
+     * Checkpoint-time location pin (see {@link CheckpointEntry.parent}); a link
+     * records its own, so a materialized or resolved entry never loses the
+     * location the path was committed under.
+     */
+    readonly parent?: string;
+    readonly time: number;
+    /** Absolute file this link was read from (in-memory only, never serialized). */
+    readonly file?: string;
+}
+/** Any on-disk entry: a full before-backup or an in-place dedup link. */
+export type StoredEntry = CheckpointEntry | LinkEntry;
+/** True when an entry is a dedup link (carries `ref`, not `before`). */
+export declare function isLinkEntry(entry: StoredEntry): entry is LinkEntry;
+/** Per-file restore impact preview (served by the host preview route). */
+export interface FileImpact {
+    readonly path: string;
+    /** `restore` = write the before content back; `delete` = remove the file. */
+    readonly action: 'restore' | 'delete';
+}
+/** A recorded path whose current on-disk size is over the backup cap. */
+export interface UncoveredPath {
+    readonly path: string;
+    /** Byte size observed on disk, when the probe could read one. */
+    readonly size?: number;
+}
+/** Outcome of one restore pass. */
+export interface RestoreOutcome {
+    readonly restored: readonly string[];
+    readonly deleted: readonly string[];
+    /** Symlinked or hard-linked paths left untouched. */
+    readonly skipped: readonly string[];
+    readonly failed: readonly {
+        path: string;
+        message: string;
+    }[];
+}
+/** Deletes one file by its real path (node:fs, bypassing the fs service). */
+export type DeleteFile = (path: string) => Promise<void>;
+/**
+ * Test-only fault injection: a crash point inside the write/restore paths.
+ * The hook THROWS to simulate a host crash at the exact point; the throw
+ * propagates out of the store method, leaving the journal on disk in its
+ * current state. Production callers never pass it (undefined = no-op).
+ */
+export type CrashPoint = 'before-action' | 'after-action' | 'after-temp-write';
+/** Options for the journaled restore paths; `crash` is the test-only seam. */
+export interface RestoreRunOptions {
+    /**
+     * Throws at the given point to simulate a host crash: `before-action`
+     * (before an action's fs op), `after-action` (right after the fs op,
+     * before its done-mark is persisted), `after-temp-write` (inside an atomic
+     * commit, between the temp write and the rename). `index` is the action
+     * index for the restore loops.
+     */
+    readonly crash?: (point: CrashPoint, index?: number) => void;
+}
+/**
+ * Lifecycle of one restore operation journal. Terminal states are kept on
+ * disk as a tiny audit trail and skipped by reconciliation.
+ */
+export type RestoreJournalState = 'running' | 'rollback-running' | 'completed' | 'rolled-back' | 'recovery-required';
+/**
+ * One journaled restore action — a mutable working record that the restore
+ * loop updates (done/failed) as it applies the pass.
+ */
+export interface RestoreJournalAction {
+    readonly path: string;
+    readonly action: 'restore' | 'delete';
+    /** Target content for a restore; null for a delete. */
+    readonly before: ByteSource | null;
+    /**
+     * Pre-restore disk state ("rescue"): a raw byte copy of what the file had
+     * right before the restore started, or null when it was absent. Rollback
+     * writes this back, so the pre-restore state is recoverable exactly.
+     */
+    readonly rescue: ByteSource | null;
+    /** Set when the rescue capture failed: rollback then skips this path. */
+    rescueError?: string;
+    /** Permission bits the restored content should end up with, when recorded. */
+    readonly mode?: number;
+    /**
+     * Checkpoint-time location pin copied from the entry the action was planned
+     * from (see {@link CheckpointEntry.parent}): a continue or rollback after a
+     * restart re-checks it before touching the path.
+     */
+    readonly parent?: string;
+    /** Permission bits the file had BEFORE the restore, for a faithful rollback. */
+    readonly rescueMode?: number;
+    /** True once the action's fs op completed and was marked. */
+    done: boolean;
+    /** Per-action failure message; the restore pass never aborts. */
+    failed?: string;
+}
+/** Durable journal for one attempted restore (written atomically). */
+export interface RestoreJournal {
+    /** On-disk schema version: 2 = byte references, 1 = inline legacy strings. */
+    readonly version: 1 | 2;
+    readonly id: string;
+    readonly sessionId: string;
+    readonly targetSeq: number;
+    readonly startedAt: number;
+    finishedAt?: number;
+    state: RestoreJournalState;
+    readonly actions: RestoreJournalAction[];
+    /** Set when a rollback pass failed partway (state becomes `recovery-required`). */
+    rollbackError?: string;
+    /**
+     * Absolute file this journal was read from (in-memory only, never
+     * serialized): a legacy `restore-journal-` file is updated IN PLACE so an
+     * op that was interrupted before the upgrade never ends up with two
+     * divergent versions on disk.
+     */
+    sourceFile?: string;
+}
+/**
+ * Result of reconciling one interrupted restore journal against the real
+ * disk. Path status is relative to the op's current goal: the restore target
+ * for `running` journals, the pre-restore (rescue) state for
+ * `rollback-running` / `recovery-required` journals — disambiguate with
+ * {@link RestoreReconcileReport.journalState}.
+ */
+export interface RestoreReconcileReport {
+    readonly opId: string;
+    /** `interrupted` = a crash left the op unfinished; `recovery-required` = a rollback could not complete. */
+    readonly state: 'interrupted' | 'recovery-required';
+    /** Raw journal state (`running` | `rollback-running` | `recovery-required`). */
+    readonly journalState: RestoreJournalState;
+    readonly targetSeq: number;
+    readonly startedAt: number;
+    /** Paths whose disk already matches the op's goal. */
+    readonly restored: readonly string[];
+    /** Paths still short of the op's goal (not yet applied / not yet rolled back). */
+    readonly pending: readonly string[];
+    /** Actions that failed during the pass (kept failed until a redo succeeds). */
+    readonly failed: readonly {
+        path: string;
+        message: string;
+    }[];
+    readonly rollbackError?: string;
+    /** Set when the journal file itself is corrupt: it cannot be reconciled. */
+    readonly corrupt?: string;
+}
+/**
+ * Current-on-disk state probe used by restore planning and reconciliation.
+ * Injected so the logic runs against a fake FS in tests; the production
+ * default reads the real file system with plain `node:fs` (see
+ * {@link defaultProbe}) and compares byte streams, never whole files in memory.
+ */
+export interface DiskProbe {
+    /**
+     * Compare the recorded content with the file currently at `path`.
+     *
+     * - `true`  = the disk matches the record byte-for-byte (for a `null`
+     *   source: the path is absent).
+     * - `false` = it differs — including "the record says the file did not
+     *   exist but it does" and "the record has content but the file is gone".
+     * - `undefined` = the comparison could not be decided (IO/permission
+     *   failure). Callers stay conservative: a restore is still attempted and a
+     *   delete still attempted, so an unreadable file is never silently skipped.
+     *
+     * A `lossyText` source is compared with the same lossy decode the released
+     * v1 build used (its original bytes cannot be recovered).
+     */
+    matches(source: ByteSource | null, path: string): Promise<boolean | undefined>;
+    /**
+     * Stage a raw byte copy of the file at `path` into `dest` (the store's
+     * rescue area) without loading it into memory.
+     */
+    copy(path: string, dest: string): Promise<CopyOutcome>;
+    /**
+     * Byte size of the regular file at `path`, or `undefined` when absent or
+     * unreadable. Consulted before any content comparison so an over-cap file is
+     * skipped without being read. Optional; a missing accessor reads as "size
+     * unknown", which never counts as "too big".
+     */
+    size?(path: string): Promise<number | undefined>;
+    /**
+     * True when the path's final component is not a single regular file: a
+     * symlink, a hard link (`nlink > 1`), a directory, a FIFO or a device. The
+     * planner and the apply pass both refuse one — a link redirects the write,
+     * a hard link shares the inode with other names, and a FIFO or device is
+     * neither restorable nor safe to open.
+     */
+    isUnsafeTarget(path: string): Promise<boolean>;
+}
+/** Result of staging one on-disk byte copy. */
+export type CopyOutcome = {
+    readonly kind: 'copied';
+    readonly size: number;
+} | {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'failed';
+    readonly message: string;
+};
+/** One restore action the planner derived from record + disk reconciliation. */
+export type PlannedAction = {
+    readonly path: string;
+    readonly action: 'restore';
+    readonly before: ByteSource;
+    readonly mode?: number;
+    readonly parent?: string;
+} | {
+    readonly path: string;
+    readonly action: 'delete';
+    readonly parent?: string;
+};
+/** Sanitize a call id into a safe file name. */
+export declare function safeFileId(callId: string): string;
+/**
+ * Sanitize a session id into a safe path segment. Real ids are harness-minted
+ * UUIDs (a no-op here), but a hostile or malformed id must never traverse out
+ * of the snapshot root — `.` and `..` are the only bare values the charset
+ * permits that would alias the root or its parent.
+ */
+export declare function safeSessionId(sessionId: string): string;
+/**
+ * Structural validation of a parsed journal. Unlike checkpoint entries (whose
+ * corruption is silently skipped), a corrupt journal is reported
+ * fail-loud by `reconcileRestores` — silently dropping it would silently
+ * erase the ability to recover the interrupted restore.
+ *
+ * Accepts both formats: `version: 2` (byte references), the released
+ * `version: 1` (inline strings) and the legacy prefix that carried no
+ * `version` at all — but never best-effort-coerces a malformed action.
+ */
+export declare function isRestoreJournal(value: unknown): value is RestoreJournal;
+/**
+ * Format a store-relative filesystem path as a serialized ref. Refs are always
+ * POSIX-separated (`13/call.before`) even on Windows, where `relative()`
+ * returns backslashes; the journal and link validators only accept `/`.
+ */
+export declare function sessionRelativeRef(sessionDir: string, file: string): string;
+/** Serialized (on-disk) form of a journal action. */
+export declare function journalToJson(journal: RestoreJournal, sessionDir: string): Record<string, unknown>;
+/** Parse a validated journal's raw shape into the in-memory form. */
+export declare function journalFromJson(raw: Record<string, unknown>, sessionDir: string): RestoreJournal | undefined;
+/** True when a session-dir member is a restore journal (either prefix). */
+export declare function isJournalName(name: string): boolean;
+/** The op id encoded in a journal file name. */
+export declare function journalOpIdOf(name: string): string;
+/** The entry file name one call id maps to (the single naming function). */
+export declare function entryFileName(callId: string): string;
+/** Stable 8-hex digest of an arbitrary string (ids, paths, capture keys). */
+export declare function shortHash(value: string): string;
+/** The sidecar file name of one entry file (`<base>.json` → `<base>.before`). */
+export declare function sidecarName(entryFile: string): string;
+/** Anchor seq encoded in a link `ref` (`<anchorSeq>/<file>.json`). */
+export declare function refAnchorOf(ref: string): number;
+/** Serialize one in-memory entry for disk (the current byte format). */
+export declare function entryToJson(entry: CheckpointEntry): Record<string, unknown>;
+/** Serialize one in-memory dedup link for disk (the current byte format). */
+export declare function linkToJson(link: LinkEntry): Record<string, unknown>;
+/**
+ * Read one committed entry, or undefined when missing/corrupt. Accepts both
+ * formats: the current byte format (`store: 2`, `file`, `blob` + sidecar) and
+ * the released v1 format (`anchorSeq` + inline `before` string).
+ *
+ * The byte format deliberately does NOT carry `anchorSeq` (it equals the
+ * parent directory) and does NOT reuse the v1 key names — a downgraded v1
+ * build rejects such an entry instead of reading it as "created", which is
+ * what keeps a downgrade from deleting workspace files. See
+ * `tests/downgrade-safety.test.ts`.
+ */
+export declare function readEntry(file: string, anchorSeq: number): Promise<StoredEntry | undefined>;
+/**
+ * True when a dedup-link `ref` is a SAFE relative reference to a checkpoint
+ * entry — `<digits>/<callId>.json`, a single level below the session dir, with
+ * no traversal or absolute segment. The plugin always writes refs this way
+ * ({@link SnapshotStore.entryRefOf}); this validates a `ref` read back from
+ * disk so a hostile or corrupt ref can never escape the store root when a
+ * restore resolution or prune materialization follows it (mirrors the
+ * `safeSessionId` / `safeFileId` containment guarantee).
+ */
+export declare function isSafeLinkRef(ref: string): boolean;
+/**
+ * True when a journal's byte reference is SAFE and relative to the session
+ * dir: either `<digits>/<name>.before` (an entry sidecar) or
+ * `rescue/<opId>/<index>.before` (a rescue copy). Validated on both write and
+ * read, so a corrupt or hostile journal can never point a restore or a
+ * rollback outside the store (`..`, absolute paths and unknown roots are
+ * rejected).
+ */
+export declare function isSafeBackupRef(ref: string): boolean;
+/**
+ * Result of a stale-session cleanup sweep ({@link SnapshotStore.pruneStale}).
+ *
+ * The sweep is ANTI-DELETE: it only ever removes WHOLE session directories
+ * that have been idle past `maxAgeDays`. `scanned` counts every session dir
+ * evaluated; `kept` + `skippedActive` + `deleted` sum to it. `remainingBytes`
+ * is the total of directories that SURVIVE the policy (when `dryRun` it is the
+ * would-be total, not the current on-disk total), so it is comparable across
+ * dry and real runs.
+ */
+export interface PruneStaleReport {
+    /** Number of session directories evaluated. */
+    readonly scanned: number;
+    /** Session directories removed (would-be count when `dryRun`). */
+    readonly deleted: number;
+    /** Bytes reclaimed (would-be bytes when `dryRun`). */
+    readonly freedBytes: number;
+    /** Session directories retained (not past the cutoff, not the active one). */
+    readonly kept: number;
+    /** Bytes across the retained + skipped-active directories. */
+    readonly remainingBytes: number;
+    /** Directories skipped because they are the active session. */
+    readonly skippedActive: number;
+    /** Whether nothing was really removed (the sweep only reported). */
+    readonly dryRun: boolean;
+}
+/**
+ * Result of a manual whole-session clear ({@link SnapshotStore.clearSession}).
+ *
+ * Unlike the age-based sweep, a clear removes EVERY snapshot of ONE session
+ * (all anchor groups, all checkpoint entries, all restore journals) on demand —
+ * the active session the user is driving, to drop the rewind overhead or to
+ * archive a conversation immediately. `dryRun` reports what would be removed
+ * without touching disk or memory.
+ */
+export interface ClearSessionReport {
+    /** The session whose records were (or would be) cleared. */
+    readonly sessionId: string;
+    /** Number of anchor-group (user-message) directories present. */
+    readonly anchorGroups: number;
+    /** Number of committed checkpoint entries (full backups + dedup links). */
+    readonly entries: number;
+    /** Number of restore-journal files (terminal + pending). */
+    readonly journals: number;
+    /** Bytes occupied by the session directory (the amount freed). */
+    readonly bytes: number;
+    /** Whether nothing was really removed (the clear only reported). */
+    readonly dryRun: boolean;
+}