@harness-mix/cli 0.1.3

package/scripts/openclaw-adapter-test.cjs

@@ -0,0 +1,180 @@
+const assert = require('node:assert/strict');
+const { manifest, create, projectAgentEvent, projectApproval, applySessionDescription } = require('../src/main/adapters/openclaw');
+const hermes = require('../src/main/adapters/hermes');
+
+// OpenClaw Adapter 投影单元测试。帧形状以 Gateway 2026.5.12 实测捕获为准
+// （agent 流：{runId, stream, data, sessionKey, seq, ts}；审批广播：{id, request, createdAtMs, expiresAtMs}）。
+
+// 1. assistant 流：delta 优先，缺 delta 时按累计 text 差分
+{
+  const session = { state: {} };
+  const evts = [
+    ...projectAgentEvent({ stream: 'assistant', data: { text: 'PONG', delta: 'PONG' } }, session),
+    ...projectAgentEvent({ stream: 'assistant', data: { text: 'PONG。完成' } }, session),
+  ];
+  assert.deepEqual(evts.map((e) => e.text), ['PONG', '。完成'], 'delta 与差分补齐');
+  assert.equal(session.state.lastAssistantText, 'PONG。完成', '累计文本跟踪');
+}
+
+// 2. tool 流全链路：start(running+input) → update(running+output) → result(done)
+{
+  const call = { toolCallId: 'call_1', name: 'exec', meta: 'print text' };
+  const events = [
+    ...projectAgentEvent({ stream: 'tool', data: { ...call, phase: 'start', args: { command: 'echo hi' } } }),
+    ...projectAgentEvent({ stream: 'tool', data: { ...call, phase: 'update', partialResult: { content: [{ type: 'text', text: 'hi\r\n' }] } } }),
+    ...projectAgentEvent({ stream: 'tool', data: { ...call, phase: 'result', isError: false, result: { content: [{ type: 'text', text: 'hi' }] } } }),
+  ];
+  assert.equal(events[0].state, 'running');
+  assert.ok(events[0].input.includes('echo hi'), '入参投影');
+  assert.equal(events[0].title, 'exec print text', '标题含 meta');
+  assert.equal(events.at(-1).state, 'done');
+  assert.equal(events.at(-1).output, 'hi');
+  const failed = projectAgentEvent({ stream: 'tool', data: { ...call, phase: 'result', isError: true, result: { content: [] } } });
+  assert.equal(failed[0].state, 'error');
+}
+
+// 3. command_output 流：delta 增量挂同一 toolCallId，end 收尾带退出码
+{
+  const events = [
+    ...projectAgentEvent({ stream: 'command_output', data: { phase: 'delta', toolCallId: 'c1', title: 'command print text', output: 'hello' } }),
+    ...projectAgentEvent({ stream: 'command_output', data: { phase: 'end', toolCallId: 'c1', title: 'command print text', output: 'hello', status: 'completed', exitCode: 0 } }),
+  ];
+  assert.equal(events[0].kind, 'tool');
+  assert.equal(events[0].state, 'running');
+  assert.equal(events[1].state, 'done');
+  assert.equal(events[1].detail, 'exit 0');
+}
+
+// 4. lifecycle error 只累积上下文（结算由 agent.wait 驱动），未知流不投影
+{
+  const session = { state: {} };
+  assert.equal(projectAgentEvent({ stream: 'lifecycle', data: { phase: 'start' } }, session).length, 0);
+  assert.equal(projectAgentEvent({ stream: 'lifecycle', data: { phase: 'error', error: 'boom' } }, session).length, 0);
+  assert.equal(session.state.lastError, 'boom');
+  assert.equal(projectAgentEvent({ stream: 'patch', data: {} }, session).length, 0, '未验证的流不伪造');
+}
+
+// 5. 审批投影与应答路由（exec/plugin 分流；deny 为唯一拒绝决定）
+(async () => {
+{
+  const projected = projectApproval('exec.approval.requested', {
+    id: 'ap-1',
+    request: { command: 'rm -rf build', cwd: 'E:\\harness-mix', sessionKey: 'agent:main:hm-1' },
+  }, 'agent:main:hm-1');
+  assert.equal(projected.kind, 'approval');
+  assert.equal(projected.requestId, 'openclaw-ap-1');
+  assert.ok(projected.message.includes('rm -rf build'));
+  assert.equal(projected.options.length, 3);
+
+  const calls = [];
+  const session = {
+    nativeSessionId: 'agent:main:hm-1',
+    pendingApprovals: new Map([['openclaw-ap-1', { approvalId: 'ap-1' }], ['openclaw-plugin:x', { approvalId: 'plugin:x' }]]),
+    host: { call: async (method, params) => calls.push({ method, params }) },
+  };
+  const adapter = create();
+  await adapter.respond(session, 'openclaw-ap-1', { optionId: 'allowed-once' });
+  assert.deepEqual(calls.at(-1), { method: 'exec.approval.resolve', params: { id: 'ap-1', decision: 'allow-once' } });
+  await adapter.respond(session, 'openclaw-plugin:x', { optionId: 'rejected' });
+  assert.deepEqual(calls.at(-1), { method: 'plugin.approval.resolve', params: { id: 'plugin:x', decision: 'deny' } }, '插件审批按 id 前缀路由');
+  session.pendingApprovals.set('openclaw-ap-2', { approvalId: 'ap-2' });
+  await adapter.respond(session, 'openclaw-ap-2', { cancelled: true });
+  assert.equal(calls.at(-1).params.decision, 'deny', '取消即拒绝，不替用户放行');
+  await assert.rejects(adapter.respond(session, 'openclaw-unknown', { optionId: 'allowed-once' }), /未知/);
+}
+
+// 6. send 流程：agent 受理 → agent.wait 结算；in_flight 拒绝并发；model/thinking 透传
+{
+  const emitted = [];
+  const calls = [];
+  const host = {
+    call: async (method, params) => {
+      calls.push({ method, params });
+      if (method === 'agent') return { runId: 'run-1', status: 'accepted', acceptedAt: 1 };
+      if (method === 'agent.wait') return { runId: 'run-1', status: 'ok', startedAt: 1, endedAt: 2 };
+      throw new Error('unexpected ' + method);
+    },
+  };
+  const session = { host, nativeSessionId: 'agent:main:hm-2', state: {}, modelOverride: 'minimax/MiniMax-M2.7', thinkingOverride: 'low' };
+  const adapter = create();
+  await adapter.send(session, '你好', { emit: (e) => emitted.push(e) });
+  assert.deepEqual(emitted, [{ kind: 'completed', finalAnswer: true }]);  const agentCall = calls.find((c) => c.method === 'agent');
+  assert.equal(agentCall.params.sessionKey, 'agent:main:hm-2');
+  assert.equal(agentCall.params.model, 'minimax/MiniMax-M2.7');
+  assert.equal(agentCall.params.thinking, 'low');
+  assert.equal(agentCall.params.deliver, false, '回复不外投到 OpenClaw 渠道');
+  assert.ok(agentCall.params.idempotencyKey, '幂等键必传');
+
+  const busy = { ...session, host: { call: async () => ({ status: 'in_flight' }) } };
+  await assert.rejects(adapter.send(busy, 'x', { emit: () => {} }), /进行中/);
+
+  // 用户取消（stopReason: rpc 的 timeout 快照）：安静返回，不再重复结算
+  const cancelled = [];
+  const cancelHost = { call: async (method) => method === 'agent' ? { runId: 'r', status: 'accepted' } : { status: 'timeout', stopReason: 'rpc' } };
+  await adapter.send({ ...session, host: cancelHost }, 'x', { emit: (e) => cancelled.push(e) });
+  assert.deepEqual(cancelled, [], '取消由 runtime 结算');
+
+  // 原生失败：错误优先取 agent.wait 快照，其次 lifecycle 累计
+  const failHost = { call: async (method) => method === 'agent' ? { runId: 'r', status: 'accepted' } : { status: 'error', error: '模型限流' } };
+  await assert.rejects(adapter.send({ ...session, host: failHost, state: {} }, 'x', { emit: () => {} }), /模型限流/);
+  const lifecycleErr = [];
+  const lcHost = { call: async (method) => {
+    if (method === 'agent') return { runId: 'r', status: 'accepted' };
+    for (const e of projectAgentEvent({ stream: 'lifecycle', data: { phase: 'error', error: { message: '上下文溢出' } } }, lcSession)) lifecycleErr.push(e);
+    return { status: 'error' };
+  } };
+  const lcSession = { ...session, host: lcHost, state: {} };
+  await assert.rejects(adapter.send(lcSession, 'x', { emit: () => {} }), /上下文溢出/);
+}
+
+// 7. cancel 路由 sessions.abort（带 runId 限定作用域）
+{
+  const calls = [];
+  const session = { host: { call: async (m, p) => calls.push({ m, p }) }, nativeSessionId: 'agent:main:hm-3', state: { runId: 'run-9' } };
+  await create().cancel(session);
+  assert.deepEqual(calls[0], { m: 'sessions.abort', p: { key: 'agent:main:hm-3', runId: 'run-9' } });
+}
+
+// 8. sessions.describe 行投影：生效模型 / 思考目录 / 原生用量（totalTokensFresh 才可信）
+{
+  const session = { state: {}, models: [{ id: 'minimax/MiniMax-M2.7', name: 'MiniMax M2.7' }] };
+  applySessionDescription(session, {
+    modelProvider: 'minimax', model: 'MiniMax-M2.7',
+    thinkingLevels: [{ id: 'off', label: 'off' }, { id: 'low', label: 'low' }], thinkingDefault: 'off',
+    inputTokens: 47, outputTokens: 19, totalTokens: 28656, contextTokens: 200000, estimatedCostUsd: 0,
+  });
+  assert.equal(session.model.id, 'minimax/MiniMax-M2.7', '模型命中目录条目');
+  assert.deepEqual(session.state.thinkingLevels.map((l) => l.id), ['off', 'low']);
+  assert.equal(session.state.thinkingDefault, 'off');
+  assert.deepEqual(session.state.usage, { tokens: 28656, contextWindow: 200000, contextPercent: 14.33 });
+  // 0 成本不冒充 cost；缺字段不产出 usage
+  assert.equal(session.state.usage.cost, undefined);
+  const empty = { state: {} };
+  applySessionDescription(empty, { label: 'x' });
+  assert.equal(empty.state.usage, undefined);
+}
+
+// 9. Manifest 能力声明（诚实面：reasoning 流/plan/patch/图片未实测不声明；usage 取自原生 token 统计）
+{
+  assert.equal(manifest.id, 'openclaw');
+  assert.deepEqual(manifest.capabilities, { streaming: true, thinking: false, tools: true, approvals: true, questions: false, models: true, thinkingLevels: true, permissionModes: false, resume: true, fork: false, forkFromMessage: false, compaction: false, usage: true, contextUsage: true, attachments: true });
+}
+
+// 10. Hermes 经 ACP 家族工厂接入，未文档化能力不声明
+{
+  assert.equal(hermes.manifest.id, 'hermes');
+  assert.equal(hermes.manifest.capabilities.streaming, true);
+  assert.equal(hermes.manifest.capabilities.fork, true, '文档支持 fork');
+  assert.equal(hermes.manifest.capabilities.resume, true, '文档支持 resume');
+  assert.equal(hermes.manifest.capabilities.usage, false);
+  assert.equal(hermes.manifest.capabilities.compaction, false);
+  assert.equal(hermes.manifest.capabilities.attachments, true);
+  assert.equal(hermes.manifest.capabilities.questions, false);
+  const adapter = hermes.create();
+  for (const method of ['inspect', 'open', 'send', 'cancel', 'close', 'respond', 'fork', 'listModelsFor', 'setModel']) {
+    assert.equal(typeof adapter[method], 'function', `hermes 缺 ${method}()`);
+  }
+}
+
+console.log('openclaw-adapter: Gateway 帧投影/审批路由/发送结算/取消/Hermes 能力声明 passed');
+})().catch((error) => { console.error(error); process.exitCode = 1; });

package/scripts/openclaw-models-probe.cjs

@@ -0,0 +1,13 @@
+// 列出 OpenClaw 模型及其视觉支持标记
+const { OpenClawGatewayHost } = require("../src/main/adapters/openclaw-gateway");
+(async () => {
+  const host = await OpenClawGatewayHost.acquire(() => {});
+  try {
+    const res = await host.call("models.list", {});
+    const models = res?.models ?? res ?? [];
+    for (const m of models) {
+      console.log(JSON.stringify({ id: m.id ?? m, name: m.name, input: m.input ?? m.modalities ?? m.inputs ?? m.capabilities?.input, vision: m.vision ?? m.supportsImages ?? m.image }));
+    }
+  } finally { await OpenClawGatewayHost.release(); }
+  process.exit(0);
+})().catch((e) => { console.error("FAILED:", e.message); process.exit(1); });

package/scripts/platform-test.cjs

@@ -0,0 +1,62 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { dataDirectory, executableName, inspectPosix, assertDesktopStopped } = require('../src/main/native/platform');
+const { nativePaths } = require('../src/main/native/config');
+const { descendantPids, terminateTree } = require('../src/main/native/process-utils');
+const { evaluateDesktopCompatibility, enforceDesktopCompatibility } = require('../src/main/native/compatibility');
+
+async function main() {
+  const home = path.resolve(os.tmpdir(), 'hm-home');
+  assert.equal(dataDirectory({}, 'darwin', home), path.join(home, 'Library/Application Support/harness-mix/codexhost'));
+  assert.equal(dataDirectory({}, 'linux', home), path.join(home, '.local/share/harness-mix/codexhost'));
+  assert.equal(dataDirectory({ XDG_DATA_HOME: home }, 'linux', '/ignored'), path.join(home, 'harness-mix/codexhost'));
+  assert.equal(dataDirectory({ XDG_DATA_HOME: 'relative' }, 'linux', home), dataDirectory({}, 'linux', home));
+  assert.equal(dataDirectory({ CODEXHOST_DATA_DIR: home }, 'darwin'), home);
+  assert.equal(dataDirectory({ APPDATA: home }, 'win32'), path.join(home, 'harness-mix/codexhost'));
+  for (const platform of ['win32', 'darwin', 'linux']) {
+    assert.equal(path.basename(nativePaths(platform).shim), executableName('harness-mix-shim', platform));
+    assert.equal('activation' in nativePaths(platform), platform === 'win32');
+    const result = evaluateDesktopCompatibility('26.901.2854.0', undefined, platform);
+    assert.equal(result.state, platform === 'win32' ? 'observed' : 'unverified');
+    assert.throws(() => enforceDesktopCompatibility(result, { HARNESS_MIX_STRICT_COMPATIBILITY: '1' }));
+  }
+  assert.equal(evaluateDesktopCompatibility('1.2.3', undefined, 'darwin').state, 'unverified');
+  const env = { HARNESS_MIX_DESKTOP_EXECUTABLE: process.execPath, CODEXHOST_STOCK_CODEX_PATH: process.execPath };
+  assert.equal(inspectPosix(env, 'linux').version, 'unknown');
+  assert.equal(inspectPosix({ ...env, HARNESS_MIX_DESKTOP_VERSION: '1.2.3' }, 'linux').stock, fs.realpathSync(process.execPath));
+  assert.throws(() => inspectPosix({}, 'linux'), /Install Codex Desktop/);
+  assert.throws(() => inspectPosix({ ...env, HARNESS_MIX_DESKTOP_EXECUTABLE: 'relative' }, 'linux'), /absolute/);
+  assert.throws(() => inspectPosix(env, 'freebsd'), /Unsupported/);
+  const bundle = fs.mkdtempSync(path.join(os.tmpdir(), 'hm Mac app spaces-'));
+  try {
+    fs.mkdirSync(path.join(bundle, 'Contents/MacOS'), { recursive: true });
+    fs.mkdirSync(path.join(bundle, 'Contents/Resources'), { recursive: true });
+    for (const name of ['Contents/MacOS/Codex', 'Contents/Resources/codex']) fs.writeFileSync(path.join(bundle, name), 'fixture', { mode: 0o755 });
+    const installation = inspectPosix({ HARNESS_MIX_DESKTOP_APP: bundle }, 'darwin', (command, args) => {
+      assert.equal(command, '/usr/bin/plutil');
+      assert.equal(args.at(-1), path.join(bundle, 'Contents/Info.plist'));
+      return JSON.stringify({ CFBundleExecutable: 'Codex', CFBundleShortVersionString: '1.2.3' });
+    });
+    assert.equal(installation.stock, fs.realpathSync(path.join(bundle, 'Contents/Resources/codex')));
+    assert.equal(installation.version, '1.2.3');
+  } finally { fs.rmSync(bundle, { recursive: true, force: true }); }
+  assert.deepEqual(descendantPids('101 100\n102 101\n103 1\n104 100', 100), [102, 101, 104]);
+  await terminateTree(-1); // Must never signal the current process group.
+  if (process.platform !== 'win32') {
+    const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)']);
+    await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+    try {
+      assert.throws(() => assertDesktopStopped({ executable: fs.realpathSync(process.execPath) }), /Quit Codex Desktop/);
+    } finally {
+      const closed = new Promise(resolve => child.once('close', resolve));
+      await terminateTree(child.pid);
+      await closed;
+    }
+    await assert.rejects(require('../src/main/native/secure-store').getSecret('test'), /unavailable/);
+  }
+  console.log('PASS: platform paths, executable discovery, compatibility isolation and process lifecycle');
+}
+main().catch(error => { console.error(error); process.exitCode = 1; });

package/scripts/projector-test.cjs

@@ -0,0 +1,144 @@
+// PR 2 验收：Projector 测试 — Event → State（无 Electron）。
+const assert = require('node:assert');
+const { ProtocolCore } = require('../src/main/protocol-core');
+
+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; }
+}
+
+function coreWithThread() {
+  const core = new ProtocolCore();
+  const thread = core.createThread({ id: 'thread_1', workspaceId: '/repo', harnessId: 'harness-x' });
+  return { core, thread };
+}
+
+test('agent_message streaming: started → delta × N → completed（§7 示例）', () => {
+  const { core } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.started', payload: { type: 'agent_message' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.delta', payload: { text: '你好' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.delta', payload: { text: '，世界' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.completed' });
+  const item = core.getItem('item_m1');
+  assert.strictEqual(item.content, '你好，世界');
+  assert.strictEqual(item.status, 'completed');
+  assert.deepStrictEqual(turn.itemIds, ['item_m1']);
+});
+
+test('reasoning streaming 独立于 agent_message', () => {
+  const { core } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_r1', type: 'item.started', payload: { type: 'reasoning' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_r1', type: 'item.delta', payload: { text: '思考一下' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_a1', type: 'item.started', payload: { type: 'agent_message' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_a1', type: 'item.delta', payload: { text: '回答' } });
+  assert.strictEqual(core.getItem('item_r1').content, '思考一下');
+  assert.strictEqual(core.getItem('item_a1').content, '回答');
+});
+
+test('tool lifecycle: started(running) → updated → completed(done/error)', () => {
+  const { core } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_t1', type: 'item.started', payload: { type: 'tool_call', title: 'bash', state: 'running' }, nativeRef: { toolCallId: 'tc1' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_t1', type: 'item.updated', payload: { detail: 'ls', output: 'partial' } });
+  let tool = core.getItem('item_t1');
+  assert.strictEqual(tool.status, 'started');
+  assert.strictEqual(tool.state, 'running');
+  assert.strictEqual(tool.output, 'partial');
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_t1', type: 'item.completed', payload: { state: 'done', output: 'final' } });
+  tool = core.getItem('item_t1');
+  assert.strictEqual(tool.status, 'completed');
+  assert.strictEqual(tool.state, 'done');
+  // error 工具
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_t2', type: 'item.started', payload: { type: 'tool_call', title: 'bash', state: 'running' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_t2', type: 'item.completed', payload: { state: 'error' } });
+  assert.strictEqual(core.getItem('item_t2').status, 'error');
+});
+
+test('duplicate eventId → ignore（§9）', () => {
+  const { core } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.started', payload: { type: 'agent_message' } });
+  const dup = { eventId: 'evt_dup', threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.delta', payload: { text: 'X' } };
+  const first = core.dispatch(dup);
+  const second = core.dispatch({ ...dup });
+  assert.strictEqual(first.accepted, true);
+  assert.strictEqual(second.ignored, true);
+  assert.strictEqual(core.getItem('item_m1').content, 'X'); // 只投影一次
+});
+
+test('out-of-order event：默认拒绝并记录警告，状态不被破坏', () => {
+  const { core } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' }); // seq 1
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.started', payload: { type: 'agent_message' } });
+  const late = core.dispatch({ sequence: 1, threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.delta', payload: { text: '晚到' } });
+  assert.strictEqual(late.ignored, true);
+  assert.ok(late.warnings.some((w) => w.includes('sequence regression')));
+  assert.strictEqual(core.getItem('item_m1').content, '');
+});
+
+test('turn completed：thread 回 idle，open items 收尾，running 工具 → interrupted', () => {
+  const { core, thread } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' });
+  assert.strictEqual(thread.status, 'running');
+  assert.strictEqual(thread.activeTurnId, turn.id);
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.started', payload: { type: 'agent_message' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_m1', type: 'item.delta', payload: { text: '答案' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, itemId: 'item_t1', type: 'item.started', payload: { type: 'tool_call', title: 'read', state: 'running' } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.completed' });
+  assert.strictEqual(thread.status, 'idle');
+  assert.strictEqual(thread.activeTurnId, null);
+  assert.strictEqual(turn.status, 'completed');
+  assert.strictEqual(core.getItem('item_m1').status, 'completed');
+  const tool = core.getItem('item_t1');
+  assert.strictEqual(tool.state, 'interrupted');
+  assert.strictEqual(tool.status, 'cancelled');
+});
+
+test('turn cancel / failure：stopReason=cancelled 与 turn.failed', () => {
+  const { core, thread } = coreWithThread();
+  const t1 = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: t1.id, type: 'turn.started' });
+  core.dispatch({ threadId: 'thread_1', turnId: t1.id, type: 'turn.completed', payload: { stopReason: 'cancelled' } });
+  assert.strictEqual(t1.status, 'cancelled');
+  const t2 = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: t2.id, type: 'turn.started' });
+  core.dispatch({ threadId: 'thread_1', turnId: t2.id, type: 'turn.failed', payload: { message: '网络错误' } });
+  assert.strictEqual(t2.status, 'error');
+  assert.strictEqual(t2.error, '网络错误');
+  assert.strictEqual(thread.status, 'error');
+});
+
+test('usage.updated：upsert usage item + thread.usage 合并', () => {
+  const { core, thread } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'usage.updated', payload: { inputTokens: 10 } });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'usage.updated', payload: { outputTokens: 5 } });
+  const usages = core.getItemsForTurn(turn.id).filter((i) => i.type === 'usage');
+  assert.strictEqual(usages.length, 1);
+  assert.deepStrictEqual(usages[0].usage, { inputTokens: 10, outputTokens: 5 });
+  assert.deepStrictEqual(thread.usage, { inputTokens: 10, outputTokens: 5 });
+});
+
+test('snapshot / reset', () => {
+  const { core } = coreWithThread();
+  const turn = core.createTurn({ threadId: 'thread_1' });
+  core.dispatch({ threadId: 'thread_1', turnId: turn.id, type: 'turn.started' });
+  const snap = core.snapshot();
+  assert.strictEqual(snap.threads.length, 1);
+  assert.strictEqual(snap.turns.length, 1);
+  core.reset();
+  assert.strictEqual(core.snapshot().threads.length, 0);
+  assert.strictEqual(core.getTurn(turn.id), null);
+});
+
+console.log(`projector: ${passed} passed`);

package/scripts/sequence-test.cjs

@@ -0,0 +1,57 @@
+// PR 2 验收：Sequence Validator 测试（无 Electron）。
+const assert = require('node:assert');
+const { SequenceValidator } = require('../src/main/protocol-core/sequence-validator');
+
+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; }
+}
+
+test('正常递增 15 → 16 接受', () => {
+  const v = new SequenceValidator();
+  assert.strictEqual(v.check({ eventId: 'e1', threadId: 't', sequence: 15 }).action, 'accept');
+  const r = v.check({ eventId: 'e2', threadId: 't', sequence: 16 });
+  assert.strictEqual(r.action, 'accept');
+  assert.deepStrictEqual(r.warnings, []);
+});
+
+test('重复 eventId → ignore', () => {
+  const v = new SequenceValidator();
+  v.check({ eventId: 'e1', threadId: 't', sequence: 1 });
+  const r = v.check({ eventId: 'e1', threadId: 't', sequence: 2 });
+  assert.strictEqual(r.action, 'ignore');
+  assert.ok(r.warnings.some((w) => w.includes('duplicate')));
+});
+
+test('sequence 回退：非严格模式 warn 但接受，不破坏状态', () => {
+  const v = new SequenceValidator();
+  v.check({ eventId: 'e1', threadId: 't', sequence: 15 });
+  const r = v.check({ eventId: 'e2', threadId: 't', sequence: 14 });
+  assert.strictEqual(r.action, 'accept');
+  assert.ok(r.warnings.some((w) => w.includes('regression')));
+  // 回退后 lastSequence 不被拉低，后续 16 仍正常接受
+  assert.strictEqual(v.check({ eventId: 'e3', threadId: 't', sequence: 16 }).action, 'accept');
+});
+
+test('strict 模式：回退直接 ignore', () => {
+  const v = new SequenceValidator({ strict: true });
+  v.check({ eventId: 'e1', threadId: 't', sequence: 15 });
+  assert.strictEqual(v.check({ eventId: 'e2', threadId: 't', sequence: 14 }).action, 'ignore');
+});
+
+test('sequence 按 thread 隔离', () => {
+  const v = new SequenceValidator();
+  v.check({ eventId: 'a1', threadId: 'ta', sequence: 5 });
+  const r = v.check({ eventId: 'b1', threadId: 'tb', sequence: 1 });
+  assert.strictEqual(r.action, 'accept');
+  assert.deepStrictEqual(r.warnings, []);
+});
+
+test('无 sequence 的事件仅做去重', () => {
+  const v = new SequenceValidator();
+  assert.strictEqual(v.check({ eventId: 'e1', threadId: 't' }).action, 'accept');
+  assert.strictEqual(v.check({ eventId: 'e1', threadId: 't' }).action, 'ignore');
+});
+
+console.log(`sequence: ${passed} passed`);

package/scripts/shadow-test.cjs

@@ -0,0 +1,154 @@
+// PR 3 基础验收：Shadow Mode —— legacy 统一事件经 Normalizer → Core 投影，
+// 并用 ShadowComparator 验证与 legacy transcript 语义一致（无 Electron、无真实 Harness）。
+const assert = require('node:assert');
+const { ProtocolCore } = require('../src/main/protocol-core');
+const { ShadowMirror } = require('./support/shadow.cjs');
+
+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; }
+}
+
+/** 模拟 Runtime legacy 侧的最终 thread 形态（#applyEvent 投影完成后的样子） */
+function legacyThreadAfterTurn() {
+  return {
+    id: 'thread_1', harnessId: 'harness-x', cwd: '/repo',
+    messages: [
+      { id: 'm0', role: 'user', text: '帮我列目录', at: 1 },
+      {
+        id: 'm1', role: 'assistant', text: '我先看一下。目录里有 a.js', thinking: '需要先列目录',
+        at: 2, endedAt: 3, stopReason: 'completed',
+        items: [
+          { id: 'i1', kind: 'thinking', text: '需要先列目录', at: 2, endedAt: 3 },
+          { id: 'i2', kind: 'text', text: '我先看一下。', at: 2, endedAt: 3 },
+          { id: 'i3', kind: 'tool', toolId: 'tc1', at: 2, endedAt: 3 },
+          { id: 'i4', kind: 'text', text: '目录里有 a.js', at: 2, endedAt: 3 },
+        ],
+      },
+    ],
+    tools: [{ id: 'tc1', messageId: 'm1', title: 'bash', state: 'done', at: 2, endedAt: 3 }],
+    usage: { inputTokens: 100, outputTokens: 20 },
+    status: 'ready',
+  };
+}
+
+/** 模拟一轮真实 legacy 事件流（与 Pi/Claude/DSH Adapter 输出同形状） */
+function runShadowTurn(shadow, thread) {
+  shadow.threadCreated(thread);
+  shadow.turnStarted(thread, '帮我列目录');
+  const emit = (event) => shadow.applyLegacyEvent(thread, event);
+  emit({ kind: 'thinking-delta', text: '需要先' });
+  emit({ kind: 'thinking-delta', text: '列目录' });
+  emit({ kind: 'text-delta', text: '我先看一下。' });
+  emit({ kind: 'tool', toolCallId: 'tc1', title: 'bash', state: 'running', detail: 'ls', input: 'ls' });
+  emit({ kind: 'tool', toolCallId: 'tc1', title: 'bash', state: 'done', detail: 'a.js', output: 'a.js' });
+  emit({ kind: 'text-delta', text: '目录里有 a.js' });
+  emit({ kind: 'usage', usage: { inputTokens: 100, outputTokens: 20 } });
+  emit({ kind: 'completed', finalAnswer: true });
+}
+
+test('shadow：一轮完整 turn 投影出 §64 要求的 Core Snapshot', () => {
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  const thread = legacyThreadAfterTurn();
+  runShadowTurn(shadow, thread);
+
+  const snap = shadow.snapshot();
+  assert.strictEqual(snap.threads.length, 1);
+  assert.strictEqual(snap.turns.length, 1);
+
+  const turn = snap.turns[0];
+  assert.strictEqual(turn.status, 'completed');
+  assert.strictEqual(typeof turn.startedAt, 'number');
+  assert.strictEqual(typeof turn.completedAt, 'number');
+
+  const items = core.getItemsForTurn(turn.id);
+  const byType = (type) => items.filter((i) => i.type === type);
+  // UserMessage / Reasoning / ToolCall / AgentMessage / Usage 全部齐备
+  assert.strictEqual(byType('user_message').length, 1);
+  assert.strictEqual(byType('user_message')[0].content, '帮我列目录');
+  assert.strictEqual(byType('user_message')[0].status, 'completed');
+  assert.strictEqual(byType('reasoning').map((i) => i.content).join(''), '需要先列目录');
+  const tools = byType('tool_call');
+  assert.strictEqual(tools.length, 1);
+  assert.strictEqual(tools[0].state, 'done');
+  assert.strictEqual(tools[0].status, 'completed');
+  assert.deepStrictEqual(tools[0].nativeRef, { toolCallId: 'tc1' });
+  assert.strictEqual(byType('agent_message').map((i) => i.content).join(''), '我先看一下。目录里有 a.js');
+  assert.strictEqual(byType('usage').length, 1);
+  assert.deepStrictEqual(byType('usage')[0].usage, { inputTokens: 100, outputTokens: 20 });
+});
+
+test('shadow comparator：与 legacy transcript 语义一致 → 零 mismatch', () => {
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  const thread = legacyThreadAfterTurn();
+  runShadowTurn(shadow, thread);
+  assert.deepStrictEqual(shadow.report().mismatches, []);
+  assert.deepStrictEqual(shadow.report().errors, []);
+});
+
+test('shadow comparator：legacy 与 core 不一致时记录差异，不影响投影', () => {
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  const thread = legacyThreadAfterTurn();
+  runShadowTurn(shadow, thread);
+  // legacy 侧文本被改动（模拟不一致），再触发一次 completed 比较
+  thread.messages.push({ id: 'm2', role: 'assistant', text: '被改过的答案', at: 4, endedAt: 5, stopReason: 'completed' });
+  shadow.turnStarted(thread, '再来一次');
+  shadow.applyLegacyEvent(thread, { kind: 'text-delta', text: '不一样的答案' });
+  shadow.applyLegacyEvent(thread, { kind: 'completed', finalAnswer: true });
+  const { mismatches } = shadow.report();
+  assert.strictEqual(mismatches.length, 1);
+  assert.ok(mismatches[0].mismatches.some((m) => m.includes('final answer')));
+});
+
+test('shadow：cancel 与 error 路径', () => {
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  const base = legacyThreadAfterTurn();
+  // cancel
+  const t1 = { ...base, id: 'thread_c', messages: [base.messages[0], { ...base.messages[1], text: '', thinking: undefined, stopReason: 'cancelled' }], tools: [{ ...base.tools[0], state: 'interrupted' }], usage: {} };
+  shadow.threadCreated(t1);
+  shadow.turnStarted(t1, '帮我列目录');
+  shadow.applyLegacyEvent(t1, { kind: 'tool', toolCallId: 'tc1', title: 'bash', state: 'running' });
+  shadow.applyLegacyEvent(t1, { kind: 'completed', stopReason: 'cancelled' });
+  const cancelledTurn = core.turns.turnsForThread('thread_c')[0];
+  assert.strictEqual(cancelledTurn.status, 'cancelled');
+  // error
+  const t2 = { ...base, id: 'thread_e', error: '原生进程崩溃', messages: [base.messages[0], { ...base.messages[1], text: '', thinking: undefined, stopReason: 'error' }], tools: [], usage: {} };
+  shadow.threadCreated(t2);
+  shadow.turnStarted(t2, '帮我列目录');
+  shadow.applyLegacyEvent(t2, { kind: 'error', message: '原生进程崩溃' });
+  const failedTurn = core.turns.turnsForThread('thread_e')[0];
+  assert.strictEqual(failedTurn.status, 'error');
+  assert.strictEqual(failedTurn.error, '原生进程崩溃');
+  assert.strictEqual(core.getThread('thread_e').status, 'error');
+});
+
+test('shadow：approval → question/approval item 带 interactionId，turn 结算时收尾', () => {
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  const thread = { ...legacyThreadAfterTurn(), id: 'thread_a', pendingApprovals: [] };
+  shadow.threadCreated(thread);
+  shadow.turnStarted(thread, '改文件');
+  shadow.applyLegacyEvent(thread, { kind: 'approval', requestId: 'req-1', method: 'confirm', title: '允许写入？' });
+  shadow.applyLegacyEvent(thread, { kind: 'text-delta', text: '完成' });
+  shadow.applyLegacyEvent(thread, { kind: 'completed', finalAnswer: true });
+  const turn = core.turns.turnsForThread('thread_a')[0];
+  const approvals = core.getItemsForTurn(turn.id).filter((i) => i.type === 'approval');
+  assert.strictEqual(approvals.length, 1);
+  assert.deepStrictEqual(approvals[0].nativeRef, { interactionId: 'req-1' });
+  assert.strictEqual(approvals[0].status, 'completed');
+});
+
+test('shadow：自身异常被吞掉并记录（绝不影响 legacy）', () => {
+  const core = new ProtocolCore();
+  const shadow = new ShadowMirror({ core });
+  shadow.threadCreated(null); // 触发内部异常
+  assert.strictEqual(shadow.report().errors.length, 1);
+  assert.strictEqual(shadow.report().errors[0].phase, 'threadCreated');
+});
+
+console.log(`shadow: ${passed} passed`);