harness-mix 0.1.0

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` : ''}`);

package/scripts/core-runtime-test.cjs

@@ -0,0 +1,104 @@
+const { ParityObserver } = require('./support/parity-observer.cjs');
+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-runtime-'));
+  const root = path.join(directory, 'workspace'); await fs.mkdir(root);
+  const rt = new HostRuntime({ observer: new ParityObserver(), dataDirectory: directory });
+  await rt.store.load();
+  let emit, sent = 0, mode = 'hold', rejectResponse = false;
+  const adapter = {
+    manifest: { id: 'test-harness', name: 'Test', capabilities: {} },
+    async open(input) { emit = input.emit; return {}; },
+    async send() {
+      sent++;
+      const turn = rt.execution.lastTurn(thread.id);
+      assert.equal(turn.status, 'running', 'Core Turn exists before native send');
+      if (mode === 'failure') throw new Error('native failure');
+    },
+    async cancel() { emit({ kind: 'completed', finalAnswer: true }); emit({ kind: 'text-delta', text: 'LATE' }); },
+    async respond() { if (rejectResponse) throw new Error('response failed'); },
+    async close() {},
+  };
+  rt.adapters.set(adapter.manifest.id, adapter); rt.status[adapter.manifest.id] = { available: true };
+  const thread = await rt.createThread({ harnessId: adapter.manifest.id, cwd: root });
+  try {
+    await rt.send(thread.id, 'hello');
+    const first = thread.messages.at(-1).coreTurnId;
+    const notices = []; const unsubscribe = rt.subscribe(event => notices.push(event));
+    emit({ kind: 'status', text: 'native progress' });
+    assert.ok(notices.some(event => event.type === 'toast' && event.threadId === thread.id));
+    unsubscribe();
+    emit({ kind: 'approval', requestId: 'a', method: 'confirm', title: 'Allow?' });
+    emit({ kind: 'approval', requestId: 'q', method: 'input', title: 'Name?' });
+    assert.equal(rt.execution.lastTurn(thread.id).status, 'waiting_interaction');
+    rejectResponse = true;
+    await assert.rejects(rt.respondApproval(thread.id, 'a', {}), /response failed/);
+    assert.equal(rt.execution.lastTurn(thread.id).status, 'waiting_interaction');
+    rejectResponse = false;
+    await rt.respondApproval(thread.id, 'a', { confirmed: true });
+    assert.equal(rt.execution.lastTurn(thread.id).status, 'waiting_interaction');
+    await rt.respondApproval(thread.id, 'q', { value: 'test' });
+    assert.equal(rt.execution.lastTurn(thread.id).status, 'running');
+    emit({ kind: 'thinking-delta', text: 'think' });
+    emit({ kind: 'text-delta', text: 'answer' });
+    emit({ kind: 'usage', usage: { inputTokens: 10 } });
+    await fs.writeFile(path.join(root, 'change.txt'), 'Core review content');
+    emit({ kind: 'completed', finalAnswer: true });
+    await until(() => (thread.status === 'ready' && !thread.reviewPending));
+    assert.equal(thread.messages.at(-1).coreTurn.status, 'completed');
+    const completedMessage = thread.messages.at(-1);
+    const review = await rt.readReview(thread, completedMessage);
+    assert.equal(review.files[0].type, 'file_change');
+    assert.equal(review.files[0].source, 'snapshot');
+    assert.equal((await rt.readReview(thread, completedMessage, 'change.txt')).rows[0].kind, 'add');
+    await rt.undoFile(thread.id, completedMessage.id, 'change.txt');
+    assert.equal(completedMessage.coreReview.files[0].undone, true);
+    await assert.rejects(fs.access(path.join(root, 'change.txt')));
+    assert.ok(thread.messages.at(-1).coreItems.some(i => i.phase === 'final' && i.content === 'answer'));
+    assert.deepEqual(rt.shadowReport().mismatches, []);
+    await rt.send(thread.id, 'cancel');
+    assert.notEqual(thread.messages.at(-1).coreTurnId, first);
+    await rt.cancel(thread.id);
+    await until(() => (thread.status === 'ready' && !thread.reviewPending));
+    assert.equal(thread.messages.at(-1).coreTurn.status, 'cancelled');
+    assert.equal(thread.messages.at(-1).text, '');
+    mode = 'failure';
+    await rt.send(thread.id, 'fail');
+    await until(() => thread.status === 'error' && !thread.reviewPending);
+    assert.equal(thread.messages.at(-1).coreTurn.status, 'error');
+    mode = 'hold';
+    let release;
+    const begin = rt.reviews.begin.bind(rt.reviews);
+    rt.reviews.begin = () => new Promise(resolve => { release = resolve; });
+    const before = sent;
+    const pending = rt.send(thread.id, 'cancel during preparation');
+    await until(() => release);
+    await rt.cancel(thread.id);
+    release(undefined); await pending;
+    await until(() => (thread.status === 'ready' && !thread.reviewPending));
+    assert.equal(sent, before);
+    assert.equal(thread.messages.at(-1).coreTurn.status, 'cancelled');
+    rt.reviews.begin = begin;
+    assert.deepEqual(rt.shadowReport().errors, []);
+    await rt.close();
+    const saved = await rt.store.load();
+    assert.equal(saved[0].messages.find(m => m.coreTurnId === first).coreTurn.status, 'completed');
+    const restored = new HostRuntime({ dataDirectory: directory });
+    restored.threads = await restored.store.load();
+    for (const record of restored.threads) restored.execution.threadCreated(record);
+    assert.equal(restored.core.getTurn(first).status, 'completed');
+    assert.ok(restored.core.getItemsForTurn(first).some(i => i.type === 'file_change' && i.undone));
+    assert.equal(restored.shadowReport().enabled, false);
+    await restored.close();
+    console.log('core-runtime: independent turns, waiting/responses, failure, cancel races, persistence passed');
+  } finally { await rt.close(); }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/scripts/core-services-test.cjs

@@ -0,0 +1,50 @@
+const assert = require('node:assert/strict');
+const { ProtocolCore } = require('../src/main/protocol-core');
+const { ShadowMirror } = require('./support/shadow.cjs');
+const { CapabilityManager } = require('../src/main/protocol-core/capability-manager');
+const { normalizeCapabilities } = require('../src/main/harness-adapter/manifest');
+
+(async () => {
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  const thread = { id: 't', cwd: '/test', messages: [{ role: 'assistant', at: 1 }] };
+  shadow.threadCreated(thread); shadow.turnStarted(thread, 'test');
+  const turn = shadow.lastTurn('t');
+  const emit = e => shadow.applyLegacyEvent(thread, e);
+  emit({ kind: 'approval', requestId: 'q', method: 'input', title: 'Question' });
+  assert.equal(core.interactions.pending('t').length, 1);
+  let release, calls = 0;
+  const response = core.interactions.respond('t', 'q', {}, async () => { calls++; await new Promise(resolve => { release = resolve; }); });
+  await assert.rejects(core.interactions.respond('t', 'q', {}, () => {}), /正在提交/);
+  await assert.rejects(core.interactions.respond('other', 'q', {}, () => {}), /过期/);
+  release(); await response;
+  assert.equal(calls, 1); assert.equal(turn.status, 'running');
+  assert.equal(core.interactions.pending('t').length, 0);
+  const files = (source, changes, replace = false) => core.dispatch({ threadId: 't', turnId: turn.id,
+    type: 'files.updated', payload: { source, changes, replace } });
+  files('snapshot', [{ path: 'a', before: 'x', after: 'y', complete: true }]);
+  files('native', [{ path: 'a', patch: 'incomplete', complete: false }]);
+  assert.equal(core.getItemsForTurn(turn.id).find(i => i.type === 'file_change').source, 'snapshot');
+  files('native', [{ path: 'a', before: 'x', after: 'y', complete: true }]);
+  files('snapshot', [{ path: 'a', after: 'other' }]);
+  const changes = core.getItemsForTurn(turn.id).filter(i => i.type === 'file_change');
+  assert.equal(changes.length, 1); assert.equal(changes[0].source, 'native');
+  files('git', [{ path: 'b', after: 'z' }]);
+  files('git', [], true);
+  assert.equal(core.getItemsForTurn(turn.id).filter(i => i.type === 'file_change').length, 1);
+  emit({ kind: 'plan', entries: [{ content: 'Inspect', status: 'in_progress' }] });
+  emit({ kind: 'plan', entries: [{ content: 'Inspect', status: 'completed' }] });
+  assert.equal(core.getItemsForTurn(turn.id).filter(i => i.type === 'plan').length, 1);
+  assert.equal(core.getItemsForTurn(turn.id).find(i => i.type === 'plan').entries[0].status, 'completed');
+  core.dispatch({ threadId: 't', turnId: turn.id, type: 'turn.completed' });
+  files('snapshot', [{ path: 'c', after: 'settled review' }]);
+  assert.ok(core.getItemsForTurn(turn.id).some(i => i.path === 'c'));
+  const caps = new CapabilityManager();
+  caps.register('new-harness', normalizeCapabilities({ fork: true, questions: true, plan: true }));
+  caps.require('new-harness', 'session', 'fork');
+  assert.throws(() => caps.require('new-harness', 'model', 'selection'));
+  const copy = caps.get('new-harness'); copy.session.fork = false;
+  assert.equal(caps.get('new-harness').session.fork, true);
+  assert.deepEqual(shadow.report().errors, []);
+  console.log('core-services: interaction race/ownership, capability negotiation, native precedence, file replacement and plan passed');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/scripts/determinism-test.cjs

@@ -0,0 +1,36 @@
+const assert = require('node:assert/strict');
+const { ProtocolCore } = require('../src/main/protocol-core');
+
+// A captured CoreEvent stream must replay without pre-created objects or a clock.
+const events = [
+  { type: 'thread.created', payload: { workspaceId: '/fixture' } },
+  { type: 'turn.started', turnId: 'native-turn' },
+  { type: 'item.started', turnId: 'native-turn', itemId: 'answer', payload: { type: 'agent_message' } },
+  { type: 'item.delta', turnId: 'native-turn', itemId: 'answer', payload: { text: 'hello' } },
+  { type: 'usage.updated', turnId: 'native-turn', payload: { inputTokens: 12 } },
+  { type: 'usage.updated', turnId: 'native-turn', payload: { outputTokens: 3 } },
+  { type: 'turn.waiting', turnId: 'native-turn' },
+  { type: 'turn.completed', turnId: 'native-turn' },
+].map((e, index) => ({ ...e, threadId: 'thread', eventId: `e${index}`, timestamp: 1000 + index, sequence: index + 1 }));
+function replay(clock) {
+  const original = Date.now;
+  Date.now = () => clock;
+  try {
+    const core = new ProtocolCore();
+    for (const event of events) core.dispatch(structuredClone(event));
+    return structuredClone(core.snapshot());
+  } finally { Date.now = original; }
+}
+const first = replay(9000);
+assert.deepEqual(first, replay(999999));
+assert.equal(first.turns[0].id, 'native-turn');
+assert.equal(first.turns[0].startedAt, 1001);
+assert.equal(first.turns[0].completedAt, 1007);
+assert.equal(first.items[0].content, 'hello');
+assert.deepEqual(first.turns[0].itemIds, ['answer', 'usage_native-turn']);
+const core = new ProtocolCore();
+for (const event of events) core.dispatch(structuredClone(event));
+const settled = structuredClone(core.snapshot());
+core.dispatch({ threadId: 'thread', turnId: 'native-turn', itemId: 'answer', type: 'item.updated', payload: { content: 'late rewrite' } });
+assert.deepEqual(core.snapshot().items, settled.items, 'terminal items cannot be rewritten');
+console.log('determinism: exact snapshots and native turn identity passed');

package/scripts/docs-command-test.cjs

@@ -0,0 +1,49 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const root = path.resolve(__dirname, '..');
+const packageJson = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+const scripts = new Set(Object.keys(packageJson.scripts || {}));
+const shellFence = /^(powershell|pwsh|bash|sh|shell|cmd|console)?$/i;
+
+function markdownFiles(directory) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) return markdownFiles(target);
+    return entry.isFile() && entry.name.endsWith('.md') ? [target] : [];
+  });
+}
+
+const files = [path.join(root, 'README.md'), ...markdownFiles(path.join(root, 'docs'))];
+const missing = [];
+let checked = 0;
+
+for (const file of files) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  let inShellFence = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const fence = line.match(/^\s*```([^`]*)\s*$/);
+    if (fence) {
+      if (inShellFence) inShellFence = false;
+      else inShellFence = shellFence.test(fence[1].trim());
+      continue;
+    }
+    if (!inShellFence || /^\s*#/.test(line)) continue;
+    for (const match of line.matchAll(/\bnpm(?:\.cmd)?\s+run\s+([A-Za-z0-9:_-]+)/g)) {
+      checked += 1;
+      if (!scripts.has(match[1])) {
+        missing.push(`${path.relative(root, file)}:${index + 1} npm run ${match[1]}`);
+      }
+    }
+  }
+}
+
+if (missing.length) {
+  console.error('Documented npm scripts missing from package.json:');
+  for (const item of missing) console.error(`- ${item}`);
+  process.exitCode = 1;
+} else {
+  console.log(`docs-command: ${checked} runnable npm commands verified across ${files.length} files`);
+}