@armadra/agent 0.4.0 → 0.5.0

package/dist/checkpoints/backend.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 会话侧的检查点后端（与 RW-B 约定的接口）。[RW-A]
+ *
+ * 会话（`src/agent/session-rewind.ts`）只经这里的接口使用检查点：工厂拿到会话上下文后返回后端；
+ * 内存会话不调工厂，`mode: "off"` 时工厂返回 undefined。条目重放在第一次使用时惰性执行。
+ *
+ * `shadow-git`（§6，RW-D）：在 tools 的基础上，每个新回合先做影子快照，提交 id 记进
+ * `CheckpointData.shadowCommit`；恢复时目标有影子提交就以影子差异为准（同时覆盖 edit / write 跟踪的文件），
+ * 否则回退 tools。git 不可用、cwd 是家目录或根目录、文件数或快照耗时超限 → 本会话降级为 tools 并 warn 一次。
+ */
+import type { SessionEntry } from "../session/types.js";
+import { type ShadowGitOptions } from "./shadow-git.js";
+import type { CheckpointHooks, CheckpointMode, CodeRestoreResult } from "./types.js";
+export interface CheckpointBackendContext {
+    cwd: string;
+    /** 全部会话条目（重放 ama.checkpoint* 用；不限活动分支）。 */
+    entries(): readonly SessionEntry[];
+    /** 追加 custom 条目（ama.checkpoint / ama.checkpoint-track）。 */
+    appendCustom(customType: string, data: unknown): void;
+    /** 当前回合的用户消息 id（beforeWrite 追加 checkpoint-track 时用；无回合时 undefined）。 */
+    currentTurn(): string | undefined;
+    log(level: "debug" | "info" | "warn" | "error", message: string): void;
+}
+export interface CheckpointBackend {
+    /** 交给 ToolContext.checkpoint（子会话共用父会话的这一份）。 */
+    readonly hooks: CheckpointHooks;
+    /** 新回合用户消息落盘后调用。 */
+    snapshot(userEntryId: string): Promise<void>;
+    /** 该用户消息有可用检查点（含 keep 上限）。 */
+    hasCheckpoint(userEntryId: string): boolean;
+    /**
+     * 恢复到 userEntryId 之前；dryRun 只做 §3.2 1–4 + diff。
+     * touched = 被恢复 / 删除文件的绝对路径（从 readFiles 移除；dryRun 时为空）。
+     */
+    restore(userEntryId: string, options: {
+        dryRun: boolean;
+        onConflict: "skip" | "overwrite";
+    }): Promise<{
+        result: CodeRestoreResult;
+        touched: string[];
+    }>;
+    /** 记录的 HEAD 与当前不同时返回。 */
+    gitHint(userEntryId: string): Promise<{
+        recordedHead: string;
+        currentHead: string;
+    } | undefined>;
+}
+export type CheckpointBackendFactory = (ctx: CheckpointBackendContext) => CheckpointBackend | undefined;
+export interface CheckpointBackendSettings {
+    mode: CheckpointMode;
+    dataDir: string;
+    maxFileBytes?: number;
+    keep?: number;
+    /** 会话根目录：登记进 file-history/roots.json，GC 标记时会扫描它。 */
+    sessionsRoot?: string;
+    /** 影子 git 的参数（测试注入阈值、git 路径、环境）。 */
+    shadow?: ShadowGitOptions & {
+        homeDir?: string;
+    };
+}
+export declare function createCheckpointBackendFactory(settings: CheckpointBackendSettings): CheckpointBackendFactory;

package/dist/checkpoints/backend.js

@@ -0,0 +1,135 @@
+/**
+ * 会话侧的检查点后端（与 RW-B 约定的接口）。[RW-A]
+ *
+ * 会话（`src/agent/session-rewind.ts`）只经这里的接口使用检查点：工厂拿到会话上下文后返回后端；
+ * 内存会话不调工厂，`mode: "off"` 时工厂返回 undefined。条目重放在第一次使用时惰性执行。
+ *
+ * `shadow-git`（§6，RW-D）：在 tools 的基础上，每个新回合先做影子快照，提交 id 记进
+ * `CheckpointData.shadowCommit`；恢复时目标有影子提交就以影子差异为准（同时覆盖 edit / write 跟踪的文件），
+ * 否则回退 tools。git 不可用、cwd 是家目录或根目录、文件数或快照耗时超限 → 本会话降级为 tools 并 warn 一次。
+ */
+import { registerSessionRoot } from "./gc.js";
+import { loadCheckpoints, isRewindable } from "./replay.js";
+import { emptyCodeResult, gitHintFor, restoreCheckpoint } from "./restore.js";
+import { GitMissingError, ShadowRepo, unsafeShadowCwd, } from "./shadow-git.js";
+import { latestShadowCommit, restoreFromShadow } from "./shadow-restore.js";
+import { CheckpointTracker } from "./tracker.js";
+export function createCheckpointBackendFactory(settings) {
+    return (ctx) => {
+        if (settings.mode === "off")
+            return undefined;
+        let tracker;
+        let registered = false;
+        const warn = (message) => ctx.log("warn", message);
+        const get = () => {
+            tracker ??= new CheckpointTracker({
+                cwd: ctx.cwd,
+                dataDir: settings.dataDir,
+                ...(settings.maxFileBytes !== undefined ? { maxFileBytes: settings.maxFileBytes } : {}),
+                append: (customType, data) => ctx.appendCustom(customType, data),
+                currentTurn: () => ctx.currentTurn(),
+                warn,
+                initial: loadCheckpoints(ctx.entries()),
+            });
+            if (!registered && settings.sessionsRoot !== undefined) {
+                registered = true;
+                registerSessionRoot(settings.dataDir, settings.sessionsRoot).catch((error) => ctx.log("debug", `检查点：登记会话目录失败（${String(error)}）`));
+            }
+            return tracker;
+        };
+        // 影子 git：undefined = 未建；null = 本会话不用（模式不是 shadow-git 或已降级）
+        let shadow = settings.mode === "shadow-git" ? undefined : null;
+        const degrade = (message) => {
+            shadow = null;
+            warn(`检查点：影子 git 不可用（${message}），本会话改用 tools 模式`);
+        };
+        const getShadow = () => {
+            if (shadow !== undefined)
+                return shadow;
+            const unsafe = unsafeShadowCwd(ctx.cwd, settings.shadow?.homeDir);
+            if (unsafe !== undefined) {
+                degrade(unsafe);
+                return null;
+            }
+            shadow = new ShadowRepo(settings.dataDir, ctx.cwd, settings.shadow ?? {});
+            return shadow;
+        };
+        const shadowSnapshot = async (userEntryId) => {
+            const repo = getShadow();
+            if (repo === null)
+                return undefined;
+            try {
+                const parent = latestShadowCommit(get().state);
+                const snap = await repo.snapshot(parent, `ama checkpoint ${userEntryId}`);
+                if (snap.degrade !== undefined)
+                    degrade(snap.degrade.message);
+                return snap.commit;
+            }
+            catch (error) {
+                degrade(error instanceof GitMissingError ? "PATH 里找不到 git" : describe(error));
+                return undefined;
+            }
+        };
+        const hooks = {
+            beforeWrite: (absolutePath) => get().beforeWrite(absolutePath),
+            afterWrite: (absolutePath, content) => get().afterWrite(absolutePath, content),
+        };
+        return {
+            hooks,
+            snapshot: async (userEntryId) => {
+                try {
+                    const shadowCommit = await shadowSnapshot(userEntryId);
+                    await get().snapshot(userEntryId, shadowCommit !== undefined ? { shadowCommit } : {});
+                }
+                catch (error) {
+                    warn(`检查点：建立失败（${describe(error)}）`);
+                }
+            },
+            hasCheckpoint: (userEntryId) => isRewindable(get().state, userEntryId, settings.keep),
+            restore: async (userEntryId, options) => {
+                const t = get();
+                const target = t.state.byUserEntry.get(userEntryId);
+                if (target === undefined || !isRewindable(t.state, userEntryId, settings.keep)) {
+                    return { result: emptyCodeResult(), touched: [] };
+                }
+                const base = {
+                    cwd: ctx.cwd,
+                    dataDir: settings.dataDir,
+                    state: t.state,
+                    target,
+                    lastWritten: t.lastWritten,
+                    dryRun: options.dryRun,
+                    onConflict: options.onConflict,
+                    ...(settings.maxFileBytes !== undefined ? { maxDiffBytes: settings.maxFileBytes } : {}),
+                };
+                // 有影子提交就以影子差异为准（降级前留下的提交照样可用）；影子不可用时回退 tools
+                if (target.shadowCommit !== undefined && settings.mode === "shadow-git") {
+                    const unsafe = unsafeShadowCwd(ctx.cwd, settings.shadow?.homeDir);
+                    if (unsafe === undefined) {
+                        const repo = shadow ?? new ShadowRepo(settings.dataDir, ctx.cwd, settings.shadow ?? {});
+                        try {
+                            return await restoreFromShadow({
+                                ...base,
+                                repo,
+                                ...(settings.maxFileBytes !== undefined
+                                    ? { maxFileBytes: settings.maxFileBytes }
+                                    : {}),
+                            });
+                        }
+                        catch (error) {
+                            warn(`检查点：按影子提交恢复失败（${describe(error)}），改按 tools 记录恢复`);
+                        }
+                    }
+                }
+                return restoreCheckpoint(base);
+            },
+            gitHint: async (userEntryId) => {
+                const target = get().state.byUserEntry.get(userEntryId);
+                return target === undefined ? undefined : gitHintFor(ctx.cwd, target);
+            },
+        };
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/checkpoints/blobs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 检查点备份存储（docs/rewind-plan.md §1.1）。[RW-A]
+ *
+ * - 位置 `<dataDir>/file-history/blobs/<sha256 前 2 位>/<sha256>`，内容为文件原字节；
+ *   先写 `<name>.tmp-<pid>-<序号>` 再 rename，已存在即跳过（内容寻址，同内容只存一份）。
+ * - `recordFile` 把磁盘上一个路径变成 `FileRecord`：不存在记 `blob: null`；符号链接与非普通文件记
+ *   `skipped: "not_regular"`；超过上限记 `skipped: "too_large"`（都不写 blob）。
+ * - 路径键（§1.2）：cwd 内为相对路径（`/` 分隔），cwd 外为绝对路径。
+ */
+import type { FileRecord } from "./types.js";
+export declare const FILE_HISTORY_DIR = "file-history";
+export declare const BLOBS_DIR = "blobs";
+export declare const DEFAULT_MAX_FILE_BYTES: number;
+export declare function fileHistoryDir(dataDir: string): string;
+export declare function blobsDir(dataDir: string): string;
+export declare function isBlobHash(value: unknown): value is string;
+/** blob 的路径；哈希格式不对时抛（防止拼出目录穿越）。 */
+export declare function blobPath(dataDir: string, hash: string): string;
+export declare function hashBytes(bytes: Uint8Array | string): string;
+/** 流式算文件 sha256（不受 maxFileBytes 限制，冲突检测用）。 */
+export declare function hashFile(path: string): Promise<string>;
+/** 写入 blob（已存在跳过），返回哈希。 */
+export declare function putBlob(dataDir: string, bytes: Uint8Array, hash?: string): Promise<string>;
+/** 读 blob；不存在返回 undefined。 */
+export declare function readBlob(dataDir: string, hash: string): Promise<Buffer | undefined>;
+export declare function hasBlob(dataDir: string, hash: string): Promise<boolean>;
+export interface RecordFileOptions {
+    dataDir: string;
+    maxFileBytes?: number;
+}
+/** 记录时一并给出的 lstat 信息（快照沿用判断用）。 */
+export interface RecordedFile {
+    record: FileRecord;
+    /** 记录开始的时间（毫秒）；mtime 不晚于它（减去粒度余量）才可沿用。 */
+    at: number;
+}
+/** 父目录 realpath；父目录不存在时 undefined。 */
+export declare function realParentOf(absolutePath: string): Promise<string | undefined>;
+/** 把磁盘上的一个路径记成 FileRecord（需要时写 blob）。 */
+export declare function recordFile(absolutePath: string, options: RecordFileOptions): Promise<RecordedFile>;
+/** 绝对路径 → 记录键（cwd 内相对、`/` 分隔；cwd 外绝对）。 */
+export declare function pathKey(cwd: string, absolutePath: string): string;
+/** 记录键 → 绝对路径。 */
+export declare function keyToPath(cwd: string, key: string): string;
+export interface BlobUsage {
+    blobs: number;
+    bytes: number;
+}
+/** file-history 的 blob 数与字节数（不含临时文件）。 */
+export declare function blobUsage(dataDir: string): Promise<BlobUsage>;
+export interface BlobFile {
+    path: string;
+    /** 哈希；临时文件为 undefined。 */
+    hash?: string;
+    size: number;
+    mtimeMs: number;
+}
+/** 列出 blob 目录下的文件（含残留的临时文件）。 */
+export declare function listBlobs(dataDir: string, includeTemp?: boolean): Promise<BlobFile[]>;
+export declare function isNotFound(error: unknown): boolean;

package/dist/checkpoints/blobs.js

@@ -0,0 +1,203 @@
+/**
+ * 检查点备份存储（docs/rewind-plan.md §1.1）。[RW-A]
+ *
+ * - 位置 `<dataDir>/file-history/blobs/<sha256 前 2 位>/<sha256>`，内容为文件原字节；
+ *   先写 `<name>.tmp-<pid>-<序号>` 再 rename，已存在即跳过（内容寻址，同内容只存一份）。
+ * - `recordFile` 把磁盘上一个路径变成 `FileRecord`：不存在记 `blob: null`；符号链接与非普通文件记
+ *   `skipped: "not_regular"`；超过上限记 `skipped: "too_large"`（都不写 blob）。
+ * - 路径键（§1.2）：cwd 内为相对路径（`/` 分隔），cwd 外为绝对路径。
+ */
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, utimes, writeFile, } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+export const FILE_HISTORY_DIR = "file-history";
+export const BLOBS_DIR = "blobs";
+export const DEFAULT_MAX_FILE_BYTES = 5 * 1024 * 1024;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+export function fileHistoryDir(dataDir) {
+    return join(dataDir, FILE_HISTORY_DIR);
+}
+export function blobsDir(dataDir) {
+    return join(fileHistoryDir(dataDir), BLOBS_DIR);
+}
+export function isBlobHash(value) {
+    return typeof value === "string" && SHA256_HEX.test(value);
+}
+/** blob 的路径；哈希格式不对时抛（防止拼出目录穿越）。 */
+export function blobPath(dataDir, hash) {
+    if (!isBlobHash(hash))
+        throw new Error(`invalid blob hash: ${hash}`);
+    return join(blobsDir(dataDir), hash.slice(0, 2), hash);
+}
+export function hashBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** 流式算文件 sha256（不受 maxFileBytes 限制，冲突检测用）。 */
+export function hashFile(path) {
+    return new Promise((resolvePromise, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(path);
+        stream.on("error", reject);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolvePromise(hash.digest("hex")));
+    });
+}
+let tmpCounter = 0;
+/** 写入 blob（已存在跳过），返回哈希。 */
+export async function putBlob(dataDir, bytes, hash = hashBytes(bytes)) {
+    const target = blobPath(dataDir, hash);
+    if (await exists(target)) {
+        // 复用旧 blob：刷新 mtime，避免并发的 GC 在新条目落盘前把它当作「未引用且超过 1 天」删掉。
+        const now = new Date();
+        await utimes(target, now, now).catch(() => undefined);
+        return hash;
+    }
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const tmp = `${target}.tmp-${process.pid}-${tmpCounter++}`;
+    try {
+        await writeFile(tmp, bytes, { mode: 0o600 });
+        await rename(tmp, target);
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        if (await exists(target))
+            return hash;
+        throw error;
+    }
+    return hash;
+}
+/** 读 blob；不存在返回 undefined。 */
+export async function readBlob(dataDir, hash) {
+    try {
+        return await readFile(blobPath(dataDir, hash));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+export async function hasBlob(dataDir, hash) {
+    return exists(blobPath(dataDir, hash));
+}
+/** 父目录 realpath；父目录不存在时 undefined。 */
+export async function realParentOf(absolutePath) {
+    try {
+        return await realpath(dirname(absolutePath));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+/** 把磁盘上的一个路径记成 FileRecord（需要时写 blob）。 */
+export async function recordFile(absolutePath, options) {
+    const at = Date.now();
+    const max = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    let info;
+    try {
+        info = await lstat(absolutePath);
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+        const realParentDir = await realParentOf(absolutePath);
+        return {
+            record: { blob: null, ...(realParentDir !== undefined ? { realParentDir } : {}) },
+            at,
+        };
+    }
+    if (!info.isFile())
+        return { record: { blob: null, skipped: "not_regular" }, at };
+    const mode = info.mode & 0o7777;
+    const realParentDir = await realParentOf(absolutePath);
+    const base = { mode, size: info.size, ...(realParentDir !== undefined ? { realParentDir } : {}) };
+    if (info.size > max)
+        return { record: { blob: null, ...base, skipped: "too_large" }, at };
+    const bytes = await readFile(absolutePath);
+    if (bytes.length > max)
+        return { record: { blob: null, ...base, size: bytes.length, skipped: "too_large" }, at };
+    const blob = await putBlob(options.dataDir, bytes);
+    return { record: { blob, ...base, size: bytes.length }, at };
+}
+/** 绝对路径 → 记录键（cwd 内相对、`/` 分隔；cwd 外绝对）。 */
+export function pathKey(cwd, absolutePath) {
+    const abs = resolve(absolutePath);
+    const rel = relative(resolve(cwd), abs);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return abs;
+    return rel.split(sep).join("/");
+}
+/** 记录键 → 绝对路径。 */
+export function keyToPath(cwd, key) {
+    return isAbsolute(key) ? resolve(key) : resolve(cwd, ...key.split("/"));
+}
+/** file-history 的 blob 数与字节数（不含临时文件）。 */
+export async function blobUsage(dataDir) {
+    const usage = { blobs: 0, bytes: 0 };
+    for (const blob of await listBlobs(dataDir)) {
+        usage.blobs++;
+        usage.bytes += blob.size;
+    }
+    return usage;
+}
+/** 列出 blob 目录下的文件（含残留的临时文件）。 */
+export async function listBlobs(dataDir, includeTemp = false) {
+    const root = blobsDir(dataDir);
+    let shards;
+    try {
+        shards = await readdir(root);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const shard of shards) {
+        if (!/^[0-9a-f]{2}$/.test(shard))
+            continue;
+        let names;
+        try {
+            names = await readdir(join(root, shard));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const isBlob = isBlobHash(name) && name.startsWith(shard);
+            if (!isBlob && !(includeTemp && name.includes(".tmp-")))
+                continue;
+            const path = join(root, shard, name);
+            try {
+                const info = await stat(path);
+                if (!info.isFile())
+                    continue;
+                out.push({
+                    path,
+                    ...(isBlob ? { hash: name } : {}),
+                    size: info.size,
+                    mtimeMs: info.mtimeMs,
+                });
+            }
+            catch {
+                // 并发删除：忽略
+            }
+        }
+    }
+    return out;
+}
+export function isNotFound(error) {
+    return error?.code === "ENOENT";
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/checkpoints/gc.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 备份清理（docs/rewind-plan.md §1.4）。[RW-A]
+ *
+ * - 标记：递归扫描会话根目录下全部 `*.jsonl`（含 `.trash/`，trash 里的会话还能找回），凡含
+ *   `ama.checkpoint` 的行，取其中所有 64 位十六进制串作为引用。不解析 JSON：损坏或未来格式的行也只会
+ *   多保留，不会误删。任何会话文件读不了 → 整次 GC 放弃（抛错），不删除任何东西。
+ * - 清除：未被引用且 mtime 早于 `minAgeMs`（缺省 1 天）的 blob；同样年龄的残留临时文件一并删除。
+ * - 会话根目录除调用方给出的以外，还包括 `<dataDir>/file-history/roots.json` 里登记过的（宿主 profile
+ *   的 `sessionDir` 不在缺省位置时，备份仍被看到）。
+ */
+export declare const GC_MIN_AGE_MS: number;
+export declare const ROOTS_FILE = "roots.json";
+/** 已登记的会话根目录。 */
+export declare function readSessionRoots(dataDir: string): Promise<string[]>;
+/** 登记会话根目录（已登记则不写）。 */
+export declare function registerSessionRoot(dataDir: string, sessionsRoot: string): Promise<void>;
+export interface BlobRefs {
+    refs: Set<string>;
+    sessionFiles: number;
+}
+/** 标记：会话根目录下全部会话文件引用的 blob。 */
+export declare function collectBlobRefs(sessionRoots: readonly string[]): Promise<BlobRefs>;
+export interface GcOptions {
+    dataDir: string;
+    /** 要扫描的会话根目录；登记过的根目录自动并入。 */
+    sessionRoots: readonly string[];
+    dryRun?: boolean;
+    /** 缺省 1 天。 */
+    minAgeMs?: number;
+    now?: number;
+}
+export interface GcResult {
+    sessionFiles: number;
+    referenced: number;
+    /** 删除（dryRun 时为将删除）的 blob 与临时文件路径。 */
+    removed: string[];
+    removedBytes: number;
+    /** 保留的 blob 数与字节数。 */
+    kept: {
+        blobs: number;
+        bytes: number;
+    };
+}
+/** 标记 + 清除。 */
+export declare function gcBlobs(options: GcOptions): Promise<GcResult>;
+/** 人读的字节数（doctor / prune 输出）。 */
+export declare function formatBytes(bytes: number): string;

package/dist/checkpoints/gc.js

@@ -0,0 +1,144 @@
+/**
+ * 备份清理（docs/rewind-plan.md §1.4）。[RW-A]
+ *
+ * - 标记：递归扫描会话根目录下全部 `*.jsonl`（含 `.trash/`，trash 里的会话还能找回），凡含
+ *   `ama.checkpoint` 的行，取其中所有 64 位十六进制串作为引用。不解析 JSON：损坏或未来格式的行也只会
+ *   多保留，不会误删。任何会话文件读不了 → 整次 GC 放弃（抛错），不删除任何东西。
+ * - 清除：未被引用且 mtime 早于 `minAgeMs`（缺省 1 天）的 blob；同样年龄的残留临时文件一并删除。
+ * - 会话根目录除调用方给出的以外，还包括 `<dataDir>/file-history/roots.json` 里登记过的（宿主 profile
+ *   的 `sessionDir` 不在缺省位置时，备份仍被看到）。
+ */
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileHistoryDir, isNotFound, listBlobs } from "./blobs.js";
+import { CHECKPOINT_CUSTOM_TYPE } from "./types.js";
+export const GC_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+export const ROOTS_FILE = "roots.json";
+const HASH_IN_LINE = /\b[0-9a-f]{64}\b/g;
+function rootsFile(dataDir) {
+    return join(fileHistoryDir(dataDir), ROOTS_FILE);
+}
+/** 已登记的会话根目录。 */
+export async function readSessionRoots(dataDir) {
+    try {
+        const value = JSON.parse(await readFile(rootsFile(dataDir), "utf8"));
+        const roots = value?.roots;
+        return Array.isArray(roots) ? roots.filter((r) => typeof r === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** 登记会话根目录（已登记则不写）。 */
+export async function registerSessionRoot(dataDir, sessionsRoot) {
+    const root = resolve(sessionsRoot);
+    const roots = await readSessionRoots(dataDir);
+    if (roots.includes(root))
+        return;
+    const dir = fileHistoryDir(dataDir);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${rootsFile(dataDir)}.tmp-${process.pid}`;
+    await writeFile(tmp, `${JSON.stringify({ roots: [...roots, root] }, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await rename(tmp, rootsFile(dataDir));
+}
+async function* sessionFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return;
+        throw error;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* sessionFiles(full);
+        else if (entry.isFile() && entry.name.endsWith(".jsonl"))
+            yield full;
+    }
+}
+/** 标记：会话根目录下全部会话文件引用的 blob。 */
+export async function collectBlobRefs(sessionRoots) {
+    const refs = new Set();
+    let count = 0;
+    const seen = new Set();
+    for (const root of sessionRoots) {
+        const abs = resolve(root);
+        if (seen.has(abs))
+            continue;
+        seen.add(abs);
+        for await (const file of sessionFiles(abs)) {
+            let text;
+            try {
+                text = await readFile(file, "utf8");
+            }
+            catch (error) {
+                if (isNotFound(error))
+                    continue; // 扫描期间被移走：移到的位置（trash）也在扫描范围内或已删
+                throw error;
+            }
+            count++;
+            if (!text.includes(CHECKPOINT_CUSTOM_TYPE))
+                continue;
+            for (const line of text.split("\n")) {
+                if (!line.includes(CHECKPOINT_CUSTOM_TYPE))
+                    continue;
+                for (const match of line.matchAll(HASH_IN_LINE))
+                    refs.add(match[0]);
+            }
+        }
+    }
+    return { refs, sessionFiles: count };
+}
+/** 标记 + 清除。 */
+export async function gcBlobs(options) {
+    const minAge = options.minAgeMs ?? GC_MIN_AGE_MS;
+    const now = options.now ?? Date.now();
+    const roots = [...options.sessionRoots, ...(await readSessionRoots(options.dataDir))];
+    const { refs, sessionFiles: count } = await collectBlobRefs(roots);
+    const result = {
+        sessionFiles: count,
+        referenced: refs.size,
+        removed: [],
+        removedBytes: 0,
+        kept: { blobs: 0, bytes: 0 },
+    };
+    for (const blob of await listBlobs(options.dataDir, true)) {
+        const old = now - blob.mtimeMs > minAge;
+        const unreferenced = blob.hash === undefined || !refs.has(blob.hash);
+        if (old && unreferenced) {
+            if (options.dryRun !== true) {
+                try {
+                    await rm(blob.path, { force: true });
+                }
+                catch {
+                    continue;
+                }
+            }
+            result.removed.push(blob.path);
+            result.removedBytes += blob.size;
+        }
+        else if (blob.hash !== undefined) {
+            result.kept.blobs++;
+            result.kept.bytes += blob.size;
+        }
+    }
+    return result;
+}
+/** 人读的字节数（doctor / prune 输出）。 */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KiB", "MiB", "GiB", "TiB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unit]}`;
+}

package/dist/checkpoints/git-head.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 读 git HEAD（docs/rewind-plan.md §1.2、D6）。[RW-A]
+ *
+ * 不起 git 进程：从 cwd 向上找 `.git`（目录，或 worktree / 子模块的 `gitdir: <路径>` 文件），读 `HEAD`；
+ * 符号引用先查 gitdir 再查 `commondir`（worktree 的分支引用在主仓库），最后查 `packed-refs`。
+ * 读不到（不在仓库、未提交过的分支、格式不认识）返回 undefined。
+ */
+export interface GitHead {
+    head: string;
+    branch?: string;
+}
+/** 找到 cwd 所在仓库的 gitdir；不在仓库返回 undefined。 */
+export declare function findGitDir(cwd: string): Promise<string | undefined>;
+/** cwd 所在仓库的 HEAD 提交与分支；detached 时没有 branch。 */
+export declare function readGitHead(cwd: string): Promise<GitHead | undefined>;