dsh-rewind-plugin 0.11.0 → 0.12.0

package/lib/types/snapshot.d.ts

@@ -13,8 +13,10 @@
  *   around-dispatch stage, so an approval `ask` short-circuit cannot skip it
  *   and a denied call never records.
  * - The entry is committed to disk at `tools/post-execute` under the turn's
- *   anchor seq: `<root>/<sessionId>/<anchorSeq>/<callId>.json`, carrying the
- *   path and the before content (`before: null` = the file was created).
+ *   anchor seq: `<root>/<sessionId>/<anchorSeq>/<callId>.json` carries the
+ *   metadata, and the before content lives beside it as a RAW BYTE sidecar
+ *   (`<callId>.before`, copied with `copyFile`). Content never travels through
+ *   a JS string, so binary and non-UTF-8 files round-trip byte-exactly.
  * - Because entries live on disk under the dsh data directory, they survive a
  *   host restart, are bounded (the newest 100 anchor groups per session are
  *   kept), and restores read/write the real file system with plain `node:fs`
@@ -26,17 +28,18 @@
  * file (e.g. `.env`) is a model-permission concern (see `SECURITY.md`).
  *
  * Crash safety (this module's own engineering asset):
- *  - Checkpoint commits are ATOMIC: the entry JSON is written to a sibling
- *    temp file and renamed over the target, so a host crash mid-write can
- *    never leave a readable half-written entry — at worst an inert `.tmp`
- *    leftover that the next commit of the same file overwrites and that no
- *    reader ever picks up.
+ *  - Checkpoint commits are ATOMIC: the sidecar is fully written first, then
+ *    the entry JSON is written to a sibling temp file and renamed over the
+ *    target, so a host crash mid-write can never leave a readable entry
+ *    without its bytes — at worst an unreferenced orphan sidecar, or an inert
+ *    `.tmp` leftover that the next commit of the same file overwrites and that
+ *    no reader ever picks up.
  *  - Every restore pass is JOURNALED. Before mutating anything the store
- *    captures the pre-restore ("rescue") state of each planned path and
- *    persists an intent journal (`restore-journal-<op>.json` in the session
- *    dir), then marks each action done as it is applied. A crash at any point
- *    leaves the journal on disk; after a host restart
- *    `reconcileRestores(sessionId)` re-derives from the REAL disk which
+ *    captures the pre-restore ("rescue") state of each planned path as a raw
+ *    byte copy and persists an intent journal (`journal-<op>.json` in the
+ *    session dir) holding only references, then marks each action done as it
+ *    is applied. A crash at any point leaves the journal on disk; after a host
+ *    restart `reconcileRestores(sessionId)` re-derives from the REAL disk which
  *    paths already match the target and which are still pending (reporting
  *    "restored up to where, what changed"), auto-heals journals whose goal is
  *    already reached, and `continueRestore` / `rollbackRestore` finish the
@@ -51,6 +54,15 @@
  * creation. Symlinked and hard-linked paths are skipped and reported, never
  * written through.
  *
+ * Format compatibility: entries written before this module stored bytes
+ * (released v1: `{callId, anchorSeq, path, before: string | null}` plus the
+ * `restore-journal-` prefix) are still READ — their string content is the
+ * exact UTF-8 bytes it always was, except for records that were decoded
+ * lossily (they contain U+FFFD: comparable, but never written back). New
+ * writes are always the byte format; the marker contract that keeps a
+ * downgraded v1 build from touching the workspace lives in
+ * `tests/downgrade-safety.test.ts`.
+ *
  * @module dsh-rewind/snapshot
  */
 /**
@@ -64,6 +76,66 @@ export declare const DEFAULT_SNAPSHOT_ROOT: string;
 export declare const SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
 /** Number of newest anchor groups (user messages) kept per session. */
 export declare const MAX_ANCHOR_GROUPS = 100;
+/**
+ * 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;
+};
+/** 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;
@@ -71,22 +143,51 @@ export interface CheckpointEntry {
     readonly anchorSeq: number;
     /** Resolved display path (absolute) of the tracked file. */
     readonly path: string;
-    /** Full content before the change; null when the file was created. */
-    readonly before: string | null;
+    /** 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: the `realpath` of `dirname(path)` at the
+     * moment the entry was committed. 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 — only the path's FINAL component is link-checked. Absent means
+     * "no pin": a released-v1 entry, a v2 entry written before this field
+     * existed, or a commit whose parent could not be resolved; the restore then
+     * 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 `before`, only a `ref` naming the prior entry file
+ * 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.
- *
- * The real-entry format ({@link CheckpointEntry}) is unchanged so existing
- * data reads identically; links are a NEW entry kind only the current build
- * understands (old-build reads of links are explicitly out of scope).
  */
 export interface LinkEntry {
     readonly callId: string;
@@ -94,7 +195,15 @@ export interface LinkEntry {
     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;
@@ -150,15 +259,25 @@ export interface RestoreJournalAction {
     readonly path: string;
     readonly action: 'restore' | 'delete';
     /** Target content for a restore; null for a delete. */
-    readonly before: string | null;
+    readonly before: ByteSource | null;
     /**
-     * Pre-restore disk state ("rescue"): the content 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.
+     * 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: string | null;
+    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. */
@@ -166,7 +285,8 @@ export interface RestoreJournalAction {
 }
 /** Durable journal for one attempted restore (written atomically). */
 export interface RestoreJournal {
-    readonly version: 1;
+    /** On-disk schema version: 2 = byte references, 1 = inline legacy strings. */
+    readonly version: 1 | 2;
     readonly id: string;
     readonly sessionId: string;
     readonly targetSeq: number;
@@ -176,6 +296,13 @@ export interface RestoreJournal {
     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
@@ -206,32 +333,58 @@ export interface RestoreReconcileReport {
     readonly corrupt?: string;
 }
 /**
- * Current-on-disk state probe used by restore planning. Injected so the plan
- * logic runs against a fake FS in tests; the production default reads the
- * real file system with plain `node:fs` (see {@link defaultProbe}).
+ * 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 {
     /**
-     * Full text of the file, or undefined when the file does not exist.
-     * Any thrown error is treated as a probe failure: restore planning then
-     * conservatively treats the file as DIFFERING from its record (a restore
-     * still attempts the write / a delete still attempts the unlink), so an
-     * unreadable file is never silently skipped.
+     * 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.
      */
-    readText(path: string): Promise<string | undefined>;
+    copy(path: string, dest: string): Promise<CopyOutcome>;
     /** True when the path is a symlink or a hard link (never planned/restored). */
     isLink(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: string;
+    readonly before: ByteSource;
+    readonly mode?: number;
+    readonly parent?: string;
 } | {
     readonly path: string;
     readonly action: 'delete';
+    readonly parent?: string;
 };
-/** Production probe: real reads via node:fs, links detected by lstat + nlink. */
+/** Production probe: real byte comparisons via node:fs, links via lstat + nlink. */
 export declare const defaultProbe: DiskProbe;
 /**
  * Result of a stale-session cleanup sweep ({@link SnapshotStore.pruneStale}).
@@ -289,6 +442,10 @@ export interface ClearSessionReport {
 export declare class SnapshotStore {
     /** Debounce window for the per-commit prune (keeps the readdir+sort off the hot path). */
     private static readonly PRUNE_INTERVAL_MS;
+    /** Session-format-version marker file inside the session dir. Non-`.json`, so it never counts as a checkpoint entry. */
+    private static readonly FORMAT_FILE;
+    /** Plugin STORE-format marker file inside the session dir (non-`.json`, same reasoning). */
+    private static readonly STORE_FILE;
     private lastPruneAt;
     /**
      * Monotonic entry clock. Date.now() has 1ms precision, so back-to-back
@@ -309,14 +466,18 @@ export declare class SnapshotStore {
     readonly root: string;
     /**
      * In-memory per-path "most recent entry" for content dedup, keyed by
-     * `<sessionId>\0<path>`. Each value holds the entry's effective `before`
-     * content and its own file ref, so a new record with the same content links
-     * to the immediately-prior entry (linear chain). Seeded lazily per session
-     * from the bounded on-disk window, so dedup survives a host restart.
+     * `<sessionId>\0<path>`. Each value holds the entry's effective byte source
+     * (a handle, not a copy) and its own file ref, so a new record with the same
+     * content links to the immediately-prior entry (linear chain). Seeded lazily
+     * per session from the bounded on-disk window, so dedup survives a host
+     * restart. A handle whose bytes vanished (pruned out of band) is treated as
+     * "never recorded" — dedup then stores MORE, never less.
      */
     private readonly lastEntry;
     /** Sessions whose dedup state has been seeded from disk this process. */
     private readonly seededSessions;
+    /** Sessions whose store-format marker this process has already stamped. */
+    private readonly storeStamped;
     /**
      * Session-format version snapshots are anchored under, stamped into each
      * session's `format` marker when an entry is recorded. `null` until the host
@@ -334,6 +495,30 @@ export declare class SnapshotStore {
     anchorDir(sessionId: string, anchorSeq: number): string;
     /** Absolute file ref (relative to the session dir) of an entry. */
     private entryRefOf;
+    /**
+     * The session-relative ref of an entry READ from disk: the file that really
+     * holds it. A v1 entry keeps its released name, so recomputing the name from
+     * the call id would produce a dangling reference.
+     */
+    private refOfRead;
+    /** Drop every in-memory trace of one session (its directory is gone). */
+    private forgetSession;
+    /**
+     * Forget in-memory state for sessions whose directory no longer exists —
+     * after a sweep, or after the user removed a session dir out of band. A
+     * stale handle is SAFE (dedup and the boundary both fail toward storing
+     * more), but keeping it means the store holds state for a session it deleted
+     * and skips re-stamping that session's `format`/`store` markers.
+     */
+    private forgetMissingSessions;
+    /**
+     * Stage a capture slot for one tool call: create the session's `.pending/`
+     * area and return the absolute path the caller copies the before-bytes into
+     * (never through memory). The slot lives inside the session dir so the
+     * commit can `rename` it into the anchor group atomically; a slot that is
+     * never committed is either unlinked by its caller or collected by `prune`.
+     */
+    stageCapture(sessionId: string, key: string): Promise<string>;
     /**
      * Seed a session's dedup state from the existing (bounded) on-disk window:
      * scan entries newest-first and record the most recent entry per path. This
@@ -349,20 +534,76 @@ export declare class SnapshotStore {
      * path from a restore).
      */
     private resolveBefore;
-    /** Commit one before-backup (or an in-place dedup link) under its anchor. */
-    recordEntry(sessionId: string, entry: Omit<CheckpointEntry, 'time'>, opts?: {
+    /**
+     * Validate a real entry's byte source against the store's own files: a
+     * sidecar that is missing, not a regular file, or a different size than the
+     * metadata records is an INTEGRITY failure (thrown), never a silent skip and
+     * never a fallback to "the file was created" — a restore must not delete a
+     * file whose backup it cannot read.
+     */
+    private validatedSource;
+    /**
+     * True when two recorded byte sources are the same content. Comparison is
+     * STREAMING (size first, then chunks) so large files never enter memory.
+     * Any unreadable handle — or any legacy lossy source, whose original bytes
+     * are unknowable — answers `false`: dedup must fail toward storing more,
+     * never toward claiming "unchanged".
+     */
+    private sourcesMatch;
+    /**
+     * Write raw bytes to a sidecar path atomically (temp + rename): a crash
+     * between the steps leaves only a `.tmp` that no reader picks up.
+     */
+    private writeSidecar;
+    /**
+     * Place one entry's sidecar next to its entry file: MOVE a staged capture
+     * (same filesystem, atomic) or write the bytes from a source. Returns the
+     * blob source and its size, or null for a created file. The sidecar is
+     * always complete before the entry JSON is written.
+     */
+    private placeSidecar;
+    /**
+     * Commit one entry (a full before-backup or an in-place dedup link) under
+     * its anchor group.
+     */
+    private commit;
+    /**
+     * Commit one before-backup whose content the caller already holds as raw
+     * text (the boundary-friendly API: tests, synthetic records). The bytes are
+     * encoded UTF-8, exactly as the released v1 build did for text content.
+     */
+    recordEntry(sessionId: string, entry: {
+        readonly callId: string;
+        readonly anchorSeq: number;
+        readonly path: string;
+        readonly before: string | null;
+    }, opts?: {
         readonly dedup?: boolean;
         readonly crash?: (point: CrashPoint) => void;
     }): Promise<void>;
     /**
-     * The effective content recorded by the path's MOST RECENT entry, or
-     * undefined when the path has never been recorded (a fresh tracking sight).
-     * This is the single in-memory "last known state" the boundary uses to
-     * decide whether a tracked file changed — the same source `recordEntry`
-     * dedups against, so there is one content copy and one comparison per
-     * decision, not two. Seeding is idempotent (once per session from disk).
+     * Commit one before-backup whose content is an existing byte file (the
+     * capture and boundary paths): `backup.file` is MOVED into the anchor group
+     * (same filesystem, so this is atomic), or `null` when the file did not
+     * exist — a creation.
      */
-    lastKnownContent(sessionId: string, path: string): Promise<string | null | undefined>;
+    recordBackup(sessionId: string, entry: {
+        readonly callId: string;
+        readonly anchorSeq: number;
+        readonly path: string;
+    }, backup: PendingBackup | null, opts?: {
+        readonly dedup?: boolean;
+        readonly crash?: (point: CrashPoint) => void;
+    }): Promise<void>;
+    /**
+     * The byte source recorded by the path's MOST RECENT entry, or undefined
+     * when the path has never been recorded (a fresh tracking sight). This is
+     * the single in-memory "last known state" the boundary compares the disk
+     * against — the same source `recordEntry` dedups against, so there is one
+     * handle and one comparison per decision, not two. Seeding is idempotent
+     * (once per session from disk).
+     */
+    lastKnownContent(sessionId: string, path: string): Promise<ByteSource | null | undefined>;
     /**
      * All committed entries anchored at or after `targetSeq`, newest first (for
      * preview ordering). The boundary is inclusive: rewinding to a message also
@@ -390,9 +631,15 @@ export declare class SnapshotStore {
      *   `delete` ONLY when the file currently exists; an already-absent file
      *   is a no-op — this kills the "ghost impact" of replaying an entry a
      *   previous rewind already consumed.
-     * - `before === 'X'` plans a `restore` ONLY when the current content
-     *   differs from X (or the file is missing); identical content is a no-op
-     *   — this keeps repeated rewinds idempotent.
+     * - a recorded byte source plans a `restore` ONLY when the current bytes
+     *   differ from it (or the file is missing); identical bytes are a no-op —
+     *   this keeps repeated rewinds idempotent.
+     * - A released-v1 record that lost bytes to a lossy decode (`lossyText`) is
+     *   compared with the same lossy decode but NEVER written back: a skip is
+     *   reported instead of destroying live bytes with U+FFFD content.
+     * - An unreadable / unresolvable record is a per-file FAILURE, never a
+     *   delete: planning a delete for a file we cannot restore is the one
+     *   mistake that loses data.
      * - Symlinked / hard-linked paths are never planned (they are reported as
      *   skipped by the restore pass, never written through).
      * - A probe failure (e.g. a permission error reading the file) plans the
@@ -428,24 +675,31 @@ export declare class SnapshotStore {
      * restore (it degrades to a journal-less pass).
      */
     restoreAfter(sessionId: string, targetSeq: number, deleteFile: DeleteFile, probe?: DiskProbe, opts?: RestoreRunOptions): Promise<RestoreOutcome>;
-    /** Prefix of one restore-op journal file inside the session dir. */
-    private static readonly JOURNAL_PREFIX;
-    /** Session-format-version marker file inside the session dir. Non-`.json`, so it never counts as a checkpoint entry. */
-    private static readonly FORMAT_FILE;
-    /** Absolute path of one restore-op journal file. */
+    /** Absolute path of one restore-op journal file (the current prefix). */
     private journalPath;
+    /**
+     * Locate an existing journal file for an op: the current prefix first, then
+     * the prefix the released v1 build wrote (a restore interrupted before the
+     * upgrade must still be continuable / rollbackable).
+     */
+    private findJournalFile;
     /**
      * Best-effort journal persist: journal IO failures are non-fatal by design —
      * a restore must never fail because its audit journal could not be written.
      * reconcileRestores() re-derives the true state from the disk, so a missing
      * or stale journal only loses the trail, never the recovery ability.
+     *
+     * A journal read back from a legacy file is rewritten IN PLACE (same file),
+     * so a redo / rollback of a pre-upgrade op never leaves two divergent
+     * versions of the same op on disk.
      */
     private saveJournal;
     /**
      * Journal one restore pass before mutating anything: capture the rescue
-     * (pre-restore) state of every planned path and persist the intent
-     * atomically. Returns the in-memory journal; a persist failure degrades to
-     * a journal-less restore (non-fatal, see {@link saveJournal}).
+     * (pre-restore) state of every planned path as a raw byte copy and persist
+     * the intent (references only) atomically. Returns the in-memory journal; a
+     * persist failure degrades to a journal-less restore (non-fatal, see
+     * {@link saveJournal}).
      */
     private beginRestore;
     /**
@@ -455,23 +709,32 @@ export declare class SnapshotStore {
      */
     private readJournal;
     /**
-     * Every journal file of a session — valid ones plus corrupt ones with their
-     * error — so reconciliation can report corruption instead of dropping it.
+     * Every journal file of a session (both prefixes) — valid ones plus corrupt
+     * ones with their error — so reconciliation can report corruption instead of
+     * dropping it.
      */
     private listJournals;
     /**
      * Execute ONE fs mutation with exactly the pre-journal semantics: a delete
      * runs through the injected deleteFile (ENOENT tolerated — the file is
-     * already absent, i.e. the target state is reached), a restore is a plain
-     * writeFile with a recursive mkdir of the parent. Returns how the outcome
-     * should record it.
+     * already absent, i.e. the target state is reached), a restore copies the
+     * recorded bytes back over the file (creating the parent if needed).
      *
      * This is the only place the store writes restored content to the real FS,
-     * and it is deliberately a raw `writeFile`/`unlink` rather than the fs
-     * service: the caller only ever hands it a path from `planRestore` — one the
-     * session's own write-class tool call recorded and resolved (never a
+     * and it is deliberately raw `copyFile`/`writeFile`/`unlink` rather than the
+     * fs service: the caller only ever hands it a path from `planRestore` — one
+     * the session's own write-class tool call recorded and resolved (never a
      * symlink/hard link) and only when it differs from the live disk. So no
      * arbitrary path, no model input, never automatic.
+     *
+     * The write is IN PLACE (no temp + rename): it keeps the file's inode and
+     * thus its xattrs/ACL, and crash safety is provided by the journal plus disk
+     * reconciliation instead (a half-written file simply does not match the
+     * goal, so a redo rewrites it).
+     *
+     * Permissions are best-effort (ADR-9/R3): the mode is only ever applied as
+     * part of a CONTENT restore (never as a reason to plan one), and a chmod
+     * failure never fails the restore.
      */
     private applyActionToDisk;
     /**
@@ -483,6 +746,13 @@ export declare class SnapshotStore {
      * terminal state and not reported. A corrupt journal is reported
      * `recovery-required` — never silently dropped.
      *
+     * Deliberately NOT gated on the session's `store` marker: a journal is fully
+     * self-describing (`version` plus byte references), and refusing to finish an
+     * interrupted op merely because the SESSION marker looks newer would strand a
+     * half-restored workspace — the outcome the legacy-journal support exists to
+     * prevent. A reference the newer build moved shows up as a per-file failure,
+     * never as a silent write.
+     *
      * @param sessionId - session whose journals to reconcile.
      * @param probe - current-disk state probe (defaults to the real FS).
      * @returns one report per non-terminal journal still needing attention.
@@ -498,7 +768,7 @@ export declare class SnapshotStore {
      */
     private reconcileJournal;
     /**
-     * 补做 (redo) an interrupted restore: finish the op by applying every action
+     * Continue (redo) an interrupted restore: finish the op by applying every action
      * whose disk state does not yet match its goal — the restore target for
      * `running` journals. Actions are decided by the REAL disk (the same "disk
      * is truth" rule as reconciliation), so a crash between an fs op and its
@@ -509,7 +779,7 @@ export declare class SnapshotStore {
      */
     continueRestore(sessionId: string, opId: string, deleteFile: DeleteFile, probe?: DiskProbe, opts?: RestoreRunOptions): Promise<RestoreOutcome>;
     /**
-     * 回滚 (roll back) an interrupted restore: undo every action whose disk
+     * Roll back an interrupted restore: undo every action whose disk
      * state does not match its rescue (pre-restore) record, returning the
      * workspace to the exact state it had before the restore started. Decided
      * by the REAL disk, so actions the crash left applied-but-unmarked are
@@ -543,13 +813,28 @@ export declare class SnapshotStore {
     prune(sessionId: string, keep?: number, opts?: {
         readonly crash?: (point: CrashPoint) => void;
     }): Promise<void>;
+    /**
+     * Collect staged captures that were never committed and are older than
+     * {@link PENDING_MAX_AGE_MS}: a crash between `tools/execute` and
+     * `tools/post-execute` can leak one, and the process that would have
+     * unlinked it is gone.
+     */
+    private prunePendingCaptures;
+    /**
+     * Anchor groups a NON-TERMINAL journal still depends on — the groups holding
+     * the sidecars its actions restore from. `prune` must not evict them while
+     * the op can still be finished. Rescue copies live under `rescue/`, never in
+     * an anchor group, so only `before` references matter; a group is pinned only
+     * for a well-formed, safe reference (a corrupt journal pins nothing).
+     */
+    private pinnedAnchors;
     /**
      * Recycle terminal restore journals (`completed` / `rolled-back`): once an
-     * op finished, its journal's before + rescue content is dead weight that
-     * would otherwise accumulate without bound (one journal per both-mode
-     * rewind). Non-terminal journals (crashed ops awaiting reconcile /
-     * continue / rollback) and unclassifiable (corrupt) ones are ALWAYS kept —
-     * a recovery record that cannot be classified is never destroyed.
+     * op finished, its journal and its rescue bytes are dead weight that would
+     * otherwise accumulate without bound (one journal per both-mode rewind).
+     * Non-terminal journals (crashed ops awaiting reconcile / continue /
+     * rollback) and unclassifiable (corrupt) ones are ALWAYS kept — a recovery
+     * record that cannot be classified is never destroyed.
      */
     private pruneTerminalJournals;
     /** True when a path exists on disk (used by tests and diagnostics). */
@@ -571,7 +856,9 @@ export declare class SnapshotStore {
      *  - a non-positive `maxAgeDays` throws instead of degenerating into a
      *    mass-destructive `cutoff` in the far future;
      *  - the walk uses `lstat` (no symlink following) and skips dot-prefixed
-     *    temp left overs, so measurement stays inside the store root.
+     *    temp left overs — except the real `.pending/` area, whose staged bytes
+     *    are content and whose freshness is activity — so measurement stays
+     *    inside the store root.
      *
      * `dryRun` computes and reports exactly what would be removed without
      * deleting anything — the `/snapshot-auto-cleanup run` preview.
@@ -590,11 +877,16 @@ export declare class SnapshotStore {
     trackedPaths(sessionId: string): Promise<Set<string>>;
     /**
      * Summarize a session's on-disk footprint for a clear dry-run: anchor-group
-     * count, committed checkpoint-entry count, restore-journal count, and total
-     * bytes. Walks with `lstat` (never follows a symlink, so a hostile symlink
-     * cannot escape the store root or inflate the measurement) and skips
-     * dot-prefixed temp leftovers and non-`.json` members — they are never
-     * checkpoint entries.
+     * count, committed checkpoint-entry count (one per `.json` in an anchor
+     * group), restore-journal count (both journal prefixes), and the total bytes
+     * the session dir occupies — entry JSONs, raw byte sidecars, `rescue/**` and
+     * the staged `.pending/**` copies alike, so the number matches what a `du` of
+     * that directory reports.
+     *
+     * Walks with `lstat` (never follows a symlink, so a hostile symlink cannot
+     * escape the store root or inflate the measurement) and skips dot-prefixed
+     * temp leftovers (the one exception is `.pending/`, whose staged bytes are
+     * real store content).
      */
     private sessionStats;
     /**
@@ -654,6 +946,28 @@ export declare class SnapshotStore {
      * session that actually records a snapshot.
      */
     setFormatVersion(sessionVersion: number): void;
+    /**
+     * Read the plugin's STORE-format marker for a session, or null when there is
+     * none (a released-v1 dir, or a session that never recorded a snapshot). The
+     * marker is a quick session-level signal; every entry and journal is also
+     * self-describing (`store` / `version`), so a missing marker never changes
+     * how an entry is read.
+     */
+    readStoreVersion(sessionId: string): Promise<number | null>;
+    /**
+     * Stamp the store-format marker (atomically, like `format`). Written
+     * alongside every byte-format entry, so a session that only ever holds the
+     * released string format keeps no marker and is read as v1.
+     */
+    markStoreVersion(sessionId: string, storeVersion: number): Promise<void>;
+    /**
+     * Refuse to plan against (or write into) a session whose store format is
+     * NEWER than this build understands (ADR-10): the caller reports it and
+     * changes nothing — no partial restore, no clear, no v2 entry written into a
+     * v3 store. Checked before any entry is read, so the marker alone is enough
+     * to fail closed.
+     */
+    assertKnownStoreVersion(sessionId: string): Promise<void>;
     /**
      * Session-format-version guard: clear a session's snapshot dir when the
      * format its snapshots were anchored under differs from the current session
@@ -696,8 +1010,8 @@ export declare class SnapshotStore {
  * from the recent record, so the link decision would never apply there.
  *
  * Symlinked / hard-linked paths are never re-checked (restores skip them).
- * A probe failure skips the file with a warning-level no-op; it never
- * aborts the boundary pass.
+ * A probe failure skips the file with a warning-level no-op; it never aborts
+ * the boundary pass, and it never records the path as absent.
  *
  * @param store - the session's snapshot store.
  * @param sessionId - session whose tracked files to re-check.