@harness-mix/cli 0.2.0 → 0.2.1

package/src/main/native/thread-list.js

@@ -16,7 +16,12 @@ function includesThread(thread, query = {}, threads = []) {
   if (query.isPinned === false && thread.isPinned) return false;
   if (query.cwd != null && !(Array.isArray(query.cwd) ? query.cwd : [query.cwd]).includes(thread.cwd)) return false;
   if (query.modelProviders?.length && !query.modelProviders.includes('harnessmix')) return false;
-  if (query.sourceKinds?.length && !query.sourceKinds.includes('vscode')) return false;
+  if (query.sourceKinds?.length) {
+    // 协作子任务线程投影为 subAgentThreadSpawn（Desktop 子代理入口按此 sourceKind 查询）；
+    // 其余外部线程保持 vscode 来源。
+    const sourceKind = thread.parentThreadId ? 'subAgentThreadSpawn' : 'vscode';
+    if (!query.sourceKinds.includes(sourceKind)) return false;
+  }
   if (query.searchTerm && !(thread.title || '').toLowerCase().includes(query.searchTerm.toLowerCase())) return false;
   return true;
 }

package/src/main/workspace/core-review.js

@@ -1,5 +1,69 @@
 const { diff } = require('./diff');
 
+// 把工具/文件事件里的路径归一化成「相对 cwd、小写、正斜杠」的形式，
+// 绝对路径只接受 cwd 之下的；归一化失败返回 null（忽略该条目）。
+function normalizePath(cwd) {
+  return value => {
+    if (typeof value !== 'string' || !value) return null;
+    let p = value.replace(/\\/g, '/');
+    if (/^[a-z]:\//i.test(p)) {
+      const lower = p.toLowerCase();
+      if (!cwd || !lower.startsWith(cwd + '/')) return null;
+      p = p.slice(cwd.length + 1);
+    }
+    p = p.replace(/^\.\//, '');
+    return p ? p.toLowerCase() : null;
+  };
+}
+
+// 收集一组 Core Turn 中可归因的触碰路径（file_change 条目与工具结构化 path）。
+function collectTurnPaths(runtime, turnIds, cwd) {
+  const add = normalizePath(cwd);
+  const touched = new Set();
+  for (const turnId of turnIds) {
+    for (const item of runtime.core.getItemsForTurn(turnId)) {
+      if (item.type !== 'file_change' && item.type !== 'tool_call') continue;
+      const p = add(item.path);
+      if (p) touched.add(p);
+    }
+  }
+  return touched;
+}
+
+// 本轮真实触碰的文件路径集合（相对 cwd、小写、正斜杠）：来自文件编辑类工具的
+// 结构化 path 与原生 file_change 条目。协作 Lead 回合合并其子线程的触碰路径，
+// 让团队卡片展示的是整个团队而非其他会话的改动。
+function touchedPaths(runtime, thread, message) {
+  const cwd = String(thread.cwd || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const turns = [message.coreTurnId];
+  for (const child of runtime.threads ?? []) {
+    if (child.parentThreadId !== thread.id) continue;
+    for (const m of child.messages ?? []) if (m.coreTurnId) turns.push(m.coreTurnId);
+  }
+  return collectTurnPaths(runtime, turns, cwd);
+}
+
+// 明确归属于「其他会话」的文件路径集合：同目录并发时，对方 Harness 上报的
+// file_change / 工具 path 条目是正向归属证据。本回合快照（目录级 diff）会把
+// 这些外来改动一起捕进来，必须按归属剔除，否则 Agent Team / 并发会话的编辑
+// 会污染本回合的变更卡片与撤回列表。只处理同 cwd 的线程：不同 cwd（worktree
+// 等）的相对路径不可比较，也进不了本目录快照。无归属证据的改动保持原行为。
+function foreignPaths(runtime, thread, message) {
+  const cwd = String(thread.cwd || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const mine = new Set([thread.id]);
+  for (const child of runtime.threads ?? []) {
+    if (child.parentThreadId === thread.id) mine.add(child.id);
+  }
+  const foreign = new Set();
+  for (const other of runtime.threads ?? []) {
+    if (mine.has(other.id)) continue;
+    if (String(other.cwd || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase() !== cwd) continue;
+    const turns = (other.messages ?? []).map(m => m.coreTurnId).filter(Boolean);
+    for (const p of collectTurnPaths(runtime, turns, cwd)) foreign.add(p);
+  }
+  return foreign;
+}
+
 // Snapshot acquisition/undo stay in Workspace. Core stores their presentation.
 async function projectReview(runtime, thread, message, record) {
   const core = runtime.core;
@@ -17,8 +81,19 @@ async function projectReview(runtime, thread, message, record) {
     const nativeItems = core.getItemsForTurn(message.coreTurnId).filter(item => item.type === 'file_change' && item.source === 'native');
     const nativePaths = new Set(nativeItems.map(item => item.path));
     changes = changes.filter(change => nativePaths.has(change.path));
+  } else if (!hasNativePatch && record.concurrent) {
+    // 无原生 patch 的 Harness（如 Pi）：并发同目录时用本轮工具触碰路径收窄全量快照，
+    // 避免同项目其他会话的改动出现在本回合卡片里。本轮没有任何可归因路径时
+    // （纯 shell 会话等）保留全量快照，不虚报归属。
+    const touched = touchedPaths(runtime, thread, message);
+    if (touched.size) changes = changes.filter(change => touched.has(change.path.toLowerCase()));
   }
 
+  // 正向归属于其他会话的改动无条件剔除（不依赖 concurrent 标记：对方可能
+  // 在本回合开始后才启动）。无归属证据的改动保持原样，不虚报归属。
+  const foreign = foreignPaths(runtime, thread, message);
+  if (foreign.size) changes = changes.filter(change => !foreign.has(change.path.toLowerCase()));
+
   core.dispatch({ threadId: thread.id, turnId: message.coreTurnId, type: 'files.updated', payload: {
     source: 'snapshot', replace: true,
     changes: changes.map(change => ({

package/src/main/workspace/diff.js

@@ -1,6 +1,10 @@
 // Bounded line LCS; large inputs use a content-exact coarse replacement.
+// Line comparison ignores CR/LF differences: a whole-file line-ending flip
+// (checkout/stash with autocrlf, editor re-save) is not a content edit and
+// must not surface as a full-file +N/-N phantom change.
+const eolSafe = s => s.replace(/\r\n$/, '\n');
 function diff(before = '', after = '') {
-  const lines = s => s ? s.match(/[^\n]*\n|[^\n]+$/g) ?? [] : [];
+  const lines = s => s ? (s.match(/[^\n]*\n|[^\n]+$/g) ?? []).map(eolSafe) : [];
   const a = lines(before), b = lines(after), rows = [];
   let old = 1, next = 1;
   const add = (kind, text) => rows.push({ kind, text: text.replace(/\r?\n$/, ''), old: kind === 'add' ? null : old++, next: kind === 'remove' ? null : next++ });

package/src/main/workspace/file-changes.js

@@ -1,12 +1,17 @@
 const path = require('node:path');
 const { diff } = require('./diff');
 
+// 工作区外的改动（Claude 计划文件、全局配置、其他盘符……）是合法事件：保留展示
+// （规范绝对路径 + outsideWorkspace 标记），撤回/预览等磁盘操作仍由既有守卫优雅拒绝。
+// 注意：这里绝不能抛错——异常会沿 emit 同步传回 Adapter 事件泵，把原生会话误判为
+// 崩溃（crashed），之后所有 send 都报“原生会话不可用”。无路径的改动同样静默丢弃。
 function canonicalChanges(cwd, changes = [], previous = []) {
-  return changes.map(change => {
+  return changes.filter(change => typeof change?.path === 'string' && change.path.trim()).map(change => {
     const absolute = path.resolve(cwd, change.path);
     const relative = path.relative(cwd, absolute).replace(/\\/g, '/');
-    if (!relative || relative === '..' || relative.startsWith('../') || path.isAbsolute(relative)) throw new Error('FileChange is outside the workspace');
-    const old = previous.find(item => item.path === relative);
+    const outside = !relative || relative === '..' || relative.startsWith('../') || path.isAbsolute(relative);
+    const canonical = outside ? absolute.replace(/\\/g, '/') : relative;
+    const old = previous.find(item => item.path === canonical);
     if (old && typeof old.before === 'string' && typeof old.after === 'string') {
       if (change.before === old.after) {
         change = { ...change, before: old.before, changeType: old.changeType === 'added' && change.changeType !== 'deleted' ? 'added' : change.changeType };
@@ -15,7 +20,7 @@ function canonicalChanges(cwd, changes = [], previous = []) {
       }
     }
     const patch = typeof change.before === 'string' && typeof change.after === 'string' ? diff(change.before, change.after) : change.patch;
-    return { ...change, path: relative, ...(patch ? { patch, added: patch.added, removed: patch.removed } : {}) };
+    return { ...change, path: canonical, ...(outside ? { outsideWorkspace: true } : {}), ...(patch ? { patch, added: patch.added, removed: patch.removed } : {}) };
   });
 }
 module.exports = { canonicalChanges };

package/src/main/workspace/review-controller.js

@@ -1,102 +1,115 @@
-const fs = require('node:fs/promises');
-const { projectReview, readReview } = require('./core-review');
-
-// Owns workspace review settlement, live refresh and undo. It never decides Turn state.
-class ReviewController {
-  constructor(runtime, { save, broadcast }) {
-    this.runtime = runtime; this.save = save; this.broadcast = broadcast;
-  }
-  get threads() { return this.runtime.threads; }
-  get reviews() { return this.runtime.reviews; }
-  get listeners() { return this.runtime.listeners; }
-  get settlements() { return this.runtime.settlements; }
-  get reviewMonitors() { return this.runtime.reviewMonitors; }
-  async settle(thread, message) {
-    if (this.settlements.has(thread.id)) return;
-    this.settlements.add(thread.id);
-    const monitor = this.reviewMonitors.get(thread.id);
-    if (monitor) { monitor.closed = true; clearInterval(monitor.timer); this.reviewMonitors.delete(thread.id); }
-    thread.reviewPending = true;
-    try {
-      if (message?.reviewId) {
-        if (message.concurrent) {
-          const loaded = await this.reviews.load(message.reviewId);
-          loaded.concurrent = true;
-          loaded.note = '此轮执行期间存在同项目并发任务，文件变更可能包含其他任务的修改。';
-          await this.reviews.save(loaded);
-        }
-        message.review = await this.reviews.finish(message.reviewId);
-        if (message.concurrent && message.review) {
-          message.review.concurrent = true;
-          message.review.note = '此轮执行期间存在同项目并发任务，文件变更可能包含其他任务的修改。';
-        }
-      }
-      if (message?.review) {
-        const record = await this.reviews.load(message.reviewId);
-        if (message.concurrent) record.concurrent = true;
-        const summary = await projectReview(this.runtime, thread, message, record);
-        if (message.concurrent) summary.concurrent = true;
-        message.review = summary;
-        this.emitReviewUpdate(thread, message, summary);
-      }
-    } catch (e) { if (message) message.reviewError = '文件审查暂不可用：' + e.message; }
-    finally {
-      thread.reviewPending = false;
-      this.settlements.delete(thread.id);
-      await this.save(); this.broadcast();
-    }
-  }
-
-  readReview(thread, message, file) { return readReview(this.runtime, thread, message, file); }
-
-  reviewMessage(threadId, messageId) {
-    const thread = this.threads.find(t => t.id === threadId);
-    const message = thread.messages.find(m => m.id === messageId);
-    if (!message?.review) throw Error('该轮没有可审查的文件快照（旧历史无法补建）');
-    return { thread, message };
-  }
-
-  // The UI subscribes to a turn-scoped event; workspace snapshots stay in Main.
-  startReviewUpdates(thread, message) {
-    if (!message.reviewId || this.reviewMonitors.has(thread.id)) return;
-    const monitor = { busy: false, closed: false };
-    const tick = async () => {
-      if (monitor.closed || monitor.busy || !message.streaming) return;
-      monitor.busy = true;
-      try {
-        const fileRevision = thread.fileRevision;
-        const record = await this.reviews.preview(message.reviewId);
-        if (!monitor.closed && message.streaming && fileRevision === thread.fileRevision) {
-          if (message.concurrent) record.concurrent = true;
-          const review = await projectReview(this.runtime, thread, message, record);
-          if (message.concurrent) review.concurrent = true;
-          message.liveReview = review;
-          this.emitReviewUpdate(thread, message, review);
-        }
-      } catch (e) {
-        if (!monitor.closed) for (const listener of this.listeners) listener({ type: 'turn/diff/updated', threadId: thread.id, turnId: message.id, error: e.message });
-      } finally { monitor.busy = false; }
-    };
-    monitor.timer = setInterval(() => void tick(), 3000);
-    monitor.timer.unref?.();
-    this.reviewMonitors.set(thread.id, monitor);
-    void tick();
-  }
-
-  emitReviewUpdate(thread, message, review) {
-    for (const listener of this.listeners) listener({ type: 'turn/diff/updated', threadId: thread.id, turnId: message.id, review });
-  }
-
-  async undoFile(threadId, messageId, file) {
-    const { thread, message } = this.reviewMessage(threadId, messageId);
-    if (this.threads.some(t => t.cwd.toLowerCase() === thread.cwd.toLowerCase() && (this.runtime.execution.isRunning(t.id) || t.status === 'working' || t.reviewPending))) throw Error('项目任务执行或结算中，暂不能撤回');
-    const record = await this.reviews.load(message.review.id);
-    if ((await fs.realpath(thread.cwd)).toLowerCase() !== record.root.toLowerCase()) throw Error('任务目录已移动，禁止从新目录撤回旧项目文件');
-    message.review = await this.reviews.undo(message.review.id, file);
-    await projectReview(this.runtime, thread, message, await this.reviews.load(message.review.id));
-    await this.save(); this.broadcast();
-    return message.review;
-  }
-
-}
-module.exports = { ReviewController };
+const fs = require('node:fs/promises');
+const { projectReview, readReview } = require('./core-review');
+
+// Owns workspace review settlement, live refresh and undo. It never decides Turn state.
+class ReviewController {
+  constructor(runtime, { save, broadcast }) {
+    this.runtime = runtime; this.save = save; this.broadcast = broadcast;
+  }
+  get threads() { return this.runtime.threads; }
+  get reviews() { return this.runtime.reviews; }
+  get listeners() { return this.runtime.listeners; }
+  get settlements() { return this.runtime.settlements; }
+  get reviewMonitors() { return this.runtime.reviewMonitors; }
+  async settle(thread, message) {
+    if (this.settlements.has(thread.id)) return;
+    this.settlements.add(thread.id);
+    const monitor = this.reviewMonitors.get(thread.id);
+    if (monitor) { monitor.closed = true; clearInterval(monitor.timer); clearTimeout(monitor.nudgeTimer); this.reviewMonitors.delete(thread.id); }
+    thread.reviewPending = true;
+    try {
+      if (message?.reviewId) {
+        if (message.concurrent) {
+          const loaded = await this.reviews.load(message.reviewId);
+          loaded.concurrent = true;
+          loaded.note = '此轮执行期间存在同项目并发任务，文件变更可能包含其他任务的修改。';
+          await this.reviews.save(loaded);
+        }
+        message.review = await this.reviews.finish(message.reviewId);
+        if (message.concurrent && message.review) {
+          message.review.concurrent = true;
+          message.review.note = '此轮执行期间存在同项目并发任务，文件变更可能包含其他任务的修改。';
+        }
+      }
+      if (message?.review) {
+        const record = await this.reviews.load(message.reviewId);
+        if (message.concurrent) record.concurrent = true;
+        const summary = await projectReview(this.runtime, thread, message, record);
+        if (message.concurrent) summary.concurrent = true;
+        message.review = summary;
+        this.emitReviewUpdate(thread, message, summary);
+      }
+    } catch (e) { if (message) message.reviewError = '文件审查暂不可用：' + e.message; }
+    finally {
+      thread.reviewPending = false;
+      this.settlements.delete(thread.id);
+      await this.save(); this.broadcast();
+    }
+  }
+
+  readReview(thread, message, file) { return readReview(this.runtime, thread, message, file); }
+
+  reviewMessage(threadId, messageId) {
+    const thread = this.threads.find(t => t.id === threadId);
+    const message = thread.messages.find(m => m.id === messageId);
+    if (!message?.review) throw Error('该轮没有可审查的文件快照（旧历史无法补建）');
+    return { thread, message };
+  }
+
+  // The UI subscribes to a turn-scoped event; workspace snapshots stay in Main.
+  startReviewUpdates(thread, message) {
+    if (!message.reviewId || this.reviewMonitors.has(thread.id)) return;
+    const monitor = { busy: false, closed: false, nudgeTimer: null };
+    const tick = async () => {
+      if (monitor.closed || monitor.busy || !message.streaming) return;
+      monitor.busy = true;
+      try {
+        const fileRevision = thread.fileRevision;
+        const record = await this.reviews.preview(message.reviewId);
+        if (!monitor.closed && message.streaming && fileRevision === thread.fileRevision) {
+          if (message.concurrent) record.concurrent = true;
+          const review = await projectReview(this.runtime, thread, message, record);
+          if (message.concurrent) review.concurrent = true;
+          message.liveReview = review;
+          this.emitReviewUpdate(thread, message, review);
+        }
+      } catch (e) {
+        if (!monitor.closed) for (const listener of this.listeners) listener({ type: 'turn/diff/updated', threadId: thread.id, turnId: message.id, error: e.message });
+      } finally { monitor.busy = false; }
+    };
+    monitor.tick = tick;
+    monitor.timer = setInterval(() => void tick(), 3000);
+    monitor.timer.unref?.();
+    this.reviewMonitors.set(thread.id, monitor);
+    void tick();
+  }
+
+  // 文件编辑工具落盘后立刻刷新一次（去抖 250ms），不再等 3s 轮询；
+  // 快照仍是唯一事实来源，这里只是提前触发。
+  nudge(threadId) {
+    const monitor = this.reviewMonitors.get(threadId);
+    if (!monitor || monitor.closed || monitor.nudgeTimer) return;
+    monitor.nudgeTimer = setTimeout(() => {
+      monitor.nudgeTimer = null;
+      if (!monitor.closed) void monitor.tick?.();
+    }, 250);
+    monitor.nudgeTimer.unref?.();
+  }
+
+  emitReviewUpdate(thread, message, review) {
+    for (const listener of this.listeners) listener({ type: 'turn/diff/updated', threadId: thread.id, turnId: message.id, review });
+  }
+
+  async undoFile(threadId, messageId, file) {
+    const { thread, message } = this.reviewMessage(threadId, messageId);
+    if (this.threads.some(t => t.cwd.toLowerCase() === thread.cwd.toLowerCase() && (this.runtime.execution.isRunning(t.id) || t.status === 'working' || t.reviewPending))) throw Error('项目任务执行或结算中，暂不能撤回');
+    const record = await this.reviews.load(message.review.id);
+    if ((await fs.realpath(thread.cwd)).toLowerCase() !== record.root.toLowerCase()) throw Error('任务目录已移动，禁止从新目录撤回旧项目文件');
+    message.review = await this.reviews.undo(message.review.id, file);
+    await projectReview(this.runtime, thread, message, await this.reviews.load(message.review.id));
+    await this.save(); this.broadcast();
+    return message.review;
+  }
+
+}
+module.exports = { ReviewController };

package/src/main/workspace/review.js

@@ -1,88 +1,90 @@
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const { randomUUID } = require('node:crypto');
-const { snapshot, resolveFile, readText } = require('./files');
-const { diff } = require('./diff');
-
-class ReviewStore {
-  constructor(directory) { this.directory = path.join(directory, 'reviews'); this.locks = new Set(); this.cache = new Map(); }
-  file(id) { if (!/^[\da-f-]{36}$/.test(id)) throw Error('无效审查 ID'); return path.join(this.directory, id + '.json'); }
-  async save(record) {
-    this.cache.set(record.id, record);
-    await fs.mkdir(this.directory, { recursive: true });
-    const file = this.file(record.id);
-    await fs.writeFile(file + '.tmp', JSON.stringify(record));
-    await fs.rename(file + '.tmp', file);
-  }
-  async load(id) {
-    if (this.cache.has(id)) return this.cache.get(id);
-    const record = JSON.parse(await fs.readFile(this.file(id), 'utf8'));
-    for (const change of record.changes) change.path = change.path.replace(/\\/g, '/');
-    this.cache.set(id, record);
-    return record;
-  }
-  async begin(root) {
-    const baseline = await snapshot(root);
-    const record = { id: randomUUID(), root: await fs.realpath(root), baseline, at: Date.now(), changes: [] };
-    await this.save(record);
-    return record.id;
-  }
-  async preview(id) {
-    const record = await this.load(id);
-    if (!record.baseline) return record;
-    const after = await snapshot(record.root, record.lastSnapshot?.files || record.baseline.files);
-    record.lastSnapshot = after;
-    record.changes = [];
-    const previousNames = new Set(record.baseline.names), currentNames = new Set(after.names);
-    for (const file of new Set([...record.baseline.names, ...after.names])) {
-      const before = record.baseline.files[file], next = after.files[file];
-      // A skipped/binary/oversized file is not a deletion or an addition.
-      if ((!before && previousNames.has(file)) || (!next && currentNames.has(file))) continue;
-      if (before?.hash === next?.hash) continue;
-      const delta = diff(before?.text, next?.text);
-      record.changes.push({ path: file.replace(/\\/g, '/'), before: before ?? null, after: next ?? null, added: delta.added, removed: delta.removed, coarse: delta.coarse });
-    }
-    record.skipped = record.baseline.skipped.length + after.skipped.length;
-    return record;
-  }
-  async finish(id) {
-    const record = await this.preview(id);
-    delete record.baseline;
-    delete record.lastSnapshot;
-    record.endedAt = Date.now();
-    await this.save(record);
-    return this.summary(record);
-  }
-  summary(record) {
-    return { id: record.id, at: record.at, endedAt: record.endedAt, live: !record.endedAt, skipped: record.skipped,
-      ...(record.concurrent ? { concurrent: true, ...(record.note ? { note: record.note } : {}) } : {}),
-      files: record.changes.map(c => ({ path: c.path, added: c.added, removed: c.removed, undone: c.undone, kind: !c.before ? 'added' : !c.after ? 'deleted' : 'modified' })) };
-  }
-  async detail(id, file) {
-    const record = await this.preview(id), change = record.changes.find(c => c.path === file);
-    if (!change) throw Error('文件不在本轮审查记录中');
-    return { path: file, undone: change.undone, ...diff(change.before?.text, change.after?.text) };
-  }
-  async undo(id, file) {
-    if (this.locks.has(id)) throw Error('撤回正在进行');
-    this.locks.add(id);
-    try {
-      const record = await this.load(id), change = record.changes.find(c => c.path === file);
-      if (!record.endedAt || !change || change.undone) throw Error('该文件不可撤回');
-      const target = await resolveFile(record.root, file);
-      let current = null;
-      try { current = await readText(record.root, file); } catch (e) { if (e.code !== 'ENOENT') throw e; }
-      if (current?.hash !== change.after?.hash) throw Error('文件在任务结束后已发生变化，拒绝覆盖。请先手动处理冲突。');
-      // The review journal retains both revisions even for a removed new file.
-      if (change.before) {
-        await fs.mkdir(path.dirname(target), { recursive: true });
-        await resolveFile(record.root, file);
-        await fs.writeFile(target, change.before.text, { flag: current ? 'w' : 'wx', mode: change.before.mode });
-      } else await fs.unlink(target);
-      change.undone = true;
-      await this.save(record);
-      return this.summary(record);
-    } finally { this.locks.delete(id); }
-  }
-}
-module.exports = { ReviewStore };
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { snapshot, resolveFile, readText } = require('./files');
+const { diff } = require('./diff');
+
+class ReviewStore {
+  constructor(directory) { this.directory = path.join(directory, 'reviews'); this.locks = new Set(); this.cache = new Map(); }
+  file(id) { if (!/^[\da-f-]{36}$/.test(id)) throw Error('无效审查 ID'); return path.join(this.directory, id + '.json'); }
+  async save(record) {
+    this.cache.set(record.id, record);
+    await fs.mkdir(this.directory, { recursive: true });
+    const file = this.file(record.id);
+    await fs.writeFile(file + '.tmp', JSON.stringify(record));
+    await fs.rename(file + '.tmp', file);
+  }
+  async load(id) {
+    if (this.cache.has(id)) return this.cache.get(id);
+    const record = JSON.parse(await fs.readFile(this.file(id), 'utf8'));
+    for (const change of record.changes) change.path = change.path.replace(/\\/g, '/');
+    this.cache.set(id, record);
+    return record;
+  }
+  async begin(root) {
+    const baseline = await snapshot(root);
+    const record = { id: randomUUID(), root: await fs.realpath(root), baseline, at: Date.now(), changes: [] };
+    await this.save(record);
+    return record.id;
+  }
+  async preview(id) {
+    const record = await this.load(id);
+    if (!record.baseline) return record;
+    const after = await snapshot(record.root, record.lastSnapshot?.files || record.baseline.files);
+    record.lastSnapshot = after;
+    record.changes = [];
+    const previousNames = new Set(record.baseline.names), currentNames = new Set(after.names);
+    for (const file of new Set([...record.baseline.names, ...after.names])) {
+      const before = record.baseline.files[file], next = after.files[file];
+      // A skipped/binary/oversized file is not a deletion or an addition.
+      if ((!before && previousNames.has(file)) || (!next && currentNames.has(file))) continue;
+      if (before?.hash === next?.hash) continue;
+      const delta = diff(before?.text, next?.text);
+      // 仅行尾符/编码差异不产生真实增删行，不列为变更（防止全文件幻影 diff）
+      if (!delta.added && !delta.removed) continue;
+      record.changes.push({ path: file.replace(/\\/g, '/'), before: before ?? null, after: next ?? null, added: delta.added, removed: delta.removed, coarse: delta.coarse });
+    }
+    record.skipped = record.baseline.skipped.length + after.skipped.length;
+    return record;
+  }
+  async finish(id) {
+    const record = await this.preview(id);
+    delete record.baseline;
+    delete record.lastSnapshot;
+    record.endedAt = Date.now();
+    await this.save(record);
+    return this.summary(record);
+  }
+  summary(record) {
+    return { id: record.id, at: record.at, endedAt: record.endedAt, live: !record.endedAt, skipped: record.skipped,
+      ...(record.concurrent ? { concurrent: true, ...(record.note ? { note: record.note } : {}) } : {}),
+      files: record.changes.map(c => ({ path: c.path, added: c.added, removed: c.removed, undone: c.undone, kind: !c.before ? 'added' : !c.after ? 'deleted' : 'modified' })) };
+  }
+  async detail(id, file) {
+    const record = await this.preview(id), change = record.changes.find(c => c.path === file);
+    if (!change) throw Error('文件不在本轮审查记录中');
+    return { path: file, undone: change.undone, ...diff(change.before?.text, change.after?.text) };
+  }
+  async undo(id, file) {
+    if (this.locks.has(id)) throw Error('撤回正在进行');
+    this.locks.add(id);
+    try {
+      const record = await this.load(id), change = record.changes.find(c => c.path === file);
+      if (!record.endedAt || !change || change.undone) throw Error('该文件不可撤回');
+      const target = await resolveFile(record.root, file);
+      let current = null;
+      try { current = await readText(record.root, file); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+      if (current?.hash !== change.after?.hash) throw Error('文件在任务结束后已发生变化，拒绝覆盖。请先手动处理冲突。');
+      // The review journal retains both revisions even for a removed new file.
+      if (change.before) {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await resolveFile(record.root, file);
+        await fs.writeFile(target, change.before.text, { flag: current ? 'w' : 'wx', mode: change.before.mode });
+      } else await fs.unlink(target);
+      change.undone = true;
+      await this.save(record);
+      return this.summary(record);
+    } finally { this.locks.delete(id); }
+  }
+}
+module.exports = { ReviewStore };