@harness-mix/cli 0.1.3

package/scripts/concurrency-layers-test.cjs

@@ -0,0 +1,181 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { HostRuntime } = require('../src/main/host/runtime');
+const { git } = require('../src/main/host/collaboration-worktree');
+
+const until = async (predicate, timeoutMs = 4000) => {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) throw new Error('Timed out waiting for condition');
+    await new Promise(r => setTimeout(r, 20));
+  }
+};
+
+(async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'hm-layers-test-'));
+  const rt = new HostRuntime({ dataDirectory: path.join(tmpDir, 'data') });
+  await rt.store.load();
+
+  // -------------------------------------------------------------
+  // Test 1: 第二层 —— 原生 Codex 协议直通 (Native Patch Passthrough)
+  // -------------------------------------------------------------
+  console.log('--- Testing Layer 2: Native Codex Protocol Passthrough ---');
+  const sharedDir = path.join(tmpDir, 'shared-repo');
+  await fs.mkdir(sharedDir);
+
+  const codexEmits = new Map();
+  const workerEmits = new Map();
+
+  const codexAdapter = {
+    manifest: {
+      id: 'mock-codex',
+      name: 'Mock Codex',
+      capabilities: { nativeDiff: true, nativePatch: true },
+    },
+    async open({ thread, emit }) {
+      codexEmits.set(thread.id, emit);
+      return {};
+    },
+    async send() {},
+    async close() {},
+  };
+
+  const workerAdapter = {
+    manifest: {
+      id: 'mock-worker',
+      name: 'Mock Worker',
+      capabilities: {},
+    },
+    async open({ thread, emit }) {
+      workerEmits.set(thread.id, emit);
+      return {};
+    },
+    async send() {},
+    async close() {},
+  };
+
+  rt.adapters.set('mock-codex', codexAdapter);
+  rt.status['mock-codex'] = { available: true };
+  rt.adapters.set('mock-worker', workerAdapter);
+  rt.status['mock-worker'] = { available: true };
+
+  const codexThread = await rt.createThread({ harnessId: 'mock-codex', cwd: sharedDir });
+  const workerThread = await rt.createThread({ harnessId: 'mock-worker', cwd: sharedDir });
+
+  // 1.1 并发执行：Worker 修改 worker.txt，Codex 修改 codex.txt
+  await rt.send(codexThread.id, 'codex edit turn');
+  await rt.send(workerThread.id, 'worker edit turn');
+
+  const codexMsg1 = codexThread.messages.at(-1);
+  const workerMsg1 = workerThread.messages.at(-1);
+
+  // Worker 在磁盘写入 worker.txt
+  await fs.writeFile(path.join(sharedDir, 'worker.txt'), 'from worker\n');
+  const workerEmit1 = workerEmits.get(workerThread.id);
+  workerEmit1({ kind: 'text-delta', text: 'worker done' });
+  workerEmit1({ kind: 'completed', finalAnswer: true });
+  await until(() => workerThread.status === 'ready' && !workerThread.reviewPending);
+
+  // Codex 原生通过 fileChange 汇报修改 codex.txt
+  await fs.writeFile(path.join(sharedDir, 'codex.txt'), 'from codex\n');
+  const codexEmit1 = codexEmits.get(codexThread.id);
+  codexEmit1({
+    kind: 'file-change',
+    source: 'native',
+    changes: [{
+      path: path.join(sharedDir, 'codex.txt'),
+      patch: '@@ -0,0 +1,1 @@\n+from codex',
+      complete: true,
+    }],
+  });
+  codexEmit1({ kind: 'text-delta', text: 'codex done' });
+  codexEmit1({ kind: 'completed', finalAnswer: true });
+  await until(() => codexThread.status === 'ready' && !codexThread.reviewPending);
+
+  // 核心断言：由于原生协议直通生效，Codex 的审查记录中 ONLY 包含 codex.txt，绝不混入并发的 worker.txt！
+  const codexReview1 = await rt.readReview(codexThread, codexMsg1);
+  assert.equal(codexReview1.files.length, 1, 'Codex review should only contain its own file');
+  assert.equal(codexReview1.files[0].path, 'codex.txt');
+  assert.equal(codexReview1.files.some(f => f.path === 'worker.txt'), false, 'Worker file must NOT leak into Codex review');
+
+  // 1.2 并发执行：Worker 修改其他文件，Codex 仅纯问答（0 原生变更）
+  await rt.send(codexThread.id, 'codex question turn');
+  await rt.send(workerThread.id, 'worker second turn');
+
+  const codexMsg2 = codexThread.messages.at(-1);
+  await fs.writeFile(path.join(sharedDir, 'worker2.txt'), 'another worker edit\n');
+  const workerEmit2 = workerEmits.get(workerThread.id);
+  workerEmit2({ kind: 'completed', finalAnswer: true });
+  await until(() => workerThread.status === 'ready' && !workerThread.reviewPending);
+
+  const codexEmit2 = codexEmits.get(codexThread.id);
+  codexEmit2({ kind: 'text-delta', text: 'just an answer, no files modified' });
+  codexEmit2({ kind: 'completed', finalAnswer: true });
+  await until(() => codexThread.status === 'ready' && !codexThread.reviewPending);
+
+  const codexReview2 = await rt.readReview(codexThread, codexMsg2);
+  assert.equal(codexReview2.files.length, 0, 'Pure question in Codex must have exactly 0 files despite concurrent edits');
+
+  console.log('Layer 2 (Native Codex Protocol Passthrough) passed successfully!');
+
+  // -------------------------------------------------------------
+  // Test 2: 第三层 —— 基于 Git Worktree 的物理隔离 (Worktree Isolation)
+  // -------------------------------------------------------------
+  console.log('--- Testing Layer 3: Git Worktree Physical Isolation ---');
+  const gitRepo = path.join(tmpDir, 'git-project');
+  await fs.mkdir(gitRepo);
+  await git(gitRepo, ['init']);
+  await git(gitRepo, ['config', 'core.autocrlf', 'false']);
+  await fs.writeFile(path.join(gitRepo, 'main-code.txt'), 'initial main code\n');
+  await git(gitRepo, ['add', '.']);
+  await git(gitRepo, ['-c', 'user.name=Test', '-c', 'user.email=test@example.com', 'commit', '-m', 'initial commit']);
+
+  // 新建启用 Worktree 隔离的任务
+  const wtThread = await rt.createThread({
+    harnessId: 'mock-worker',
+    cwd: gitRepo,
+    worktree: true,
+  });
+
+  assert.equal(wtThread.isolation, 'worktree', 'Thread should have worktree isolation');
+  assert.ok(wtThread.workspace, 'Thread should hold a workspace object');
+  assert.equal(wtThread.workspace.mode, 'worktree');
+  assert.notEqual(wtThread.cwd, gitRepo, 'Worktree cwd must be physically different from gitRepo');
+  assert.equal(wtThread.originalCwd, gitRepo);
+  const [physicalSource, physicalWorktree] = await Promise.all([fs.realpath(gitRepo), fs.realpath(wtThread.cwd)]);
+  assert.notEqual(physicalWorktree, physicalSource, 'Worktree cwd must resolve to a different physical directory');
+
+  // 在主仓库和隔离分支同时并发写入同名或不同文件
+  await fs.writeFile(path.join(gitRepo, 'main-code.txt'), 'main modified\n');
+  await fs.writeFile(path.join(wtThread.cwd, 'worktree-feature.txt'), 'new feature in branch\n');
+
+  // 物理隔离验证：主仓库绝对看不到工作树创建的文件
+  await assert.rejects(fs.access(path.join(gitRepo, 'worktree-feature.txt')), 'Main repo must not see isolated worktree files');
+
+  // 审查隔离工作区改动
+  const wtReview = await rt.reviewThreadWorkspace(wtThread.id);
+  assert.match(wtReview.patch, /worktree-feature\.txt/);
+
+  // 将隔离分支改动合入主项目
+  await rt.applyThreadWorkspace(wtThread.id, wtReview.digest);
+  assert.equal(
+    await fs.readFile(path.join(gitRepo, 'worktree-feature.txt'), 'utf8'),
+    'new feature in branch\n',
+    'Main repo should now have the applied file after applyThreadWorkspace'
+  );
+
+  // 删除线程时自动清理 Worktree 分支与临时目录
+  const wtRoot = wtThread.workspace.root;
+  await rt.removeThread(wtThread.id);
+  await assert.rejects(fs.access(wtRoot), 'Worktree directory should be cleaned up on removeThread');
+
+  console.log('Layer 3 (Git Worktree Physical Isolation) passed successfully!');
+
+  await rt.close();
+  console.log('ALL CONCURRENCY LAYERS TESTS PASSED!');
+})().catch(error => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/scripts/contracts-test.cjs

@@ -0,0 +1,105 @@
+// PR 1 验收：Shared Contracts schema 测试（无 Electron）。
+const assert = require('node:assert');
+const contracts = require('../src/main/shared-contracts');
+
+let passed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log('ok', name); }
+  catch (error) { console.error('FAIL', name, '-', error.message); process.exitCode = 1; }
+}
+
+/* ---------- Thread ---------- */
+test('thread: create + validate', () => {
+  const thread = contracts.createThread({ workspaceId: '/repo', harnessId: 'harness-x', nativeSessionRef: { sessionId: 's1' } });
+  assert.deepStrictEqual(contracts.validateThread(thread), []);
+  assert.strictEqual(thread.status, 'idle');
+  assert.strictEqual(thread.activeTurnId, null);
+  assert.deepStrictEqual(thread.nativeSessionRef, { sessionId: 's1' });
+});
+
+test('thread: rejects bad status', () => {
+  const thread = contracts.createThread({ workspaceId: '/repo' });
+  thread.status = 'bogus';
+  assert.ok(contracts.validateThread(thread).some((e) => e.includes('status')));
+});
+
+/* ---------- Turn ---------- */
+test('turn: create + validate', () => {
+  const turn = contracts.createTurn({ threadId: 'thread_1', nativeTurnRef: { turnId: 'nt-1' } });
+  assert.deepStrictEqual(contracts.validateTurn(turn), []);
+  assert.strictEqual(turn.status, 'created');
+  assert.deepStrictEqual(turn.itemIds, []);
+});
+
+test('turn: transition table rejects terminal → running', () => {
+  assert.strictEqual(contracts.canTransition('running', 'completed'), true);
+  assert.strictEqual(contracts.canTransition('completed', 'running'), false);
+  assert.strictEqual(contracts.canTransition('cancelled', 'running'), false);
+  assert.strictEqual(contracts.canTransition('waiting_interaction', 'running'), true);
+  assert.strictEqual(contracts.canTransition('created', 'completed'), false);
+});
+
+/* ---------- Item ---------- */
+test('item: create + validate (all phase-1 types)', () => {
+  for (const type of contracts.ITEM_TYPES) {
+    const item = contracts.createItem({ threadId: 'thread_1', turnId: 'turn_1', type });
+    assert.deepStrictEqual(contracts.validateItem(item), [], `type ${type}`);
+  }
+});
+
+test('item: rejects unknown type', () => {
+  const item = contracts.createItem({ threadId: 'thread_1', type: 'nope' });
+  assert.ok(contracts.validateItem(item).some((e) => e.includes('type')));
+});
+
+/* ---------- CoreEvent ---------- */
+test('event: create fills eventId/timestamp/payload', () => {
+  const event = contracts.createCoreEvent({ threadId: 'thread_1', type: 'turn.started' });
+  assert.deepStrictEqual(contracts.validateCoreEvent(event), []);
+  assert.ok(event.eventId.startsWith('evt_'));
+  assert.strictEqual(typeof event.timestamp, 'number');
+  assert.deepStrictEqual(event.payload, {});
+});
+
+test('event: rejects unknown type / missing threadId', () => {
+  assert.ok(contracts.validateCoreEvent(contracts.createCoreEvent({ threadId: 't', type: 'bogus' })).length > 0);
+  assert.ok(contracts.validateCoreEvent(contracts.createCoreEvent({ type: 'turn.started' })).some((e) => e.includes('threadId')));
+});
+
+/* ---------- NativeRef ---------- */
+test('nativeRef: all fields optional, unknown keys rejected', () => {
+  assert.deepStrictEqual(contracts.validateNativeRef(undefined), []);
+  assert.deepStrictEqual(contracts.validateNativeRef({}), []);
+  assert.deepStrictEqual(contracts.validateNativeRef({ sessionId: 's', toolCallId: 'tc' }), []);
+  assert.ok(contracts.validateNativeRef({ whatever: 'x' }).some((e) => e.includes('whatever')));
+});
+
+/* ---------- Capability ---------- */
+test('capability: defaults all false, overrides applied', () => {
+  const caps = contracts.createCapabilities({ session: { fork: true }, usage: { tokens: true } });
+  assert.deepStrictEqual(contracts.validateCapabilities(caps), []);
+  assert.strictEqual(caps.session.fork, true);
+  assert.strictEqual(caps.session.resume, false);
+  assert.strictEqual(caps.usage.tokens, true);
+  assert.strictEqual(caps.conversation.streaming, false);
+  // 全组全覆盖
+  for (const group of Object.keys(contracts.CAPABILITY_GROUPS)) assert.ok(caps[group]);
+});
+
+test('capability: rejects unknown group/key', () => {
+  assert.ok(contracts.validateCapabilities({ nope: {} }).length > 0);
+  assert.ok(contracts.validateCapabilities({ session: { teleport: true } }).length > 0);
+});
+
+/* ---------- Interaction ---------- */
+test('interaction: create + validate', () => {
+  const interaction = contracts.createInteraction({
+    threadId: 'thread_1', turnId: 'turn_1', type: 'approval',
+    title: '确认', options: [{ id: 'yes' }, 'no'], nativeRef: { interactionId: 'req-1' },
+  });
+  assert.deepStrictEqual(contracts.validateInteraction(interaction), []);
+  assert.strictEqual(interaction.status, 'pending');
+  assert.deepStrictEqual(interaction.options, [{ id: 'yes', label: 'yes' }, { id: 'no', label: 'no' }]);
+});
+
+console.log(`contracts: ${passed} passed`);

package/scripts/core-concurrency-test.cjs

@@ -0,0 +1,103 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { HostRuntime } = require('../src/main/host/runtime');
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+async function until(fn) {
+  for (let i = 0; i < 200; i++) { if (fn()) return; await sleep(10); }
+  throw new Error('timed out');
+}
+
+(async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'hm-core-concurrency-'));
+  const root = path.join(directory, 'workspace');
+  await fs.mkdir(root);
+
+  const rt = new HostRuntime({ dataDirectory: directory });
+  await rt.store.load();
+
+  const emits = new Map();
+  const adapter = {
+    manifest: { id: 'test-harness', name: 'Test', capabilities: {} },
+    async open(input) {
+      emits.set(input.thread.id, input.emit);
+      return {};
+    },
+    async send(session) {},
+    async cancel(session) {},
+    async close() {},
+  };
+  rt.adapters.set(adapter.manifest.id, adapter);
+  rt.status[adapter.manifest.id] = { available: true };
+
+  const thread1 = await rt.createThread({ harnessId: adapter.manifest.id, cwd: root });
+  const thread2 = await rt.createThread({ harnessId: adapter.manifest.id, cwd: root });
+
+  try {
+    // 1. thread1 先完成一轮基础操作（生成 base.txt 与可撤回快照）
+    await rt.send(thread1.id, 'task 1 initial turn');
+    await fs.writeFile(path.join(root, 'base.txt'), 'initial content\n');
+    const emit1_initial = emits.get(thread1.id);
+    emit1_initial({ kind: 'text-delta', text: 'initial turn finished' });
+    emit1_initial({ kind: 'completed', finalAnswer: true });
+    await until(() => thread1.status === 'ready' && !thread1.reviewPending);
+    const msg0 = thread1.messages.at(-1);
+    assert.ok(msg0.review, 'msg0 should have review');
+
+    // 2. 启动 thread1 的下一轮 turn
+    await rt.send(thread1.id, 'task 1 running turn 2');
+    assert.equal(rt.execution.isRunning(thread1.id), true, 'thread1 should be running');
+
+    // 3. 在同一项目 (root) 下并发发送 thread2 的 turn（旧版本此处会硬性报错中断）
+    await rt.send(thread2.id, 'task 2 concurrent question');
+    assert.equal(rt.execution.isRunning(thread2.id), true, 'thread2 should also run concurrently');
+
+    // 验证并发标记已被打上
+    const msg1 = thread1.messages.at(-1);
+    const msg2 = thread2.messages.at(-1);
+    assert.equal(msg1.concurrent, true, 'thread1 turn should be marked concurrent');
+    assert.equal(msg2.concurrent, true, 'thread2 turn should be marked concurrent');
+
+    // 4. 并发期间撤回历史快照应当被安全拦截
+    await assert.rejects(
+      rt.undoFile(thread1.id, msg0.id, 'base.txt'),
+      /项目任务执行或结算中，暂不能撤回/
+    );
+
+    // 5. thread2 为纯问答任务，先完成
+    const emit2 = emits.get(thread2.id);
+    emit2({ kind: 'text-delta', text: 'answer for task 2' });
+    emit2({ kind: 'completed', finalAnswer: true });
+    await until(() => thread2.status === 'ready' && !thread2.reviewPending);
+
+    // thread2 无文件改动，结算正常
+    const review2 = await rt.readReview(thread2, msg2);
+    assert.equal(review2.files.length, 0, 'pure question should have 0 file changes');
+    assert.equal(review2.concurrent, true, 'review2 should record concurrent execution');
+
+    // 6. thread1 写文件后完成
+    await fs.writeFile(path.join(root, 'task1-output.txt'), 'hello from task 1\n');
+    const emit1 = emits.get(thread1.id);
+    emit1({ kind: 'text-delta', text: 'finished task 1' });
+    emit1({ kind: 'completed', finalAnswer: true });
+    await until(() => thread1.status === 'ready' && !thread1.reviewPending);
+
+    const review1 = await rt.readReview(thread1, msg1);
+    assert.equal(review1.files.length, 1, 'thread1 should track its file change');
+    assert.equal(review1.concurrent, true, 'review1 should record concurrent execution');
+    assert.ok(review1.note.includes('并发任务'), 'review note should explain concurrency');
+
+    // 7. 全部空闲后，安全撤回可以正常执行
+    await rt.undoFile(thread1.id, msg0.id, 'base.txt');
+    await assert.rejects(fs.access(path.join(root, 'base.txt')));
+
+    console.log('core-concurrency-test: same-cwd concurrency, review degradation, and undo guard passed');
+  } finally {
+    await rt.close();
+  }
+})().catch(error => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/scripts/core-replay-test.cjs

@@ -0,0 +1,179 @@
+// PR 4 验收（§18/§19）：无 Electron 回放真实 Harness 事件 fixtures。
+// 链路覆盖：Native Event → Adapter 投影（统一事件）→ Normalizer → CoreEvent → Projector → State，
+// 并用 ShadowComparator 验证 Core 投影与 Legacy Transcript 语义一致。
+const fs = require('node:fs');
+const path = require('node:path');
+const { ProtocolCore } = require('../src/main/protocol-core');
+const { ShadowMirror } = require('./support/shadow.cjs');
+const { appendDelta, projectTool, finishMessage } = require('./support/legacy-transcript.cjs');
+const pi = require('../src/main/adapters/pi');
+const claude = require('../src/main/adapters/claude');
+const dsh = require('../src/main/adapters/dsh');
+
+// Native Event → 统一事件的各 Adapter 纯投影函数（与运行时同一份实现）
+const PROJECTORS = {
+  pi: (event) => pi.project(event),
+  claude: (event) => claude.projectEvent(event),
+  dsh: (event) => dsh.projectWireEvent(event),
+};
+// Adapter 在原生流之外自行合成的事件（§replay 边界诚实声明）：
+// - cancel 场景：runtime.cancel() 直接结算为 cancelled（DSH turn/end interrupted 同为原生结算）
+function syntheticTail(harnessId, label) {
+  if (label === 'cancel') return [{ kind: 'completed', stopReason: 'cancelled' }];
+  return [];
+}
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log('ok', name); }
+  catch (error) { failed++; console.error('FAIL', name, '-', error.message); process.exitCode = 1; }
+}
+
+/** Legacy 投影模拟：与 runtime #applyEvent 对消息/工具/用量部分的语义一致 */
+function legacySimulator() {
+  const thread = { id: 'replay-thread', harnessId: null, cwd: '/replay', messages: [], tools: [], pendingApprovals: [], usage: {} };
+  const appendAssistant = () => {
+    const message = { id: `m${thread.messages.length}`, role: 'assistant', text: '', at: Date.now(), streaming: true };
+    thread.messages.push(message);
+    return message;
+  };
+  const apply = (event) => {
+    const last = thread.messages.at(-1);
+    switch (event.kind) {
+      case 'text-delta': {
+        const target = last?.role === 'assistant' && last.streaming ? last : appendAssistant();
+        target.text += event.text;
+        appendDelta(target, 'text', event.text);
+        break;
+      }
+      case 'thinking-delta': {
+        const target = last?.role === 'assistant' && last.streaming ? last : appendAssistant();
+        target.thinking = (target.thinking ?? '') + event.text;
+        appendDelta(target, 'thinking', event.text);
+        break;
+      }
+      case 'tool': {
+        const target = last?.role === 'assistant' && last.streaming ? last : appendAssistant();
+        projectTool(thread, target, event);
+        break;
+      }
+      case 'approval':
+        if (!thread.pendingApprovals.some((a) => a.requestId === event.requestId)) {
+          thread.pendingApprovals.push({ requestId: event.requestId, title: event.title });
+        }
+        break;
+      case 'usage':
+        thread.usage = { ...thread.usage, ...event.usage };
+        break;
+      case 'completed':
+        finishMessage(thread, last, event.stopReason ?? 'completed');
+        break;
+      case 'error':
+        thread.error = event.message;
+        finishMessage(thread, last, 'error');
+        break;
+      default: break; // status/notice/session/artifact 不参与对照
+    }
+  };
+  return { thread, apply };
+}
+
+function replayFixture(harnessId, label, file) {
+  const project = PROJECTORS[harnessId];
+  const records = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+  const nativeCount = records.filter((r) => !r.__control__).length;
+  const legacyEvents = [];
+  for (const record of records) {
+    // 控制记录：宿主动作（cancel）在事件流中的真实位置 → 注入 runtime 合成事件
+    if (record.__control__ === 'cancel') { legacyEvents.push({ kind: 'completed', stopReason: 'cancelled' }); continue; }
+    if (record.__control__) continue;
+    const mapped = project(record);
+    legacyEvents.push(...(Array.isArray(mapped) ? mapped : [mapped]).filter(Boolean));
+  }
+  const hasSettlement = legacyEvents.some((e) => e.kind === 'completed' || e.kind === 'error');
+  const events = hasSettlement ? legacyEvents : [...legacyEvents, ...syntheticTail(harnessId, label)];
+
+  // Legacy 路径：用户消息 + streaming assistant 占位（与 runtime.send 一致）
+  const legacy = legacySimulator();
+  legacy.thread.harnessId = harnessId;
+  legacy.thread.messages.push({ id: 'u1', role: 'user', text: '<fixture prompt>', at: Date.now() });
+  legacy.thread.messages.push({ id: 'a1', role: 'assistant', text: '', at: Date.now(), streaming: true });
+
+  // Core 路径：Shadow Mirror（与运行时同一份实现）
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  shadow.threadCreated(legacy.thread);
+  shadow.turnStarted(legacy.thread, '<fixture prompt>');
+
+  for (const event of events) {
+    legacy.apply(event); // 先更新 legacy，再让 shadow 对照（同 runtime 顺序）
+    shadow.applyLegacyEvent(legacy.thread, event);
+  }
+
+  const lastMessage = legacy.thread.messages.at(-1);
+  // 结算判定以“是否应用过结算事件”为准：cancel 后迟到的原生 chunk 会在 legacy 侧
+  // 留下悬挂的 streaming 消息（真实 runtime 行为），不代表 Turn 未结算。
+  const settled = events.some((e) => e.kind === 'completed' || e.kind === 'error');
+  const turn = core.turns.turnsForThread(legacy.thread.id)[0];
+  const items = core.getItemsForTurn(turn.id);
+  const report = shadow.report();
+
+  return { nativeCount, legacyEvents: events, legacy: legacy.thread, settled, turn, items, report, lastMessage };
+}
+
+const fixturesRoot = path.join(__dirname, '..', 'fixtures');
+if (!fs.existsSync(fixturesRoot)) {
+  console.error('FAIL fixtures/ 不存在，先运行 node scripts/fixture-capture.cjs');
+  process.exit(1);
+}
+
+for (const harnessId of Object.keys(PROJECTORS)) {
+  const dir = path.join(fixturesRoot, harnessId);
+  if (!fs.existsSync(dir)) { test(`[${harnessId}] required fixtures`, () => { throw new Error('missing fixture directory'); }); continue; }
+  for (const label of ['simple-message', 'reasoning', 'tool-call', 'file-edit', 'cancel']) {
+    test(`[${harnessId}/${label}] required scenario present`, () => {
+      if (!fs.existsSync(path.join(dir, `${label}.jsonl`))) throw new Error('missing required scenario');
+    });
+  }
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')).sort()) {
+    const label = file.replace(/\.jsonl$/, '');
+    test(`[${harnessId}/${label}] native → legacy → core 回放一致`, () => {
+      const r = replayFixture(harnessId, label, path.join(dir, file));
+      if (r.nativeCount === 0) throw new Error('empty fixture');
+      if (r.report.errors.length) throw new Error(`shadow errors: ${JSON.stringify(r.report.errors)}`);
+
+      if (!r.settled) throw new Error('fixture never settled');
+      // cancel 场景 Core 必须保持 cancelled（首次结算生效）
+      if (label === 'cancel' && r.turn.status !== 'cancelled') throw new Error(`cancel fixture but turn=${r.turn.status}`);
+      // Shadow Match：语义一致性零差异（§15）
+      // 已知可忽略差异：cancel 后原生流迟到的结算事件会覆盖 legacy stopReason（旧逻辑怪癖），
+      // Core 按“首次结算生效”保持 cancelled —— 只记录，不改变现有用户行为（约束 #14）。
+      let mismatches = r.report.mismatches.flatMap((m) => m.mismatches);
+      if (mismatches.length) throw new Error(`shadow mismatch: ${JSON.stringify(mismatches)}`);
+
+      // 场景不变量：期望状态由 legacy 终态推导（fixture 可能记录了真实的限流/错误回合）
+      const expected = label === 'cancel' ? 'cancelled' : 'completed';
+      if (r.turn.status !== expected) throw new Error(`turn=${r.turn.status}, expected ${expected}`);
+      if (r.legacy.error) console.log(`  note: [${harnessId}/${label}] fixture 为真实错误回合：${r.legacy.error.slice(0, 60)}`);
+      if (!r.items.some((i) => i.type === 'user_message')) throw new Error('missing user_message item');
+      const answer = r.items.filter((i) => i.type === 'agent_message').map((i) => i.content).join('');
+      const legacyText = r.legacy.messages.filter((m) => m.role === 'assistant').map((m) => m.text).join('');
+      if (answer !== legacyText) throw new Error('agent_message ≠ legacy text');
+      // 覆盖度提示（不否决）：fixture 名宣称的类型是否真的出现
+      const coverage = {
+        'file-edit': r.items.some((i) => i.type === 'tool_call'),
+        'tool-call': r.items.some((i) => i.type === 'tool_call'),
+        reasoning: r.items.some((i) => i.type === 'reasoning' && i.content),
+        usage: r.items.some((i) => i.type === 'usage'),
+      }[label];
+      if (coverage === false) throw new Error('fixture does not cover declared scenario');
+      if (label === 'file-edit') {
+        const evidence = JSON.parse(fs.readFileSync(path.join(dir, `${label}.capture.json`), 'utf8'));
+        if (!evidence.fileVerified) throw new Error('missing real file edit verification');
+      }
+    });
+  }
+}
+
+console.log(`core-replay: ${passed} passed${failed ? `, ${failed} failed` : ''}`);