dsh-m 0.2.8 → 0.2.9

package/lib/core/market.js

@@ -8,16 +8,12 @@
  * 新发布后 NO_MATCHING_VERSION 的退避重试 + packument 预热（B3）。
  */
 import { existsSync } from 'node:fs';
-import { Buffer } from 'node:buffer';
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { addDshPlugin, removeDshPlugin, removePatchedDependencyEntries, runCommand } from './dsh-cli.js';
-import { dshHome, installTimeoutMs, webProfileDir } from './env.js';
-import { assertNpmIntegrity, atomicWriteFile, readPnpmLockIntegrity, readPnpmLockOverrides, restoreSnapshots, snapshotFiles, } from './npm-integrity.js';
-import { listInstalledPlugins as defaultListInstalledPlugins, readProfileDeps, removeInstalledPlugin, } from './installed.js';
-import { setLivePluginDisabled } from './live-plugin.js';
+import { dshHome } from './env.js';
+import { runProfileTransaction, makeNpmWarmPackument, TransactionError, } from './profile-transaction.js';
+import { listInstalledPlugins as defaultListInstalledPlugins, } from './installed.js';
 import { loadRegistry as defaultLoadRegistry, } from './registry.js';
-import { githubLatestTag as defaultGithubLatestTag, isNewerVersion, npmLatest as defaultNpmLatest, npmPackument as defaultNpmPackument, npmVersion, } from './versions.js';
+import { githubLatestTag as defaultGithubLatestTag, isNewerVersion, npmLatest as defaultNpmLatest, npmVersion, } from './versions.js';
 // ---------- 通用工具 ----------
 const DEFAULT_DEADLINE_MS = 60_000;
 const WITH_LATEST_MAX = 50;
@@ -401,171 +397,6 @@ export async function listInstalledWithMeta(cfg = {}, opts = {}, deps = {}) {
     });
     return { items, others: installed.others, profileDir: installed.profileDir, registryState };
 }
-async function defaultRestoreInstall(profileDir) {
-    return runCommand('pnpm', ['--dir', profileDir, 'install', '--frozen-lockfile'], { timeoutMs: installTimeoutMs() });
-}
-async function defaultRebuildInstall(profileDir) {
-    return runCommand('pnpm', ['--dir', profileDir, 'install', '--no-frozen-lockfile'], { timeoutMs: installTimeoutMs() });
-}
-/** B3 默认退避：新发布 ~1 分钟内的升级失败多为 packument CDN 滞后（2026-09-05 实证）。 */
-const NO_MATCHING_VERSION_RETRY_DELAYS_MS = [5_000, 15_000];
-// ---------- B1/B2：manifest 保留与 frozen 自愈（2026-09-05 事故加固） ----------
-const LOCKFILE_CONFIG_MISMATCH_RE = /ERR_PNPM_LOCKFILE_CONFIG_MISMATCH/;
-const OUTDATED_LOCKFILE_RE = /ERR_PNPM_OUTDATED_LOCKFILE/;
-const NO_MATCHING_VERSION_RE = /ERR_PNPM_NO_MATCHING_VERSION/;
-function errText(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-async function readManifestDoc(profileDir) {
-    try {
-        const parsed = JSON.parse(await readFile(join(profileDir, 'package.json'), 'utf8'));
-        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * B1（成功路径）：安装链（pnpm / 宿主 CLI）若把升级前 manifest 的顶层键丢掉
- * （如 `pnpm.overrides` 事故前态），从安装前字节快照里找回并原子写回。
- * 只补「快照有、现在无」的键，绝不覆盖安装刚写入的 dependencies/dsh 变更。
- * 返回找回的键名列表；无需修复返回 null。
- */
-async function restoreManifestKeys(profileDir, snapshot) {
-    if (!snapshot?.existed || snapshot.bytes === null)
-        return null;
-    let prev;
-    try {
-        const parsed = JSON.parse(snapshot.bytes.toString('utf8'));
-        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
-            return null;
-        prev = parsed;
-    }
-    catch {
-        return null;
-    }
-    const cur = await readManifestDoc(profileDir);
-    if (!cur)
-        return null;
-    const missing = Object.keys(prev).filter((k) => !(k in cur));
-    if (missing.length === 0)
-        return null;
-    for (const key of missing)
-        cur[key] = prev[key];
-    const bytes = Buffer.from(`${JSON.stringify(cur, null, 2)}\n`, 'utf8');
-    await atomicWriteFile(join(profileDir, 'package.json'), bytes);
-    return missing;
-}
-/**
- * B2 第一层自愈：frozen 校验报 overrides 失配时，把 lockfile 记录的 overrides
- * 并入 manifest 的 `pnpm.overrides`（manifest 已有条目优先，绝不删用户手写的键）。
- * lockfile 的 overrides 是上一次解析实际生效的钉版，以此为准可让 frozen 直接通过
- * 而无需重建依赖树（与 2026-09-05 人工修复路径等价）。未做任何修改返回 null。
- */
-async function restoreOverridesFromLock(profileDir) {
-    let lockText;
-    try {
-        lockText = await readFile(join(profileDir, 'pnpm-lock.yaml'), 'utf8');
-    }
-    catch {
-        return null;
-    }
-    const lockOverrides = readPnpmLockOverrides(lockText);
-    const doc = await readManifestDoc(profileDir);
-    if (!doc)
-        return null;
-    const pnpm = doc.pnpm !== null && typeof doc.pnpm === 'object' && !Array.isArray(doc.pnpm)
-        ? doc.pnpm
-        : {};
-    const current = pnpm.overrides !== null && typeof pnpm.overrides === 'object' && !Array.isArray(pnpm.overrides)
-        ? pnpm.overrides
-        : {};
-    const merged = { ...lockOverrides, ...current };
-    if (JSON.stringify(merged) === JSON.stringify(current))
-        return null;
-    doc.pnpm = { ...pnpm, overrides: merged };
-    const bytes = Buffer.from(`${JSON.stringify(doc, null, 2)}\n`, 'utf8');
-    await atomicWriteFile(join(profileDir, 'package.json'), bytes);
-    const restored = Object.keys(lockOverrides).filter((k) => !(k in current));
-    return restored.length > 0 ? `（还原自 lockfile：${restored.join(', ')}）` : '（与 lockfile overrides 对齐）';
-}
-/**
- * B2 frozen 自愈阶梯：frozen install → CONFIG_MISMATCH 时先 overrides 对齐再重试 →
- * 仍失配（或 OUTDATED_LOCKFILE specifier 漂移，实机实证：override 钉直接依赖时回滚
- * 快照本身即 specifier 不一致）则降级 `--no-frozen-lockfile` 重建一致性。自愈动作按序
- * 记入 notes（最终呈现给用户）；阶梯走完仍失败时抛最后一个错误。
- */
-async function frozenInstallWithHeal(profileDir, d, notes) {
-    try {
-        await d.restoreInstall(profileDir);
-        return;
-    }
-    catch (frozenErr) {
-        const text = errText(frozenErr);
-        const isConfigMismatch = LOCKFILE_CONFIG_MISMATCH_RE.test(text);
-        if (!isConfigMismatch && !OUTDATED_LOCKFILE_RE.test(text))
-            throw frozenErr;
-        if (isConfigMismatch) {
-            const merged = await restoreOverridesFromLock(profileDir);
-            if (merged !== null) {
-                notes.push(`已把 lockfile overrides 还原进 manifest ${merged}`);
-                try {
-                    await d.restoreInstall(profileDir);
-                    notes.push('frozen 校验通过');
-                    return;
-                }
-                catch {
-                    /* 对齐后仍失配 → 走重建降级 */
-                }
-            }
-        }
-        try {
-            await d.rebuildInstall(profileDir);
-        }
-        catch (rebuildErr) {
-            throw new Error(`${text}；lockfile 重建（--no-frozen-lockfile）也失败：${errText(rebuildErr)}`);
-        }
-        notes.push('lockfile 已重建（--no-frozen-lockfile 完成一致性安装）');
-    }
-}
-/**
- * B3：ERR_PNPM_NO_MATCHING_VERSION 在刚发布的窗口内几乎都是 packument CDN 滞后
- * （2026-09-05 实证：/latest 已新、完整 packument 仍旧）。按 retryDelaysMs 退避重试，
- * 每次重试前拉一次完整 packument 预热/校验；其他错误与重试耗尽后原样抛出。
- */
-async function addDshPluginWithRetry(spec, pkg, d, retryDelaysMs, timeoutMs, signal) {
-    let attempt = 0;
-    for (;;) {
-        try {
-            return await d.addDshPlugin(spec);
-        }
-        catch (err) {
-            if (!NO_MATCHING_VERSION_RE.test(errText(err)) || attempt >= retryDelaysMs.length)
-                throw err;
-            const delay = retryDelaysMs[attempt] ?? 0;
-            attempt += 1;
-            if (delay > 0)
-                await sleep(delay);
-            await d.npmPackument(pkg, timeoutMs, signal).catch(() => undefined);
-        }
-    }
-}
-/**
- * 旧版 dsh CLI（save-prefix ^）安装后会把依赖写成 `^x.y.z` 而非精确版本
- * （2026-09-05 实机实证：升级报「profile 依赖版本 ^0.2.5 与目标 0.2.5 不一致」）。
- * 仅当 spec 恰好锚定在目标精确版本上（v 本身 / ^v / ~v）才放行；真正的精确性
- * 不靠 manifest 字符串，而由紧随其后的 lockfile importer 精确解析 + integrity
- * 比对保证——其它任何 spec 仍然 fail closed。
- */
-function specAnchoredAtVersion(spec, version) {
-    const s = String(spec || '').trim();
-    return s === version || s === `^${version}` || s === `~${version}`;
-}
 /** 从 registry 收录条目安装（npm → 精确锁定最新版；github → 锁 HEAD SHA）。 */
 export async function installFromRegistry(id, cfg = {}, opts = {}, deps) {
     const loaded = await (deps?.loadRegistry ?? defaultLoadRegistry)(cfg, { namespace: opts.namespace ?? 'host' });
@@ -582,19 +413,10 @@ export async function installEntry(entry, cfg = {}, opts = {}, deps) {
     const d = {
         npmLatest: deps?.npmLatest ?? defaultNpmLatest,
         npmVersion: deps?.npmVersion ?? npmVersion,
-        npmPackument: deps?.npmPackument ?? defaultNpmPackument,
-        addDshPlugin: deps?.addDshPlugin ?? addDshPlugin,
-        removeDshPlugin: deps?.removeDshPlugin ?? removeDshPlugin,
-        readProfileDeps: deps?.readProfileDeps ?? readProfileDeps,
-        readLockIntegrity: deps?.readLockIntegrity ?? readPnpmLockIntegrity,
-        restoreInstall: deps?.restoreInstall ?? defaultRestoreInstall,
-        rebuildInstall: deps?.rebuildInstall ?? defaultRebuildInstall,
     };
-    const retryDelaysMs = deps?.retryDelaysMs ?? NO_MATCHING_VERSION_RETRY_DELAYS_MS;
-    const profileDir = deps?.profileDir ?? webProfileDir();
     if (entry.source === 'npm' && entry.npm) {
         const pkg = entry.npm;
-        // npm：无论 latest 还是用户指定 exact，都先读取该精确版本的 dist metadata
+        // npm：无论 latest 还是用户指定 exact，都先读取该精确版本的 dist metadata（事务外解析）
         let version;
         let expectedIntegrity;
         if (opts.version) {
@@ -609,124 +431,60 @@ export async function installEntry(entry, cfg = {}, opts = {}, deps) {
         }
         if (!expectedIntegrity)
             throw new Error(`npm metadata 缺少 dist integrity：${pkg}@${version}，拒绝安装`);
-        const spec = `${pkg}@${version}`;
-        // 安装前快照：失败时 best-effort 依赖回滚与 B1 键找回的依据
-        const snapshots = await snapshotFiles([
-            join(profileDir, 'package.json'),
-            join(profileDir, 'pnpm-lock.yaml'),
-            join(profileDir, 'pnpm-workspace.yaml'),
-        ]);
-        const healNotes = [];
-        // 区分 add 阶段与校验阶段失败：回滚报错不再把 pnpm 安装失败误标成「integrity 校验失败」
-        let phase = 'install';
-        try {
-            const res = await addDshPluginWithRetry(spec, pkg, d, retryDelaysMs, timeoutMs, opts.signal);
-            phase = 'verify';
-            const depsNow = await d.readProfileDeps(profileDir);
-            if (depsNow[pkg] === undefined)
-                throw new Error(`安装后未在 profile 依赖中找到 ${pkg}`);
-            if (depsNow[pkg] !== version) {
-                if (!specAnchoredAtVersion(depsNow[pkg], version)) {
-                    throw new Error(`profile 依赖版本 ${depsNow[pkg]} 与目标 ${version} 不一致`);
-                }
-                healNotes.push(`安装链把依赖写成 range（${depsNow[pkg]}，旧版 CLI save-prefix 行为）；精确性由 lockfile integrity 校验继续保证`);
-            }
-            let lockText;
-            try {
-                lockText = await readFile(join(profileDir, 'pnpm-lock.yaml'), 'utf8');
-            }
-            catch {
-                throw new Error('安装后未找到 pnpm-lock.yaml，无法核对 integrity');
-            }
-            const actual = d.readLockIntegrity(lockText, pkg, version);
-            assertNpmIntegrity(expectedIntegrity, actual, pkg, version);
-            // B1（成功路径）：安装链若丢了 manifest 顶层键（如 pnpm.overrides），从快照找回并复验 frozen 一致性
-            const restoredKeys = await restoreManifestKeys(profileDir, snapshots[0]);
-            if (restoredKeys) {
-                healNotes.push(`安装链丢失了 manifest 顶层键（${restoredKeys.join(', ')}），已从安装前快照找回`);
-                try {
-                    await frozenInstallWithHeal(profileDir, d, healNotes);
-                }
-                catch (healErr) {
-                    healNotes.push(`frozen 一致性自愈未完成，profile 可能需要人工检查：${errText(healErr)}`);
-                }
-            }
-            return {
-                id: entry.id,
-                pkg,
-                spec,
-                version,
-                usedAllowAllBuilds: res.usedAllowAllBuilds,
-                needsRestart: true,
-                output: res.output.slice(-800) + (healNotes.length > 0 ? `\n[dsh-m 自愈] ${healNotes.join('；')}` : ''),
-            };
-        }
-        catch (err) {
-            // best-effort rollback：原子恢复 manifest/lock/workspace 快照字节，再按 frozen 自愈阶梯收敛
-            let rollbackError = null;
-            const rollbackNotes = [];
-            try {
-                await restoreSnapshots(snapshots);
-                await frozenInstallWithHeal(profileDir, d, rollbackNotes);
-            }
-            catch (rerr) {
-                rollbackError = errText(rerr);
-                // 原先不存在该依赖且恢复安装失败：尝试移除
-                const originallyAbsent = snapshots[0] && snapshots[0].existed && (() => {
-                    try {
-                        return !JSON.parse(snapshots[0].bytes.toString('utf8'))?.dependencies?.[pkg];
-                    }
-                    catch {
-                        return false;
-                    }
-                })();
-                if (originallyAbsent) {
-                    try {
-                        await d.removeDshPlugin(pkg);
-                        rollbackError = null;
-                    }
-                    catch (rmErr) {
-                        rollbackError = `${rollbackError}；移除 ${pkg} 也失败（${errText(rmErr)}）`;
-                    }
-                }
-            }
-            const prefix = phase === 'install' ? '安装失败' : 'integrity 校验失败';
-            if (rollbackError) {
-                throw new Error(`${prefix}（${errText(err)}）；依赖回滚也失败（${rollbackError}），profile 可能需要人工修复`);
-            }
-            const suffix = rollbackNotes.length > 0 ? `（${rollbackNotes.join('；')}）` : '';
-            throw new Error(`${prefix}，已回滚到安装前状态${suffix}：${errText(err)}`);
-        }
+        // 生产预热绑定：未注入时 B3 用 makeNpmWarmPackument（保留 timeout/signal、失败吞错）
+        const result = await runProfileTransaction({ kind: 'install-npm', pkg, version, integrity: expectedIntegrity, signal: opts.signal }, {
+            ...deps?.transaction,
+            warmPackument: deps?.transaction?.warmPackument ?? makeNpmWarmPackument(timeoutMs),
+        });
+        if (!result.ok)
+            throw new TransactionError(result);
+        const notes = result.healActions.map((h) => h.note).filter((n) => n !== '');
+        return {
+            id: entry.id,
+            pkg: result.pkg ?? pkg,
+            spec: result.spec ?? `${pkg}@${version}`,
+            version: result.version ?? version,
+            usedAllowAllBuilds: result.usedAllowAllBuilds === true,
+            needsRestart: true,
+            output: result.output + (notes.length > 0 ? `\n[dsh-m 自愈] ${notes.join('；')}` : ''),
+            healActions: result.healActions,
+        };
     }
     if (entry.github) {
-        const { tag, sha } = await defaultGithubLatestTag(entry.github, timeoutMs, opts.signal);
-        const spec = `github:${entry.github}#${sha}`;
-        const res = await d.addDshPlugin(spec);
-        const depsNow = await d.readProfileDeps(profileDir);
-        const pkgKey = Object.keys(depsNow).find((k) => depsNow[k] === spec || depsNow[k].startsWith(`github:${entry.github}#`));
-        if (!pkgKey)
-            throw new Error(`安装后未在 profile 依赖中找到 ${entry.github}`);
-        void tag;
+        // 版本解析在事务外（DI 修正：githubLatestTag 此前绕过注入）
+        const { tag, sha } = await (deps?.githubLatestTag ?? defaultGithubLatestTag)(entry.github, timeoutMs, opts.signal);
+        const result = await runProfileTransaction({ kind: 'install-github', repo: entry.github, sha, tag, signal: opts.signal }, deps?.transaction ?? {});
+        if (!result.ok)
+            throw new TransactionError(result);
+        const notes = result.healActions.map((h) => h.note).filter((n) => n !== '');
         return {
             id: entry.id,
-            pkg: pkgKey,
-            spec,
-            sha,
-            usedAllowAllBuilds: res.usedAllowAllBuilds,
+            pkg: result.pkg ?? entry.github,
+            spec: result.spec ?? `github:${entry.github}#${sha}`,
+            sha: result.sha ?? sha,
+            tag: result.tag ?? tag,
+            usedAllowAllBuilds: result.usedAllowAllBuilds === true,
             needsRestart: true,
-            output: res.output.slice(-800),
+            output: result.output + (notes.length > 0 ? `\n[dsh-m 自愈] ${notes.join('；')}` : ''),
+            healActions: result.healActions,
         };
     }
     throw new Error(`条目 ${entry.id} 缺少可安装来源`);
 }
-/** 卸载：live-disable → 摘除该包补丁条目 → pnpm remove → 报告疑似残留（DESIGN.md §3：删包不删数据）。 */
-export async function uninstallPlugin(pkg, _cfg = {}, _opts = {}, deps = {}) {
-    const liveDisabled = await setLivePluginDisabled(pkg, true);
-    // 依赖移除后残留的 patchedDependencies 条目会让 pnpm 以 ERR_PNPM_UNUSED_PATCH 整单失败，先摘掉
-    const patchCleanup = (deps.removePatchedEntries ?? removePatchedDependencyEntries)(webProfileDir(), pkg);
-    await (deps.removeInstalled ?? removeInstalledPlugin)(pkg);
-    const leftovers = [...new Set([...leftoverCandidates(pkg), ...patchCleanup.orphanedPatchFiles])];
-    return { pkg, liveDisabled, needsRestart: true, leftovers };
+/** 卸载：validate（严格读取）→ live-disable → 摘补丁 → pnpm remove → verify gone（DESIGN.md §3：删包不删数据）。 */
+export async function uninstallPlugin(pkg, _cfg = {}, opts = {}, deps = {}) {
+    const result = await runProfileTransaction({ kind: 'uninstall', pkg, signal: opts.signal }, deps.transaction ?? {});
+    if (!result.ok)
+        throw new TransactionError(result);
+    const orphaned = result.orphanedPatchFiles ?? [];
+    const leftovers = [...new Set([...leftoverCandidates(pkg), ...orphaned])];
+    return {
+        pkg,
+        liveDisabled: result.liveDisabled === true,
+        needsRestart: true,
+        leftovers,
+        healActions: result.healActions,
+    };
 }
 /** 升级 = 按最新重新安装（npm 拉最新精确版；github 重新锁 HEAD）。 */
 export async function upgradePlugin(pkg, cfg = {}, opts = {}, deps) {
@@ -744,14 +502,6 @@ export async function upgradePlugin(pkg, cfg = {}, opts = {}, deps) {
     const result = await installEntry(entry, cfg, opts, deps);
     return { ...result, fromVersion: target.version };
 }
-// ---------- 变更互斥 ----------
-/** 变更互斥：安装/卸载/升级串行执行（skillhub install-lock 同款思路）。 */
-let mutationTail = Promise.resolve();
-export function withMutationLock(task) {
-    const next = mutationTail.then(task, task);
-    mutationTail = next.catch(() => undefined);
-    return next;
-}
 /** 疑似残留路径（存在才列出）：删包不删数据，只报告。 */
 export function leftoverCandidates(pkg) {
     const home = dshHome();

package/lib/core/npm-integrity.js

@@ -126,33 +126,159 @@ export function readPnpmLockOverrides(lockText) {
     }
     return result;
 }
-async function atomicWriteFile(path, bytes) {
-    await mkdir(dirname(path), { recursive: true });
+/**
+ * 原子写（Task 2 加固；终审复审 Y1/F3/F5 再加固）：POSIX 直接 `rename` 原子覆盖目标
+ * （不再先 rm——旧实现的「删目标 → rename」窗口期内崩溃会直接丢文件）。仅 Windows 形态
+ * 的 `EPERM`/`EEXIST` 走备份协议：`target→backup`、`tmp→target`，任一步失败恢复
+ * `backup→target`，全部成功后删除 backup。失败清理遵守：
+ * - F5：`O_EXCL` open 成功才取得 tmp 所有权，未取得所有权绝不清理（可能是他人 in-flight 的碰撞文件）；
+ * - F3：close 失败不吞（但不掩盖 write/sync 的原始异常）；
+ * - 任何失败路径（含 write/sync/close/rename）都清理自有 tmp；备份恢复本身失败时报告
+ *   backup 路径与双重错误，不静默。
+ */
+async function atomicWriteFile(path, bytes, fsOps = {}) {
+    const mkdirOp = fsOps.mkdir ?? mkdir;
+    const openOp = fsOps.open ?? open;
+    const renameOp = fsOps.rename ?? rename;
+    const rmOp = fsOps.rm ?? rm;
+    await mkdirOp(dirname(path), { recursive: true });
     const tmp = `${path}.restore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
-    const fh = await open(tmp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+    const backup = `${path}.backup-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+    let completed = false;
+    let tmpOwned = false;
+    let mainErr;
+    let threw = false;
+    let cleanupErr;
     try {
-        await fh.write(bytes);
-        await fh.sync();
+        try {
+            const fh = await openOp(tmp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+            tmpOwned = true; // O_EXCL 成功 = tmp 由本调用创建
+            // Y1（第三轮复审）：write/sync 与 close 的错误全部保留（AggregateError），不互相覆盖
+            const errors = [];
+            try {
+                await fh.write(bytes);
+                await fh.sync();
+            }
+            catch (err) {
+                errors.push(err);
+            }
+            try {
+                await fh.close();
+            }
+            catch (err) {
+                errors.push(err); // F3：close 失败不吞
+            }
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1)
+                throw new AggregateError(errors, '临时文件写入/同步/关闭失败');
+            try {
+                await renameOp(tmp, path);
+                completed = true;
+                return;
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code !== 'EPERM' && code !== 'EEXIST') {
+                    throw err;
+                }
+            }
+            // Windows 备份协议
+            try {
+                await renameOp(path, backup);
+            }
+            catch (bakErr) {
+                throw bakErr;
+            }
+            try {
+                await renameOp(tmp, path);
+            }
+            catch (moveErr) {
+                try {
+                    await renameOp(backup, path);
+                }
+                catch (restoreErr) {
+                    throw new Error(`原子写失败：${errTextOf(moveErr)}；备份恢复也失败（${errTextOf(restoreErr)}），原文件现位于备份 ${backup}`);
+                }
+                throw moveErr;
+            }
+            await rmOp(backup, { force: true }).catch(() => undefined);
+            completed = true;
+        }
+        catch (err) {
+            threw = true;
+            mainErr = err;
+        }
     }
     finally {
-        await fh.close().catch(() => undefined);
+        if (tmpOwned && !completed) {
+            try {
+                await rmOp(tmp, { force: true });
+            }
+            catch (err) {
+                cleanupErr = err; // Y1：清理失败不覆盖主错误，随后聚合上报（含 tmp 路径）
+            }
+        }
     }
-    await rm(path, { force: true });
-    await rename(tmp, path);
+    if (threw) {
+        if (cleanupErr !== undefined) {
+            throw new AggregateError([mainErr, cleanupErr], `原子写失败且临时文件清理也失败（可能残留 tmp：${tmp}）`);
+        }
+        throw mainErr;
+    }
+}
+function errTextOf(err) {
+    return err instanceof Error ? err.message : String(err);
 }
 export { atomicWriteFile };
-/** 记录 profile 关键文件的字节快照（package.json / pnpm-lock.yaml / pnpm-workspace.yaml）。 */
-export async function snapshotFiles(paths) {
+/**
+ * 记录 profile 关键文件的字节快照（package.json / pnpm-lock.yaml / pnpm-workspace.yaml）。
+ * Task 2 加固：仅 `ENOENT`（文件本不存在）→ `existed:false`；其他读取异常（EACCES、
+ * EISDIR 等）一律 throw，由调用方 fail closed（零写入），不再把不可读误当成「不存在」。
+ */
+export async function snapshotFiles(paths, fsOps = {}) {
+    const read = fsOps.readFile ?? readFile;
     return Promise.all(paths.map(async (path) => {
         try {
-            const bytes = await readFile(path);
+            const bytes = await read(path);
             return { path, existed: true, bytes };
         }
-        catch {
-            return { path, existed: false, bytes: null };
+        catch (err) {
+            if (err?.code === 'ENOENT') {
+                return { path, existed: false, bytes: null };
+            }
+            throw err;
         }
     }));
 }
+/**
+ * 还原后立即重读比对（第一阶段验证动作；Task 2 起）。F2（第三轮复审）：仅 `ENOENT`
+ * 视为文件不存在；EACCES/EIO/EISDIR 等其他读取异常一律 fail closed（抛错）。
+ * `fsOps` 为内部测试缝（缺省真 fs），确定性注入读取异常，不依赖 chmod。
+ */
+export async function verifySnapshots(snapshots, fsOps = {}) {
+    const read = fsOps.readFile ?? readFile;
+    for (const snap of snapshots) {
+        let current;
+        try {
+            current = await read(snap.path);
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT') {
+                throw new Error(`还原后复验读取失败（${snap.path}）：${errTextOf(err)}`);
+            }
+            current = null;
+        }
+        if (snap.existed && snap.bytes !== null) {
+            if (current === null || !current.equals(snap.bytes)) {
+                throw new Error(`还原后复验不一致：${snap.path}`);
+            }
+        }
+        else if (current !== null) {
+            throw new Error(`还原后应删除的新生成文件仍存在：${snap.path}`);
+        }
+    }
+}
 /**
  * 恢复快照：原先存在的文件原样写回（原子 rename）；原先不存在的删除安装过程中
  * 新生成的文件。恢复动作本身失败由调用方汇总报告。