mocode-ai 0.7.2 → 1.0.1

package/dist/agent/index.js

@@ -17,6 +17,44 @@ import { isToolErrorOutput } from '../tools/result.js';
 import { appendCurrentSessionTraceEvent } from '../session/index.js';
 /** 当前 turn 的 batch id(runAgent 内闭包变量;一条 turn 一轮 tool batch 结束即清空)。 */
 let currentBatchId = null;
+let turnFileChanges = [];
+function lineDelta(oldText, newText) {
+    const before = oldText ? oldText.split('\n') : [];
+    const after = newText ? newText.split('\n') : [];
+    let head = 0;
+    while (head < before.length && head < after.length && before[head] === after[head])
+        head++;
+    let tail = 0;
+    while (tail < before.length - head
+        && tail < after.length - head
+        && before[before.length - 1 - tail] === after[after.length - 1 - tail])
+        tail++;
+    return { added: after.length - head - tail, removed: before.length - head - tail };
+}
+function writeChangeOverview() {
+    if (turnFileChanges.length === 0)
+        return;
+    const merged = new Map();
+    for (const change of turnFileChanges) {
+        const current = merged.get(change.path);
+        if (current) {
+            current.added += change.added;
+            current.removed += change.removed;
+            if (change.kind === 'A')
+                current.kind = 'A';
+        }
+        else {
+            merged.set(change.path, { ...change });
+        }
+    }
+    const changes = [...merged.values()];
+    const added = changes.reduce((n, c) => n + c.added, 0);
+    const removed = changes.reduce((n, c) => n + c.removed, 0);
+    layout.contentWrite(`  ${ui.dim}├─${ui.reset} ${ui.bold}${ui.green}◆${ui.reset} ${t('agent.changes')}  ${t('agent.files', { count: changes.length })}  ${ui.green}+${added}${ui.reset} ${ui.red}−${removed}${ui.reset}\n`);
+    for (const change of changes) {
+        layout.contentWrite(`  ${ui.dim}│   ${change.kind}${ui.reset}  ${change.path}  ${ui.green}+${change.added}${ui.reset} ${ui.red}−${change.removed}${ui.reset}\n`);
+    }
+}
 /** 取 userInput 的首行:字符串直接 split;多模态 parts 找首个 text part 再 split。 */
 function firstLineOf(ui) {
     if (typeof ui === 'string')
@@ -43,7 +81,9 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
     if (!currentBatchId)
         return;
     let diff = null;
-    if (isMutationTool(tc.name) && parsed && !isToolErrorOutput(output)) {
+    if ((tc.name === 'edit_file' || tc.name === 'write_file') && parsed && !isToolErrorOutput(output)) {
+        const oldText = tc.name === 'edit_file' ? String(parsed.old_string ?? '') : preWriteOld;
+        const newText = String((tc.name === 'edit_file' ? parsed.new_string : parsed.content) ?? '');
         diff = renderFileChange({
             path: String(parsed.path ?? ''),
             kind: tc.name === 'edit_file' ? 'edit' : 'write',
@@ -53,9 +93,15 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
             newStr: String((tc.name === 'edit_file' ? parsed.new_string : parsed.content) ?? ''),
             startLine: tc.name === 'edit_file' ? editStartLine : 1,
         });
+        turnFileChanges.push({
+            path: String(parsed.path ?? ''),
+            kind: tc.name === 'write_file' && preWriteOld == null ? 'A' : 'M',
+            ...lineDelta(oldText, newText),
+        });
     }
     const preview = diff ? '' : summarizeToolResult(tc.name, output);
-    batch.recordResult(currentBatchId, tc.name, preview, diff, output);
+    batch.recordResult(currentBatchId, tc.name, preview, diff, output, isToolErrorOutput(output));
+    batch.showLiveBatch(currentBatchId, layout);
     // mutation 结果（成功 diff 或错误输出）立即可见，并阻止后续普通工具并入这一批。
     if (isMutationTool(tc.name))
         flushToolBatch(true);
@@ -96,6 +142,7 @@ onContextUpdate) {
     beginTurn(truncateDisplay(firstLineOf(userInput), 40));
     layout.contentMode(); // 防御性:运行态光标归输入框光标位供 IME 锚定(enterRunningMode 已置,这里兜底)
     currentBatchId = null; // 新 turn 清旧 batch id(防上 turn 残留)
+    turnFileChanges = [];
     // spinner:状态行最前面转圈(思考中 / 生成 / 执行 工具时,状态栏 lead 位显帧 + 文字)。
     // 经 setStatus 注入状态行(spinnerFrame + statusText),composeStatus 把帧 + 文字放 lead 位;
     // 不画内容区续写位——内容区在等待期间保持干净,首 token 到达即从续写位开始写正文。
@@ -121,6 +168,8 @@ onContextUpdate) {
             // batch 收尾已经统一留了一条空白行。部分后端会把下一段正文以 \n / \n\n
             // 开头发来；去掉这些“边界换行”，避免与 UI 分隔叠成两条空白行。
             const visible = followsToolBatch ? s.replace(/^(?:[ \t]*\r?\n)+/, '') : s;
+            // 正文是工具批次边界：只有“连续且中间没有正文”的工具调用才合并。
+            // 一旦模型开始解释阶段结果，立即收尾当前摘要；后续工具重新建立批次。
             if (s)
                 flushToolBatch();
             spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
@@ -203,12 +252,14 @@ onContextUpdate) {
             const detail = validation.status === 'skipped' && validation.skipReason
                 ? `${validation.status}: ${validation.skipReason}`
                 : validation.status;
-            layout.contentWrite(`  ${color}●${ui.reset} ${t('agent.validationResult', { command, status: detail })}\n`);
+            const symbol = validation.status === 'passed' ? '◆' : validation.status === 'failed' ? '×' : '!';
+            layout.contentWrite(`  ${ui.dim}├─${ui.reset} ${color}${symbol}${ui.reset} ${t('agent.validationResult', { command, status: detail })}\n\n`);
         },
         onDone: (elapsedMs, usage) => {
             flushToolBatch();
+            writeChangeOverview();
             const tok = formatTurnTokens(usage);
-            layout.contentWrite(`  ${ui.dim}✻ ${t('agent.workedFor', { elapsed: fmtElapsed(elapsedMs) })}${tok}${ui.reset}\n`);
+            layout.contentWrite(`  ${ui.bold}${ui.green}◆${ui.reset} ${t('agent.complete')}  ${fmtElapsed(elapsedMs)}${tok}\n`);
             // 内容区触底时，DECSTBM 增量滚屏可能只推进物理终端，未把 Worked 前已在
             // buffer 中的空行完整画出来；用户滚动/点击触发 repaint 后才“突然”出现。
             // 轮次收尾立即按 buffer 原子重画，使未满屏与触底滚屏的布局一致。
@@ -279,9 +330,9 @@ function formatTurnTokens(usage) {
     const billablePrompt = usage.promptTokens - cached;
     const extras = [];
     if (cached > 0)
-        extras.push(`↻ ${fmt(cached)} cached`);
+        extras.push(`${Math.round((cached / Math.max(1, usage.promptTokens)) * 100)}% cached`);
     if (reasoning > 0)
         extras.push(`reasoning ${fmt(reasoning)}`);
     const extrasStr = extras.length > 0 ? ` · ${extras.join(' · ')}` : '';
-    return `  ·  ${fmt(total)} tokens (↑ ${fmt(billablePrompt)} ↓ ${fmt(usage.completionTokens)})${extrasStr}`;
+    return `  ${fmt(total)} tokens${extrasStr}  ${ui.dim}(↑ ${fmt(billablePrompt)} ↓ ${fmt(usage.completionTokens)})${ui.reset}`;
 }

package/dist/agent/spawn.js

@@ -5,28 +5,34 @@
 //  - 不写主屏(layout.contentWrite):中间过程(流式正文 / 工具头 / diff)缓冲到内部字符串,
 //    结束返回给 task 工具(task 把它当 tool 结果回灌主 history,主 agent 据此继续)。
 //  - 独立 history:不共享主对话,避免子任务的工具噪声污染主上下文。
-//  - 系统提示复用主 agent 组装链(config.systemPrompt + memory 段 + skills 段)+ 子 agent 角色后缀。
-//  - 工具子集:按白名单从 chatTools 过滤;无白名单 = 全量(但 task 工具调用方通常会限定只读)。
+//  - 紧凑系统提示:不复制主 agent 的 memory/skills/项目快照；由 context 传入已知事实。
+//  - 工具子集:写任务默认继承主 Agent 工具（仅禁止递归 task）；只读模式按安全语义移除写工具。
 //  - 不调 beginTurn：子 agent 共享主 agent 当前轮次；其文件修改进入同一回滚事务。
-//  - 步数上限默认更低(config.subAgentMaxSteps ?? 50),防子任务失控耗尽配额。
+//  - 步数默认与主 Agent 相同，只作为无限循环保险，不以 token 配额提前终止有效任务。
 //  - 中断透传:opts.signal(主 agent 的 abort signal)透传给 runAgentCore → chat/executeTool,
 //    主 Ctrl+C 树杀子 agent(chat 流式 abort + run_command/web_fetch 即时取消)。
 import { chatTools } from '../llm/index.js';
-import { config, isMemoryEnabled, isSubAgentEnabled } from '../config/index.js';
+import { buildMocodeCorePrompt, config, isSubAgentEnabled } from '../config/index.js';
 import { effectiveSystemPrompt } from '../skills/index.js';
-import { buildMemorySection, buildMemoryIndexSection } from '../memory/index.js';
 import { ui } from '../ui/theme.js';
 import { runAgentCore } from './core.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay } from '../ui/render.js';
 import { createContextState } from '../session/compact.js';
+import { inOverlay, mergeSubAgentChangeSet } from '../agents/coordinator.js';
 /** 子 agent 系统提示后缀:角色与约束。 */
-const SUBAGENT_SUFFIX = `
+const SUBAGENT_SUFFIX = `
 
 ## ⛯ SUB-AGENT MODE (you are a sub-agent)
 You are a sub-agent spawned by the main agent to handle an isolated sub-task. You have your own conversation history (independent of the main thread).
-- Focus solely on the assigned sub-task. Do NOT attempt to call the "task" tool (no recursive spawning).
+- Focus solely on the assigned sub-task. Do NOT attempt to call the "sub-agent" tool (no recursive spawning).
 - Use the tools available to you to complete the sub-task.
 - When done, your final text reply will be returned to the main agent as a summary — make it concise and actionable: what you did, key findings, files changed, and any issues. The main agent will decide the next step based on your summary.`;
+const SUBAGENT_ROLE = `## Sub-agent execution
+You are executing one delegated sub-task with the same engineering standards and capabilities as mocode.
+- Treat Task context as authoritative facts already established by the main agent; do not rediscover them without evidence they are stale.
+- Focus on the delegated scope, but continue until it is genuinely complete. Do not stop to save tokens.
+- Do not recursively call sub-agent. A write task runs in an isolated overlay; the coordinator merges and performs final unified verification.
+- Return concise findings, changes, verification evidence, and blockers to the coordinator.`;
 /**
  * 派生一个子 agent 执行独立子任务。
  *
@@ -45,28 +51,25 @@ export async function spawnAgent(opts) {
             summary: null,
             completed: false,
             transcript: 'Sub-agent execution is disabled. Enable it with /subagent on.',
+            status: 'failed', findings: [], readSet: [], changeSet: null, verification: null,
+            usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0, cachedTokens: 0, reasoningTokens: 0 },
         };
     }
-    const maxSteps = opts.maxSteps ?? config.subAgentMaxSteps ?? 50;
-    // 构造子 agent 系统提示:复用主 agent 组装链 + 子 agent 角色后缀 + 自定义后缀。
-    // config.systemPrompt 是 getter(每次访问现拼 buildBasePrompt,反映 isMemoryEnabled),
-    // 所以这里直接读 config.systemPrompt 即可;buildMemoryIndexSection 显式按 isMemoryEnabled() 传参,
-    // 关闭时该段不进。注意:不能从 spawn.ts 直接 import buildBasePrompt —— 这会
-    // 拉起 config → llm → registry → builtins → task → spawn 形成循环求值死锁。
-    const systemPrompt = effectiveSystemPrompt(config.systemPrompt +
-        buildMemorySection() +
-        buildMemoryIndexSection(isMemoryEnabled()) +
-        SUBAGENT_SUFFIX +
+    const maxSteps = opts.maxSteps ?? config.subAgentMaxSteps;
+    // 构造窄 worker prompt；主 Agent 已知事实只通过有界 context 注入，避免重复探索与重复计费。
+    const systemPrompt = effectiveSystemPrompt(buildMocodeCorePrompt() + '\n\n' + SUBAGENT_ROLE + SUBAGENT_SUFFIX +
         (opts.systemPromptSuffix ? `\n\n${opts.systemPromptSuffix}` : ''));
-    // 工具子集:白名单过滤。无白名单 = 全量 chatTools,但始终剔除 task(防递归派生)。
+    const taskPrompt = opts.context?.trim()
+        ? `Task context (authoritative; do not rediscover):\n${opts.context.slice(0, 4000)}\n\nSub-task:\n${opts.prompt}`
+        : opts.prompt;
+    // 写 worker 保留主 Agent 的完整能力；只读 mode 仅按调用契约移除副作用工具。
     let toolsOverride;
-    if (opts.tools && opts.tools.length > 0) {
-        const allow = new Set(opts.tools);
-        toolsOverride = chatTools.filter((t) => allow.has(t.function.name) && t.function.name !== 'task');
-    }
-    else {
-        toolsOverride = chatTools.filter((t) => t.function.name !== 'task');
-    }
+    const mode = opts.mode ?? 'read';
+    const requested = opts.tools?.length ? new Set(opts.tools) : null;
+    const readOnly = new Set(['read_file', 'glob', 'grep', 'codegraph', 'web_search', 'web_fetch', 'use_skill', 'memory_search', 'memory_list']);
+    toolsOverride = chatTools.filter((tool) => tool.function.name !== 'sub-agent' &&
+        (!requested || requested.has(tool.function.name)) &&
+        (mode === 'write' || readOnly.has(tool.function.name)));
     // 独立 history(子 agent 自己持有,不共享主对话)。
     // 只塞 system;user 消息由 runAgentCore 的 userInput 参数 push(与主 agent 一致)。
     const history = [
@@ -123,19 +126,60 @@ export async function spawnAgent(opts) {
     // 每个子 agent 独享统计/预算状态。不能保存再恢复模块级单例：多个 task 并发时
     // save/restore 会竞态，且 lastEstimate / schedulerLog 仍会污染主 agent。
     const localContextState = createContextState();
-    const result = await runAgentCore({
+    const readSet = new Set();
+    const run = () => runAgentCore({
         history,
-        userInput: opts.prompt,
-        signal: opts.signal, // 主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)
+        userInput: taskPrompt,
+        signal: opts.signal,
         hooks,
         maxSteps,
         toolsOverride,
         contextState: localContextState,
-        autoValidate: false, // 子 Agent 共享主轮工作区，由主 Agent 收尾统一验证
+        autoValidate: false,
+        onToolOutcome: (tool, args) => {
+            if (tool === 'read_file' && typeof args.path === 'string')
+                readSet.add(args.path);
+            else if (['glob', 'grep', 'codegraph'].includes(tool))
+                readSet.add('workspace');
+        },
     });
+    let result;
+    let changeSet = null;
+    let mergeStatus = 'committed';
+    if (opts.mode === 'write') {
+        const isolated = await inOverlay(run);
+        result = isolated.value;
+        changeSet = isolated.changeSet;
+        const declared = new Set((opts.writeSet ?? []).map((item) => item.replaceAll('\\', '/').toLowerCase()));
+        const outsideDeclaration = declared.size > 0 && changeSet?.changes.some((change) => !declared.has(change.path.replaceAll('\\', '/').toLowerCase()));
+        if (!result.completed || outsideDeclaration)
+            mergeStatus = 'failed';
+        else
+            mergeStatus = await mergeSubAgentChangeSet(changeSet, opts.signal);
+    }
+    else {
+        result = await run();
+    }
+    const status = opts.signal?.aborted || result.terminationReason === 'aborted'
+        ? 'aborted'
+        : mergeStatus === 'conflict' ? 'conflict'
+            : mergeStatus === 'failed' || !result.completed ? 'failed'
+                : 'completed';
     return {
         summary: result.finalText,
-        completed: result.completed,
+        completed: result.completed && status === 'completed',
         transcript: truncateDisplay(transcript, 20000), // 防过大;调试用,回灌主 history 的是 summary 不是 transcript
+        status,
+        findings: result.finalText ? [result.finalText] : [],
+        readSet: [...readSet].sort(),
+        changeSet,
+        verification: null, // 主 Agent 在所有 coordinator merge 完成后统一验证
+        usage: {
+            promptTokens: result.usage?.promptTokens ?? 0,
+            completionTokens: result.usage?.completionTokens ?? 0,
+            totalTokens: result.usage?.totalTokens ?? 0,
+            cachedTokens: result.usage?.cachedTokens ?? 0,
+            reasoningTokens: result.usage?.reasoningTokens ?? 0,
+        },
     };
 }

package/dist/agents/coordinator.js

@@ -0,0 +1,60 @@
+import { cp, mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { commitChangeSet, contentHash, createChangeSet } from '../changeset/index.js';
+import { getSandboxRoot, withSandboxRoot } from '../sandbox/index.js';
+const EXCLUDED = new Set(['.git', 'node_modules', 'dist', '.mocode']);
+async function filesBelow(root, dir = root, out = new Map()) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (EXCLUDED.has(entry.name))
+            continue;
+        const absolute = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            await filesBelow(root, absolute, out);
+        else if (entry.isFile())
+            out.set(path.relative(root, absolute).replaceAll('\\', '/'), await readFile(absolute));
+    }
+    return out;
+}
+function text(buffer) {
+    if (buffer.includes(0))
+        throw new Error('子 Agent overlay 暂不支持合并二进制文件。');
+    return buffer.toString('utf8');
+}
+function diffToChangeSet(before, after) {
+    const changes = [];
+    for (const file of new Set([...before.keys(), ...after.keys()])) {
+        const oldValue = before.get(file);
+        const newValue = after.get(file);
+        if (oldValue && newValue && oldValue.equals(newValue))
+            continue;
+        if (!oldValue && newValue)
+            changes.push({ path: file, operation: 'create', expectedHash: null, replacement: text(newValue) });
+        else if (oldValue && !newValue)
+            changes.push({ path: file, operation: 'delete', expectedHash: contentHash(oldValue) });
+        else if (oldValue && newValue)
+            changes.push({ path: file, operation: 'update', expectedHash: contentHash(oldValue), replacement: text(newValue) });
+    }
+    return changes.length ? createChangeSet(changes) : null;
+}
+/** Execute a writer in a private filesystem overlay and return, but do not merge, its ChangeSet. */
+export async function inOverlay(run) {
+    const base = path.resolve(getSandboxRoot() ?? process.cwd());
+    const overlay = await mkdtemp(path.join(os.tmpdir(), 'mocode-subagent-'));
+    try {
+        await cp(base, overlay, { recursive: true, filter: (source) => !EXCLUDED.has(path.basename(source)) });
+        const before = await filesBelow(base);
+        const value = await withSandboxRoot(overlay, run);
+        return { value, changeSet: diffToChangeSet(before, await filesBelow(overlay)) };
+    }
+    finally {
+        await rm(overlay, { recursive: true, force: true });
+    }
+}
+/** The only merge point: ChangeSet preconditions and canonical resource locks prevent silent overwrite. */
+export async function mergeSubAgentChangeSet(changeSet, signal) {
+    if (!changeSet)
+        return 'committed';
+    const result = await commitChangeSet(changeSet, signal);
+    return result.status;
+}

package/dist/changeset/index.js

@@ -0,0 +1,289 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, copyFile, mkdir, readFile, rename, rm, rmdir, stat, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { jailResolve } from '../sandbox/index.js';
+import { beginPathMutation, endPathMutation } from '../rollback/index.js';
+import { canonicalFileResourceKey, toolResourceLockManager, } from '../tools/resource-lock.js';
+export function contentHash(content) {
+    const data = typeof content === 'string' ? Buffer.from(content, 'utf8') : content;
+    return `sha256:${createHash('sha256').update(data).digest('hex')}`;
+}
+export function normalizeContentHash(value) {
+    const normalized = value.trim().toLowerCase();
+    const hex = normalized.startsWith('sha256:') ? normalized.slice(7) : normalized;
+    return /^[a-f0-9]{64}$/.test(hex) ? `sha256:${hex}` : null;
+}
+function applyTextEdits(source, edits) {
+    const ordered = [...edits].sort((left, right) => left.start - right.start || left.end - right.end);
+    let cursor = 0;
+    let output = '';
+    for (const edit of ordered) {
+        if (!Number.isInteger(edit.start) || !Number.isInteger(edit.end) ||
+            edit.start < cursor || edit.end < edit.start || edit.end > source.length) {
+            throw new Error(`无效或重叠的 TextEdit 范围: ${edit.start}..${edit.end}`);
+        }
+        output += source.slice(cursor, edit.start) + edit.newText;
+        cursor = edit.end;
+    }
+    return output + source.slice(cursor);
+}
+async function readCurrent(file) {
+    try {
+        const info = await stat(file);
+        if (!info.isFile())
+            throw new Error(`目标不是普通文件: ${file}`);
+        return await readFile(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function actualHash(content) {
+    return content === null ? null : contentHash(content);
+}
+export function createChangeSet(changes) {
+    return { id: randomUUID(), createdAt: Date.now(), changes };
+}
+/** Validate every precondition and calculate every output without touching disk. */
+export async function dryRunChangeSet(changeSet) {
+    const prepared = [];
+    const conflicts = [];
+    const seen = new Set();
+    for (const change of changeSet.changes) {
+        const absolutePath = jailResolve(change.path);
+        const identity = process.platform === 'win32' ? absolutePath.toLowerCase() : absolutePath;
+        if (seen.has(identity)) {
+            conflicts.push({
+                path: change.path,
+                expectedHash: change.expectedHash,
+                actualHash: null,
+                reason: '同一 ChangeSet 不能多次修改同一路径。',
+            });
+            continue;
+        }
+        seen.add(identity);
+        const before = await readCurrent(absolutePath);
+        const beforeHash = actualHash(before);
+        if (beforeHash !== change.expectedHash) {
+            conflicts.push({
+                path: change.path,
+                expectedHash: change.expectedHash,
+                actualHash: beforeHash,
+                reason: '文件内容已变化或存在状态与预期不一致。',
+            });
+            continue;
+        }
+        try {
+            if (change.operation === 'create' && before !== null)
+                throw new Error('创建目标已经存在。');
+            if (change.operation !== 'create' && before === null)
+                throw new Error('更新或删除目标不存在。');
+            if (change.operation === 'delete' && (change.replacement !== undefined || change.edits?.length)) {
+                throw new Error('删除操作不能包含 replacement 或 edits。');
+            }
+            if (change.replacement !== undefined && change.edits?.length) {
+                throw new Error('FileChange 不能同时包含 replacement 和 edits。');
+            }
+            let after = null;
+            if (change.operation !== 'delete') {
+                const source = before?.toString('utf8') ?? '';
+                const next = change.replacement ?? applyTextEdits(source, change.edits ?? []);
+                after = Buffer.from(next, 'utf8');
+            }
+            prepared.push({
+                ...change,
+                absolutePath,
+                before,
+                after,
+                beforeHash,
+                afterHash: actualHash(after),
+            });
+        }
+        catch (error) {
+            conflicts.push({
+                path: change.path,
+                expectedHash: change.expectedHash,
+                actualHash: beforeHash,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return conflicts.length > 0
+        ? { ok: false, conflicts }
+        : { ok: true, changeSet: { ...changeSet, prepared } };
+}
+async function removeIfPresent(target) {
+    await rm(target, { recursive: true, force: true });
+}
+async function verifyPreparedVersions(prepared) {
+    const conflicts = [];
+    for (const change of prepared) {
+        const current = await readCurrent(change.absolutePath);
+        const currentHash = actualHash(current);
+        if (currentHash !== change.beforeHash) {
+            conflicts.push({
+                path: change.path,
+                expectedHash: change.beforeHash,
+                actualHash: currentHash,
+                reason: 'dry-run 后文件又被外部修改。',
+            });
+        }
+    }
+    return conflicts;
+}
+function lockRequests(changeSet) {
+    return changeSet.changes.map((change) => ({
+        key: canonicalFileResourceKey(change.path),
+        scope: 'resource',
+        mode: 'write',
+    }));
+}
+async function missingParentDirectories(file) {
+    const result = [];
+    let cursor = path.dirname(file);
+    while (true) {
+        try {
+            await stat(cursor);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            result.push(cursor);
+            const parent = path.dirname(cursor);
+            if (parent === cursor)
+                break;
+            cursor = parent;
+        }
+    }
+    return result;
+}
+/** Commit is process-transactional: every target is prepared first and any failed swap is compensated. */
+export async function commitChangeSet(changeSet, signal) {
+    try {
+        return await toolResourceLockManager.withLocks(lockRequests(changeSet), signal, async () => {
+            if (signal?.aborted) {
+                return { status: 'failed', changeSet, error: 'ChangeSet 在提交前被中断。', changedFiles: [] };
+            }
+            const dryRun = await dryRunChangeSet(changeSet);
+            if (!dryRun.ok) {
+                return { status: 'conflict', changeSet, conflicts: dryRun.conflicts, changedFiles: [] };
+            }
+            const effective = dryRun.changeSet.prepared.filter((change) => change.beforeHash !== change.afterHash);
+            if (effective.length === 0) {
+                return { status: 'committed', changeSet: dryRun.changeSet, changedFiles: [] };
+            }
+            const captures = effective.map((change) => ({
+                change,
+                capture: beginPathMutation(change.absolutePath),
+            }));
+            const createdDirectories = new Set();
+            const tempByPath = new Map();
+            const backupByPath = new Map();
+            const committed = [];
+            try {
+                // Prepare all parent directories and temp files before replacing any target.
+                for (const change of effective) {
+                    for (const directory of await missingParentDirectories(change.absolutePath)) {
+                        createdDirectories.add(directory);
+                    }
+                    await mkdir(path.dirname(change.absolutePath), { recursive: true });
+                    if (change.after !== null) {
+                        const temp = path.join(path.dirname(change.absolutePath), `.${path.basename(change.absolutePath)}.${changeSet.id}.tmp`);
+                        await writeFile(temp, change.after, { flag: 'wx' });
+                        if (change.before !== null) {
+                            const currentMode = (await stat(change.absolutePath)).mode;
+                            await chmod(temp, currentMode);
+                        }
+                        tempByPath.set(change.absolutePath, temp);
+                    }
+                }
+                // Close the dry-run/commit gap before the first visible replacement.
+                const conflicts = await verifyPreparedVersions(effective);
+                if (conflicts.length > 0) {
+                    return { status: 'conflict', changeSet, conflicts, changedFiles: [] };
+                }
+                // Once the first swap starts, finish or compensate even if the caller aborts.
+                for (const change of effective) {
+                    const backup = path.join(path.dirname(change.absolutePath), `.${path.basename(change.absolutePath)}.${changeSet.id}.bak`);
+                    if (change.before !== null) {
+                        if (change.after === null)
+                            await rename(change.absolutePath, backup);
+                        else
+                            await copyFile(change.absolutePath, backup);
+                        backupByPath.set(change.absolutePath, backup);
+                    }
+                    committed.push(change);
+                    const temp = tempByPath.get(change.absolutePath);
+                    // Same-directory rename is the atomic visibility boundary for creates/updates.
+                    if (temp)
+                        await rename(temp, change.absolutePath);
+                }
+                for (const { change, capture } of captures)
+                    endPathMutation(capture, `changeset:${changeSet.id}`);
+                for (const backup of backupByPath.values()) {
+                    await removeIfPresent(backup).catch(() => undefined);
+                }
+                return {
+                    status: 'committed',
+                    changeSet: dryRun.changeSet,
+                    changedFiles: effective.map((change) => change.path),
+                };
+            }
+            catch (error) {
+                // Reverse every visible replacement. Backups are kept until the full set succeeds.
+                for (const change of [...committed].reverse()) {
+                    try {
+                        await removeIfPresent(change.absolutePath);
+                        const backup = backupByPath.get(change.absolutePath);
+                        if (backup) {
+                            await rename(backup, change.absolutePath);
+                            backupByPath.delete(change.absolutePath);
+                        }
+                    }
+                    catch {
+                        // Continue restoring the remaining files; report the original commit failure below.
+                    }
+                }
+                return {
+                    status: 'failed',
+                    changeSet,
+                    error: error instanceof Error ? error.message : String(error),
+                    changedFiles: [],
+                };
+            }
+            finally {
+                for (const temp of tempByPath.values())
+                    await removeIfPresent(temp).catch(() => undefined);
+                // A backup left after compensation failure is deliberately preserved for manual recovery.
+                for (const directory of [...createdDirectories].sort((a, b) => b.length - a.length)) {
+                    await rmdir(directory).catch(() => undefined);
+                }
+            }
+        });
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            changeSet,
+            error: error instanceof Error ? error.message : String(error),
+            changedFiles: [],
+        };
+    }
+}
+export function summarizeChangeSet(changeSet) {
+    const effective = changeSet.prepared.filter((change) => change.beforeHash !== change.afterHash);
+    return {
+        id: changeSet.id,
+        changedFiles: effective.map((change) => change.path),
+        changes: effective.map((change) => ({
+            path: change.path,
+            operation: change.operation,
+            beforeHash: change.beforeHash,
+            afterHash: change.afterHash,
+        })),
+    };
+}

package/dist/changeset/types.js

@@ -0,0 +1 @@
+export {};