@armadra/agent 0.4.0 → 0.5.0

package/dist/checkpoints/git-head.js

@@ -0,0 +1,89 @@
+/**
+ * 读 git HEAD（docs/rewind-plan.md §1.2、D6）。[RW-A]
+ *
+ * 不起 git 进程：从 cwd 向上找 `.git`（目录，或 worktree / 子模块的 `gitdir: <路径>` 文件），读 `HEAD`；
+ * 符号引用先查 gitdir 再查 `commondir`（worktree 的分支引用在主仓库），最后查 `packed-refs`。
+ * 读不到（不在仓库、未提交过的分支、格式不认识）返回 undefined。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+const SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+async function readText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 找到 cwd 所在仓库的 gitdir；不在仓库返回 undefined。 */
+export async function findGitDir(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const candidate = join(dir, ".git");
+        try {
+            const info = await stat(candidate);
+            if (info.isDirectory())
+                return candidate;
+            if (info.isFile()) {
+                const text = (await readText(candidate)) ?? "";
+                const match = /^gitdir:\s*(.+?)\s*$/m.exec(text);
+                if (match?.[1] !== undefined) {
+                    return isAbsolute(match[1]) ? match[1] : resolve(dir, match[1]);
+                }
+            }
+        }
+        catch {
+            // 没有 .git：继续向上
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+async function resolveRef(gitDir, ref) {
+    const commonText = await readText(join(gitDir, "commondir"));
+    const commonDir = commonText === undefined
+        ? gitDir
+        : isAbsolute(commonText.trim())
+            ? commonText.trim()
+            : resolve(gitDir, commonText.trim());
+    const dirs = commonDir === gitDir ? [gitDir] : [gitDir, commonDir];
+    for (const dir of dirs) {
+        const text = (await readText(join(dir, ...ref.split("/"))))?.trim();
+        if (text !== undefined && SHA.test(text))
+            return text;
+    }
+    for (const dir of dirs) {
+        const packed = await readText(join(dir, "packed-refs"));
+        if (packed === undefined)
+            continue;
+        for (const line of packed.split("\n")) {
+            const [sha, name] = line.trim().split(/\s+/);
+            if (name === ref && sha !== undefined && SHA.test(sha))
+                return sha;
+        }
+    }
+    return undefined;
+}
+/** cwd 所在仓库的 HEAD 提交与分支；detached 时没有 branch。 */
+export async function readGitHead(cwd) {
+    const gitDir = await findGitDir(cwd);
+    if (gitDir === undefined)
+        return undefined;
+    const head = (await readText(join(gitDir, "HEAD")))?.trim();
+    if (head === undefined)
+        return undefined;
+    if (SHA.test(head))
+        return { head };
+    const match = /^ref:\s*(\S+)$/.exec(head);
+    if (match?.[1] === undefined)
+        return undefined;
+    const ref = match[1];
+    const sha = await resolveRef(gitDir, ref);
+    if (sha === undefined)
+        return undefined;
+    const branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : undefined;
+    return { head: sha, ...(branch !== undefined ? { branch } : {}) };
+}

package/dist/checkpoints/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 检查点（docs/rewind-plan.md）的对外入口。[RW-A]
+ *
+ * 会话接线（RW-B）用 `createCheckpointBackendFactory` + `resolveCheckpointSettings`；
+ * 其余导出给 CLI（GC、占用）与测试。
+ */
+export * from "./types.js";
+export { createCheckpointBackendFactory, type CheckpointBackend, type CheckpointBackendContext, type CheckpointBackendFactory, type CheckpointBackendSettings, } from "./backend.js";
+export { resolveCheckpointSettings, type CheckpointSettings } from "./settings.js";
+export { CheckpointTracker, createCheckpointTracker, type CheckpointTrackerOptions, } from "./tracker.js";
+export { isRewindable, latestCheckpoint, loadCheckpoints, rewindableIds, trackedKeys, type CheckpointEntryLike, type LoadedCheckpoints, } from "./replay.js";
+export { countLineChanges, emptyCodeResult, gitHintFor, restoreCheckpoint, type RestoreOptions, type RestoreOutcome, } from "./restore.js";
+export { collectBlobRefs, formatBytes, gcBlobs, readSessionRoots, registerSessionRoot, type GcOptions, type GcResult, } from "./gc.js";
+export { blobPath, blobUsage, fileHistoryDir, hashBytes, keyToPath, pathKey, putBlob, readBlob, recordFile, type BlobUsage, } from "./blobs.js";
+export { readGitHead, type GitHead } from "./git-head.js";
+export { SHADOW_MAX_FILES, SHADOW_MAX_SNAPSHOT_MS, ShadowRepo, shadowRepoDir, shadowUsage, type ShadowGitOptions, } from "./shadow-git.js";
+export { restoreFromShadow, type ShadowRestoreOptions } from "./shadow-restore.js";

package/dist/checkpoints/index.js

@@ -0,0 +1,17 @@
+/**
+ * 检查点（docs/rewind-plan.md）的对外入口。[RW-A]
+ *
+ * 会话接线（RW-B）用 `createCheckpointBackendFactory` + `resolveCheckpointSettings`；
+ * 其余导出给 CLI（GC、占用）与测试。
+ */
+export * from "./types.js";
+export { createCheckpointBackendFactory, } from "./backend.js";
+export { resolveCheckpointSettings } from "./settings.js";
+export { CheckpointTracker, createCheckpointTracker, } from "./tracker.js";
+export { isRewindable, latestCheckpoint, loadCheckpoints, rewindableIds, trackedKeys, } from "./replay.js";
+export { countLineChanges, emptyCodeResult, gitHintFor, restoreCheckpoint, } from "./restore.js";
+export { collectBlobRefs, formatBytes, gcBlobs, readSessionRoots, registerSessionRoot, } from "./gc.js";
+export { blobPath, blobUsage, fileHistoryDir, hashBytes, keyToPath, pathKey, putBlob, readBlob, recordFile, } from "./blobs.js";
+export { readGitHead } from "./git-head.js";
+export { SHADOW_MAX_FILES, SHADOW_MAX_SNAPSHOT_MS, ShadowRepo, shadowRepoDir, shadowUsage, } from "./shadow-git.js";
+export { restoreFromShadow } from "./shadow-restore.js";

package/dist/checkpoints/replay.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 从会话条目重建检查点（docs/rewind-plan.md §1.2）。[RW-A]
+ *
+ * - 按文件顺序重放全部条目（不限活动分支）里的 `ama.checkpoint` 与 `ama.checkpoint-track`；
+ *   track 并入对应 userEntryId 的检查点（检查点里已有该文件时不覆盖）。
+ * - 每个文件的第一条记录永久作为回退（`earliest`）；最近一条记录与其条目时间（`latest`）给快照沿用判断。
+ * - 形状不对的条目跳过（不抛）：会话文件可能来自更新的版本。
+ */
+import { type CheckpointData, type CheckpointTrackData, type FileRecord } from "./types.js";
+/** 重放需要的最小条目形状（SessionEntry 满足）。 */
+export interface CheckpointEntryLike {
+    type: string;
+    customType?: string;
+    data?: unknown;
+    /** ISO 8601。 */
+    timestamp?: string;
+}
+export interface LoadedCheckpoints {
+    /** userEntryId → 检查点（含并入的 track）。 */
+    byUserEntry: Map<string, CheckpointData>;
+    /** userEntryId，按第一次出现的顺序（从旧到新）。 */
+    order: string[];
+    /** 路径键 → 该文件最早的记录。 */
+    earliest: Map<string, FileRecord>;
+    /** 路径键 → 最近一条记录与其条目时间（毫秒；条目无时间时 0）。 */
+    latest: Map<string, {
+        record: FileRecord;
+        at: number;
+    }>;
+}
+export declare function emptyCheckpoints(): LoadedCheckpoints;
+/** 校验并规整一条 FileRecord；不合法返回 undefined。 */
+export declare function parseFileRecord(value: unknown): FileRecord | undefined;
+/** 把一条检查点并进已加载状态（重放与运行时追加共用）。 */
+export declare function applyCheckpoint(state: LoadedCheckpoints, data: CheckpointData, at: number): void;
+/** 把一条 track 并进已加载状态。 */
+export declare function applyTrack(state: LoadedCheckpoints, track: CheckpointTrackData, at: number): void;
+/** 重放会话条目（全文件，不限活动分支）。 */
+export declare function loadCheckpoints(entries: Iterable<CheckpointEntryLike>): LoadedCheckpoints;
+export declare const DEFAULT_CHECKPOINT_KEEP = 100;
+/** 仍可作为回滚点的 userEntryId（最近 `keep` 个检查点，§1.3）。 */
+export declare function rewindableIds(state: LoadedCheckpoints, keep?: number): Set<string>;
+/** 该用户消息是否有可用检查点（含 keep 上限）。 */
+export declare function isRewindable(state: LoadedCheckpoints, userEntryId: string, keep?: number): boolean;
+/** 文件顺序上最后一个检查点（冲突检测的「最近检查点」）。 */
+export declare function latestCheckpoint(state: LoadedCheckpoints): CheckpointData | undefined;
+/** 全部出现过的路径键（= 已跟踪文件）。 */
+export declare function trackedKeys(state: LoadedCheckpoints): string[];

package/dist/checkpoints/replay.js

@@ -0,0 +1,154 @@
+/**
+ * 从会话条目重建检查点（docs/rewind-plan.md §1.2）。[RW-A]
+ *
+ * - 按文件顺序重放全部条目（不限活动分支）里的 `ama.checkpoint` 与 `ama.checkpoint-track`；
+ *   track 并入对应 userEntryId 的检查点（检查点里已有该文件时不覆盖）。
+ * - 每个文件的第一条记录永久作为回退（`earliest`）；最近一条记录与其条目时间（`latest`）给快照沿用判断。
+ * - 形状不对的条目跳过（不抛）：会话文件可能来自更新的版本。
+ */
+import { isBlobHash } from "./blobs.js";
+import { CHECKPOINT_CUSTOM_TYPE, CHECKPOINT_TRACK_CUSTOM_TYPE, } from "./types.js";
+export function emptyCheckpoints() {
+    return { byUserEntry: new Map(), order: [], earliest: new Map(), latest: new Map() };
+}
+const SKIP_REASONS = new Set(["too_large", "not_regular"]);
+/** 校验并规整一条 FileRecord；不合法返回 undefined。 */
+export function parseFileRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const v = value;
+    const blob = v["blob"];
+    if (blob !== null && !isBlobHash(blob))
+        return undefined;
+    const record = { blob };
+    if (typeof v["mode"] === "number")
+        record.mode = v["mode"];
+    if (typeof v["size"] === "number")
+        record.size = v["size"];
+    if (typeof v["realParentDir"] === "string")
+        record.realParentDir = v["realParentDir"];
+    const skipped = v["skipped"];
+    if (typeof skipped === "string" && SKIP_REASONS.has(skipped)) {
+        record.skipped = skipped;
+    }
+    return record;
+}
+function parseCheckpoint(data) {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const d = data;
+    if (d["v"] !== 1 || typeof d["userEntryId"] !== "string")
+        return undefined;
+    const files = {};
+    const rawFiles = d["files"];
+    if (typeof rawFiles === "object" && rawFiles !== null) {
+        for (const [key, raw] of Object.entries(rawFiles)) {
+            const record = parseFileRecord(raw);
+            if (record !== undefined)
+                files[key] = record;
+        }
+    }
+    const out = { v: 1, userEntryId: d["userEntryId"], files };
+    const git = d["git"];
+    if (typeof git === "object" && git !== null && typeof git["head"] === "string") {
+        out.git = {
+            head: git["head"],
+            ...(typeof git["branch"] === "string" ? { branch: git["branch"] } : {}),
+        };
+    }
+    if (typeof d["shadowCommit"] === "string")
+        out.shadowCommit = d["shadowCommit"];
+    return out;
+}
+function parseTrack(data) {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const d = data;
+    if (d["v"] !== 1 || typeof d["userEntryId"] !== "string" || typeof d["path"] !== "string") {
+        return undefined;
+    }
+    const record = parseFileRecord(d["record"]);
+    if (record === undefined)
+        return undefined;
+    return { v: 1, userEntryId: d["userEntryId"], path: d["path"], record };
+}
+function timeOf(entry) {
+    const t = entry.timestamp === undefined ? NaN : Date.parse(entry.timestamp);
+    return Number.isFinite(t) ? t : 0;
+}
+/** 把一条检查点并进已加载状态（重放与运行时追加共用）。 */
+export function applyCheckpoint(state, data, at) {
+    const existing = state.byUserEntry.get(data.userEntryId);
+    if (existing === undefined) {
+        state.byUserEntry.set(data.userEntryId, { ...data, files: { ...data.files } });
+        state.order.push(data.userEntryId);
+    }
+    else {
+        // 同一回合的检查点重复出现（重试快照等）：以后来的为准，保留已并入的 track。
+        existing.files = { ...existing.files, ...data.files };
+        if (data.git !== undefined)
+            existing.git = data.git;
+        if (data.shadowCommit !== undefined)
+            existing.shadowCommit = data.shadowCommit;
+    }
+    for (const [key, record] of Object.entries(data.files))
+        noteRecord(state, key, record, at);
+}
+/** 把一条 track 并进已加载状态。 */
+export function applyTrack(state, track, at) {
+    let checkpoint = state.byUserEntry.get(track.userEntryId);
+    if (checkpoint === undefined) {
+        checkpoint = { v: 1, userEntryId: track.userEntryId, files: {} };
+        state.byUserEntry.set(track.userEntryId, checkpoint);
+        state.order.push(track.userEntryId);
+    }
+    if (checkpoint.files[track.path] === undefined)
+        checkpoint.files[track.path] = track.record;
+    noteRecord(state, track.path, track.record, at);
+}
+function noteRecord(state, key, record, at) {
+    if (!state.earliest.has(key))
+        state.earliest.set(key, record);
+    state.latest.set(key, { record, at });
+}
+/** 重放会话条目（全文件，不限活动分支）。 */
+export function loadCheckpoints(entries) {
+    const state = emptyCheckpoints();
+    for (const entry of entries) {
+        if (entry.type !== "custom")
+            continue;
+        if (entry.customType === CHECKPOINT_CUSTOM_TYPE) {
+            const data = parseCheckpoint(entry.data);
+            if (data !== undefined)
+                applyCheckpoint(state, data, timeOf(entry));
+        }
+        else if (entry.customType === CHECKPOINT_TRACK_CUSTOM_TYPE) {
+            const track = parseTrack(entry.data);
+            if (track !== undefined)
+                applyTrack(state, track, timeOf(entry));
+        }
+    }
+    return state;
+}
+export const DEFAULT_CHECKPOINT_KEEP = 100;
+/** 仍可作为回滚点的 userEntryId（最近 `keep` 个检查点，§1.3）。 */
+export function rewindableIds(state, keep = DEFAULT_CHECKPOINT_KEEP) {
+    const n = Math.max(0, Math.floor(keep));
+    return new Set(n === 0 ? [] : state.order.slice(-n));
+}
+/** 该用户消息是否有可用检查点（含 keep 上限）。 */
+export function isRewindable(state, userEntryId, keep = DEFAULT_CHECKPOINT_KEEP) {
+    if (!state.byUserEntry.has(userEntryId))
+        return false;
+    const index = state.order.lastIndexOf(userEntryId);
+    return index >= 0 && index >= state.order.length - Math.max(0, Math.floor(keep));
+}
+/** 文件顺序上最后一个检查点（冲突检测的「最近检查点」）。 */
+export function latestCheckpoint(state) {
+    const id = state.order[state.order.length - 1];
+    return id === undefined ? undefined : state.byUserEntry.get(id);
+}
+/** 全部出现过的路径键（= 已跟踪文件）。 */
+export function trackedKeys(state) {
+    return [...state.earliest.keys()];
+}

package/dist/checkpoints/restore.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 恢复代码（docs/rewind-plan.md §3.2）。[RW-A]
+ *
+ * 对每个已跟踪文件，取目标检查点里的记录，没有则取该文件最早的记录：
+ * 1. 记录 `skipped` → 报告 too_large / not_regular；
+ *    （目标当前是符号链接 / 非普通文件时无法比较内容，直接按第 4 步报告 symlink / not_regular）
+ * 2. 当前内容与记录相同 → 跳过（不计入）；
+ * 3. 冲突：当前 sha256 ∉ {lastWritten，最近检查点的记录} → skip 时列入 conflicts 不动；
+ * 4. 安全检查：nlink > 1、父目录 realpath ≠ realParentDir → skipped；备份 blob 不在 → backup_missing；
+ * 5. `blob: null` → 删除（只删普通文件）；
+ * 6. 写回：Windows 以外用 O_NOFOLLOW 打开，fstat 与 lstat 的 dev / ino 一致才写；清空后写入并恢复 mode；
+ *    目标不存在时建父目录并再次校验；
+ * 7. 被恢复 / 删除的绝对路径作为 `touched` 返回，由调用方从 readFiles 移除。
+ *
+ * 单文件的 1–6 是 `restoreFile`，结果汇总是 `settleFile`；影子 git（`shadow-restore.ts`）复用二者，
+ * 只换掉「目标内容从哪来」（`load`）与「当前内容算不算已知」（`isKnown`）。
+ *
+ * `dryRun` 只做 1–4，并用行级 diff 计 insertions / deletions（复用 tools/edit 的 unifiedDiff）。
+ */
+import { type LoadedCheckpoints } from "./replay.js";
+import type { CheckpointData, CodeRestoreResult, FileRecord, RewindSkipReason } from "./types.js";
+export interface RestoreOptions {
+    cwd: string;
+    dataDir: string;
+    /** 重放 / tracker 的状态（提供已跟踪文件、最早记录与最近检查点）。 */
+    state: LoadedCheckpoints;
+    /** 回滚目标。 */
+    target: CheckpointData;
+    /** ama 最后写入的内容哈希（绝对路径 → sha256）。 */
+    lastWritten?: ReadonlyMap<string, string>;
+    dryRun?: boolean;
+    onConflict?: "skip" | "overwrite";
+    /** 超过它的当前文件不读内容算行数（缺省 5 MiB）。 */
+    maxDiffBytes?: number;
+    /** 只处理这些路径键（缺省全部已跟踪文件）。 */
+    keys?: Iterable<string>;
+}
+export interface RestoreOutcome {
+    result: CodeRestoreResult;
+    /** 被恢复 / 删除的绝对路径（dryRun 时为空）；调用方从 readFiles 移除。 */
+    touched: string[];
+}
+/** 单文件不恢复的原因（安全检查不通过等）；`settleFile` 把它记进 `skipped`。 */
+export declare class RestoreSkip extends Error {
+    readonly reason: RewindSkipReason;
+    constructor(reason: RewindSkipReason);
+}
+/** 没有可恢复内容时的结果。 */
+export declare function emptyCodeResult(): CodeRestoreResult;
+/** 行级增删数（current → target）。 */
+export declare function countLineChanges(current: string, target: string): {
+    insertions: number;
+    deletions: number;
+};
+/** 恢复到目标检查点（§3.2）。 */
+export declare function restoreCheckpoint(options: RestoreOptions): Promise<RestoreOutcome>;
+/** 单文件恢复的环境。 */
+export interface FileRestoreContext {
+    dataDir: string;
+    dryRun?: boolean;
+    onConflict?: "skip" | "overwrite";
+    /** 超过它的当前文件不读内容算行数。 */
+    maxDiff: number;
+    /** 当前内容（sha256；不存在为 null）是 ama 写的或最近检查点记录的 → 不算冲突（§3.2 第 3 步）。 */
+    isKnown(currentHash: string | null): boolean;
+    /** 取目标内容；缺省按 `record.blob` 读备份。返回 undefined → backup_missing。 */
+    load?(record: FileRecord): Promise<Buffer | undefined>;
+}
+export interface FileOutcome {
+    deleted: boolean;
+    conflict: boolean;
+    insertions: number;
+    deletions: number;
+}
+/** 执行单文件恢复并把结果并进 `result` / `touched`（RestoreSkip → skipped，其它错误 → failed）。 */
+export declare function settleFile(result: CodeRestoreResult, touched: string[], key: string, abs: string, options: {
+    dryRun?: boolean;
+    onConflict?: "skip" | "overwrite";
+}, work: () => Promise<FileOutcome | undefined>): Promise<void>;
+/** §3.2 的 1–6（单个文件）；内容相同返回 undefined。 */
+export declare function restoreFile(abs: string, record: FileRecord, options: FileRestoreContext): Promise<FileOutcome | undefined>;
+/** 记录的 HEAD 与当前不同时给出（只提示，不操作 git）。 */
+export declare function gitHintFor(cwd: string, target: CheckpointData): Promise<{
+    recordedHead: string;
+    currentHead: string;
+} | undefined>;

package/dist/checkpoints/restore.js

@@ -0,0 +1,263 @@
+/**
+ * 恢复代码（docs/rewind-plan.md §3.2）。[RW-A]
+ *
+ * 对每个已跟踪文件，取目标检查点里的记录，没有则取该文件最早的记录：
+ * 1. 记录 `skipped` → 报告 too_large / not_regular；
+ *    （目标当前是符号链接 / 非普通文件时无法比较内容，直接按第 4 步报告 symlink / not_regular）
+ * 2. 当前内容与记录相同 → 跳过（不计入）；
+ * 3. 冲突：当前 sha256 ∉ {lastWritten，最近检查点的记录} → skip 时列入 conflicts 不动；
+ * 4. 安全检查：nlink > 1、父目录 realpath ≠ realParentDir → skipped；备份 blob 不在 → backup_missing；
+ * 5. `blob: null` → 删除（只删普通文件）；
+ * 6. 写回：Windows 以外用 O_NOFOLLOW 打开，fstat 与 lstat 的 dev / ino 一致才写；清空后写入并恢复 mode；
+ *    目标不存在时建父目录并再次校验；
+ * 7. 被恢复 / 删除的绝对路径作为 `touched` 返回，由调用方从 readFiles 移除。
+ *
+ * 单文件的 1–6 是 `restoreFile`，结果汇总是 `settleFile`；影子 git（`shadow-restore.ts`）复用二者，
+ * 只换掉「目标内容从哪来」（`load`）与「当前内容算不算已知」（`isKnown`）。
+ *
+ * `dryRun` 只做 1–4，并用行级 diff 计 insertions / deletions（复用 tools/edit 的 unifiedDiff）。
+ */
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, realpath, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+import { unifiedDiff } from "../tools/edit.js";
+import { DEFAULT_MAX_FILE_BYTES, hashFile, isNotFound, keyToPath, readBlob, realParentOf, } from "./blobs.js";
+import { readGitHead } from "./git-head.js";
+import { latestCheckpoint } from "./replay.js";
+/** 单文件不恢复的原因（安全检查不通过等）；`settleFile` 把它记进 `skipped`。 */
+export class RestoreSkip extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+const Skip = RestoreSkip;
+const IS_WINDOWS = process.platform === "win32";
+/** Windows 没有 O_NOFOLLOW（为 undefined）；只靠 lstat 与 fstat 的 dev / ino 比较。 */
+const NOFOLLOW = IS_WINDOWS ? 0 : (constants.O_NOFOLLOW ?? 0);
+/** 没有可恢复内容时的结果。 */
+export function emptyCodeResult() {
+    return {
+        restored: [],
+        deleted: [],
+        conflicts: [],
+        skipped: [],
+        failed: [],
+        insertions: 0,
+        deletions: 0,
+    };
+}
+async function lstatOrUndefined(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+function toText(bytes) {
+    return bytes === undefined ? "" : bytes.toString("utf8");
+}
+/** 行级增删数（current → target）。 */
+export function countLineChanges(current, target) {
+    let insertions = 0;
+    let deletions = 0;
+    const diff = unifiedDiff(current, target, "f", 0);
+    const lines = diff === "" ? [] : diff.split("\n").slice(2);
+    for (const line of lines) {
+        if (line.startsWith("+"))
+            insertions++;
+        else if (line.startsWith("-"))
+            deletions++;
+    }
+    return { insertions, deletions };
+}
+/** 恢复到目标检查点（§3.2）。 */
+export async function restoreCheckpoint(options) {
+    const result = emptyCodeResult();
+    const touched = [];
+    const latest = latestCheckpoint(options.state);
+    const maxDiff = options.maxDiffBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const only = options.keys === undefined ? undefined : new Set(options.keys);
+    for (const [key, earliest] of options.state.earliest) {
+        if (only !== undefined && !only.has(key))
+            continue;
+        const record = options.target.files[key] ?? earliest;
+        const abs = keyToPath(options.cwd, key);
+        const known = new Set();
+        const written = options.lastWritten?.get(abs);
+        if (written !== undefined)
+            known.add(written);
+        const latestRecord = latest?.files[key];
+        if (latestRecord !== undefined && latestRecord.skipped === undefined) {
+            known.add(latestRecord.blob);
+        }
+        await settleFile(result, touched, key, abs, options, () => restoreFile(abs, record, {
+            dataDir: options.dataDir,
+            ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+            ...(options.onConflict !== undefined ? { onConflict: options.onConflict } : {}),
+            maxDiff,
+            isKnown: (hash) => known.has(hash),
+        }));
+    }
+    return { result, touched };
+}
+/** 执行单文件恢复并把结果并进 `result` / `touched`（RestoreSkip → skipped，其它错误 → failed）。 */
+export async function settleFile(result, touched, key, abs, options, work) {
+    try {
+        const outcome = await work();
+        if (outcome === undefined)
+            return;
+        if (outcome.conflict)
+            result.conflicts.push(key);
+        if (outcome.conflict && options.onConflict !== "overwrite")
+            return;
+        result.insertions += outcome.insertions;
+        result.deletions += outcome.deletions;
+        if (outcome.deleted)
+            result.deleted.push(key);
+        else
+            result.restored.push(key);
+        if (options.dryRun !== true)
+            touched.push(abs);
+    }
+    catch (error) {
+        if (error instanceof RestoreSkip)
+            result.skipped.push({ path: key, reason: error.reason });
+        else
+            result.failed.push({
+                path: key,
+                message: error instanceof Error ? error.message : String(error),
+            });
+    }
+}
+/** §3.2 的 1–6（单个文件）；内容相同返回 undefined。 */
+export async function restoreFile(abs, record, options) {
+    // 1. 记录时就没备份
+    if (record.skipped !== undefined)
+        throw new Skip(record.skipped);
+    // 当前状态
+    const info = await lstatOrUndefined(abs);
+    if (info?.isSymbolicLink() === true)
+        throw new Skip("symlink");
+    if (info !== undefined && !info.isFile())
+        throw new Skip("not_regular");
+    const currentHash = info === undefined ? null : await hashFile(abs);
+    // 2. 内容相同
+    if (currentHash === record.blob)
+        return undefined;
+    // 3. 冲突
+    const conflict = !options.isKnown(currentHash);
+    if (conflict && options.onConflict !== "overwrite") {
+        return { deleted: record.blob === null, conflict, insertions: 0, deletions: 0 };
+    }
+    // 4. 安全检查
+    if (info !== undefined && info.nlink > 1)
+        throw new Skip("hardlink");
+    await checkParent(abs, record);
+    const targetBytes = record.blob === null
+        ? undefined
+        : await (options.load ?? ((r) => readBlob(options.dataDir, r.blob)))(record);
+    if (record.blob !== null && targetBytes === undefined)
+        throw new Skip("backup_missing");
+    const currentBytes = info !== undefined && info.size <= options.maxDiff ? await readFile(abs) : undefined;
+    const counted = info !== undefined && currentBytes === undefined
+        ? { insertions: 0, deletions: 0 }
+        : countLineChanges(toText(currentBytes), toText(targetBytes));
+    const outcome = { deleted: record.blob === null, conflict, ...counted };
+    if (options.dryRun === true)
+        return outcome;
+    if (record.blob === null) {
+        // 5. 删除（当前一定存在：不存在时第 2 步已跳过）
+        await removeRegular(abs, info);
+    }
+    else {
+        // 6. 写回
+        await writeBack(abs, targetBytes, record, info);
+    }
+    return outcome;
+}
+async function checkParent(abs, record) {
+    if (record.realParentDir === undefined)
+        return;
+    const real = await realParentOf(abs);
+    if (real !== undefined && real !== record.realParentDir)
+        throw new Skip("parent_moved");
+}
+async function removeRegular(abs, before) {
+    const now = await lstatOrUndefined(abs);
+    if (now === undefined)
+        return;
+    if (now.isSymbolicLink())
+        throw new Skip("symlink");
+    if (!now.isFile())
+        throw new Skip("not_regular");
+    if (now.nlink > 1)
+        throw new Skip("hardlink");
+    if (now.dev !== before.dev || now.ino !== before.ino)
+        throw new Error("文件在恢复期间被替换");
+    await unlink(abs);
+}
+async function writeBack(abs, bytes, record, before) {
+    if (before === undefined) {
+        const parent = dirname(abs);
+        await mkdir(parent, { recursive: true });
+        if (record.realParentDir !== undefined && (await realpath(parent)) !== record.realParentDir) {
+            throw new Skip("parent_moved");
+        }
+        const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW;
+        const handle = await open(abs, flags, record.mode ?? 0o644);
+        try {
+            await handle.writeFile(bytes);
+            if (record.mode !== undefined)
+                await handle.chmod(record.mode);
+        }
+        finally {
+            await handle.close();
+        }
+        return;
+    }
+    let handle;
+    try {
+        handle = await open(abs, constants.O_WRONLY | NOFOLLOW);
+    }
+    catch (error) {
+        // O_NOFOLLOW 打开符号链接：ELOOP（Linux / macOS）或 EMLINK（FreeBSD）
+        const code = error.code;
+        if (code === "ELOOP" || code === "EMLINK")
+            throw new Skip("symlink");
+        throw error;
+    }
+    try {
+        const opened = await handle.stat();
+        const now = await lstat(abs);
+        if (!opened.isFile() ||
+            opened.dev !== before.dev ||
+            opened.ino !== before.ino ||
+            now.dev !== opened.dev ||
+            now.ino !== opened.ino) {
+            throw new Error("文件在恢复期间被替换");
+        }
+        if (opened.nlink > 1)
+            throw new Skip("hardlink");
+        await handle.truncate(0);
+        await handle.write(bytes, 0, bytes.length, 0);
+        if (record.mode !== undefined)
+            await handle.chmod(record.mode);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** 记录的 HEAD 与当前不同时给出（只提示，不操作 git）。 */
+export async function gitHintFor(cwd, target) {
+    if (target.git === undefined)
+        return undefined;
+    const current = await readGitHead(cwd);
+    if (current === undefined || current.head === target.git.head)
+        return undefined;
+    return { recordedHead: target.git.head, currentHead: current.head };
+}