@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/engine/engine-manifest.ts

@@ -0,0 +1,244 @@
+// src/execution/engine/engine-manifest.ts
+//
+// [W4] 引擎包 manifest 字段级解析（package.json `xyz-agent.subagentEngine` 段）。
+// 设计权威源：docs/design/subagent-engine-protocolization.md §3.4 + impl-plan §2.4。
+//
+// 自 engine-discovery-scan.ts 拆出（max-lines 纪律）：manifest 解析是纯「unknown →
+// 强类型」的字段级校验域，与发现主链（搜索路径/装载）无状态耦合；warn 经 core log
+// facade 落宿主日志。字段级契约速览：
+//   id / bin / protocol 必需；capabilities 必需（缺键保守值 + warn；未知键忽略 + warn）；
+//   envPrefixes 可选（非法条目丢弃该前缀 + warn，包仍可用）；modelCatalog 可选
+//   （缺省 = 不注入，三态语义见 parseModelCatalog）；displayName/description 可选。
+
+import * as path from "node:path";
+
+import type { ModelCatalogEntry } from "@zhushanwen/subagent-engine-sdk";
+
+import { getLogger } from "../../core/logger.ts";
+import type { EngineCapabilities } from "./types.ts";
+
+const logger = getLogger("subagents");
+
+/** 引擎 env 放行前缀的保留字（§2.4/§2.12 L2：引擎 manifest 不得声明宿主命名空间）。 */
+const RESERVED_ENV_PREFIXES = ["XYZ_", "XYZ_AGENT_", "XYZ_SUBAGENT_"];
+
+/** env 前缀合法形态（§2.4：^[A-Za-z0-9_]+$；保留前缀比对大小写不敏感）。 */
+const ENV_PREFIX_PATTERN = /^[A-Za-z0-9_]+$/;
+
+/**
+ * capabilities 全保守值（manifest capabilities 缺失/缺键时的回退——「声明即能力」
+ * 模型下，未声明 = 最弱能力：gate 同步拦生成，运行期不会踩引擎不支持的路径）。
+ */
+export const CONSERVATIVE_CAPABILITIES: EngineCapabilities = {
+  schemaEnforcement: "emulated",
+  steer: "unsupported",
+  conversation: "unsupported",
+  personaInjection: "prompt",
+  eventGranularity: "coarse",
+  sandbox: "none",
+  sessionRead: "outcome-only",
+  resume: "unsupported",
+  interrupt: "kill-only",
+  permissionMode: "ignored",
+  maxTurns: false,
+};
+
+/** 枚举能力位词表（与 types.ts EngineCapabilities 逐键对应；maxTurns 单独 boolean）。 */
+const CAPABILITY_ENUMS: Record<string, readonly string[]> = {
+  schemaEnforcement: ["native", "emulated"],
+  steer: ["native", "emulated", "unsupported"],
+  conversation: ["native", "unsupported"],
+  personaInjection: ["file", "flag", "prompt"],
+  eventGranularity: ["stream", "coarse"],
+  sandbox: ["native", "emulated", "none"],
+  sessionRead: ["full", "partial", "outcome-only"],
+  resume: ["native", "cold", "unsupported"],
+  interrupt: ["native", "kill-only"],
+  permissionMode: ["native", "fixed", "ignored"],
+};
+
+/**
+ * 解析 manifest bin → 入口文件绝对路径。package.json `bin` 为字符串（单入口形态）
+ * 直接用；为 map 时按 manifest bin key 查。查不到返回 undefined（= bin 缺失面）。
+ */
+export function resolveManifestBin(
+  pkgDir: string,
+  pkg: Record<string, unknown>,
+  manifestBin: string,
+): string | undefined {
+  const npmBin = pkg["bin"];
+  if (typeof npmBin === "string") return path.resolve(pkgDir, npmBin);
+  if (typeof npmBin === "object" && npmBin !== null) {
+    const rel = (npmBin as Record<string, unknown>)[manifestBin];
+    if (typeof rel === "string" && rel.trim() !== "") return path.resolve(pkgDir, rel);
+  }
+  return undefined;
+}
+
+/** capabilities 字段级解析：段缺失 = 全保守 + warn；缺键/坏值 = 该键保守 + warn；未知键忽略 + warn。 */
+export function parseCapabilities(id: string, raw: unknown): EngineCapabilities {
+  if (raw === undefined || raw === null) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': manifest capabilities is required — falling back to most conservative values`,
+    );
+    return { ...CONSERVATIVE_CAPABILITIES };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': manifest capabilities must be an object — falling back to most conservative values`,
+    );
+    return { ...CONSERVATIVE_CAPABILITIES };
+  }
+  const v = raw as Record<string, unknown>;
+  const out = {} as Record<string, unknown>;
+  for (const [key, allowed] of Object.entries(CAPABILITY_ENUMS)) {
+    const value = v[key];
+    if (value === undefined) {
+      out[key] = CONSERVATIVE_CAPABILITIES[key as keyof EngineCapabilities];
+      logger.warn(
+        `[engine-discovery] engine '${id}': capabilities.${key} missing — conservative default '${String(out[key])}'`,
+      );
+      continue;
+    }
+    if (typeof value === "string" && (allowed as readonly string[]).includes(value)) {
+      out[key] = value;
+      continue;
+    }
+    out[key] = CONSERVATIVE_CAPABILITIES[key as keyof EngineCapabilities];
+    logger.warn(
+      `[engine-discovery] engine '${id}': capabilities.${key}=${describeValue(value)} invalid ` +
+        `(expected one of ${allowed.join("|")}) — conservative default '${String(out[key])}'`,
+    );
+  }
+  const maxTurns = v["maxTurns"];
+  if (maxTurns === undefined) {
+    out["maxTurns"] = false;
+    logger.warn(`[engine-discovery] engine '${id}': capabilities.maxTurns missing — conservative default 'false'`);
+  } else if (typeof maxTurns !== "boolean") {
+    out["maxTurns"] = false;
+    logger.warn(
+      `[engine-discovery] engine '${id}': capabilities.maxTurns=${describeValue(maxTurns)} invalid (expected boolean) — conservative default 'false'`,
+    );
+  } else {
+    out["maxTurns"] = maxTurns;
+  }
+  // 未知键：忽略 + warn（一次汇总，防逐键刷屏）
+  const knownKeys = new Set([...Object.keys(CAPABILITY_ENUMS), "maxTurns"]);
+  const unknownKeys = Object.keys(v).filter((k) => !knownKeys.has(k));
+  if (unknownKeys.length > 0) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': unknown capabilities key(s) ignored: ${unknownKeys.join(", ")}`,
+    );
+  }
+  return out as unknown as EngineCapabilities;
+}
+
+/** envPrefixes 字段级解析：非法/保留前缀条目丢弃该前缀 + warn，包仍可用（A12②）。 */
+export function parseEnvPrefixes(id: string, raw: unknown): string[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': envPrefixes must be an array — ignoring (engine remains usable)`,
+    );
+    return [];
+  }
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== "string" || item === "" || item.includes("*") || !ENV_PREFIX_PATTERN.test(item)) {
+      logger.warn(
+        `[engine-discovery] engine '${id}': envPrefixes entry ${describeValue(item)} rejected ` +
+          `(must match ^[A-Za-z0-9_]+$, non-empty, no '*') — dropping the prefix, engine remains usable`,
+      );
+      continue;
+    }
+    const upper = item.toUpperCase();
+    if (RESERVED_ENV_PREFIXES.some((reserved) => upper.startsWith(reserved))) {
+      logger.warn(
+        `[engine-discovery] engine '${id}': envPrefixes entry '${item}' rejected (reserved host prefix) — dropping the prefix, engine remains usable`,
+      );
+      continue;
+    }
+    if (seen.has(upper)) continue; // 大小写不敏感去重（env 名在 POSIX 侧语义即不区分大小写冲突面）
+    seen.add(upper);
+    out.push(item);
+  }
+  return out;
+}
+
+/**
+ * modelCatalog 字段级解析（三态必写死，§2.4）：
+ *   缺省 → undefined（不注入——「无枚举面」必须可达）；
+ *   null → null（合法等价省略）；
+ *   对象 → { dynamic: 缺省 true, models: 条目数组 }；models 缺失/非数组 → null + warn
+ *   （显式声明了 catalog 却无有效 models = 无有效枚举面，取 null 而非 []——[] 是
+ *   「有枚举面但空」的作者显式声明，不得代填）。
+ */
+export function parseModelCatalog(
+  id: string,
+  raw: unknown,
+): { dynamic: boolean; models: ModelCatalogEntry[] } | null | undefined {
+  if (raw === undefined) return undefined;
+  if (raw === null) return null;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog must be an object — ignoring (no model catalog)`);
+    return undefined;
+  }
+  const v = raw as Record<string, unknown>;
+  const dynamic = parseCatalogDynamic(id, v);
+  if (!Array.isArray(v["models"])) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': modelCatalog.models must be an array — treating catalog as absent (null)`,
+    );
+    return null;
+  }
+  const models: ModelCatalogEntry[] = [];
+  for (const item of v["models"]) {
+    const entry = parseModelCatalogEntry(id, item);
+    if (entry === undefined) continue;
+    models.push(entry);
+  }
+  return { dynamic, models };
+}
+
+/** modelCatalog.dynamic 解析：缺省 true；非 boolean warn 后仍取缺省。 */
+function parseCatalogDynamic(id: string, v: Record<string, unknown>): boolean {
+  const rawDynamic = v["dynamic"];
+  if (rawDynamic === undefined) return true;
+  if (typeof rawDynamic === "boolean") return rawDynamic;
+  logger.warn(
+    `[engine-discovery] engine '${id}': modelCatalog.dynamic=${describeValue(rawDynamic)} invalid (expected boolean) — defaulting to true`,
+  );
+  return true;
+}
+
+/** 单条目解析：形态坏/缺 id → undefined（丢弃该条目）；非法 aliases 丢弃 aliases 但条目保留。 */
+function parseModelCatalogEntry(id: string, item: unknown): ModelCatalogEntry | undefined {
+  if (typeof item !== "object" || item === null || Array.isArray(item)) {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog entry ${describeValue(item)} is not an object — dropping entry`);
+    return undefined;
+  }
+  const entryId = (item as Record<string, unknown>)["id"];
+  if (typeof entryId !== "string" || entryId.trim() === "") {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog entry missing string id — dropping entry`);
+    return undefined;
+  }
+  const aliases = (item as Record<string, unknown>)["aliases"];
+  if (aliases !== undefined && !Array.isArray(aliases)) {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog entry '${entryId}' aliases must be an array — dropping aliases`);
+  }
+  return {
+    id: entryId,
+    ...(Array.isArray(aliases) ? { aliases: aliases.filter((a): a is string => typeof a === "string") } : {}),
+    ...((item as Record<string, unknown>)["canonicalRef"] !== undefined
+      ? { canonicalRef: (item as Record<string, unknown>)["canonicalRef"] as string }
+      : {}),
+  };
+}
+
+/** unknown 值的短描述（warn 文案；JSON.stringify 对 Symbol/BigInt 返回 undefined 不可靠）。 */
+export function describeValue(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "object" && value !== null) return Array.isArray(value) ? "array" : "object";
+  return String(value);
+}

package/src/execution/engine/host/__tests__/host-askuser-endpoint.test.ts

@@ -0,0 +1,123 @@
+// host/askUser 壳侧应答端集成断言（W6 验收，R3 MF-A / impl-plan §2.6 验收补充）：
+// fake 引擎经 host/askUser 反向请求可在 core 壳侧收到应答——链路 = fake-engine CLI
+// 帧④ → EngineClient reverse-router（ack 先行，R9-2）→ EngineClientOptions
+// .uiRequestHandler 注入点（discovery portFactory 的接线形态：读壳侧登记处）→
+// SubagentService init.uiRequestHandler 同源的 handler（[D4-④] 唯一注入入口的
+// 协议化投影）。应答复用 dialog-queue 的 UiRequest/UiResponse 形状。
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { EngineClient } from "../../client/engine-client.ts";
+import {
+  _resetHostUiRequestEndpointForTest,
+  getHostUiRequestEndpoint,
+  setHostUiRequestEndpoint,
+} from "../host-ui-endpoint.ts";
+
+const FAKE_ENGINE = fileURLToPath(
+  new URL("../../client/__tests__/__fixtures__/fake-engine.mjs", import.meta.url),
+);
+
+let dataDir: string;
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), "w6-host-askuser-"));
+});
+
+afterEach(() => {
+  rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  _resetHostUiRequestEndpointForTest();
+});
+
+describe("host/askUser 壳侧应答端（W6 R3 MF-A 集成断言）", () => {
+  it("fake 引擎经 host/askUser 反向请求 → 壳侧登记 handler 应答（ack 先行 + 结果异步补帧②）", async () => {
+    // ① 壳侧登记（生产 = SubagentService init/initSession.uiRequestHandler 写点同步登记）
+    const seenRequests: Array<{ method: string; id: string }> = [];
+    setHostUiRequestEndpoint(async (req) => {
+      seenRequests.push({ method: req.method, id: req.id });
+      return { value: "host-answer" };
+    });
+
+    // ② EngineClient 构造（discovery portFactory 同款接线形态：注入点读登记处）
+    const client = new EngineClient({
+      engineId: "fake",
+      command: process.execPath,
+      args: [
+        FAKE_ENGINE,
+        "--run-actions",
+        JSON.stringify([
+          { op: "askUser", request: { method: "select", id: "q1", title: "pick" } },
+        ]),
+      ],
+      hostKind: "test",
+      hostVersion: "test-host-1.0",
+      dataDir,
+      envPrefixes: [],
+      uiRequestHandler: getHostUiRequestEndpoint(),
+    });
+
+    const events: Array<{ type: string; message?: string }> = [];
+    const unregister = client.registerRunRoute("run-1", {
+      onEvent: (e) => {
+        events.push(e as { type: string; message?: string });
+      },
+    });
+    try {
+      await client.ensureConnected();
+      await client.request("run", {
+        runId: "run-1",
+        task: { prompt: "p" },
+        ctx: { poolKey: "shared", cwd: dataDir },
+      });
+    } finally {
+      unregister();
+      await client.dispose();
+    }
+
+    // ③ 壳侧收到请求（形状 = dialog-queue UiRequest）
+    expect(seenRequests).toEqual([{ method: "select", id: "q1" }]);
+    // ④ 引擎收到应答（fake-engine 把 host/askUser 应答 echo 成 event；ack 先行语义
+    //    由 client/__tests__/engine-client.test.ts 的 ack 两阶段用例锁定）
+    const echo = events.find((e) => e.message?.startsWith("askUser-result:"));
+    expect(echo?.message).toContain('"value":"host-answer"');
+  });
+
+  it("登记处为空（未注入 handler）→ 引擎收 {unsupported:true} 自行降级（不炸链路）", async () => {
+    const client = new EngineClient({
+      engineId: "fake",
+      command: process.execPath,
+      args: [
+        FAKE_ENGINE,
+        "--run-actions",
+        JSON.stringify([{ op: "askUser", request: { method: "confirm", id: "q2" } }]),
+      ],
+      hostKind: "test",
+      dataDir,
+      envPrefixes: [],
+      uiRequestHandler: getHostUiRequestEndpoint(), // undefined
+    });
+    const events: Array<{ type: string; message?: string }> = [];
+    const unregister = client.registerRunRoute("run-1", {
+      onEvent: (e) => {
+        events.push(e as { type: string; message?: string });
+      },
+    });
+    try {
+      await client.ensureConnected();
+      await client.request("run", {
+        runId: "run-1",
+        task: { prompt: "p" },
+        ctx: { poolKey: "shared", cwd: dataDir },
+      });
+    } finally {
+      unregister();
+      await client.dispose();
+    }
+    const echo = events.find((e) => e.message?.startsWith("askUser-result:"));
+    expect(echo?.message).toContain('"unsupported":true');
+  });
+});

package/src/execution/engine/host/__tests__/host-bridge.test.ts

@@ -0,0 +1,135 @@
+// HostBridge 契约 + core 实现 单测（W6，impl-plan §2.6 第 2 条 / 设计 §3.8 最小示例 9 方法）。
+// 覆盖：9 方法委托行为、getRecordForAction 异常 → null、cancel 的 void 包装、
+// takeChatRound 未提供 → null、armIdleTimer/disarmIdleTimer 对 lifecycle-manager 的
+// 接线（含超时回调 onIdleTimeout 触发，fake timers）。
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+import {
+  createHostBridge,
+  type HostBridge,
+  type HostBridgeServiceFace,
+  type HostChatRoundTicket,
+} from "../host-bridge.ts";
+import {
+  _resetLifecycleState,
+  hasIdleTimer,
+} from "../../../lifecycle-manager.ts";
+import type { ExecutionRecord, SubagentRecord } from "../../../types.ts";
+
+/** 最小 record fake（HostBridge 只透传，不读字段）。 */
+function fakeRecord(id: string): ExecutionRecord {
+  return { id } as ExecutionRecord;
+}
+
+/** 服务面 fake：全部方法 vi.fn，逐方法断言委托。 */
+function makeService(): HostBridgeServiceFace & {
+  spies: Record<string, ReturnType<typeof vi.fn>>;
+} {
+  const spies = {
+    executeAndAwait: vi.fn(async () => ({ content: "ok" })),
+    getRecordForAction: vi.fn((id: string) => fakeRecord(id)),
+    closeSubagent: vi.fn(async () => {}),
+    cancel: vi.fn(() => true),
+    collectRecords: vi.fn((): SubagentRecord[] => [{ id: "r1" } as SubagentRecord]),
+    takeChatRound: vi.fn(() => undefined),
+    reportRecordTransition: vi.fn(() => {}),
+  };
+  return {
+    spies,
+    executeAndAwait: spies.executeAndAwait as HostBridgeServiceFace["executeAndAwait"],
+    getRecordForAction: spies.getRecordForAction,
+    closeSubagent: spies.closeSubagent,
+    cancel: spies.cancel,
+    collectRecords: spies.collectRecords,
+    takeChatRound: spies.takeChatRound as HostBridgeServiceFace["takeChatRound"],
+    reportRecordTransition: spies.reportRecordTransition,
+  };
+}
+
+describe("HostBridge（W6，设计 §3.8 最小示例 9 方法）", () => {
+  let service: ReturnType<typeof makeService>;
+  let onIdleTimeout: (recordId: string) => void;
+  let bridge: HostBridge;
+
+  beforeEach(() => {
+    _resetLifecycleState();
+    service = makeService();
+    onIdleTimeout = vi.fn();
+    bridge = createHostBridge({ service, onIdleTimeout });
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+  });
+
+  it("executeAndAwait 委托服务面（opts/signal/onEvent/stream 四参透传）", async () => {
+    const opts = { task: "t" } as Parameters<HostBridge["executeAndAwait"]>[0];
+    const signal = new AbortController().signal;
+    const onEvent = () => {};
+    const result = await bridge.executeAndAwait(opts, signal, onEvent);
+    expect(result).toEqual({ content: "ok" });
+    expect(service.spies.executeAndAwait).toHaveBeenCalledWith(opts, signal, onEvent, undefined);
+  });
+
+  it("getRecordForAction：存在 → 返回 record；throw → null（resolveRecord 语义内聚）", () => {
+    expect(bridge.getRecordForAction("r1")?.id).toBe("r1");
+    (service.spies.getRecordForAction as ReturnType<typeof vi.fn>).mockImplementation(() => {
+      throw new Error("not found");
+    });
+    expect(bridge.getRecordForAction("missing")).toBeNull();
+  });
+
+  it("collectRecords 委托（limit/filter 透传）", () => {
+    expect(bridge.collectRecords(10, "all")).toEqual([{ id: "r1" }]);
+    expect(service.spies.collectRecords).toHaveBeenCalledWith(10, "all");
+  });
+
+  it("closeSubagent 委托（record/force 透传，Promise 语义保持）", async () => {
+    const record = fakeRecord("r1");
+    await bridge.closeSubagent(record, true);
+    expect(service.spies.closeSubagent).toHaveBeenCalledWith(record, true);
+  });
+
+  it("cancel：服务面 boolean → 契约 void（resolve 语义归引擎侧判 notResumable）", async () => {
+    await expect(bridge.cancel("r1")).resolves.toBeUndefined();
+    expect(service.spies.cancel).toHaveBeenCalledWith("r1");
+  });
+
+  it("takeChatRound：有票 → 透传；无票 / 服务面未提供 → null", () => {
+    expect(bridge.takeChatRound("t1")).toBeNull();
+    const ticket: HostChatRoundTicket = {
+      record: fakeRecord("r1"),
+      opts: {} as HostChatRoundTicket["opts"],
+      signal: undefined,
+      priority: 1,
+    };
+    (service.spies.takeChatRound as ReturnType<typeof vi.fn>).mockReturnValue(ticket);
+    expect(bridge.takeChatRound("t1")).toBe(ticket);
+  });
+
+  it("reportRecordTransition 委托（record 整体上报，无 patch 形态——见契约头注释）", () => {
+    const record = fakeRecord("r1");
+    bridge.reportRecordTransition(record);
+    expect(service.spies.reportRecordTransition).toHaveBeenCalledWith(record);
+  });
+
+  it("armIdleTimer/disarmIdleTimer 接线 lifecycle-manager（D2 表：idle 定时器归 HostBridge）", () => {
+    expect(hasIdleTimer("r1")).toBe(false);
+    bridge.armIdleTimer("r1", 60_000);
+    expect(hasIdleTimer("r1")).toBe(true);
+    bridge.disarmIdleTimer("r1");
+    expect(hasIdleTimer("r1")).toBe(false);
+  });
+
+  it("idle timer 超时触发 onIdleTimeout（宿主杀链注入点）", () => {
+    vi.useFakeTimers();
+    try {
+      bridge.armIdleTimer("r1", 1_000);
+      vi.advanceTimersByTime(1_000);
+      expect(onIdleTimeout).toHaveBeenCalledWith("r1");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/execution/engine/host/__tests__/spawned-children.test.ts

@@ -0,0 +1,73 @@
+// core 侧 spawnedChildren 状态镜像单测（W6 建立；[W3 改写] 纯镜像形态）。
+// 覆盖：注册记账、终止意图置死位、镜像整体置死、hasLiveProcessHandleCore 读点。
+// inproc 过渡桥（双写/委托杀/并读）随 inproc pi 引擎目录 删除消亡——实际终止在引擎进程内
+// 经协议 interact cancel/close 承载，本模块只做镜像记账。
+
+import { describe, it, expect, beforeEach } from "vitest";
+
+import type { ChildProcess } from "node:child_process";
+import {
+  _resetCoreSpawnedChildrenMirrorForTest,
+  coreSpawnedChildrenMirror,
+  hasLiveProcessHandleCore,
+  killAllSpawnedChildren,
+  killRecordChildWithEscalation,
+  registerSpawnedChildForRecord,
+} from "../spawned-children.ts";
+
+/** 最小 ChildProcess fake（镜像注册只读 pid/killed）。 */
+function fakeChild(id: string): ChildProcess {
+  return { pid: 10_000 + (id.charCodeAt(0) % 1000), killed: false } as unknown as ChildProcess;
+}
+
+describe("core 侧 spawnedChildren 状态镜像（W6；W3 纯镜像形态）", () => {
+  beforeEach(() => {
+    _resetCoreSpawnedChildrenMirrorForTest();
+  });
+
+  it("registerSpawnedChildForRecord：写镜像（host/childSpawned 上报的同款落点）", () => {
+    const child = fakeChild("sa-a");
+    registerSpawnedChildForRecord("sa-a", child);
+    expect(coreSpawnedChildrenMirror().getChildByRecord("sa-a")).toMatchObject({
+      pid: child.pid,
+      killed: false,
+    });
+  });
+
+  it("hasLiveProcessHandleCore：镜像注册后 true；markKilled 后 false", () => {
+    registerSpawnedChildForRecord("sa-a", fakeChild("sa-a"));
+    expect(hasLiveProcessHandleCore("sa-a")).toBe(true);
+    coreSpawnedChildrenMirror().markKilled("sa-a");
+    expect(hasLiveProcessHandleCore("sa-a")).toBe(false);
+  });
+
+  it("killRecordChildWithEscalation：终止意图记账（镜像置死位；实际终止经协议承载）", () => {
+    registerSpawnedChildForRecord("sa-a", fakeChild("sa-a"));
+    killRecordChildWithEscalation("sa-a", "test escalation");
+    expect(coreSpawnedChildrenMirror().getChildByRecord("sa-a")?.killed).toBe(true);
+    expect(hasLiveProcessHandleCore("sa-a")).toBe(false);
+  });
+
+  it("killAllSpawnedChildren：镜像整体置死（失效语义 2+3），返回清理条目数", () => {
+    registerSpawnedChildForRecord("sa-a", fakeChild("sa-a"));
+    registerSpawnedChildForRecord("sa-b", fakeChild("sa-b"));
+    const killed = killAllSpawnedChildren();
+    expect(killed).toBe(2);
+    expect(coreSpawnedChildrenMirror().snapshot()).toEqual([]);
+    expect(hasLiveProcessHandleCore("sa-a")).toBe(false);
+    expect(hasLiveProcessHandleCore("sa-b")).toBe(false);
+  });
+
+  it("不存在的 record killAll：返回 0（幂等）", () => {
+    expect(killAllSpawnedChildren()).toBe(0);
+  });
+
+  it("同 recordId 重 spawn：镜像覆盖旧句柄（与引擎侧 Map 覆盖语义同构）", () => {
+    registerSpawnedChildForRecord("sa-a", fakeChild("sa-a"));
+    killRecordChildWithEscalation("sa-a", "old killed");
+    const fresh = fakeChild("sa-b");
+    registerSpawnedChildForRecord("sa-a", fresh);
+    expect(coreSpawnedChildrenMirror().getChildByRecord("sa-a")?.pid).toBe(fresh.pid);
+    expect(hasLiveProcessHandleCore("sa-a")).toBe(true);
+  });
+});