berry-agent 0.1.0-alpha.1

package/dist/checkpoint/restore.js

@@ -0,0 +1,172 @@
+/**
+ * checkpoint 回退执行（05 §5.3 批 15d——/rewind 两段事务的程序面真身）。
+ *
+ * preview（段一，零改动承诺）：只读对账——当前 walk 域哈希清单 vs manifest
+ * 文件表，报恢复 N（内容异或缺席）/ 删除 M（manifest 外新文件）/ 不动 U
+ * （哈希同）。纯读面：不写不删不 fork。
+ *
+ * restore（段二，三步序）：
+ *   ① pre-rewind 保底快照先行——把「即将被回退覆盖的现状」先拍下来
+ *      （rewind 自身可回退——痕迹可清算）；
+ *   ② 文件恢复——逐 manifest 条目 tmp+rename 原子写（哈希同则不写——
+ *      保 mtime；缺席父目录 mkdir recursive）+ walk 域内真恢复（manifest
+ *      外文件删除 + 空目录自底向上清剪、根不删）。中途崩溃重跑同
+ *      manifest 幂等收敛（v1 诚实边界：无整事务原子性，靠逐文件原子 +
+ *      重跑收敛）；
+ *   ③ fork(upToSeq = manifest.boundarySeq)——旧史保留，新会话净边界起跑
+ *      （05 §5.0 净边界纪律：不破「不在进行中 turn 中间切」）。fork 被
+ *      veto 时文件已恢复（序是保底→恢复→fork 的规范序）——回执诚实报
+ *      vetoReason，痕迹链完整。
+ *
+ * 错误分码：manifest 缺席 = NOT_FOUND；仓坏形 = STORE_CORRUPT（blob 读
+ * 侧 fail-loud 直通透传）；恢复执行 IO 失败 = RESTORE_FAILED（保底快照
+ * 在场，重跑收敛）。
+ */
+import { mkdir, readdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { BaseError } from '../contracts/index.js';
+import { createCapture } from './capture.js';
+import { contentHash } from './store.js';
+import { readWorkspaceFile, walkWorkspaceFiles } from './walk.js';
+/** 恢复执行 IO 失败折 RESTORE_FAILED（保底快照在场——重跑同 manifest 收敛） */
+function restoreFailed(detail) {
+    return new BaseError('CHECKPOINT_RESTORE_FAILED', `[CHECKPOINT_RESTORE_FAILED] 恢复执行失败：${detail}`);
+}
+/** 当前 walk 域哈希清单（preview/restore 共用对账基线——单遍读+哈希） */
+async function currentHashes(root) {
+    const walked = await walkWorkspaceFiles(root);
+    const out = new Map();
+    for (const file of walked) {
+        out.set(file.path, contentHash(await readWorkspaceFile(file.absPath)));
+    }
+    return out;
+}
+/** 逐文件 tmp+rename 原子写（与 store.atomicWrite 同 idiom——恢复面独立成文） */
+async function atomicWriteFile(absPath, content) {
+    try {
+        await mkdir(dirname(absPath), { recursive: true });
+        const tmp = `${absPath}.rewind-tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+        await writeFile(tmp, content);
+        await rename(tmp, absPath);
+    }
+    catch (err) {
+        throw restoreFailed(`写 ${absPath}（${err instanceof Error ? err.message : String(err)}）`);
+    }
+}
+/** 空目录自底向上清剪（删除步的后置——根自身不删；非空/竞态吞错继续） */
+async function pruneEmptyDirs(root, dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    // 先清子目录再判本层（只含空目录的目录也该清）；符号链目录 Dirent 谓词
+    // 恒 false 不入——不 rmdir 间接层
+    for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        if (!entry.isDirectory())
+            continue;
+        await pruneEmptyDirs(root, join(dir, entry.name));
+    }
+    if (dir === root)
+        return; // 根不删（删根 = 删工作区本身）
+    try {
+        await rmdir(dir);
+    }
+    catch {
+        // 非空（gitignore 域内文件等）或竞态——保留，重跑幂等
+    }
+}
+/** 段一：preview（只读对账——恢复 N / 删除 M / 不动 U；不写不删不 fork） */
+export async function previewRewind(store, id) {
+    const manifest = await store.loadManifest(id); // NOT_FOUND / STORE_CORRUPT 直通
+    const current = await currentHashes(manifest.workspaceRoot);
+    const manifestMap = new Map(manifest.files.map((f) => [f.path, f.hash]));
+    let restoreCount = 0;
+    let deleteCount = 0;
+    let untouchedCount = 0;
+    for (const [path, hash] of current) {
+        const want = manifestMap.get(path);
+        if (want === undefined)
+            deleteCount += 1;
+        else if (want === hash)
+            untouchedCount += 1;
+        else
+            restoreCount += 1;
+    }
+    // manifest 有而当前缺席（删过/现为 gitignore 域外）——同入恢复账
+    for (const f of manifest.files) {
+        if (!current.has(f.path))
+            restoreCount += 1;
+    }
+    return { manifest, restoreCount, deleteCount, untouchedCount };
+}
+/** 段二：restore 三步序（保底快照 → 文件恢复 → fork） */
+export async function restoreRewind(deps, id) {
+    const manifest = await deps.store.loadManifest(id); // NOT_FOUND / STORE_CORRUPT 直通
+    /* ---- ① pre-rewind 保底快照（rewind 自身可回退——痕迹可清算） ---- */
+    const snapshotOwner = deps.invokingSessionId ?? manifest.sessionId;
+    const boundary = (deps.session !== undefined && deps.invokingSessionId !== undefined
+        ? deps.session.contextOf(deps.invokingSessionId)?.lastClosedBoundary
+        : undefined) ?? -1;
+    const capture = createCapture(deps.store, { now: deps.now, newId: deps.newId });
+    const preRewind = await capture({
+        sessionId: snapshotOwner,
+        boundarySeq: boundary,
+        workspaceRoot: manifest.workspaceRoot,
+        trigger: 'pre-rewind',
+    });
+    /* ---- ② 文件恢复（walk 域内真恢复：改/补 manifest 条目 + 删域外文件 + 清空目录） ---- */
+    const current = await currentHashes(manifest.workspaceRoot);
+    const manifestMap = new Map(manifest.files.map((f) => [f.path, f.hash]));
+    let restoredCount = 0;
+    let deletedCount = 0;
+    let untouchedCount = 0;
+    // ②a 逐 manifest 条目：哈希同不动（保 mtime）；异/缺席读 blob 原子写回
+    for (const entry of manifest.files) {
+        if (current.get(entry.path) === entry.hash) {
+            untouchedCount += 1;
+            continue;
+        }
+        const content = await deps.store.readBlob(entry.hash); // STORE_CORRUPT fail-loud 直通
+        await atomicWriteFile(join(manifest.workspaceRoot, ...entry.path.split('/')), content);
+        restoredCount += 1;
+    }
+    // ②b walk 域内 manifest 外文件删除（真恢复——不留快照后新增物）
+    for (const path of current.keys()) {
+        if (manifestMap.has(path))
+            continue;
+        try {
+            await rm(join(manifest.workspaceRoot, ...path.split('/')), { force: true });
+        }
+        catch (err) {
+            throw restoreFailed(`删 ${path}（${err instanceof Error ? err.message : String(err)}）`);
+        }
+        deletedCount += 1;
+    }
+    // ②c 空目录自底向上清剪（删除步后置；根不删）
+    await pruneEmptyDirs(manifest.workspaceRoot, manifest.workspaceRoot);
+    /* ---- ③ fork（旧史保留——新会话净边界起跑；veto 不回滚文件恢复） ---- */
+    const outcome = await deps.fork.fork(manifest.sessionId, {
+        upToSeq: manifest.boundarySeq,
+        title: `rewind:${manifest.id}`,
+    });
+    return outcome.status === 'forked'
+        ? {
+            id: manifest.id,
+            preRewindId: preRewind.id,
+            restoredCount,
+            deletedCount,
+            untouchedCount,
+            forkedSessionId: outcome.sessionId,
+        }
+        : {
+            id: manifest.id,
+            preRewindId: preRewind.id,
+            restoredCount,
+            deletedCount,
+            untouchedCount,
+            vetoReason: outcome.reason,
+        };
+}

package/dist/checkpoint/store.js

@@ -0,0 +1,247 @@
+/**
+ * checkpoint 快照仓（05 §5.3 批 15d——纯文件域存储面，零 SQLite 表不占迁移号）。
+ *
+ * 布局：`<dataDir>/data/checkpoint/` 下——
+ *   blobs/<hash 前二>/<sha256>   内容寻址 blob（跨 workspace 共享天然去重；
+ *                                tmp+rename 原子写；写前查在场跳过——同内容
+ *                                零重写）
+ *   manifests/<id>.json          manifest 目录面（files 即恢复清单）
+ *
+ * 坏形两分（02 §5.3 批 15d 四码语义）：id 缺席/坏形 = CHECKPOINT_NOT_FOUND
+ * （/rewind 作用目标守卫）；manifest JSON 坏形、blob 缺席或哈希不符 =
+ * CHECKPOINT_STORE_CORRUPT（fail-loud 宁拒不误读）。id/hash 是路径段——
+ * 白名单字符校验防路径注入（/rewind 的 id 来自用户输入面）。
+ *
+ * 裁剪（每次捕获后由 capture 侧调 prune）：per workspace 保最新
+ * CHECKPOINT_RETENTION_PER_WORKSPACE 份 manifest（trigger 两形同计，capturedAt
+ * 降序、同刻 id 决胜）；随后 blob 引用计数 GC——扫全仓在册 manifest 收集引用
+ * 哈希（跨 workspace 共享不误杀），无引用才删。
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BaseError } from '../contracts/index.js';
+import { CHECKPOINT_RETENTION_PER_WORKSPACE } from './types.js';
+/** manifest id 合法形（自产 uuid 子集；用户输入面的路径段白名单） */
+const MANIFEST_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** blob 哈希合法形（sha256 小写 hex 64 位） */
+const BLOB_HASH_RE = /^[0-9a-f]{64}$/;
+/** 内容哈希（sha256 hex——内容寻址与一致性校验的单源） */
+export function contentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** 快照仓相对布局（blo 前二分桶 = 目录爆炸防线） */
+function blobPath(baseDir, hash) {
+    return join(baseDir, 'blobs', hash.slice(0, 2), hash);
+}
+/** manifest 坏形折 STORE_CORRUPT（宁拒不误读——字段缺失/型不符全收） */
+function corrupt(detail) {
+    return new BaseError('CHECKPOINT_STORE_CORRUPT', `[CHECKPOINT_STORE_CORRUPT] 快照仓坏形：${detail}`);
+}
+/** manifest JSON 形校验（loadManifest/listManifests 共用判据） */
+function validateManifest(raw, source) {
+    if (typeof raw !== 'object' || raw === null)
+        throw corrupt(`${source} 非 JSON 对象`);
+    const m = raw;
+    const id = m.id;
+    const sessionId = m.sessionId;
+    const boundarySeq = m.boundarySeq;
+    const workspaceRoot = m.workspaceRoot;
+    const capturedAt = m.capturedAt;
+    const trigger = m.trigger;
+    const files = m.files;
+    if (typeof id !== 'string' || !MANIFEST_ID_RE.test(id))
+        throw corrupt(`${source} id 坏形`);
+    if (typeof sessionId !== 'string' || sessionId === '')
+        throw corrupt(`${source} sessionId 坏形`);
+    if (typeof boundarySeq !== 'number' || !Number.isInteger(boundarySeq) || boundarySeq < -1)
+        throw corrupt(`${source} boundarySeq 坏形`);
+    if (typeof workspaceRoot !== 'string' || workspaceRoot === '')
+        throw corrupt(`${source} workspaceRoot 坏形`);
+    if (typeof capturedAt !== 'number' || !Number.isFinite(capturedAt))
+        throw corrupt(`${source} capturedAt 坏形`);
+    if (trigger !== 'mutation' && trigger !== 'pre-rewind')
+        throw corrupt(`${source} trigger 坏形`);
+    if (!Array.isArray(files))
+        throw corrupt(`${source} files 非数组`);
+    const entries = files.map((f, i) => {
+        if (typeof f !== 'object' || f === null)
+            throw corrupt(`${source} files[${i}] 非对象`);
+        const e = f;
+        if (typeof e.path !== 'string' || e.path === '')
+            throw corrupt(`${source} files[${i}].path 坏形`);
+        if (typeof e.hash !== 'string' || !BLOB_HASH_RE.test(e.hash))
+            throw corrupt(`${source} files[${i}].hash 坏形`);
+        if (typeof e.bytes !== 'number' || !Number.isInteger(e.bytes) || e.bytes < 0)
+            throw corrupt(`${source} files[${i}].bytes 坏形`);
+        return { path: e.path, hash: e.hash, bytes: e.bytes };
+    });
+    return {
+        id,
+        sessionId,
+        boundarySeq,
+        workspaceRoot,
+        capturedAt,
+        trigger: trigger,
+        files: entries,
+    };
+}
+/** tmp+rename 原子写（tmp 落同目录保 rename 同卷；写后即终形） */
+async function atomicWrite(absPath, data) {
+    await mkdir(join(absPath, '..'), { recursive: true });
+    const tmp = `${absPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+    await writeFile(tmp, data);
+    await rename(tmp, absPath);
+}
+/**
+ * 开快照仓（装配根/命令面一次性开——baseDir 惰性建：首次写 blob/manifest 时
+ * mkdir recursive，空仓读面按空集处理不诊断）。
+ */
+export function openCheckpointStore(dataDir) {
+    const baseDir = join(dataDir, 'data', 'checkpoint');
+    return {
+        baseDir,
+        async writeBlob(hash, content) {
+            if (!BLOB_HASH_RE.test(hash))
+                throw corrupt(`blob 哈希坏形：${hash}`);
+            const target = blobPath(baseDir, hash);
+            try {
+                await readFile(target);
+                return; // 在场即跳过——内容寻址共享，同内容零重写
+            }
+            catch {
+                // 缺席——落盘（走原子写）
+            }
+            await atomicWrite(target, content);
+        },
+        async readBlob(hash) {
+            if (!BLOB_HASH_RE.test(hash))
+                throw corrupt(`blob 哈希坏形：${hash}`);
+            let content;
+            try {
+                content = await readFile(blobPath(baseDir, hash));
+            }
+            catch {
+                throw corrupt(`blob 缺席：${hash}`);
+            }
+            if (contentHash(content) !== hash)
+                throw corrupt(`blob 哈希不符：${hash}`);
+            return content;
+        },
+        async saveManifest(manifest) {
+            // id 白名单校验（防路径注入——manifest id 亦是路径段）
+            if (!MANIFEST_ID_RE.test(manifest.id))
+                throw corrupt(`manifest id 坏形：${manifest.id}`);
+            await atomicWrite(join(baseDir, 'manifests', `${manifest.id}.json`), JSON.stringify(manifest, null, 2));
+        },
+        async loadManifest(id) {
+            if (!MANIFEST_ID_RE.test(id))
+                throw notFound(id);
+            let text;
+            try {
+                text = await readFile(join(baseDir, 'manifests', `${id}.json`), 'utf8');
+            }
+            catch {
+                throw notFound(id);
+            }
+            let raw;
+            try {
+                raw = JSON.parse(text);
+            }
+            catch (err) {
+                throw corrupt(`manifest ${id} JSON 解析失败（${err instanceof Error ? err.message : String(err)}）`);
+            }
+            return validateManifest(raw, `manifest ${id}`);
+        },
+        async listManifests() {
+            let names;
+            try {
+                names = await readdir(join(baseDir, 'manifests'));
+            }
+            catch {
+                return []; // 空仓/仓未建——空集不诊断
+            }
+            const loaded = [];
+            for (const name of names) {
+                if (!name.endsWith('.json'))
+                    continue;
+                loaded.push(await this.loadManifest(name.slice(0, -5)));
+            }
+            // capturedAt 降序（同刻 id 决胜——确定性序；最新在前）
+            loaded.sort((a, b) => b.capturedAt - a.capturedAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            return loaded;
+        },
+        async deleteManifest(id) {
+            if (!MANIFEST_ID_RE.test(id))
+                return; // 坏形 id 无文件可删——幂等 no-op
+            await rm(join(baseDir, 'manifests', `${id}.json`), { force: true });
+        },
+        async listBlobHashes() {
+            const hashes = [];
+            let prefixDirs;
+            try {
+                prefixDirs = await readdir(join(baseDir, 'blobs'));
+            }
+            catch {
+                return []; // 空仓——空集
+            }
+            for (const prefix of prefixDirs.sort()) {
+                let names = [];
+                try {
+                    names = await readdir(join(baseDir, 'blobs', prefix));
+                }
+                catch {
+                    continue; // 竞态消失——跳过
+                }
+                for (const name of names.sort()) {
+                    if (BLOB_HASH_RE.test(name))
+                        hashes.push(name);
+                }
+            }
+            return hashes;
+        },
+        async deleteBlob(hash) {
+            if (!BLOB_HASH_RE.test(hash))
+                return;
+            await rm(blobPath(baseDir, hash), { force: true });
+        },
+        async prune() {
+            /* ---- 段一：per workspace 保留帽（trigger 两形同计） ---- */
+            const all = await this.listManifests();
+            const byWorkspace = new Map();
+            for (const m of all) {
+                const bucket = byWorkspace.get(m.workspaceRoot);
+                if (bucket !== undefined)
+                    bucket.push(m);
+                else
+                    byWorkspace.set(m.workspaceRoot, [m]);
+            }
+            let removedManifests = 0;
+            for (const [, bucket] of byWorkspace) {
+                // listManifests 已 capturedAt 降序——保前 N 删余
+                for (const stale of bucket.slice(CHECKPOINT_RETENTION_PER_WORKSPACE)) {
+                    await this.deleteManifest(stale.id);
+                    removedManifests += 1;
+                }
+            }
+            /* ---- 段二：blob 引用计数 GC（扫全仓在册 manifest——跨 workspace 共享不误杀） ---- */
+            const referenced = new Set();
+            for (const m of await this.listManifests()) {
+                for (const f of m.files)
+                    referenced.add(f.hash);
+            }
+            let removedBlobs = 0;
+            for (const hash of await this.listBlobHashes()) {
+                if (referenced.has(hash))
+                    continue;
+                await this.deleteBlob(hash);
+                removedBlobs += 1;
+            }
+            return { removedManifests, removedBlobs };
+        },
+    };
+}
+/** 回退点缺席折 NOT_FOUND（已裁剪或坏 id） */
+function notFound(id) {
+    return new BaseError('CHECKPOINT_NOT_FOUND', `[CHECKPOINT_NOT_FOUND] 回退点不存在或已裁剪：${id}`);
+}

package/dist/checkpoint/types.js

@@ -0,0 +1,4 @@
+/** per-workspace manifest 保留份数（裁剪帽——trigger 两形同计；05 §5.3） */
+export const CHECKPOINT_RETENTION_PER_WORKSPACE = 10;
+/** 单次快照 walk 文件帽（防误指巨型目录炸快照——超帽捕获失败 fail-closed） */
+export const CHECKPOINT_WALK_FILE_CAP = 100_000;

package/dist/checkpoint/walk.js

@@ -0,0 +1,146 @@
+/**
+ * checkpoint 工作区遍历（05 §5.3 批 15d——快照/回退的 walk 域定界）。
+ *
+ * 遍历语义与 skills 发现（discovery.ts）/检索族（tools/search.ts）三副本
+ * 同笔同判（04 遍历语义条款）：尊重 .gitignore——逐目录读规则按所在目录
+ * 前缀化挂匹配器（根 .gitignore 前导 / 保留——锚定语义不降级）；剪枝
+ * node_modules/.git；**不跟随符号链**（Dirent.isDirectory 对符号链 false
+ * ——目录链不入、文件链同样跳过：快照域不收间接层，恢复面才可精确对账）。
+ *
+ * 与技能面的遍历差异：技能面跟随符号链目录（realpath 去重防环）；本面
+ * 不跟随——快照的诚实 = 只拍实文件域，间接层由所指文件自身入册。
+ * 点文件（.env 等）入册：快照承诺的是工作区状态全恢复，非 git 索引面。
+ *
+ * 实现与 skills/discovery.ts 同语义独立成文（07 §2 词面独立律——三副本
+ * 各自实现，判据漂移由回归测试锁）。
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import ignore from 'ignore';
+import { BaseError } from '../contracts/index.js';
+import { CHECKPOINT_WALK_FILE_CAP } from './types.js';
+/** 遍历常量剪枝（与 skills/检索族同表语义：依赖目录与 git 元数据） */
+const PRUNE_DIRS = new Set(['node_modules', '.git']);
+/** 平台路径分隔符归一为 /（gitignore 模式语义在 posix 路径上） */
+function toPosix(p) {
+    return p.split(sep).join('/');
+}
+/**
+ * 单行 gitignore 模式前缀化（锚定判据——与 skills/检索族三副本同笔同判）。
+ * 注释/空行丢弃；`!` 否定与 `\!`/`\#` 转义保留；模式体去尾随目录标记斜杠
+ * 后含斜杠或带前导 / = 锚定本层精确匹配；纯 basename 模式前缀化插目录
+ * 通配前缀（`**`+`/`）保深层同配。根 .gitignore 前导 / 保留（git 语义）。
+ */
+function prefixIgnorePattern(line, prefix) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith('#') && !trimmed.startsWith('\\#'))
+        return null;
+    let pattern = line;
+    let negated = false;
+    if (pattern.startsWith('!')) {
+        negated = true;
+        pattern = pattern.slice(1);
+    }
+    else if (pattern.startsWith('\\!')) {
+        pattern = pattern.slice(1);
+    }
+    const rooted = pattern.startsWith('/');
+    if (rooted)
+        pattern = pattern.slice(1);
+    if (!prefix) {
+        const passed = rooted ? `/${pattern}` : pattern;
+        return negated ? `!${passed}` : passed;
+    }
+    const body = pattern.endsWith('/') ? pattern.slice(0, -1) : pattern;
+    const anchored = rooted || body.includes('/');
+    const prefixed = anchored ? `${prefix}${pattern}` : `${prefix}**/${pattern}`;
+    return negated ? `!${prefixed}` : prefixed;
+}
+/** 读 dir 下 .gitignore 并按所在目录前缀化挂上匹配器（嵌套规则只作用本子树） */
+async function addIgnoreRules(matcher, dir, rootDir) {
+    let content;
+    try {
+        content = await readFile(join(dir, '.gitignore'), 'utf8');
+    }
+    catch {
+        return; // 无 .gitignore 或读失败——本目录无额外规则
+    }
+    const prefix = toPosix(relative(rootDir, dir));
+    const prefixed = prefix ? `${prefix}/` : '';
+    const patterns = content
+        .split(/\r?\n/)
+        .map((line) => prefixIgnorePattern(line, prefixed))
+        .filter((line) => line !== null);
+    if (patterns.length > 0)
+        matcher.add(patterns);
+}
+/** 路径 gitignore 判定（目录双测带/不带尾斜杠——兼容 `dir/` 与 `dir` 两种写法） */
+function ignoredPath(matcher, root, fullPath, isDir = false) {
+    const rel = toPosix(relative(root, fullPath));
+    if (rel === '')
+        return false; // 根自身不判
+    return isDir ? matcher.ignores(rel) || matcher.ignores(`${rel}/`) : matcher.ignores(rel);
+}
+/**
+ * 枚举工作区 walk 域内全部实文件（确定性序：目录序 × 名称字典序——manifest
+ * files 的稳定形态）。读文件内容与哈希不在本面（capture/preview 各自单遍
+ * 读+哈希——避免「walk 读一遍、写 blob 再读一遍」的双读）。
+ *
+ * 非常规文件（FIFO/socket/device）静默跳过——快照域只收常规实文件；符号
+ * 链（目录/文件两形）跳过。常规文件读失败（权限/竞态）抛
+ * CHECKPOINT_CAPTURE_FAILED——fail-closed：读不了的文件进不了快照，
+ * 放行变异即伪承诺。文件数超帽（缺省 CHECKPOINT_WALK_FILE_CAP）同码
+ * fail-closed（防误指巨型目录炸快照）。
+ */
+export async function walkWorkspaceFiles(root, fileCap = CHECKPOINT_WALK_FILE_CAP) {
+    const files = [];
+    const absRoot = resolve(root);
+    await walkDir(absRoot, absRoot, ignore(), files, fileCap);
+    return files;
+}
+/** 实际递归（点目录入册、依赖目录剪枝、符号链不跟随、gitignore 逐目录挂规则） */
+async function walkDir(dir, root, matcher, files, fileCap) {
+    await addIgnoreRules(matcher, dir, root);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        throw new BaseError('CHECKPOINT_CAPTURE_FAILED', `[CHECKPOINT_CAPTURE_FAILED] 工作区目录读取失败：${dir}（${err instanceof Error ? err.message : String(err)}）`);
+    }
+    // 名称字典序——确定性遍历序（manifest files 稳定形态的锚）
+    const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of sorted) {
+        // 符号链不跟随（目录/文件两形同判——Dirent 谓词对符号链恒 false）
+        if (entry.isSymbolicLink())
+            continue;
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (PRUNE_DIRS.has(entry.name))
+                continue; // 依赖目录与 git 元数据剪枝
+            if (ignoredPath(matcher, root, fullPath, true))
+                continue;
+            await walkDir(fullPath, root, matcher, files, fileCap);
+            continue;
+        }
+        if (!entry.isFile())
+            continue; // FIFO/socket/device 等——非常规文件不入快照域
+        if (ignoredPath(matcher, root, fullPath))
+            continue;
+        if (files.length >= fileCap) {
+            throw new BaseError('CHECKPOINT_CAPTURE_FAILED', `[CHECKPOINT_CAPTURE_FAILED] 工作区文件数超快照帽（>${fileCap}，根 ${root}）——疑似误指巨型目录，fail-closed 拒拍。`);
+        }
+        files.push({ path: toPosix(relative(root, fullPath)), absPath: fullPath });
+    }
+}
+/** 读单文件字节（读失败折 CHECKPOINT_CAPTURE_FAILED——fail-closed） */
+export async function readWorkspaceFile(absPath) {
+    try {
+        return await readFile(absPath);
+    }
+    catch (err) {
+        throw new BaseError('CHECKPOINT_CAPTURE_FAILED', `[CHECKPOINT_CAPTURE_FAILED] 工作区文件读取失败：${absPath}（${err instanceof Error ? err.message : String(err)}）`);
+    }
+}