@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/shared/atomic-write.ts

@@ -1,11 +1,13 @@
 /**
  * 原子写原语（sink 设计 U6a / B6）：tmp+rename 的单一实现。
  *
- * 背景：core 内部散布 6-7 份 tmp+rename 写点（manifest-store / sessions-index /
+ * 背景：core 内部曾散布 6-7 份 tmp+rename 写点（manifest-store / sessions-index /
  * worktree-registry / engine-discovery / zcode preparer / zcode appserver-home），
  * tmp 命名各异（`.tmp.<pid>` / `.tmp_<pid>_<rand>` / `.tmp-<pid>-<ts>`）、失败路径
  * 清理纪律不齐（worktree-registry 失败时漏清残留 tmp）。本模块给出统一原语供全
- * 部写点收敛（调用点迁移归 u-wire 单元，本单元只建原语）。
+ * 部写点收敛（调用点迁移归 u-wire 单元，本单元只建原语）。现存消费方 4 处：
+ * manifest-store / sessions-index / worktree-registry / engine-discovery——zcode
+ * preparer 与 zcode appserver-home 两处写点已随 2026-09 共享宿主 HOME 重构删除。
  *
  * **统一 tmp 命名约定**：`<最终路径>.tmp.<pid>.<seq>-<rand>`。
  * - `.tmp.` 标记向后兼容 manifest-store 既有扫描（`x.json` 的 tmp 名为
@@ -21,8 +23,8 @@
  *
  * **两种耐久档位**（对齐现存两族写点的生产模式）：
  * - sync（writeAtomicFileSync）：writeFileSync + renameSync，无 fsync——对齐
- *   worktree-registry / engine-discovery / zcode preparer / appserver-home 四处
- *   同步写点现状（prep/注册表类，进程崩溃窗口可容忍）；
+ *   worktree-registry / engine-discovery 两处同步写点现状（注册表/发现缓存类，
+ *   进程崩溃窗口可容忍）；
  * - async（writeAtomicFile）：fsync 文件 → rename → 尽力 fsync 目录——对齐
  *   manifest-store / sessions-index 的生产耐久模式（掉电也不丢已确认写入）。
  */
@@ -32,6 +34,7 @@ import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
 
 import { getLogger } from "../core/logger.ts";
+import { toErrorMessage } from "../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -111,7 +114,7 @@ function removeTmpBestEffortSync(tmpPath: string): void {
   } catch (cleanupErr) {
     // tmp 可能已被 rename 消费或从未创建；原错误由调用方上抛
     logger.debug("[subagent-core] atomic-write cleanup tmp failed", {
-      detail: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
+      detail: toErrorMessage(cleanupErr),
       tmpPath,
     });
   }
@@ -188,7 +191,7 @@ export async function writeAtomicFile(
         }
       } catch (dirSyncErr) {
         logger.debug("[subagent-core] atomic-write fsync dir failed", {
-          detail: dirSyncErr instanceof Error ? dirSyncErr.message : String(dirSyncErr),
+          detail: toErrorMessage(dirSyncErr),
           dirPath,
         });
       }
@@ -200,7 +203,7 @@ export async function writeAtomicFile(
         await fsPromises.unlink(tmpPath);
       } catch (cleanupErr) {
         logger.debug("[subagent-core] atomic-write cleanup tmp failed", {
-          detail: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
+          detail: toErrorMessage(cleanupErr),
           tmpPath,
         });
       }
@@ -293,7 +296,7 @@ export function cleanupStaleTmpFiles(
           continue;
         }
         logger.debug("[subagent-core] cleanupStaleTmpFiles stat failed", {
-          detail: statErr instanceof Error ? statErr.message : String(statErr),
+          detail: toErrorMessage(statErr),
           tmpPath: ref.tmpPath,
         });
         result.failed.push(ref.tmpPath);
@@ -309,7 +312,7 @@ export function cleanupStaleTmpFiles(
         result.removed.push(ref.tmpPath);
       } else {
         logger.debug("[subagent-core] cleanupStaleTmpFiles unlink failed", {
-          detail: unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr),
+          detail: toErrorMessage(unlinkErr),
           tmpPath: ref.tmpPath,
         });
         result.failed.push(ref.tmpPath);

package/src/shared/meta-parser.ts

@@ -75,6 +75,10 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
  * 把 parseYaml 结果（unknown）校验为类型化 ResourceMeta，失败返 null（语义非法，非语法错）。
  * 严格化（exec-review minor-2..5）：kind 专属字段不可串类、description 必填、
  * phase detail 非字符串/parameters 非对象均 reject（消除「静默丢弃非法字段」）。
+ *
+ * 结构（行为保持提取，主函数只留公共校验 + kind 分派；各分支校验顺序不可调换）：
+ * workflow → typecheckWorkflowMeta（串类 → phases → parameters）；
+ * agent → typecheckAgentMeta（串类 → examples → tools → model/engine → maxTurns → disallowedTools → skills）。
  */
 function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
   if (!isPlainObject(raw)) return null;
@@ -87,99 +91,140 @@ function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
   const notFor = isString(o.notFor) ? o.notFor : undefined;
 
   if (kind === "workflow") {
-    // minor-2：agent 专属字段不可出现在 workflow（串类 reject）
-    if (
-      o.examples !== undefined || o.tools !== undefined || o.model !== undefined
-      || o.engine !== undefined || o.maxTurns !== undefined
-      || o.disallowedTools !== undefined || o.skills !== undefined
-    ) {
-      return null;
-    }
-    // phases 必填数组，元素为 string | {title:string, detail?:string}
-    if (!Array.isArray(o.phases)) return null;
-    const phases: WorkflowMeta["phases"] = [];
-    for (const p of o.phases) {
-      if (isString(p)) {
-        phases.push(p);
-      } else if (isPlainObject(p) && isNonEmptyString(p.title)) {
-        // minor-4：detail 存在但非字符串 → reject（不再静默丢弃）
-        if (p.detail !== undefined && !isString(p.detail)) return null;
-        phases.push(isString(p.detail) ? { title: p.title, detail: p.detail } : { title: p.title });
-      } else {
-        return null;
-      }
-    }
-    // minor-5：parameters 存在但非 plain object → reject（不再静默当 undefined）
-    const parameters = o.parameters;
-    if (parameters !== undefined && !isPlainObject(parameters)) return null;
-    const usage = isString(o.usage) ? o.usage : undefined;
-
-    const meta: WorkflowMeta = {
-      kind: "workflow",
-      name: o.name,
-      description: o.description,
-      phases,
-      ...(parameters !== undefined ? { parameters: parameters as Record<string, unknown> } : {}),
-      ...(usage !== undefined ? { usage } : {}),
-      ...(when !== undefined ? { when } : {}),
-      ...(notFor !== undefined ? { notFor } : {}),
-    };
-    return meta;
+    return typecheckWorkflowMeta(o, o.name, o.description, when, notFor);
   }
+  return typecheckAgentMeta(o, o.name, o.description, when, notFor);
+}
 
-  // kind === "agent"
-  // minor-2：workflow 专属字段不可出现在 agent（串类 reject）
-  if (o.phases !== undefined || o.parameters !== undefined || o.usage !== undefined) return null;
-  let examples: RoutingExample[] | undefined;
-  if (o.examples !== undefined) {
-    if (!Array.isArray(o.examples)) return null;
-    const exs: RoutingExample[] = [];
-    for (const e of o.examples) {
-      if (
-        isPlainObject(e) &&
-        isString(e.match) &&
-        isString(e.action) &&
-        typeof e.positive === "boolean"
-      ) {
-        exs.push({ match: e.match, action: e.action, positive: e.positive });
-      } else {
-        return null;
-      }
+/** minor-2 串类守卫（workflow 分支）：agent 专属字段任一出现 → reject。 */
+function hasAgentOnlyFields(o: Record<string, unknown>): boolean {
+  return (
+    o.examples !== undefined || o.tools !== undefined || o.model !== undefined
+    || o.engine !== undefined || o.maxTurns !== undefined
+    || o.disallowedTools !== undefined || o.skills !== undefined
+  );
+}
+
+/** minor-2 串类守卫（agent 分支）：workflow 专属字段任一出现 → reject。 */
+function hasWorkflowOnlyFields(o: Record<string, unknown>): boolean {
+  return o.phases !== undefined || o.parameters !== undefined || o.usage !== undefined;
+}
+
+/**
+ * phases 元素校验（string | {title:string, detail?:string}）：合法元素逐个投影，
+ * 任一非法 → null。
+ * minor-4：detail 存在但非字符串 → reject（不再静默丢弃）。
+ */
+function typecheckPhases(rawPhases: unknown[]): WorkflowMeta["phases"] | null {
+  const phases: WorkflowMeta["phases"] = [];
+  for (const p of rawPhases) {
+    if (isString(p)) {
+      phases.push(p);
+    } else if (isPlainObject(p) && isNonEmptyString(p.title)) {
+      if (p.detail !== undefined && !isString(p.detail)) return null;
+      phases.push(isString(p.detail) ? { title: p.title, detail: p.detail } : { title: p.title });
+    } else {
+      return null;
     }
-    examples = exs;
   }
-  let tools: string[] | undefined;
-  if (o.tools !== undefined) {
-    if (Array.isArray(o.tools)) {
-      if (!o.tools.every(isString)) return null;
-      tools = o.tools as string[];
-    } else if (isString(o.tools)) {
-      // 兼容 agent .md 的逗号分隔字符串约定（如 `tools: read, bash, grep`）
-      const parts = o.tools.split(",").map((s) => s.trim()).filter(Boolean);
-      tools = parts.length > 0 ? parts : undefined;
+  return phases;
+}
+
+/** workflow meta 组装（校验全过后的纯投影——可选字段缺席不进键）。 */
+function buildWorkflowMeta(
+  name: string,
+  description: string,
+  phases: WorkflowMeta["phases"],
+  parameters: Record<string, unknown> | undefined,
+  usage: string | undefined,
+  when: string | undefined,
+  notFor: string | undefined,
+): WorkflowMeta {
+  return {
+    kind: "workflow",
+    name,
+    description,
+    phases,
+    ...(parameters !== undefined ? { parameters } : {}),
+    ...(usage !== undefined ? { usage } : {}),
+    ...(when !== undefined ? { when } : {}),
+    ...(notFor !== undefined ? { notFor } : {}),
+  };
+}
+
+/** workflow 分支校验（顺序 = 串类 → phases → parameters；usage 宽容投影）。 */
+function typecheckWorkflowMeta(
+  o: Record<string, unknown>,
+  name: string,
+  description: string,
+  when: string | undefined,
+  notFor: string | undefined,
+): WorkflowMeta | null {
+  // minor-2：agent 专属字段不可出现在 workflow（串类 reject）
+  if (hasAgentOnlyFields(o)) return null;
+  // phases 必填数组，元素为 string | {title:string, detail?:string}
+  const rawPhases = o.phases;
+  if (!Array.isArray(rawPhases)) return null;
+  const phases = typecheckPhases(rawPhases);
+  if (phases === null) return null;
+  // minor-5：parameters 存在但非 plain object → reject（不再静默当 undefined）
+  const parameters = o.parameters;
+  if (parameters !== undefined && !isPlainObject(parameters)) return null;
+  const usage = isString(o.usage) ? o.usage : undefined;
+  return buildWorkflowMeta(name, description, phases, parameters, usage, when, notFor);
+}
+
+/**
+ * examples 校验三态：undefined → 缺席（不进 meta）；非数组 → null；
+ * 元素须为 {match: string, action: string, positive: boolean}，任一非法 → null。
+ */
+function typecheckExamples(raw: unknown): RoutingExample[] | null | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) return null;
+  const exs: RoutingExample[] = [];
+  for (const e of raw) {
+    if (
+      isPlainObject(e) &&
+      isString(e.match) &&
+      isString(e.action) &&
+      typeof e.positive === "boolean"
+    ) {
+      exs.push({ match: e.match, action: e.action, positive: e.positive });
     } else {
       return null;
     }
   }
-  const model = isString(o.model) ? o.model : undefined;
-  const engine = isString(o.engine) ? o.engine : undefined;
-  // D3 可选执行字段（maxTurns/disallowedTools/skills）：与 tools 同风格投影
-  // （空数组 [] 同 tools 保留键——列表字段族空列表语义一致）。严格层对非法类型
-  // reject（minor-2..5 既有精神：不静默丢弃非法字段）——宽容降级是
-  // parseAgentProfile（agent-registry）的职责，不在本严格层。
-  if (o.maxTurns !== undefined && (typeof o.maxTurns !== "number" || !Number.isFinite(o.maxTurns))) {
-    return null;
-  }
-  const maxTurns = typeof o.maxTurns === "number" ? o.maxTurns : undefined;
-  const disallowedTools = parseStringListField(o.disallowedTools);
-  if (disallowedTools === null) return null;
-  const skills = parseStringListField(o.skills);
-  if (skills === null) return null;
+  return exs;
+}
+
+/**
+ * maxTurns 校验三态：undefined → 缺席；非 number 或非有限值（NaN/Infinity）→ null；
+ * 合法 number 原样投影。
+ */
+function typecheckMaxTurns(raw: unknown): number | null | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return null;
+  return raw;
+}
 
-  const meta: AgentMeta = {
+/** agent meta 组装（校验全过后的纯投影——可选字段缺席不进键）。 */
+function buildAgentMeta(
+  name: string,
+  description: string,
+  examples: RoutingExample[] | undefined,
+  tools: string[] | undefined,
+  model: string | undefined,
+  engine: string | undefined,
+  maxTurns: number | undefined,
+  disallowedTools: string[] | undefined,
+  skills: string[] | undefined,
+  when: string | undefined,
+  notFor: string | undefined,
+): AgentMeta {
+  return {
     kind: "agent",
-    name: o.name,
-    description: o.description,
+    name,
+    description,
     ...(examples !== undefined ? { examples } : {}),
     ...(tools !== undefined ? { tools } : {}),
     ...(model !== undefined ? { model } : {}),
@@ -190,7 +235,36 @@ function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
     ...(when !== undefined ? { when } : {}),
     ...(notFor !== undefined ? { notFor } : {}),
   };
-  return meta;
+}
+
+/** agent 分支校验（顺序 = 串类 → examples → tools → model/engine → maxTurns → disallowedTools → skills）。 */
+function typecheckAgentMeta(
+  o: Record<string, unknown>,
+  name: string,
+  description: string,
+  when: string | undefined,
+  notFor: string | undefined,
+): AgentMeta | null {
+  // minor-2：workflow 专属字段不可出现在 agent（串类 reject）
+  if (hasWorkflowOnlyFields(o)) return null;
+  const examples = typecheckExamples(o.examples);
+  if (examples === null) return null;
+  // tools 三态经 parseStringListField（数组逐元素 string / 逗号分隔字符串 / 非法形态 → null）
+  const tools = parseStringListField(o.tools);
+  if (tools === null) return null;
+  const model = isString(o.model) ? o.model : undefined;
+  const engine = isString(o.engine) ? o.engine : undefined;
+  // D3 可选执行字段（maxTurns/disallowedTools/skills）：与 tools 同风格投影
+  // （空数组 [] 同 tools 保留键——列表字段族空列表语义一致）。严格层对非法类型
+  // reject（minor-2..5 既有精神：不静默丢弃非法字段）——宽容降级是
+  // parseAgentProfile（agent-registry）的职责，不在本严格层。
+  const maxTurns = typecheckMaxTurns(o.maxTurns);
+  if (maxTurns === null) return null;
+  const disallowedTools = parseStringListField(o.disallowedTools);
+  if (disallowedTools === null) return null;
+  const skills = parseStringListField(o.skills);
+  if (skills === null) return null;
+  return buildAgentMeta(name, description, examples, tools, model, engine, maxTurns, disallowedTools, skills, when, notFor);
 }
 
 /**

package/src/shared/model-ref.ts

@@ -188,6 +188,16 @@ function findSimilarSuggestions(
     .slice(0, MODEL_LIST_LIMIT);
 }
 
+/**
+ * [u-h2 D2-4] notFoundError 的结构化标记：编排层（pi 未命中跨引擎反查）据此区分
+ * 「pi registry 未命中」与孪生歧义/auth 等其他裁决失败——只有未命中形态做反查。
+ */
+interface NotFoundMarker {
+  refNotFound: true;
+  /** 裁决的原始输入串（strip thinking 后缀前的原样值），跨引擎反查的匹配源。 */
+  refInput: string;
+}
+
 /** 规则⑤未命中错误：问句候选 + 合法串全集（无候选时）+ 继承指引。 */
 function notFoundError(
   input: string,
@@ -195,7 +205,7 @@ function notFoundError(
   provider: string,
   id: string,
   source: ModelRefSource,
-): Error {
+): Error & NotFoundMarker {
   const lines = [
     `Model "${input}"${prefix} is not a registry entry. ` +
       `Registry match is case-sensitive — the string must equal a registry entry exactly, including letter case.`,
@@ -230,7 +240,10 @@ function notFoundError(
   }
 
   lines.push(`Or omit the \`model\` param to inherit the main agent model.`);
-  return new Error(lines.join("\n"));
+  const err = new Error(lines.join("\n")) as Error & NotFoundMarker;
+  err.refNotFound = true;
+  err.refInput = input;
+  return err;
 }
 
 // ============================================================

package/src/shared/resource-discovery.ts

@@ -132,8 +132,8 @@ function isDirectChildOfWorkspaceRoot(dir: string, workspaceRoot: string): boole
 // ── 统一 mtime 缓存层（m5 IF10）────────────────────────────────────
 //
 // 模块级 Map<path, { mtimeMs, content }>：mtime 判变缓存文件内容。
-// - sync 实现（statSync/readFileSync）：agent-registry discoverAll 是同步路径，
-//   async 缓存无法被 await（m5 design-review A1 探针实证约束）
+// - sync 实现（statSync/readFileSync）：getCachedFile 同步返回，供 async 发现流程
+//   与 agent-registry loadByPath 在流程内同步读缓存
 // - stat 失败/ENOENT → 驱逐条目（mtime 缓存下文件删除不自愈——A3 修复）
 // - 已知局限（C3 记录）：内容变 mtime 未变（cp -p/rsync -t 保留源 mtime、
 //   2s 粒度文件系统）→ 漏判，invalidateCache/clearFileCache 兜底；
@@ -383,7 +383,7 @@ async function scanDirectory(dirPath: string, kind: ResourceKind): Promise<strin
 /**
  * 读取 package.json 的 pi.{kind} manifest（pi.agents / pi.workflows）。
  * 返回 undefined 表示无 manifest 声明（无 pi / pi[kind] 非数组 / 解析失败）。
- * 内部走 manifestCache（与 readPackageManifestSync 共享同一 Map，失败语义见声明处）。
+ * 内部走 manifestCache（失败语义见声明处）。
  */
 async function readPackageManifest(pkgDir: string, kind: ResourceKind): Promise<string[] | undefined> {
   const pkgJsonPath = resolve(pkgDir, "package.json");
@@ -477,9 +477,9 @@ async function scanNpmDir(
   }
 
   // [perf] 包级并行（swf-perf-impl cleanup TC2/IF2）：entries.map + Promise.all，
-  // perEntry.flat() 按原 readdir 序 concat——输出序与串行逐包 push 等价。
+  // perEntry.flat() 按原 readdir 序 concat——输出序与 readdir 包序一致。
   // 不加新增 catch：每包失败面由 processPackage 内部既有 catch 承担，未捕获异常
-  // 传播语义与串行版一致（Promise.all 整体 reject ↔ 串行版向上抛）。
+  // 经 Promise.all 以首个 reject 整体向上抛。
   const perEntry = await Promise.all(
     entries.map(async (entry): Promise<DiscoveredResource[]> => {
       const entryPath = resolve(nodeModulesDir, entry);
@@ -624,7 +624,7 @@ function buildScanTargets(config: ScanConfig): ScanTarget[] {
  * 原 path，属预期失败不抛。
  *
  * Throws on unrecoverable scan errors——未捕获异常向上抛（Promise.all 首个 reject
- * 即整体拒绝，与串行版 discoverResourcesSync 的传播语义一致，见实现内 [perf] 注释）。
+ * 即整体拒绝，见实现内 [perf] 注释）。
  * 预期失败不抛：目录不存在/不可读返回空列表，manifest 声明路径缺失以 available=false 返回。
  *
  * @returns 去重后的资源列表（按优先级合并，高优先级覆盖低优先级同名）
@@ -634,11 +634,10 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
 
   // [perf] 源级并行（swf-perf-impl cleanup TC2/IF2）：targets.map + Promise.all，
   // Promise.all 对 map 数组保序——allBySource 顺序 = targets 优先级序（低→高），
-  // 与串行逐源 push 完全一致 → 下方合并去重逻辑零改动、输出逐字节等价。
+  // 下方合并去重按该顺序 last-writer-wins。
   // 不加新增 catch：每源预期失败路径由内部既有 catch 面承担（scanDirectory access
-  // catch / scanNpmDir readdir catch / processPackage 全链 catch），未捕获异常
-  // 传播语义与串行版等价（ES2：串行版 target k 抛错中断后续源，并行版全部源已并发
-  // 启动、以首个 reject 拒绝——两版对调用方同为 discoverResources 抛出，各源只读无副作用）。
+  // catch / scanNpmDir readdir catch / processPackage 全链 catch）；未捕获异常经
+  // Promise.all 以首个 reject 整体向上拒绝（各源只读无副作用）。
   const allBySource: Array<{ source: ResourceSource; resources: DiscoveredResource[] }> = await Promise.all(
     targets.map(async (target) => {
       if (target.source === "npm" || target.source === "npm-dev") {
@@ -727,176 +726,3 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
   return Array.from(merged.values());
 }
 
-/**
- * 同步版：扫描单个目录下的资源文件路径。
- *
- * 消费关系（W2⑤ 漂移修正）：当前无非测试调用方——agent-registry 只 import
- * getCachedFile（mtime 缓存），不消费 sync 扫描。保留作 async scanDirectory 的
- * 对称 API / 测试用；生产 agent/workflow 发现统一走 async discoverResources
- * （红线 4：修对生产面）。npm/dev 包内发现仍需 async（scanNpmDir）。
- */
-export function scanDirectorySync(dirPath: string, kind: ResourceKind): string[] {
-  try {
-    fsSync.accessSync(dirPath);
-  } catch {
-    return [];
-  }
-
-  let entries: string[];
-  try {
-    entries = fsSync.readdirSync(dirPath);
-  } catch {
-    return [];
-  }
-
-  const files: string[] = [];
-  for (const entry of entries) {
-    if (!isTargetFile(entry, kind)) continue;
-    files.push(resolve(dirPath, entry));
-  }
-  return files;
-}
-
-/**
- * 同步版：读取 package.json 的 pi.{kind} manifest。
- * 当前无非测试调用方（W2⑤ 漂移修正，保留作对称 API/测试用）。与 async 版
- * 共享 manifestCache（双读者同一 Map）。
- */
-export function readPackageManifestSync(pkgDir: string, kind: ResourceKind): string[] | undefined {
-  const pkgJsonPath = resolve(pkgDir, "package.json");
-  let mtimeMs: number;
-  try {
-    mtimeMs = fsSync.statSync(pkgJsonPath).mtimeMs;
-  } catch {
-    // stat 失败：文件不存在/不可 stat → 驱逐条目（对齐 getCachedFile 语义）
-    manifestCache.delete(pkgJsonPath);
-    return undefined;
-  }
-  const entry = manifestCache.get(pkgJsonPath);
-  if (entry && entry.mtimeMs === mtimeMs) return piToManifest(entry.pi, kind);
-  let pi: Record<string, unknown> | undefined;
-  try {
-    const content = fsSync.readFileSync(pkgJsonPath, "utf-8");
-    pi = parsePiField(content);
-  } catch {
-    // read 失败或坏 JSON → 不缓存不驱逐已有好条目，下次调用重试
-    return undefined;
-  }
-  manifestCache.set(pkgJsonPath, { mtimeMs, pi });
-  return piToManifest(pi, kind);
-}
-
-/**
- * 同步版：处理单个 npm/dev 包。
- * 当前无非测试调用方（W2⑤ 漂移修正，保留作对称 API/测试用）。
- */
-export function processPackageSync(pkgDir: string, kind: ResourceKind): DiscoveredResource[] {
-  const manifestPaths = readPackageManifestSync(pkgDir, kind);
-
-  if (manifestPaths && manifestPaths.length > 0) {
-    const results: DiscoveredResource[] = [];
-
-    for (const relPath of manifestPaths) {
-      const absPath = resolve(pkgDir, relPath);
-      let fileStat: fsSync.Stats | null;
-      try {
-        fileStat = fsSync.statSync(absPath);
-      } catch {
-        fileStat = null;
-      }
-      if (!fileStat) {
-        results.push({ path: absPath, source: "npm", available: false });
-        continue;
-      }
-
-      if (fileStat.isDirectory()) {
-        const files = scanDirectorySync(absPath, kind);
-        for (const f of files) {
-          results.push({ path: f, source: "npm", available: true });
-        }
-      } else if (fileStat.isFile()) {
-        results.push({ path: absPath, source: "npm", available: true });
-      }
-    }
-
-    return results;
-  }
-
-  // 无 manifest：扫约定目录
-  const conventionDir = resolve(pkgDir, kind);
-  const files = scanDirectorySync(conventionDir, kind);
-  return files.map((f) => ({ path: f, source: "npm", available: true }));
-}
-
-/**
- * 同步版：扫描 npm node_modules 目录。
- * 当前无非测试调用方（W2⑤ 漂移修正，保留作对称 API/测试用）。
- */
-export function scanNpmDirSync(nodeModulesDir: string, kind: ResourceKind): DiscoveredResource[] {
-  let entries: string[];
-  try {
-    entries = fsSync.readdirSync(nodeModulesDir);
-  } catch {
-    return [];
-  }
-
-  const results: DiscoveredResource[] = [];
-  for (const entry of entries) {
-    const entryPath = resolve(nodeModulesDir, entry);
-
-    if (entry.startsWith("@")) {
-      let scopedEntries: string[];
-      try {
-        scopedEntries = fsSync.readdirSync(entryPath);
-      } catch {
-        continue;
-      }
-      for (const scopedPkg of scopedEntries) {
-        const scopedPkgDir = resolve(entryPath, scopedPkg);
-        results.push(...processPackageSync(scopedPkgDir, kind));
-      }
-    } else {
-      results.push(...processPackageSync(entryPath, kind));
-    }
-  }
-  return results;
-}
-
-/**
- * 同步版：发现所有资源。
- *
- * 当前无非测试调用方（W2⑤ 漂移修正：agent-registry 只 import getCachedFile，
- * 不消费本族；保留作 async discoverResources 的对照实现/测试用——两版输出等价
- * 由既有快照用例锁定）。
- *
- * 与 discoverResources 对应的同步实现，扫描相同的源，同 stem last-writer-wins
- * 合并（不含 async 链的 realpath 去重——sync 链无非测试调用方，勿扩面，红线 4）。
- */
-export function discoverResourcesSync(config: ScanConfig): DiscoveredResource[] {
-  const targets = buildScanTargets(config);
-  const all: DiscoveredResource[] = [];
-
-  for (const target of targets) {
-    if (target.source === "npm" || target.source === "npm-dev") {
-      const resources = scanNpmDirSync(target.dir, config.kind);
-      all.push(...resources.map((r) => ({ ...r, source: target.source })));
-    } else if (target.source === "user-extension-paths") {
-      // XYZ_EXTENSION_PATHS（dev-link）：每个 dir 是单个包目录
-      const resources = processPackageSync(target.dir, config.kind);
-      all.push(...resources.map((r) => ({ ...r, source: target.source })));
-    } else {
-      const files = scanDirectorySync(target.dir, config.kind);
-      all.push(...files.map((f) => ({ path: f, source: target.source, available: true })));
-    }
-  }
-
-  // 按优先级合并（targets 顺序 = 优先级低→高）
-  const merged = new Map<string, DiscoveredResource>();
-  for (const r of all) {
-    const key = stem(r.path);
-    if (!r.available && merged.has(key)) continue;
-    merged.set(key, r);
-  }
-
-  return Array.from(merged.values());
-}

package/src/shared/schema-jsonify.ts

@@ -3,7 +3,7 @@
  *
  * 同一 schema 对象引用的重复 JSON.stringify 消除：resolver（compact，instruction
  * 与 schemaEnv 复用同串，formatSchemaInstruction 现居 resolver）在单次 agent call
- * 内对同一 schema 对象各 stringify 一次；error-recovery 重试路径再加一次。本
+ * 内对同一 schema 对象各 stringify 一次；worker-message-pump 重试路径再加一次。本
  * helper 用 WeakMap 按对象引用缓存两种格式，命中返回缓存串。
  *
  * 返回值与直接 JSON.stringify 逐字节一致（compact = JSON.stringify(x)、