@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/engine/engines/zcode/launcher.ts

@@ -1,161 +0,0 @@
-// src/execution/engine/engines/zcode/launcher.ts
-//
-// ZcodeEngine launcher（P3）：spawn 命令组装 + 进程启动——四件套里唯一持有 spawn 权
-// 的模块（设计 §3.3.7）。TS 重写自 zsub driver.js 的 runHeadless 命令组装段，机制
-// 保留（真机验证过）：
-//   - argv 形态：`node <zcode.cjs> --json --cwd <dir> --mode yolo [--disallowed-tools a,b]
-//     [--resume <sid>] --prompt <text>`；flag 拒收清单（--model/--skill/--max-turns 等
-//     help 漂移项）一个不用；
-//   - stdin: 'ignore'（CLI 不读 stdin，置管道会挂起——zsub 实测）；
-//   - env：HOME=隔离池目录（provider 配置与 db 全部落池内）+ 嵌套防护标记；
-//   - 杀链：SIGTERM → grace → SIGKILL，exited 用 close 事件维护的标志判断
-//     （child.killed 在 kill() 调用后恒 true，zsub 修过的原版死代码 bug）。
-//
-// 与 zsub 的差异：超时不在本模块（宿主公共杀链职责，设计 D4/附录 A「CLI 超时 6/6
-// 全缺全补」）；abort 由 AbortSignal 驱动（EnginePort 契约），zsub 的 cancel() 变为
-// abort(graceMs)。
-
-import { spawn, type ChildProcess } from "node:child_process";
-import { Readable } from "node:stream";
-
-import { killChain } from "../../common/kill-chain.ts";
-import { buildNestedSpawnEnv } from "../../common/nesting-guard.ts";
-import { assertArgvBudget } from "../../common/persona-router.ts";
-import { ZCODE_KILL_GRACE_MS } from "./constants.ts";
-
-// ============================================================
-// argv 组装与字节预算（对齐点②收口：估算/断言单一权威 = common/persona-router，
-// 本模块只组装；引擎侧在 launch 前调 assertArgvBudget）
-// ============================================================
-
-export interface ZcodeSpawnSpec {
-  /** 任务运行目录（--cwd flag 的值）。 */
-  cwd: string;
-  /** 完整 prompt（persona 拼接后的产物）。 */
-  prompt: string;
-  /** 工具 denylist（逗号连接进 --disallowed-tools；空数组不加 flag）。 */
-  denyTools?: string[];
-  /** 冷续聊目标 session（--resume；spawn 单轮模式内不做 resume 仿真，留给宿主）。 */
-  resumeSessionId?: string;
-}
-
-/** 组装 zcode.cjs 的 argv（不含 `node` 与 cli 路径两个前导元素）。 */
-export function buildZcodeArgv(spec: ZcodeSpawnSpec): string[] {
-  const args = ["--json", "--cwd", spec.cwd, "--mode", "yolo"];
-  // denylist 硬约束：非空数组才落 flag（CLI 对空值行为未定义，不赌——zsub 同判）
-  const disallowed = (spec.denyTools ?? []).filter((t) => typeof t === "string" && t.trim() !== "");
-  if (disallowed.length > 0) args.push("--disallowed-tools", disallowed.join(","));
-  if (spec.resumeSessionId) args.push("--resume", String(spec.resumeSessionId));
-  args.push("--prompt", String(spec.prompt));
-  return args;
-}
-
-/**
- * argv 预算断言（launch 前调用；对齐点②：公共 persona-router 的单一权威实现，
- * DEFAULT_ARGV_BUDGET_BYTES 128KB 阈值同源——超限抛 EngineError(prompt_too_large)，
- * 进程创建前拦截，禁止 spawn 后撞 E2BIG）。
- */
-export function assertZcodeArgvBudget(nodeBin: string, cliPath: string, args: string[]): void {
-  assertArgvBudget([nodeBin, cliPath, ...args]);
-}
-
-// ============================================================
-// env 构造
-// ============================================================
-
-/**
- * 构造子进程 env：嵌套防护经公共 nesting-guard（D8：注入统一 XYZ_AGENT_SUBAGENT=1 +
- * 剥离引擎原生嵌套标记 ZSW_NESTED/PI_SUBAGENT_*——旧标记继承会让孙代理误判嵌套层），
- * HOME 最后落（隔离 HOME 是 provider 配置与 db 的定位锚，基 env 同名键不许覆盖）。
- */
-export function buildZcodeEnv(homeDir: string, baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  return { ...buildNestedSpawnEnv(baseEnv), HOME: homeDir };
-}
-
-// ============================================================
-// 进程启动（EngineProcess 形态，设计 §3.3.7）
-// ============================================================
-
-/** launcher 产出的进程句柄（parser 消费 stdout/stderr/exited；abort 是杀链执行体）。 */
-export interface ZcodeLaunchedProcess {
-  /** spawn 出的原始子进程句柄（[U0 D10] 终止链记账——引擎经 RunContext.onChildSpawned 注册进宿主 spawnedChildren）。 */
-  readonly child: ChildProcess;
-  readonly pid: number;
-  readonly stdout: Readable;
-  readonly stderr: Readable;
-  /** 杀链：SIGTERM → graceMs 后未退出则 SIGKILL；resolve 于进程退出。幂等。 */
-  readonly abort: (graceMs?: number) => Promise<void>;
-  /** 进程退出（code=null 表示被信号杀死）。 */
-  readonly exited: Promise<{ code: number | null; signal: string | undefined }>;
-  /** 本方杀链是否介入过（合成终态的判据：介入后 code 语义不再是引擎自身失败）。 */
-  readonly killedByUs: () => boolean;
-}
-
-export interface ZcodeLaunchOptions {
-  /** zcode CLI 路径（node 脚本）。 */
-  cliPath: string;
-  /** cliPath 之后的 argv（buildZcodeArgv 产物）。 */
-  args: string[];
-  /** 完整 env（buildZcodeEnv 产物）。 */
-  env: NodeJS.ProcessEnv;
-  /** node 二进制（缺省 'node'，走 PATH）。 */
-  nodeBin?: string;
-}
-
-/**
- * 启动 zcode 子进程。spawn 同步失败（如 node 不存在）直接 throw——调用方（引擎 run）
- * 按进程创建前错误处理；启动成功后的一切失败归 parser 终态路径（不 throw）。
- *
- * 杀链（对齐点②收口）：SIGTERM → grace → SIGKILL 的实现单一权威 =
- * common/kill-chain.killChain（ChildProcess 结构满足 KillableChild）——本模块只保留
- * killedByUs 标志（合成终态判据：「我方介入过」与「引擎自身失败」的区分）与幂等守卫。
- */
-export function launchZcodeProcess(opts: ZcodeLaunchOptions): ZcodeLaunchedProcess {
-  const nodeBin = opts.nodeBin ?? "node";
-  const child = spawn(nodeBin, [opts.cliPath, ...opts.args], {
-    env: opts.env,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
-  let exited = false;
-  let killTriggered = false;
-
-  // ENOENT（node 缺失）等 spawn 失败经 'error' 事件异步到达且 stdout/stderr 可能为
-  // null——空流兜底，保证消费方（parser）始终拿到可读流
-  const emptyStream = (): Readable => Readable.from([]);
-  const stdoutStream = child.stdout ?? emptyStream();
-  const stderrStream = child.stderr ?? emptyStream();
-
-  const exitedPromise = new Promise<{ code: number | null; signal: string | undefined }>((resolve) => {
-    child.once("close", (code, signal) => {
-      exited = true;
-      resolve({ code, signal: signal ?? undefined });
-    });
-    child.once("error", () => {
-      // spawn 失败（ENOENT 等）也会走 error；close 不一定触发，这里兜底 resolve 防
-      // exited 永挂——code 取 null（无引擎语义可判）
-      exited = true;
-      resolve({ code: null, signal: undefined });
-    });
-  });
-
-  const abort = (graceMs: number = ZCODE_KILL_GRACE_MS): Promise<void> => {
-    if (!killTriggered && !exited) {
-      killTriggered = true;
-      // 公共杀链（不 await：abort 以 exitedPromise 为准；killChain 自身含 grace/
-      // SIGKILL/收尸全时序，fire-and-forget 不改变 abort 的 resolve 语义）
-      void killChain(child, { graceMs });
-    }
-    return exitedPromise.then(() => undefined);
-  };
-
-  return {
-    child,
-    pid: child.pid ?? -1,
-    stdout: stdoutStream,
-    stderr: stderrStream,
-    abort,
-    exited: exitedPromise,
-    killedByUs: () => killTriggered,
-  };
-}

package/src/execution/execute-options-mapper.ts

@@ -1,115 +0,0 @@
-// src/execution/execute-options-mapper.ts
-//
-// D-A2: AgentCallOpts → ExecuteOptions 映射（adapter 职责）
-// D-A9: per-call timeoutMs 合并进 AbortSignal
-//
-// 接线层级：[模块内直调] —— SAR.run 内调。
-
-import type { AgentCallOpts } from "../orchestration/models/types.ts";
-import { HOST_TIMEOUT_ABORT_REASON } from "./engine/common/kill-chain.ts";
-import type { ModelInfo } from "./model-resolver.ts";
-import type { ExecuteOptions } from "./types.ts";
-
-// SLUG_MAX_LENGTH 权威定义（subagent-core 包抽离 u1-move 内化）：core 切面不得反向
-// import 壳侧 interface（D1 依赖闭包判据），常量定义回归 execution 侧本文件——
-// 与 tool schema 的 maxLength 语义同源（壳侧 subagent-tool-schema.ts 改经本文件 import）。
-/**
- * slug 最大长度。历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/
- * "fix-subagent-wf-tools"（21）会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」
- * 与「容纳合理描述性 kebab-case 名」。
- */
-export const SLUG_MAX_LENGTH = 35;
-
-/**
- * D-A2: AgentCallOpts → ExecuteOptions 映射。
- *
- * adapter 职责——SubagentService 的 ExecuteOptions 是稳定内部契约，不为 workflow 的
- * AgentCallOpts 做适配（映射归调用方 SAR）。
- *
- * 映射规则：
- *   prompt          → task
- *   description     → slug（≤35 字符，超长截断。缺失时回落 agent 名）
- *   agent           → agent
- *   schema          → schema
- *   schemaEnv       → schemaEnv（D-A6 bridge）
- *   cwd             → cwd
- *   model           → model（显式 override 透传，ctxModel 不再压扁为 id 填底）
- *   ctxModel        → ctxModel（完整 ModelInfo 对象透传，让 resolveModel 走第 3 层透明传递）
- *   skillPath       → skillPath
- *   thinkingLevel   → thinkingLevel（M1: 否则下游 subagent-service 读到 undefined）
- *   appendSystemPrompt → appendSystemPrompt（内容数组，同名同义透传）
- *   maxTurns        → maxTurns（turn limiter 上限；undefined = 不限，不挂 turns 估算 watchdog）
- *
- * 忽略字段（委托后由 executeAndAwait 内部机制替代）：
- *   timeoutMs         —— mergeTimeoutSignal 单独处理
- *   scene             —— subagents 不消费
- *
- * description 原先被忽略，现作为 slug 透传（ExecuteOptions.slug 必填）。
- */
-export function mapToExecuteOptions(
-  opts: AgentCallOpts,
-  ctxModel?: ModelInfo,
-): ExecuteOptions {
-  // slug：优先 description，缺失回落 agent 名（保证非空）。超长截断。
-  const rawSlug = opts.description ?? opts.agent ?? "workflow-agent";
-  return {
-    task: opts.prompt,
-    slug: rawSlug.length > SLUG_MAX_LENGTH ? rawSlug.slice(0, SLUG_MAX_LENGTH) : rawSlug,
-    agent: opts.agent,
-    schema: opts.schema,
-    schemaEnv: opts.schemaEnv,
-    cwd: opts.cwd,
-    fork: opts.fork,
-    worktree: opts.worktree,
-    model: opts.model,
-    ctxModel,
-    skillPath: opts.skillPath,
-    thinkingLevel: opts.thinkingLevel,
-    appendSystemPrompt: opts.appendSystemPrompt,
-    maxTurns: opts.maxTurns,
-  };
-}
-
-/**
- * D-A9: per-call timeoutMs 合并进 AbortSignal。
- *
- * 墙钟 timeoutMs（per-call）+ 外部 signal（run 级 abort）都生效。
- * 缺此合并则 agent({timeoutMs:5000}) 静默无效（BC-9）。
- *
- * @param signal    外部 signal（workflow run 级 controller.signal）
- * @param timeoutMs per-call 墙钟超时；undefined/<=0 → 不设超时，原样返回 signal
- * @returns 合并后的 signal（timeoutMs 或外部 signal 任一 abort 都触发）
- */
-export function mergeTimeoutSignal(
-  signal: AbortSignal,
-  timeoutMs?: number,
-): AbortSignal {
-  if (!timeoutMs || timeoutMs <= 0) {
-    return signal;
-  }
-
-  const controller = new AbortController();
-  // 超时 abort 带 reason 标记（对齐点④）：引擎合成终态时判别「宿主超时」
-  // （engine_timeout 公共合成）vs「外部 cancel」（中止标记）——pi 链路不读 reason，
-  // 行为不变。外部 signal abort 不带标记（用户/编排层 cancel 语义）。
-  const timer = setTimeout(() => controller.abort(HOST_TIMEOUT_ABORT_REASON), timeoutMs);
-  timer.unref();
-
-  const onExternalAbort = (): void => controller.abort();
-  if (signal.aborted) {
-    controller.abort();
-  } else {
-    signal.addEventListener("abort", onExternalAbort, { once: true });
-  }
-
-  controller.signal.addEventListener(
-    "abort",
-    () => {
-      clearTimeout(timer);
-      if (!signal.aborted) signal.removeEventListener("abort", onExternalAbort);
-    },
-    { once: true },
-  );
-
-  return controller.signal;
-}

package/src/shared/__tests__/resource-discovery-manifest-cache.test.ts

@@ -1,288 +0,0 @@
-// src/shared/__tests__/resource-discovery-manifest-cache.test.ts
-//
-// manifestCache 专项测试（swf-perf-impl cleanup IF1/DM1/TC1）。
-// readPackageManifestSync / async readPackageManifest 共享同一 Map：
-// - 命中：同 mtime 二次调用不重读（readFileSync 计数不增）
-// - 失效：package.json 重写（mtime 变）→ 重读
-// - 坏 JSON：不缓存（mtime 未变时二次调用仍重新 read）、不驱逐已有好条目
-//   （恢复原内容 + utimesSync 恢复原 mtime → 命中原条目，readFileSync 不增）
-// - stat 失败（文件删除）→ undefined 且条目驱逐（重建同内容同 mtime → 必重读）
-// - 双读者共享：sync 写入的条目被 async 命中（fs/promises readFile 零调用），反之亦然
-//
-// ESM 下 node:fs 命名空间不可直接 spyOn（resource-discovery.test.ts TC4a 注记），
-// 计数走 vi.mock 工厂包装（透传 actual 实现 + vi.fn 计数，行为零变化）。
-// mtime 控制用 utimesSync 定值（整数 ms），消除写入浮点 mtime 的精度/flake 面。
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import * as fsp from "node:fs/promises";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-// 隔离真实用户全局目录（homedir 推导 user-agents 源，同 resource-discovery.test.ts）
-vi.mock("node:os", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("node:os")>();
-  return { ...actual, homedir: () => "/nonexistent-home-for-tests" };
-});
-
-vi.mock("node:fs", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("node:fs")>();
-  return {
-    ...actual,
-    readFileSync: vi.fn(
-      (...args: Parameters<typeof actual.readFileSync>) => actual.readFileSync(...args),
-    ),
-    statSync: vi.fn(
-      (...args: Parameters<typeof actual.statSync>) => actual.statSync(...args),
-    ),
-  };
-});
-
-vi.mock("node:fs/promises", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("node:fs/promises")>();
-  return {
-    ...actual,
-    readFile: vi.fn(
-      (...args: Parameters<typeof actual.readFile>) => actual.readFile(...args),
-    ),
-  };
-});
-
-import { clearFileCache, discoverResources, readPackageManifestSync } from "../resource-discovery.ts";
-
-// ── helpers ──
-
-function tmpPkgDir(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), "manifest-cache-test-"));
-}
-
-function writePackageJson(pkgDir: string, pi: Record<string, unknown> | undefined): string {
-  fs.mkdirSync(pkgDir, { recursive: true });
-  const filePath = path.join(pkgDir, "package.json");
-  fs.writeFileSync(filePath, JSON.stringify({ name: "test-pkg", pi }), "utf-8");
-  return filePath;
-}
-
-/** 写原始（非 JSON）package.json 内容——坏 JSON 用例。 */
-function writeRawPackageJson(pkgDir: string, content: string): string {
-  fs.mkdirSync(pkgDir, { recursive: true });
-  const filePath = path.join(pkgDir, "package.json");
-  fs.writeFileSync(filePath, content, "utf-8");
-  return filePath;
-}
-
-/** 定值 mtime（整数 ms，消除浮点 mtime 与 utimesSync 恢复的精度差）。 */
-const T1 = new Date("2026-01-01T00:00:00Z");
-const T2 = new Date("2026-01-01T00:00:10Z");
-
-function setMtime(filePath: string, t: Date): void {
-  fs.utimesSync(filePath, t, t);
-}
-
-function readCount(): number {
-  return vi.mocked(fs.readFileSync).mock.calls.length;
-}
-
-/** node:fs/promises readFile 包装计数（异步读者）。 */
-function asyncReadCount(): number {
-  return vi.mocked(fsp.readFile).mock.calls.length;
-}
-
-// ============================================================
-// manifestCache（IF1）
-// ============================================================
-
-describe("manifestCache（readPackageManifestSync）", () => {
-  let pkgDir: string;
-  let pkgJson: string;
-
-  beforeEach(() => {
-    clearFileCache();
-    vi.mocked(fs.readFileSync).mockClear();
-    pkgDir = tmpPkgDir();
-  });
-  afterEach(() => {
-    fs.rmSync(pkgDir, { recursive: true, force: true });
-  });
-
-  it("命中：同 mtime 二次调用不重读（readFileSync 只调 1 次）", () => {
-    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
-    setMtime(pkgJson, T1);
-    const r1 = readPackageManifestSync(pkgDir, "agents");
-    expect(r1).toEqual(["./a.md"]);
-    expect(readCount()).toBe(1);
-    const r2 = readPackageManifestSync(pkgDir, "agents");
-    expect(r2).toEqual(["./a.md"]);
-    // 命中缓存：statSync 每次（判 mtime）但 readFileSync 不增
-    expect(readCount()).toBe(1);
-  });
-
-  it("kind 共享一次 parse：同 package.json 的 agents/workflows 两 kind 只读一次", () => {
-    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"], workflows: ["./w.js"] });
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
-    expect(readPackageManifestSync(pkgDir, "workflows")).toEqual(["./w.js"]);
-    expect(readCount()).toBe(1);
-  });
-
-  it("失效：package.json 重写（mtime 变）→ 重读新内容", () => {
-    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
-    writePackageJson(pkgDir, { agents: ["./b.md"] });
-    // 不需显式设 mtime：新写入的 mtime 必 ≠ 定值 T1
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./b.md"]);
-    expect(readCount()).toBe(2);
-  });
-
-  it("坏 JSON → undefined 且不缓存：mtime 未变时二次调用仍重新 read（计数递增）", () => {
-    // 起点即坏 JSON（无缓存条目）——若坏结果被缓存，二次调用不会重新 readFile。
-    // （good→bad 且 mtime 未变的场景由上一用例的命中路径覆盖：mtime 相等直接命中原好条目）
-    pkgJson = writeRawPackageJson(pkgDir, "{ broken json");
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
-    expect(readCount()).toBe(1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
-    expect(readCount()).toBe(2); // 二次调用仍重新 read = 坏结果未入缓存（毒条目永不入缓存）
-  });
-
-  it("坏 JSON 不驱逐已有好条目：恢复原内容 + 恢复原 mtime → 命中原条目（readFileSync 不增）", () => {
-    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
-    expect(readCount()).toBe(1);
-    // 改坏且 mtime 变（T2）→ undefined（read 失败路径，不驱逐 {T1, pi} 好条目）
-    fs.writeFileSync(pkgJson, "{ broken", "utf-8");
-    setMtime(pkgJson, T2);
-    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
-    expect(readCount()).toBe(2);
-    // 恢复原内容 + utimesSync 恢复原 mtime → 若好条目仍在则命中（不重 read）
-    writePackageJson(pkgDir, { agents: ["./a.md"] });
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
-    expect(readCount()).toBe(2); // 无第 3 次 read = 命中保留的原条目
-  });
-
-  it("stat 失败（文件删除）→ undefined 且条目驱逐（重建同内容同 mtime → 必重读）", () => {
-    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
-    expect(readCount()).toBe(1);
-    fs.rmSync(pkgJson);
-    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
-    expect(readCount()).toBe(1); // stat 失败路径不触发 read
-    // 重建同内容 + 恢复同 mtime：条目已被驱逐 → 必重 read（计数 +1）
-    writePackageJson(pkgDir, { agents: ["./a.md"] });
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
-    expect(readCount()).toBe(2);
-  });
-
-  it("无 pi 字段（合法解析结果）也缓存：二次调用不重读", () => {
-    pkgJson = writePackageJson(pkgDir, undefined);
-    setMtime(pkgJson, T1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
-    expect(readCount()).toBe(1);
-    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
-    expect(readCount()).toBe(1);
-  });
-
-  // [review 修复] 非对象 JSON 结构守卫：JSON.parse 对 "42" / '"str"' / "null" 等
-  // 合法 JSON 产出非对象值，旧 `as Record<string, unknown>` 盲断言下 .pi 访问
-  // 「碰巧不抛」（primitive 装箱返 undefined / null 抛 TypeError 落 catch）——
-  // 显式守卫后按「无 manifest」（undefined）处理，行为等价但不再依赖巧合。
-  it("非对象 JSON（42 / null / string / pi 字段非对象或数组）→ undefined 不抛，按合法解析结果缓存", () => {
-    const cases: Array<{ raw: string; label: string }> = [
-      { raw: "42", label: "number" },
-      { raw: "null", label: "null" },
-      { raw: '"just-a-string"', label: "string" },
-      { raw: '{"name":"p","pi":42}', label: "pi-field-not-object" },
-      // [review 修复] 数组能骗过 typeof "object" 守卫（装箱对象）——非合法 pi 容器，
-      // 显式归 undefined（语义上仍是「无 manifest」，与数组 entries 读出 undefined 一致）
-      { raw: '{"name":"p","pi":[]}', label: "pi-field-array" },
-    ];
-    // 每 case 独立子目录（缓存 key = package.json 绝对路径），互不命中；
-    // readCount 是跨 case 累积计数，断言用本 case 增量
-    for (const { raw, label } of cases) {
-      const before = readCount();
-      const caseDir = path.join(pkgDir, label);
-      pkgJson = writeRawPackageJson(caseDir, raw);
-      setMtime(pkgJson, T1);
-      expect(readPackageManifestSync(caseDir, "agents"), `case ${label}`).toBeUndefined();
-      expect(readPackageManifestSync(caseDir, "workflows"), `case ${label}`).toBeUndefined();
-      // 合法解析 + 无 manifest → 缓存 undefined 条目（同「无 pi 字段」语义，二次调用不重读）
-      expect(readCount() - before, `case ${label}`).toBe(1);
-    }
-  });
-});
-
-// ============================================================
-// 双读者共享（async readPackageManifest ↔ sync 共享同一 Map）
-// ============================================================
-
-describe("manifestCache 双读者共享（async ↔ sync）", () => {
-  let ws: string;
-  let pkgDir: string;
-  let savedEnv: string | undefined;
-
-  beforeEach(() => {
-    clearFileCache();
-    vi.mocked(fs.readFileSync).mockClear();
-    vi.mocked(fsp.readFile).mockClear();
-    ws = tmpPkgDir();
-    pkgDir = path.join(ws, "my-ext");
-    savedEnv = process.env.XYZ_EXTENSION_PATHS;
-  });
-  afterEach(() => {
-    if (savedEnv === undefined) delete process.env.XYZ_EXTENSION_PATHS;
-    else process.env.XYZ_EXTENSION_PATHS = savedEnv;
-    fs.rmSync(ws, { recursive: true, force: true });
-  });
-
-  it("sync 写入的条目被 async 命中：discoverResources 零 fs/promises readFile", async () => {
-    const pkgJson = writePackageJson(pkgDir, { agents: ["./agents"] });
-    fs.mkdirSync(path.join(pkgDir, "agents"), { recursive: true });
-    fs.writeFileSync(path.join(pkgDir, "agents", "a.md"), "body", "utf-8");
-    setMtime(pkgJson, T1);
-    // sync 读者先填充缓存
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./agents"]);
-    expect(readCount()).toBe(1);
-    // async 读者（XYZ_EXTENSION_PATHS → processPackage → readPackageManifest）应命中共享条目
-    process.env.XYZ_EXTENSION_PATHS = pkgDir;
-    const result = await discoverResources({
-      kind: "agents",
-      workspaceRoot: ws,
-      hostRoots: [
-        { dir: path.join(ws, ".fake-agent", "agents"), source: "user-pi" },
-        { dir: path.join(ws, ".fake-agent", "npm", "node_modules"), source: "npm" },
-        { dir: path.join(ws, ".fake-agent", "extensions"), source: "npm-dev" },
-      ],
-    });
-    const ext = result.filter((r) => r.source === "user-extension-paths");
-    expect(ext.map((r) => path.basename(r.path))).toEqual(["a.md"]);
-    expect(asyncReadCount()).toBe(0); // async readFile 未被调用 = 命中共享缓存
-    expect(readCount()).toBe(1); // sync 侧无新增 read
-  });
-
-  it("async 写入的条目被 sync 命中：async 读后 sync 不再 readFileSync", async () => {
-    const pkgJson = writePackageJson(pkgDir, { agents: ["./agents"] });
-    fs.mkdirSync(path.join(pkgDir, "agents"), { recursive: true });
-    fs.writeFileSync(path.join(pkgDir, "agents", "a.md"), "body", "utf-8");
-    setMtime(pkgJson, T1);
-    process.env.XYZ_EXTENSION_PATHS = pkgDir;
-    await discoverResources({
-      kind: "agents",
-      workspaceRoot: ws,
-      hostRoots: [
-        { dir: path.join(ws, ".fake-agent", "agents"), source: "user-pi" },
-        { dir: path.join(ws, ".fake-agent", "npm", "node_modules"), source: "npm" },
-        { dir: path.join(ws, ".fake-agent", "extensions"), source: "npm-dev" },
-      ],
-    });
-    expect(asyncReadCount()).toBe(1); // async 读者读了一次
-    // sync 读者应命中 async 写入的条目（readFileSync 计数不变）
-    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./agents"]);
-    expect(readCount()).toBe(0);
-  });
-});