harness-mix 0.1.0

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`);

package/scripts/support/legacy-projection.cjs

@@ -0,0 +1,95 @@
+const { randomUUID } = require('node:crypto');
+const { appendDelta, projectTool, finishMessage } = require('./legacy-transcript.cjs');
+
+// Compatibility projection retained only while Shadow parity gates are active.
+function applyLegacyEvent(thread, event, effects) {
+    const last = thread.messages.at(-1);
+    let structural = true;
+    switch (event.kind) {
+      case "text-delta": {
+        const target = last?.role === "assistant" && last.streaming ? last : appendAssistant(thread);
+        target.text += event.text;
+        appendDelta(target, 'text', event.text);
+        structural = false;
+        break;
+      }
+      case "thinking-delta": {
+        const target = last?.role === "assistant" && last.streaming ? last : appendAssistant(thread);
+        target.thinking = (target.thinking ?? "") + event.text;
+        appendDelta(target, 'thinking', event.text);
+        structural = false;
+        break;
+      }
+      case "tool": {
+        const target = last?.role === 'assistant' && last.streaming ? last : appendAssistant(thread);
+        projectTool(thread, target, event);
+        break;
+      }
+      case "artifact": {
+        // 各 Harness 返回的图片 / 文件产物：挂到当前 assistant 消息上，Renderer 统一渲染
+        const a = event.artifact;
+        if (!a || typeof a !== "object") break;
+        const target = last?.role === "assistant" ? last : appendAssistant(thread);
+        target.artifacts ??= [];
+        if (target.artifacts.some((x) => x.id === a.id)) break;
+        target.artifacts.push({
+          id: a.id ?? randomUUID(),
+          type: a.type === "image" ? "image" : "file",
+          name: String(a.name ?? a.uri ?? "产物").slice(0, 120),
+          mime: typeof a.mime === "string" ? a.mime : undefined,
+          uri: typeof a.uri === "string" ? a.uri : undefined,
+          data: typeof a.data === "string" && a.data.length <= 5_500_000 ? a.data : undefined,
+        });
+        break;
+      }
+      case "approval":
+        thread.pendingApprovals ??= [];
+        if (!thread.pendingApprovals.some((a) => a.requestId === event.requestId)) {
+          thread.pendingApprovals.push({ requestId: event.requestId, method: event.method, title: event.title, message: event.message, options: event.options, placeholder: event.placeholder, at: Date.now() });
+        }
+        break;
+      case "plan":
+      case "file-change":
+        break;
+      case "usage":
+        thread.usage = { ...thread.usage, ...event.usage };
+        structural = false;
+        break;
+      case "session":
+        if (event.nativeSessionId) thread.nativeSessionId = event.nativeSessionId;
+        if (event.model) thread.model = event.model;
+        break;
+      case "status":
+
+        effects.notify("status", event.text, thread.id);
+        return { handled: true, structural: false };
+      case "notice":
+
+        effects.notify(event.level ?? "info", event.text);
+        return { handled: true, structural: false };
+      case "completed": {
+        finishMessage(thread, last, event.stopReason ?? 'completed', event.timestamp);
+        thread.updatedAt = Date.now();
+        effects.refreshUsage(thread);
+        void effects.settleReview(thread, last, 'ready');
+        break;
+      }
+      case "error": {
+        thread.error = event.message;
+        finishMessage(thread, last, 'error', event.timestamp);
+        void effects.settleReview(thread, last, 'error');
+        break;
+      }
+      default:
+        return { handled: false };
+    }
+    return { handled: true, structural };
+}
+
+function appendAssistant(thread) {
+  const message = { id: randomUUID(), role: 'assistant', text: '', at: Date.now(), streaming: true };
+  thread.messages.push(message);
+  return message;
+}
+
+module.exports = { applyLegacyEvent };

package/scripts/support/legacy-transcript.cjs

@@ -0,0 +1,48 @@
+const { randomUUID } = require('node:crypto');
+
+// A durable, ordered projection. Native tools keep their identities; the host
+// records presentation order only, never replays their side effects.
+function appendDelta(message, kind, text, now = Date.now()) {
+  if (!text) return;
+  message.items ??= [];
+  const previous = message.items.at(-1);
+  if (previous?.kind === kind && !previous.endedAt) previous.text += text;
+  else {
+    if (previous && !previous.endedAt) previous.endedAt = now;
+    message.items.push({ id: randomUUID(), kind, text, at: now });
+  }
+}
+
+function projectTool(thread, message, event, now = Date.now()) {
+  thread.tools ??= [];
+  let tool = event.toolCallId
+    ? thread.tools.findLast(t => t.id === event.toolCallId && t.messageId === message.id)
+    : thread.tools.findLast(t => t.title === event.title && t.state === 'running' && t.messageId === message.id);
+  if (!tool) {
+    tool = { id: event.toolCallId ?? randomUUID(), messageId: message.id, title: event.title, at: now };
+    thread.tools.push(tool);
+    message.items ??= [];
+    const previous = message.items.at(-1);
+    if (previous && !previous.endedAt) previous.endedAt = now;
+    message.items.push({ id: randomUUID(), kind: 'tool', toolId: tool.id, at: now });
+  }
+  tool.state = event.state ?? tool.state ?? 'running';
+  for (const key of ['detail', 'input', 'output']) if (typeof event[key] === 'string') tool[key] = event[key];
+  if (tool.state !== 'running') tool.endedAt = now;
+}
+
+function finishMessage(thread, message, reason = 'completed', now = Date.now()) {
+  if (!message || message.role !== 'assistant') return;
+  delete message.streaming;
+  message.endedAt ??= now;
+  message.stopReason = reason;
+  for (const item of message.items ?? []) item.endedAt ??= now;
+  for (const tool of thread.tools ?? []) {
+    if (tool.messageId === message.id && tool.state === 'running') {
+      tool.state = 'interrupted'; // A settled turn is not proof of tool success.
+      tool.endedAt = now;
+    }
+  }
+}
+
+module.exports = { appendDelta, projectTool, finishMessage };

package/scripts/support/parity-observer.cjs

@@ -0,0 +1,27 @@
+const { applyLegacyEvent } = require('./legacy-projection.cjs');
+const { compareTurn } = require('./shadow-comparator.cjs');
+
+// Independent legacy oracle for acceptance only. Never imported by src/.
+class ParityObserver {
+  constructor() { this.threads = new Map(); this.mismatches = []; this.errors = []; this.comparisons = 0; }
+  turnStarted(thread) {
+    const message = thread.messages.at(-1);
+    this.threads.set(thread.id, { id: thread.id, usage: structuredClone(thread.usage), tools: [], messages: [{ id: message.id, role: 'assistant', at: message.at, text: '', streaming: true }] });
+  }
+  event(thread, event, core) {
+    this.warnings = [...core.warnings];
+    const legacy = this.threads.get(thread.id);
+    if (!legacy) return;
+    try {
+      applyLegacyEvent(legacy, event, { notify() {}, refreshUsage() {}, settleReview() {} });
+      if (['completed', 'error'].includes(event.kind)) {
+        const turn = core.getTurn(thread.messages.at(-1).coreTurnId);
+        const mismatches = compareTurn({ thread: legacy, coreThread: core.getThread(thread.id), coreTurn: turn, coreItems: core.getItemsForTurn(turn.id) });
+        this.comparisons++;
+        if (mismatches.length) this.mismatches.push({ threadId: thread.id, turnId: turn.id, mismatches });
+      }
+    } catch (error) { this.errors.push(error.message); }
+  }
+  report() { return { enabled: true, comparisons: this.comparisons, mismatches: this.mismatches, errors: this.errors, warnings: this.warnings ?? [] }; }
+}
+module.exports = { ParityObserver };

package/scripts/support/shadow-comparator.cjs

@@ -0,0 +1,62 @@
+const { isDeepStrictEqual } = require('node:util');
+// Shadow Comparator（§14）：Turn 完成后比较 Legacy Transcript 与 Core 投影。
+// 不要求内部结构完全相同，要求语义一致。差异只记录，绝不影响用户执行（§15/约束#14）。
+function compareTurn({ thread, coreThread, coreTurn, coreItems }) {
+  const mismatches = [];
+  if (!thread || !coreTurn) return ['missing thread or core turn'];
+
+  const message = [...(thread.messages ?? [])].reverse().find((m) => m.role === 'assistant');
+  const tools = (thread.tools ?? []).filter((t) => message && t.messageId === message.id);
+  const items = coreItems ?? [];
+  const agentMessages = items.filter((i) => i.type === 'agent_message');
+  const reasoning = items.filter((i) => i.type === 'reasoning');
+  const toolCalls = items.filter((i) => i.type === 'tool_call');
+  const usageItems = items.filter((i) => i.type === 'usage');
+
+  // Turn 状态：legacy stopReason ↔ core status
+  const expectedStatus = message?.stopReason === 'cancelled' ? 'cancelled'
+    : message?.stopReason === 'error' || thread.error ? 'error'
+    : 'completed';
+  if (coreTurn.status !== expectedStatus) {
+    mismatches.push(`turn status: legacy=${expectedStatus} core=${coreTurn.status}`);
+  }
+
+  // 最终回答全文
+  const legacyText = message?.text ?? '';
+  const coreText = agentMessages.map((i) => i.content ?? '').join('');
+  if (legacyText !== coreText) {
+    mismatches.push(`final answer: legacy ${legacyText.length} chars vs core ${coreText.length} chars`);
+  }
+
+  // Reasoning 是否存在
+  const legacyThinking = Boolean(message?.thinking);
+  const coreThinking = reasoning.some((i) => (i.content ?? '').length > 0);
+  if (legacyThinking !== coreThinking) {
+    mismatches.push(`reasoning presence: legacy=${legacyThinking} core=${coreThinking}`);
+  }
+
+  // 工具数量与状态
+  if (tools.length !== toolCalls.length) {
+    mismatches.push(`tool count: legacy=${tools.length} core=${toolCalls.length}`);
+  } else {
+    for (let i = 0; i < tools.length; i++) {
+      const legacyState = tools[i].state ?? 'done';
+      const coreState = toolCalls[i].state === 'interrupted' ? 'interrupted'
+        : toolCalls[i].status === 'error' ? 'error'
+        : toolCalls[i].state ?? 'done';
+      if (legacyState !== coreState) {
+        mismatches.push(`tool[${i}] state: legacy=${legacyState} core=${coreState}`);
+      }
+    }
+  }
+
+  // Compare the same normalized usage values; units stay owned by the adapter.
+  const coreUsage = coreThread?.usage ?? Object.assign({}, ...usageItems.map(i => i.usage));
+  if (!isDeepStrictEqual(thread.usage ?? {}, coreUsage)) mismatches.push('usage values differ');
+  if (coreTurn.startedAt !== message?.at) mismatches.push(`start time: legacy=${message?.at} core=${coreTurn.startedAt}`);
+  if (coreTurn.completedAt !== message?.endedAt) mismatches.push(`end time: legacy=${message?.endedAt} core=${coreTurn.completedAt}`);
+
+  return mismatches;
+}
+
+module.exports = { compareTurn };

package/scripts/support/shadow.cjs

@@ -0,0 +1,114 @@
+const { EventNormalizer } = require('../../src/main/harness-adapter/event-normalizer');
+const { compareTurn } = require('./shadow-comparator.cjs');
+
+/**
+ * Shadow Mirror（§11）：Adapter → Runtime → ┬→ Legacy Transcript（现状不变）
+ *                                           └→ Normalizer → Protocol Core（影子）
+ * 所有方法永不抛出：Shadow 的任何失败只记录，绝不影响旧系统（§13/约束#14）。
+ */
+class ShadowMirror {
+  constructor({ core }) {
+    this.core = core;
+    this.normalizers = new Map();  // threadId -> EventNormalizer
+    this.activeTurns = new Map();  // threadId -> core turnId
+    this.mismatchLog = [];         // { threadId, turnId, mismatches[] }
+    this.lastTurns = new Map();
+    this.errorLog = [];            // { phase, message }
+  }
+
+  /** Legacy 任务建立 → Core Thread（复用同一 threadId，便于对照） */
+  threadCreated(thread) {
+    this.#guard('threadCreated', () => {
+      this.core.createThread({
+        id: thread.id,
+        workspaceId: thread.cwd,
+        harnessId: thread.harnessId,
+        nativeSessionRef: thread.nativeSessionId ? { sessionId: String(thread.nativeSessionId) } : undefined,
+        metadata: { title: thread.title },
+      });
+      if (thread.usage) this.core.dispatch({ threadId: thread.id, type: 'thread.updated', payload: { usage: thread.usage } });
+    });
+  }
+
+  /** 用户发送 → 先创建 Core Turn 并启动，再随 Harness 事件推进（§26 的 Shadow 版） */
+  turnStarted(thread, userText) {
+    this.#guard('turnStarted', () => {
+      const turn = this.core.createTurn({
+        threadId: thread.id,
+        nativeTurnRef: thread.nativeSessionId ? { sessionId: String(thread.nativeSessionId) } : undefined,
+      });
+      this.activeTurns.set(thread.id, turn.id);
+      this.lastTurns.set(thread.id, turn.id);
+      const message = thread.messages?.findLast(m => m.role === 'assistant');
+      if (message) message.coreTurnId = turn.id;
+      const normalizer = this.#normalizer(thread);
+      const beginEvents = normalizer.beginTurn(turn.id, userText);
+      const timestamp = thread.messages?.findLast(m => m.role === 'assistant')?.at ?? Date.now();
+      this.core.dispatch({ timestamp, threadId: thread.id, turnId: turn.id, type: 'turn.started', payload: {} });
+      for (const event of beginEvents) this.core.dispatch({ ...event, timestamp });
+    });
+  }
+
+  /** Legacy 统一事件 → Normalizer → Core dispatch；completed/error 时跑 Comparator */
+  applyLegacyEvent(thread, legacyEvent) {
+    this.#guard('applyLegacyEvent', () => {
+      const normalizer = this.#normalizer(thread);
+      const events = normalizer.normalize(legacyEvent);
+      const message = thread.messages?.findLast(m => m.role === 'assistant');
+      const timestamp = legacyEvent.timestamp ?? (['completed', 'error'].includes(legacyEvent.kind) ? message?.endedAt ?? Date.now() : Date.now());
+      for (const event of events) this.core.dispatch({ ...event, timestamp });
+      if (legacyEvent.kind === 'completed' || legacyEvent.kind === 'error') {
+        const turnId = this.activeTurns.get(thread.id);
+        this.activeTurns.delete(thread.id);
+        if (!turnId) return; // 迟到结算：首次结算已对照过，不再重复比较
+        const coreTurn = this.core.getTurn(turnId);
+        const mismatches = compareTurn({
+          thread,
+          coreThread: this.core.getThread(thread.id),
+          coreTurn,
+          coreItems: coreTurn ? this.core.getItemsForTurn(coreTurn.id) : [],
+        });
+        if (mismatches.length) this.mismatchLog.push({ threadId: thread.id, turnId, mismatches });
+      }
+    });
+  }
+
+  lastTurn(threadId) {
+    return this.core.getTurn(this.lastTurns.get(threadId));
+  }
+
+  snapshot() {
+    return this.core.snapshot();
+  }
+
+  report() {
+    return {
+      enabled: true,
+      threads: this.core.snapshot().threads.length,
+      mismatches: this.mismatchLog,
+      errors: this.errorLog,
+      warnings: this.core.warnings,
+    };
+  }
+
+  /* ---------------- 内部 ---------------- */
+
+  #normalizer(thread) {
+    let normalizer = this.normalizers.get(thread.id);
+    if (!normalizer) {
+      normalizer = new EventNormalizer({ threadId: thread.id, source: thread.harnessId });
+      this.normalizers.set(thread.id, normalizer);
+    }
+    return normalizer;
+  }
+
+  #guard(phase, fn) {
+    try {
+      fn();
+    } catch (error) {
+      this.errorLog.push({ phase, message: String(error?.message ?? error) });
+    }
+  }
+}
+
+module.exports = { ShadowMirror };

package/scripts/switch-harness-test.cjs

@@ -0,0 +1,145 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { HostRuntime } = require('../src/main/host/runtime');
+
+/**
+ * 跨 Harness 原地切换（switchHarness）脚本级测试：
+ * 双假 Adapter 注入 → A 会话产出历史 → /switch 到 B → 信封注入校验 →
+ * 切回 A 的原生恢复校验 → 守卫边界 → 持久化校验。
+ * 运行：npm run test:switch-harness
+ */
+const wait = async fn => { for (let i = 0; i < 300; i++) { if (fn()) return; await new Promise(r => setTimeout(r, 10)); } throw new Error('Timed out'); };
+
+function fakeHarness(id, name) {
+  const state = { sent: [], opens: [], closed: 0, hold: null, withFileChange: false };
+  const adapter = {
+    manifest: { id, name, aliases: [id], capabilities: {} },
+    async open(input) {
+      state.opens.push({ restore: input.thread.restore === true, nativeSessionId: input.thread.nativeSessionId, nativeSessionFile: input.thread.nativeSessionFile });
+      return { nativeSessionId: input.thread.nativeSessionId };
+    },
+    async send(session, text, hooks) {
+      state.sent.push(text);
+      if (state.hold) { state.hold.hooks = hooks; return; } // 挂起：Turn 保持 running，等待测试手动 settle
+      if (state.withFileChange) hooks.emit({ kind: 'file-change', changes: [{ path: 'src/login.ts', before: '', after: 'x', complete: true, changeType: 'added' }] });
+      hooks.emit({ kind: 'text-delta', text: `${name} 回复` });
+      hooks.emit({ kind: 'completed', finalAnswer: true });
+    },
+    async cancel() {},
+    async close() { state.closed++; },
+  };
+  return { adapter, state };
+}
+
+async function main() {
+  await fs.mkdir('output', { recursive: true });
+  const root = await fs.mkdtemp(path.resolve('output/switch-harness-'));
+  const rt = new HostRuntime({ dataDirectory: path.join(root, 'data') });
+  await rt.store.load();
+  const a = fakeHarness('a', 'Alpha');
+  const b = fakeHarness('b', 'Beta');
+  rt.adapters.set('a', a.adapter); rt.status.a = { available: true };
+  rt.adapters.set('b', b.adapter); rt.status.b = { available: true };
+  const threadOf = id => rt.threads.find(t => t.id === id);
+  const settle = async id => { await wait(() => !rt.execution.isRunning(id)); await wait(() => !threadOf(id).reviewPending); };
+
+  try {
+    // 1) 在 A 上产出会话历史（含一次文件变更）
+    a.state.withFileChange = true;
+    const thread = await rt.createThread({ harnessId: 'a', cwd: root });
+    const aNativeId = thread.nativeSessionId;
+    assert.equal(a.state.opens.length, 1);
+    assert.equal(a.state.opens[0].restore, false);
+    await rt.send(thread.id, '帮我重构登录模块');
+    await settle(thread.id);
+    assert.equal(a.state.sent.length, 1);
+    assert.ok(!a.state.sent[0].includes('[Harness Mix handoff]'), '未切换时不得注入信封');
+    assert.equal(thread.messages.find(m => m.role === 'assistant').text, 'Alpha 回复');
+
+    // 2) 指令菜单含 /switch，且候选里排除当前 Harness
+    const commands = await rt.listCommands({ threadId: thread.id });
+    const entry = commands.find(c => c.id === 'switch');
+    assert.ok(entry, '指令菜单应包含 /switch');
+    assert.ok(entry.description.includes('Beta') && !entry.description.includes('Alpha'), '候选只列其他可用 Harness');
+
+    // 3) /switch 到 B（带备注；按 Harness 名解析，大小写不敏感）
+    await rt.send(thread.id, '/switch Beta 优先把测试补完');
+    assert.equal(thread.harnessId, 'b');
+    assert.equal(thread.harnessChain.length, 1);
+    assert.equal(thread.harnessChain[0].harnessId, 'a');
+    assert.equal(thread.harnessChain[0].nativeSessionId, aNativeId);
+    assert.equal(thread.pendingHandoff.fromHarnessId, 'a');
+    assert.equal(thread.pendingHandoff.note, '优先把测试补完');
+    assert.equal(thread.restore, false, '新 Harness 上是全新原生会话');
+    assert.equal(rt.sessions.has(thread.id), false, '切换后旧原生会话已关闭');
+    assert.equal(a.state.closed, 1);
+    assert.equal(b.state.opens.length, 0, '目标 Harness 惰性拉起，切换瞬间不开进程');
+    assert.equal(thread.messages.filter(m => m.role === 'user').length, 1, '/switch 指令本身不落在会话里');
+
+    // 4) 切换后首轮：信封注入 prompt，可见消息保持干净，注入后清除标记
+    await rt.send(thread.id, '继续');
+    await settle(thread.id);
+    assert.equal(b.state.opens.length, 1);
+    assert.equal(b.state.opens[0].restore, false);
+    assert.notEqual(thread.nativeSessionId, aNativeId);
+    assert.match(b.state.sent[0], /\[Harness Mix handoff\]/);
+    assert.match(b.state.sent[0], /untrusted historical data/);
+    assert.match(b.state.sent[0], /帮我重构登录模块/);
+    assert.match(b.state.sent[0], /Alpha 回复/);
+    assert.match(b.state.sent[0], /added src\/login\.ts/);
+    assert.match(b.state.sent[0], /优先把测试补完/);
+    const visible = thread.messages.filter(m => m.role === 'user').at(-1);
+    assert.equal(visible.text, '继续', '信封不进用户可见消息');
+    assert.equal(thread.pendingHandoff, undefined, '信封发送成功后标记已清除');
+
+    // 5) 第二轮起不再注入
+    await rt.send(thread.id, '第二步');
+    await settle(thread.id);
+    assert.ok(!b.state.sent[1].includes('[Harness Mix handoff]'), '信封只注入一次');
+
+    // 6) 切回 A：原生会话引用恢复（惰性 open 走 restore 路径），chain 压栈两条
+    await rt.send(thread.id, '/switch a');
+    assert.equal(thread.harnessId, 'a');
+    assert.equal(thread.harnessChain.length, 2);
+    assert.equal(thread.harnessChain[1].harnessId, 'b');
+    assert.equal(thread.nativeSessionId, aNativeId, '切回恢复原原生会话标识');
+    assert.equal(thread.restore, true);
+    await rt.send(thread.id, '我回来了');
+    await settle(thread.id);
+    assert.equal(a.state.opens.length, 2);
+    assert.equal(a.state.opens[1].restore, true, '切回走原生恢复路径');
+    assert.equal(a.state.opens[1].nativeSessionId, aNativeId);
+    assert.match(a.state.sent[1], /\[Harness Mix handoff\]/, '切回首轮同样注入信封');
+
+    // 7) 守卫：执行中 / 同 Harness / 未知 Harness / 草稿 / 协作子任务
+    a.state.hold = {};
+    await rt.send(thread.id, '会挂起的任务');
+    await wait(() => rt.execution.isRunning(thread.id));
+    await assert.rejects(rt.switchHarness(thread.id, 'b'), /正在执行/);
+    await assert.rejects(rt.send(thread.id, '/switch b'), /正在执行/);
+    a.state.hold.hooks.emit({ kind: 'completed', finalAnswer: true });
+    a.state.hold = null;
+    await settle(thread.id);
+    await assert.rejects(rt.switchHarness(thread.id, 'a'), /已经在该 Harness/);
+    await assert.rejects(rt.switchHarness(thread.id, 'Nope'), /未知 Harness/);
+    const draft = await rt.createThread({ harnessId: 'a', cwd: root, ephemeral: true });
+    await assert.rejects(rt.switchHarness(draft.id, 'b'), /草稿任务/);
+    const child = await rt.createThread({ harnessId: 'a', cwd: root, parentThreadId: thread.id });
+    await assert.rejects(rt.switchHarness(child.id, 'b'), /协作子任务/);
+
+    // 8) 持久化：threads.json 里切换链完整（含原生会话引用，供重启后惰性恢复）
+    await rt.store.save(rt.threads);
+    const persisted = JSON.parse(await fs.readFile(path.join(root, 'data', 'threads.json'), 'utf8')).find(t => t.id === thread.id);
+    assert.equal(persisted.harnessId, 'a');
+    assert.deepEqual(persisted.harnessChain.map(e => e.harnessId), ['a', 'b']);
+    assert.equal(persisted.harnessChain[0].nativeSessionId, aNativeId);
+    // restore 是 initialize() 按 nativeSessionId+messages 重新推导的瞬态标记，不持久化；
+    // 重启恢复的真正契约是持久化的 harnessId + nativeSessionId（指向 A 的原生会话）。
+    assert.equal(persisted.nativeSessionId, aNativeId);
+    assert.equal(persisted.restore, undefined);
+
+    console.log('PASS: in-place harness switch → one-shot context envelope → switch-back native resume, guards and persistence');
+  } finally { await rt.close(); }
+}
+main().catch(error => { console.error(error); process.exitCode = 1; });