@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/__tests__/ui-request-queue.test.ts

@@ -1,298 +0,0 @@
-// src/__tests__/ui-request-queue.test.ts
-//
-// W3 测试：UI 请求队列机制（L1 per-child createUiRequestQueue）
-// 1. 多个请求按 FIFO 顺序处理
-// 2. 第一个请求未完成时第二个不开始
-//
-// 直接测试 createUiRequestQueue 的队列逻辑（纯函数，不需要 mock runSpawn）。
-// 用 fake child（PassThrough stdin）+ 手动控制 Promise resolve 时序。
-//
-// 协议迁移（W2）：enqueue 第二参从旧 Record params（含 questions/context）改为
-// ExtensionUiRequest（method 平铺）；handler 签名从 (questions,context) 改为
-// UiRequestHandler (req: UiRequest) => Promise<UiResponse>。
-
-import type { ChildProcess } from "node:child_process";
-import { PassThrough } from "node:stream";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import {
-  createUiRequestQueue,
-  type UiRequest,
-  type UiRequestHandler,
-  type UiResponse,
-} from "../ui-request-queue.ts";
-
-beforeEach(() => {
-  vi.useFakeTimers();
-});
-
-afterEach(() => {
-  vi.useRealTimers();
-});
-
-function makeFakeChild(): ChildProcess {
-  const stdin = new PassThrough();
-  return {
-    stdin,
-    killed: false,
-    pid: 10001,
-    on: vi.fn(),
-    removeListener: vi.fn(),
-  } as unknown as ChildProcess;
-}
-
-/** 构造 select method 的 ExtensionUiRequest（ask_user 借道 select dialog 通道）。 */
-function makeSelectReq(question: string): { method: "select"; title: string; options: string[] } {
-  return {
-    method: "select",
-    title: question,
-    options: [JSON.stringify({ question, options: [{ label: "A" }] })],
-  };
-}
-
-describe("UI 请求队列", () => {
-  it("多个 extension_ui_request 按 FIFO 顺序处理", async () => {
-    const callOrder: string[] = [];
-    // 每个请求返回独立的可控 Promise
-    const resolvers: Array<(v: UiResponse) => void> = [];
-
-    const handler: UiRequestHandler = vi.fn((req: UiRequest) => {
-      callOrder.push(req.title ?? "");
-      return new Promise<UiResponse>((resolve) => {
-        resolvers.push(resolve);
-      });
-    }) as unknown as UiRequestHandler;
-
-    const child = makeFakeChild();
-    const ctx = { uiRequestHandler: handler } as Parameters<
-      typeof createUiRequestQueue
-    >[1];
-    const enqueue = createUiRequestQueue(child, ctx);
-
-    // 快速入队三个请求（handler 被调用但不 resolve）
-    enqueue("r1", makeSelectReq("Q1"));
-    enqueue("r2", makeSelectReq("Q2"));
-    enqueue("r3", makeSelectReq("Q3"));
-
-    // 第一个请求立即开始处理
-    expect(handler).toHaveBeenCalledTimes(1);
-    expect(callOrder).toEqual(["Q1"]);
-
-    // resolve 第一个 → 第二个开始处理
-    resolvers[0]({ value: "a1" });
-    await vi.advanceTimersByTimeAsync(0);
-    expect(handler).toHaveBeenCalledTimes(2);
-    expect(callOrder).toEqual(["Q1", "Q2"]);
-
-    // resolve 第二个 → 第三个开始处理
-    resolvers[1]({ value: "a2" });
-    await vi.advanceTimersByTimeAsync(0);
-    expect(handler).toHaveBeenCalledTimes(3);
-    expect(callOrder).toEqual(["Q1", "Q2", "Q3"]);
-  });
-
-  it("第一个请求未 resolve 时第二个不调用 uiRequestHandler", async () => {
-    const callOrder: string[] = [];
-    let firstResolve: (v: UiResponse) => void;
-
-    const handler: UiRequestHandler = vi.fn((req: UiRequest) => {
-      callOrder.push(req.title ?? "");
-      if (req.title === "Q1") {
-        return new Promise<UiResponse>((resolve) => {
-          firstResolve = resolve;
-        });
-      }
-      return Promise.resolve<UiResponse>({ value: "done" });
-    }) as unknown as UiRequestHandler;
-
-    const child = makeFakeChild();
-    const ctx = { uiRequestHandler: handler } as Parameters<
-      typeof createUiRequestQueue
-    >[1];
-    const enqueue = createUiRequestQueue(child, ctx);
-
-    enqueue("r1", makeSelectReq("Q1"));
-    enqueue("r2", makeSelectReq("Q2"));
-
-    // 只有 Q1 被调用，Q2 还在队列里
-    expect(handler).toHaveBeenCalledTimes(1);
-    expect(callOrder).toEqual(["Q1"]);
-
-    // 等一下，Q2 仍然不应该被调用
-    await vi.advanceTimersByTimeAsync(100);
-    expect(handler).toHaveBeenCalledTimes(1);
-    expect(callOrder).toEqual(["Q1"]);
-
-    // resolve Q1 → Q2 才开始
-    firstResolve!({ value: "a1" });
-    await vi.advanceTimersByTimeAsync(0);
-    expect(handler).toHaveBeenCalledTimes(2);
-    expect(callOrder).toEqual(["Q1", "Q2"]);
-  });
-});
-
-// ── LC-3/T2⑦ 验收⑤：timeout 字段透传链路（L1 队列 → handler 段）──
-// 下游段（handler → dialogQueue 消费）由 dialog-queue.test.ts / ui-request-handler-factory.test.ts 锁死。
-
-describe("UI 请求队列 — timeout 字段透传（LC-3/T2⑦）", () => {
-  it("ExtensionUiRequest.timeout 经 handleUiRequest 到达 uiRequestHandler 收到的 UiRequest", async () => {
-    const received: UiRequest[] = [];
-    const handler: UiRequestHandler = (req: UiRequest) => {
-      received.push(req);
-      return Promise.resolve<UiResponse>({ value: "ok" });
-    };
-
-    const child = makeFakeChild();
-    const ctx = { uiRequestHandler: handler } as Parameters<
-      typeof createUiRequestQueue
-    >[1];
-    const enqueue = createUiRequestQueue(child, ctx);
-
-    enqueue("r1", { ...makeSelectReq("Q1"), timeout: 5000 });
-    await vi.advanceTimersByTimeAsync(0);
-
-    expect(received).toHaveLength(1);
-    expect(received[0].timeout).toBe(5000);
-  });
-});
-
-// ── extractMethodFields 字段复制链路（经 createUiRequestQueue → handleUiRequest 锁定）──
-// 13 个 method-specific 字段的复制语义：typed 守卫字段（string/number/array）验型通过才复制、
-// presence-only 字段（statusText/widgetLines/widgetPlacement）仅 in 检查直赋、缺失字段不复制。
-// 协议形状来自 JSON 反序列化，坏类型运行时可达——用例以 as unknown as 构造越界形状做防御锁定。
-
-describe("UI 请求队列 — method-specific 字段复制（extractMethodFields 链路）", () => {
-  function makeQueue(handler: UiRequestHandler): { enqueue: ReturnType<typeof createUiRequestQueue> } {
-    const child = makeFakeChild();
-    const ctx = { uiRequestHandler: handler } as Parameters<
-      typeof createUiRequestQueue
-    >[1];
-    return { enqueue: createUiRequestQueue(child, ctx) };
-  }
-
-  it("全字段请求：typed 守卫字段与 presence-only 字段全部复制到 UiRequest", async () => {
-    const received: UiRequest[] = [];
-    const { enqueue } = makeQueue((req) => {
-      received.push(req);
-      return Promise.resolve<UiResponse>({ ack: true });
-    });
-
-    // 13 字段全量形状（协议 union 无单变体携带全部字段，运行时平铺可达）
-    const req = {
-      method: "select",
-      title: "t",
-      options: ["a", "b"],
-      message: "m",
-      placeholder: "p",
-      prefill: "pf",
-      notifyType: "warning",
-      statusKey: "sk",
-      statusText: "st",
-      widgetKey: "wk",
-      widgetLines: ["l1"],
-      widgetPlacement: "belowEditor",
-      text: "tx",
-      timeout: 2500,
-    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
-
-    enqueue("r1", req);
-    await vi.advanceTimersByTimeAsync(0);
-
-    expect(received).toHaveLength(1);
-    expect(received[0]).toMatchObject({
-      title: "t",
-      options: ["a", "b"],
-      message: "m",
-      placeholder: "p",
-      prefill: "pf",
-      notifyType: "warning",
-      statusKey: "sk",
-      statusText: "st",
-      widgetKey: "wk",
-      widgetLines: ["l1"],
-      widgetPlacement: "belowEditor",
-      text: "tx",
-      timeout: 2500,
-    });
-  });
-
-  it("typed 守卫字段类型不符时跳过复制，其余字段照常", async () => {
-    const received: UiRequest[] = [];
-    const { enqueue } = makeQueue((req) => {
-      received.push(req);
-      return Promise.resolve<UiResponse>({ ack: true });
-    });
-
-    const req = {
-      method: "select",
-      title: "kept-title", // 合法（title 非法值会在链路上游 startsWith 处炸掉整条请求，见下一条用例）
-      options: "not-array", // string ≠ array → 跳过
-      timeout: "5000", // string ≠ number → 跳过
-      message: "kept",
-    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
-
-    enqueue("r1", req);
-    await vi.advanceTimersByTimeAsync(0);
-
-    expect(received).toHaveLength(1);
-    expect(received[0].title).toBe("kept-title");
-    expect("options" in received[0]).toBe(false);
-    expect("timeout" in received[0]).toBe(false);
-    expect(received[0].message).toBe("kept");
-  });
-
-  it("typed 非法 title（number）在上游 startsWith 处炸链路 → handler 不被调、单请求失败被吞不阻塞队列", async () => {
-    // HEAD 真实行为锚定（探针实证）：title: 42 在 extractMethodFields 之前的环节
-    // 触发 str.startsWith is not a function，异常被 handleUiRequest 的 .catch 吞掉
-    //（注释声明的「单个请求失败不阻塞后续」语义）——守卫的「跳过该字段」对 title 不可达。
-    const received: UiRequest[] = [];
-    const { enqueue } = makeQueue((req) => {
-      received.push(req);
-      return Promise.resolve<UiResponse>({ ack: true });
-    });
-
-    const badReq = {
-      method: "select",
-      title: 42,
-      message: "kept",
-    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
-    enqueue("r1", badReq);
-    await vi.advanceTimersByTimeAsync(0);
-    expect(received).toHaveLength(0); // handler 未被调（链路在上游失败）
-
-    // 队列不阻塞：后续合法请求照常处理
-    enqueue("r2", {
-      method: "select",
-      title: "Q2",
-      options: [JSON.stringify({ question: "Q2", options: [{ label: "A" }] })],
-    });
-    await vi.advanceTimersByTimeAsync(0);
-    expect(received).toHaveLength(1);
-    expect(received[0].title).toBe("Q2");
-  });
-
-  it("presence-only 字段仅 in 检查直赋；未声明的字段不复制（保持 UiRequest 可选）", async () => {
-    const received: UiRequest[] = [];
-    const { enqueue } = makeQueue((req) => {
-      received.push(req);
-      return Promise.resolve<UiResponse>({ ack: true });
-    });
-
-    // statusText 存在但值为 undefined（statusText: string | undefined 变体合法形态）→ 仍复制
-    const req = {
-      method: "setStatus",
-      statusKey: "k",
-      statusText: undefined,
-      unknownField: "should-not-copy",
-    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
-
-    enqueue("r1", req);
-    await vi.advanceTimersByTimeAsync(0);
-
-    expect(received).toHaveLength(1);
-    expect("statusText" in received[0]).toBe(true);
-    expect(received[0].statusText).toBeUndefined();
-    expect("unknownField" in received[0]).toBe(false);
-  });
-});

package/src/execution/__tests__/worktree-pid-registration.integration.test.ts

@@ -1,230 +0,0 @@
-// src/execution/__tests__/worktree-pid-registration.integration.test.ts
-//
-// [worktree-reaper-fix] 端到端集成测试：验证 worktree pid 注册链路（接线层）。
-//
-// 背景：2026-08-11 生产事故——reaper 误清活 worktree。根因：pid 补全代码唯一生产调用点
-// 挂在 session-runner 的 header 分支（RPC mode 永不触发），注册表 pid 恒为 0，超
-// SPAWN_GRACE_MS(60s) 后任意 session_start 触发的 scan() 必然误删活 worktree。
-// 修复：spawn() 返回后同步补 pid。
-//
-// 为什么用真实 spawn（而非现有 run-spawn-* 的 FakeChild mock）：
-//   现有测试全 mock registerPid（session-start-reaper/crash-recovery/index-session-start/
-//   stream-sink-guard），验证的是「mock 了补全回调后的 reaper 行为」，从未验证
-//   「真实调用链中补全回调是否被调用」——接线错误零检测能力（结构性盲区）。
-//   本测试走真实链路：真实 git repo + 真实 worktree 创建 + 真实 spawn node 子进程 +
-//   真实注册表文件，仅 mock ./pi-invocation.ts（把 pi 二进制替换为 node -e 脚本）。
-//
-// mock 最小化原则：
-//   - node:child_process 不 mock（真实 spawn / spawnSync git）
-//   - node:fs 不 mock（真实目录/文件：worktree checkout、注册表 JSON）
-//   - alive-store 不 mock（真实 process.kill(pid, 0) 探活）
-//   - 仅 vi.mock("./pi-invocation.ts")：getPiInvocation 返回 node -e 脚本
-//   - fake timers 仅 toFake: ["Date"]：推进注册表宽限判定用，不干扰真实 I/O 事件
-
-import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-// vi.hoisted：vi.mock 工厂体内不能引用顶层 let/const（提升限制），脚本字符串必须放这。
-// scriptHolder 是可变对象：getPiInvocation 每次调用时读它（工厂函数体在运行时执行），
-// 用例内可切换长驻/短命脚本。
-const { scriptHolder, LONG_RUNNING_SCRIPT, SHORT_LIVED_SCRIPT } = vi.hoisted(() => {
-  const scriptHolder: { script: string } = { script: "process.exit(0)" };
-  return {
-    scriptHolder,
-    // 长驻脚本：90s 后退出（测试在 61s scan 时它必须还活着，验证「活 worktree 不被清」）
-    LONG_RUNNING_SCRIPT:
-      "setTimeout(() => process.exit(0), 90000);",
-    // 短命脚本：立即退出（模拟快速完成的子 agent，验证「真孤儿被回收」）
-    SHORT_LIVED_SCRIPT: "process.exit(0)",
-  };
-});
-
-vi.mock("./pi-invocation.ts", () => ({
-  getPiInvocation: (userArgs: string[]) => ({
-    command: process.execPath,
-    args: ["-e", scriptHolder.script, ...userArgs],
-  }),
-}));
-
-import { WorktreeManager } from "../worktree-manager.ts";
-import { WorktreeRegistry, SPAWN_GRACE_MS } from "../worktree-registry.ts";
-import { runSpawn } from "../engine/engines/pi/session-runner.ts";
-import type { WorktreeHandle } from "../types.ts";
-import { makeCtx, makeOpts, makeRecord } from "./helpers/spawn-mock.ts";
-
-// ── 测试夹具：临时 git repo + 临时 agentDir（避免污染 ~/.pi/agent）──
-
-let tmpRoot: string;
-let repoDir: string;
-let agentDir: string;
-let wtm: WorktreeManager;
-let registry: WorktreeRegistry;
-let handle: WorktreeHandle | undefined;
-let spawnedPid: number | undefined;
-
-function git(args: string[], cwd: string): string {
-  const r = spawnSync("git", args, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
-  return (r.stdout ?? "").trim();
-}
-
-/** 初始化临时 git repo（至少一个 commit，worktreeManager.create 需要 clean tree + HEAD）。 */
-function initRepo(): void {
-  repoDir = path.join(tmpRoot, "repo");
-  fs.mkdirSync(repoDir, { recursive: true });
-  git(["init", "-b", "main"], repoDir);
-  git(["config", "user.email", "test@test.local"], repoDir);
-  git(["config", "user.name", "test"], repoDir);
-  git(["commit", "--allow-empty", "-m", "init"], repoDir);
-}
-
-/** 从注册表文件读指定 branch 的条目（真实文件，轮询用）。 */
-function readEntry(branch: string): { pid: number; createdAt: number } | undefined {
-  return registry.load().find((e) => e.branch === branch);
-}
-
-/** 轮询注册表直到 pid 补全（真实 fs 读 + 真实 setTimeout 轮询）。 */
-async function waitForPid(branch: string, timeoutMs = 5000): Promise<number> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    const entry = readEntry(branch);
-    if (entry && entry.pid !== 0) return entry.pid;
-    await new Promise((r) => setTimeout(r, 20));
-  }
-  throw new Error(`pid not registered within ${timeoutMs}ms (branch=${branch})`);
-}
-
-/** 清理：kill 子进程 + worktree cleanup + 删除临时目录。 */
-async function cleanup(): Promise<void> {
-  if (spawnedPid) {
-    try {
-      process.kill(spawnedPid, "SIGKILL");
-    } catch {
-      // 已退出
-    }
-    spawnedPid = undefined;
-  }
-  if (handle) {
-    try {
-      await wtm.cleanup(handle);
-    } catch (err) {
-      // best-effort：git worktree remove 失败不阻断测试清理
-      // eslint-disable-next-line no-console -- 测试 teardown 兜底留痕（清理失败不阻断后续 rmSync），非产品日志面
-      console.warn("worktree cleanup failed in test teardown", err);
-    }
-    handle = undefined;
-  }
-  try {
-    fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-  } catch {
-    // best-effort
-  }
-}
-
-beforeEach(() => {
-  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "wt-reaper-it-"));
-  agentDir = path.join(tmpRoot, "agent");
-  initRepo();
-  wtm = new WorktreeManager(agentDir);
-  registry = new WorktreeRegistry(agentDir);
-});
-
-afterEach(async () => {
-  vi.useRealTimers();
-  await cleanup();
-});
-
-// ── 用例 ──
-
-// [HISTORICAL] 2026-08-20 PR #185：真实 spawn node 子进程 + 真实 git worktree + 注册表
-// 文件锁集成用例显式超时——整包满并行 + 系统余载下真实子进程链路超 vitest 默认 5s
-// testTimeout（对齐本包 worktree-registry D5a / process-shutdown-hook 口径）。
-describe("worktree pid 注册链路（真实 spawn 集成）", { timeout: 30_000 }, () => {
-  it("正向：spawn 返回后注册表 pid 同步补全，活 worktree 超宽限不被 scan 误清", async () => {
-    // 0. 长驻脚本（子进程 90s 内不退出，模拟长跑子 agent）
-    scriptHolder.script = LONG_RUNNING_SCRIPT;    // 1. 真实创建 worktree（pid=0 占位）
-    handle = await wtm.create(repoDir, "rec-1");
-    expect(readEntry(handle.branch)).toMatchObject({ pid: 0 });
-
-    // 2. runSpawn 挂后台（不 await——长驻子进程 close 不触发，await 会挂死），
-    //    ctx.onWorktreePid 接真实 registerPid（模拟 subagent-service 接线）
-    const ctx = makeCtx({
-      agentDir,
-      cwd: repoDir,
-      mainCwd: repoDir,
-      rootCwd: repoDir,
-      onWorktreePid: (branch: string, pid: number) => wtm.registerPid(branch, pid),
-    });
-    const runPromise = runSpawn(
-      makeRecord(),
-      "test task",
-      makeOpts({ worktree: handle }),
-      ctx,
-    );
-
-    // 3. 断言 spawn 后 pid 已补全（真实注册表文件轮询）——修复前此步超时红
-    spawnedPid = await waitForPid(handle.branch);
-    expect(spawnedPid).toBeGreaterThan(0);
-
-    // 4. 推进时钟超 SPAWN_GRACE_MS（仅 fake Date，不干扰真实 I/O）
-    vi.useFakeTimers({ toFake: ["Date"] });
-    vi.setSystemTime(Date.now() + SPAWN_GRACE_MS + 1000);
-
-    // 5. scan()：活 worktree 必须不被清（修复前：pid=0 超宽限 → 误删 → 红）
-    await wtm.scan();
-    expect(fs.existsSync(handle.path)).toBe(true);
-
-    // 6. 收尾：真实时钟恢复 + kill 子进程让 runPromise settle
-    vi.useRealTimers();
-    try {
-      process.kill(spawnedPid, "SIGTERM");
-    } catch {
-      // 已退出
-    }
-    await runPromise;
-
-    // 7. 反向：进程死后 scan 回收真孤儿
-    await wtm.scan();
-    expect(fs.existsSync(handle.path)).toBe(false);
-    const entryAfter = readEntry(handle.branch);
-    expect(entryAfter).toBeUndefined();
-  }, 15000);
-
-  it("反向：短命子进程退出后，pid>0 且进程死 → scan 立即回收", async () => {
-    // 0. 短命脚本（子进程立即退出，模拟快速完成的子 agent）
-    scriptHolder.script = SHORT_LIVED_SCRIPT;
-    // 1. 真实创建 worktree
-    handle = await wtm.create(repoDir, "rec-2");
-
-    // 2. 短命脚本子进程：spawn 后同步补 pid（修复前 pid=0，且未超宽限 → 不回收 → 红）
-    const ctx = makeCtx({
-      agentDir,
-      cwd: repoDir,
-      mainCwd: repoDir,
-      rootCwd: repoDir,
-      onWorktreePid: (branch: string, pid: number) => wtm.registerPid(branch, pid),
-    });
-    const result = await runSpawn(
-      makeRecord(),
-      "test task",
-      makeOpts({ worktree: handle }),
-      ctx,
-    );
-    // 历史「status !== error」弱断言：AgentResult 无 status 字段，经视图访问保持断言语义不变
-    expect((result as { status?: string }).status).not.toBe("error"); // 进程正常退出（exit 0），非 spawn 失败
-
-    // 3. pid 已补全（短命进程退出后 pid 仍有效，registerPid 同步执行不受退出影响）
-    const entry = readEntry(handle.branch);
-    expect(entry).toBeDefined();
-    expect(entry!.pid).toBeGreaterThan(0);
-    spawnedPid = entry!.pid;
-
-    // 4. scan：pid>0 且进程死 → 立即判孤儿回收（无需等宽限）
-    await wtm.scan();
-    expect(fs.existsSync(handle.path)).toBe(false);
-    expect(readEntry(handle.branch)).toBeUndefined();
-  }, 15000);
-});

package/src/execution/engine/__tests__/common/schema-emulation.test.ts

@@ -1,128 +0,0 @@
-// schema-emulation.test.ts —— 三级容错提取逐级用例 + ajv 校验 + tail 载体。
-//
-// 三视角：①构建者——三级容错每级有独立触达用例（直接 parse / fence / 括号扫描）；
-// ②使用者——ok:false 时 error 简述 + tail 足以构造重试 prompt；③观察者——prompt
-// 注入段含 schema 声明与输出约定（emulated 引擎拼进 prompt 后模型可遵循）。
-
-import { describe, expect, it } from "vitest";
-
-import {
-  buildSchemaEmulationSegment,
-  extractAndValidateStructuredOutput,
-  SCHEMA_EMULATION_TAIL_CHARS,
-} from "../../common/schema-emulation.ts";
-
-const objectSchema = {
-  type: "object",
-  properties: { verdict: { type: "string" }, issues: { type: "array", items: { type: "string" } } },
-  required: ["verdict"],
-} as const;
-
-describe("buildSchemaEmulationSegment", () => {
-  it("注入段含 schema JSON 声明 + 输出格式约定（用户可见 prompt 断言）", () => {
-    const segment = buildSchemaEmulationSegment(objectSchema);
-    expect(segment).toContain("## Structured Output Requirement");
-    expect(segment).toContain(JSON.stringify(objectSchema));
-    expect(segment).toMatch(/```json/);
-    expect(segment).toMatch(/ONLY the JSON value/);
-    expect(segment).toMatch(/JSON Schema \(draft-07\)/);
-  });
-});
-
-describe("extractAndValidateStructuredOutput 三级容错", () => {
-  it("第 1 级：输出整体即合法 JSON → 直接 parse 通过 + ajv 通过", () => {
-    const text = JSON.stringify({ verdict: "pass", issues: [] });
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "pass", issues: [] } });
-  });
-
-  it("第 2 级：markdown code fence 包裹 → 剥 fence 后 parse 通过", () => {
-    const text = "Here is my answer:\n```json\n{\"verdict\": \"fail\", \"issues\": [\"a\", \"b\"]}\n```\n";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["a", "b"] } });
-  });
-
-  it("第 2 级：无语言标注的裸 fence 也能剥", () => {
-    const text = "```\n{\"verdict\": \"pass\"}\n```";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "pass" } });
-  });
-
-  it("第 3 级：前后杂文本包裹 → 首尾括号扫描提取", () => {
-    const text = "Sure! The review result is:\n\n{\"verdict\": \"fail\", \"issues\": [\"x\"]}\n\nHope this helps.";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["x"] } });
-  });
-
-  it("第 3 级：array 根也支持（首个 '[' 到末个 ']'）", () => {
-    const arraySchema = { type: "array", items: { type: "string" } };
-    const result = extractAndValidateStructuredOutput("prefix [\"a\",\"b\"] suffix", arraySchema);
-    expect(result).toEqual({ ok: true, parsed: ["a", "b"] });
-  });
-
-  it("提取成功但 ajv 校验失败 → ok:false 含 ajv 错误明细与原始尾部", () => {
-    // verdict 缺失（required）+ issues 类型错
-    const text = '{"issues": "not-an-array"}';
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("Schema validation failed");
-      expect(result.error).toContain("verdict");
-      expect(result.tail).toBe(text);
-    }
-  });
-
-  it("三级提取全失败（无任何 JSON）→ ok:false 且 error 指明三级路径", () => {
-    const result = extractAndValidateStructuredOutput("no json here at all", objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("3-stage");
-      expect(result.error).toContain("code-fence");
-      expect(result.error).toContain("bracket scan");
-    }
-  });
-
-  it("提取成功但 JSON 语法损坏（括号扫描后仍 parse 失败）→ ok:false", () => {
-    const result = extractAndValidateStructuredOutput("result: {verdict: pass}", objectSchema);
-    expect(result.ok).toBe(false);
-  });
-
-  it("ajv 编译失败（非法 schema）→ ok:false 指明 host 侧编译失败", () => {
-    // type: "foo" 是 ajv 编译期拒绝的非法类型值
-    const result = extractAndValidateStructuredOutput('{"a":1}', { type: "foo" });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("compilation failed");
-    }
-  });
-});
-
-describe("tail 载体（错误展示）", () => {
-  it(`tail 截断到原始输出尾部 ${SCHEMA_EMULATION_TAIL_CHARS} 字`, () => {
-    const head = "H".repeat(300);
-    const tailPart = "T".repeat(400);
-    const text = `${head}${tailPart}`; // 700 字，尾部 500 = 末段（100H + 400T）
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.tail.length).toBe(SCHEMA_EMULATION_TAIL_CHARS);
-      expect(result.tail).toBe("H".repeat(100) + "T".repeat(400));
-    }
-  });
-
-  it("短输出 tail 为原文（不截断）", () => {
-    const text = "short broken output";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.tail).toBe(text);
-    }
-  });
-});
-
-describe("D4 硬分流守护（静态断言）", () => {
-  it("本模块的 ajv 只在 emulated 路径——native 引擎（pi-env 链路）不 import 本模块（由全仓 grep 守护，见任务报告）", () => {
-    // 占位用例：硬分流是 import 约束，运行时无对应断言点；保留用例记录守护方式
-    expect(typeof extractAndValidateStructuredOutput).toBe("function");
-  });
-});