dsh-rewind-plugin 0.21.0 → 0.21.1

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

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

@@ -0,0 +1,85 @@
+/**
+ * Filesystem primitives for the checkpoint store.
+ *
+ * Every operation that can touch the real file system lives here: atomic JSON
+ * writes (temp + rename), streaming byte comparisons (never a whole file in
+ * memory), the on-disk probe that classifies links and non-regular targets,
+ * and the containment checks that keep a restore inside the location it
+ * recorded. Nothing here holds state; the store passes in what it needs.
+ *
+ * @module dsh-rewind/snapshot-fs
+ */
+import { type DiskProbe } from './snapshot-format.ts';
+/** Streaming byte equality of two files (never loads either one whole). */
+export declare function sameFileBytes(aPath: string, bPath: string): Promise<boolean>;
+/** Streaming byte equality of a file against an in-memory buffer. */
+export declare function sameFileBuffer(path: string, bytes: Buffer): Promise<boolean>;
+/** True when the error means "the path does not exist". */
+export declare function isEnoent(error: unknown): boolean;
+/** Production probe: real byte comparisons via node:fs, links via lstat + nlink. */
+export declare const defaultProbe: DiskProbe;
+/**
+ * Atomic JSON file write: serialize to a sibling temp file, then rename over
+ * the target. A crash between the two steps leaves only the temp — never a
+ * readable half-written target — and rename is atomic, so readers always see
+ * either the old file or the complete new one. The temp name is deterministic
+ * (`<target>.tmp`): a crash-leftover temp is overwritten by the next write of
+ * the same target and is never picked up by readers (it does not end in
+ * `.json`). `afterTempWrite` is the test-only crash seam between the steps.
+ */
+export declare function writeJsonAtomic(file: string, data: unknown, afterTempWrite?: () => void): Promise<void>;
+/** Recursive byte total of a directory tree (never follows symlinks). */
+export declare function dirBytes(dir: string): Promise<number>;
+/**
+ * True when the path is not a single regular file: a symlink, a hard link
+ * (`nlink > 1`), a directory, a FIFO or a device. None is ever written,
+ * created or read through on restore — a symlink redirects the operation, a
+ * hard link clobbers every other name of the inode (e.g. pnpm-installed
+ * files), and a FIFO or device either blocks the read or streams forever.
+ * Mirrors Claude Code's "symlinked and hard-linked paths not restored", plus
+ * the non-regular targets its restore guard also refuses.
+ */
+export declare function isUnsafeTarget(path: string): Promise<boolean>;
+/**
+ * Where `path`'s directory resolved when the entry was captured — the location
+ * pin. A directory that does not exist (or does not exist any more) pins where
+ * it WOULD resolve: the `realpath` of its nearest surviving ancestor plus the
+ * missing segments. A link created there later therefore cannot pass as the
+ * same location, which is what makes an unpinned fallback unreachable for a
+ * record this build writes. Undefined only when nothing at all resolves.
+ */
+export declare function locationPin(path: string): Promise<string | undefined>;
+/**
+ * True when `path`'s parent directory still resolves where it did at checkpoint
+ * time (`recorded`, the entry's location pin). Only the path's FINAL component
+ * is checked for links and non-regular files (see {@link isUnsafeTarget});
+ * without this a repointed ancestor
+ * directory would redirect a restore — or, worse, an unlink — outside the
+ * recorded location.
+ *
+ * - no pin (a legacy entry, or a commit that could not resolve its parent) →
+ *   true: the released behavior is preserved;
+ * - the parent resolves to the pinned location → true. A STABLE symlinked
+ *   ancestor resolves identically on both sides (the pin is a `realpath`), so
+ *   a symlinked workspace root is never a false skip;
+ * - the parent resolves elsewhere → false;
+ * - the parent chain is gone → true only while the nearest surviving ancestor
+ *   still resolves INSIDE the pinned location, which keeps "recreate a deleted
+ *   parent directory" working without following a repointed ancestor;
+ * - anything undecidable (a link loop, an unreadable component) → false:
+ *   refuse rather than write into a location that cannot be verified.
+ */
+export declare function parentStillMatches(path: string, recorded: string | undefined): Promise<boolean>;
+/**
+ * Walk one directory tree and compute the total size (regular files only) and
+ * the newest stamp (max `lstat.mtimeMs` over every member, directories
+ * included). `lstat` never follows a symlink, so a hostile symlink inside the
+ * store cannot escape the root or inflate the measurement; a symlink is
+ * counted as one file's own metadata and not descended into. Directory members
+ * beginning with `.` (atomic-write temp leftovers, editor droppings) are
+ * skipped — they are never checkpoint entries.
+ */
+export declare function dirSizeAndLastActive(dir: string): Promise<{
+    size: number;
+    lastActiveMs: number;
+}>;