@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/dist/chunk-VURUAGMM.js

@@ -0,0 +1,2305 @@
+// src/execution/engine/engine-discovery-scan.ts
+import * as path5 from "path";
+
+// src/execution/engine/engine-manifest.ts
+import * as path from "path";
+
+// src/core/host-services.ts
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_DATA_ROOT = join(homedir(), ".subagent-core");
+var HOST_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-core.host-services");
+function getHostSlot() {
+  let slot = Reflect.get(globalThis, HOST_SLOT_KEY);
+  if (!slot) {
+    slot = { current: void 0 };
+    Reflect.set(globalThis, HOST_SLOT_KEY, slot);
+  }
+  return slot;
+}
+function configureCore(host) {
+  getHostSlot().current = host;
+}
+var NULL_HOST = {
+  dataRoot() {
+    throw new Error(
+      "[subagent-core] core_host_not_configured: HostServices is not configured \u2014 the host shell must call configureCore(host) during initialization, before any core API that needs host services is consumed. Recovery: pi shell wires HostServices in src/host/pi-host.ts of @zhushanwen/pi-subagent-workflow; zsw shell: see the wiring example in the @zhushanwen/subagent-core package README."
+    );
+  },
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    if (level === "error") {
+      if (data === void 0) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === void 0) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+  }
+  // discoveryRoots 刻意不实现：可选端口缺席 = undefined，由调用方走缺省发现语义。
+};
+function getHostServices() {
+  return getHostSlot().current ?? NULL_HOST;
+}
+
+// src/core/logger.ts
+var facadeCache = /* @__PURE__ */ new Map();
+function getLogger(component) {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade = {
+    debug(msg, data) {
+      getHostServices().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      getHostServices().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      getHostServices().log("error", component, msg, data);
+    }
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}
+
+// src/execution/engine/engine-manifest.ts
+var logger = getLogger("subagents");
+var RESERVED_ENV_PREFIXES = ["XYZ_", "XYZ_AGENT_", "XYZ_SUBAGENT_"];
+var ENV_PREFIX_PATTERN = /^[A-Za-z0-9_]+$/;
+var CONSERVATIVE_CAPABILITIES = {
+  schemaEnforcement: "emulated",
+  steer: "unsupported",
+  conversation: "unsupported",
+  personaInjection: "prompt",
+  eventGranularity: "coarse",
+  sandbox: "none",
+  sessionRead: "outcome-only",
+  resume: "unsupported",
+  interrupt: "kill-only",
+  permissionMode: "ignored",
+  maxTurns: false
+};
+var CAPABILITY_ENUMS = {
+  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"]
+};
+function resolveManifestBin(pkgDir, pkg, manifestBin) {
+  const npmBin = pkg["bin"];
+  if (typeof npmBin === "string") return path.resolve(pkgDir, npmBin);
+  if (typeof npmBin === "object" && npmBin !== null) {
+    const rel = npmBin[manifestBin];
+    if (typeof rel === "string" && rel.trim() !== "") return path.resolve(pkgDir, rel);
+  }
+  return void 0;
+}
+function parseCapabilities(id, raw) {
+  if (raw === void 0 || raw === null) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': manifest capabilities is required \u2014 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 \u2014 falling back to most conservative values`
+    );
+    return { ...CONSERVATIVE_CAPABILITIES };
+  }
+  const v = raw;
+  const out = {};
+  for (const [key, allowed] of Object.entries(CAPABILITY_ENUMS)) {
+    const value = v[key];
+    if (value === void 0) {
+      out[key] = CONSERVATIVE_CAPABILITIES[key];
+      logger.warn(
+        `[engine-discovery] engine '${id}': capabilities.${key} missing \u2014 conservative default '${String(out[key])}'`
+      );
+      continue;
+    }
+    if (typeof value === "string" && allowed.includes(value)) {
+      out[key] = value;
+      continue;
+    }
+    out[key] = CONSERVATIVE_CAPABILITIES[key];
+    logger.warn(
+      `[engine-discovery] engine '${id}': capabilities.${key}=${describeValue(value)} invalid (expected one of ${allowed.join("|")}) \u2014 conservative default '${String(out[key])}'`
+    );
+  }
+  const maxTurns = v["maxTurns"];
+  if (maxTurns === void 0) {
+    out["maxTurns"] = false;
+    logger.warn(`[engine-discovery] engine '${id}': capabilities.maxTurns missing \u2014 conservative default 'false'`);
+  } else if (typeof maxTurns !== "boolean") {
+    out["maxTurns"] = false;
+    logger.warn(
+      `[engine-discovery] engine '${id}': capabilities.maxTurns=${describeValue(maxTurns)} invalid (expected boolean) \u2014 conservative default 'false'`
+    );
+  } else {
+    out["maxTurns"] = maxTurns;
+  }
+  const knownKeys = /* @__PURE__ */ 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;
+}
+function parseEnvPrefixes(id, raw) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': envPrefixes must be an array \u2014 ignoring (engine remains usable)`
+    );
+    return [];
+  }
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  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 '*') \u2014 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) \u2014 dropping the prefix, engine remains usable`
+      );
+      continue;
+    }
+    if (seen.has(upper)) continue;
+    seen.add(upper);
+    out.push(item);
+  }
+  return out;
+}
+function parseModelCatalog(id, raw) {
+  if (raw === void 0) return void 0;
+  if (raw === null) return null;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog must be an object \u2014 ignoring (no model catalog)`);
+    return void 0;
+  }
+  const v = raw;
+  const dynamic = parseCatalogDynamic(id, v);
+  if (!Array.isArray(v["models"])) {
+    logger.warn(
+      `[engine-discovery] engine '${id}': modelCatalog.models must be an array \u2014 treating catalog as absent (null)`
+    );
+    return null;
+  }
+  const models = [];
+  for (const item of v["models"]) {
+    const entry = parseModelCatalogEntry(id, item);
+    if (entry === void 0) continue;
+    models.push(entry);
+  }
+  return { dynamic, models };
+}
+function parseCatalogDynamic(id, v) {
+  const rawDynamic = v["dynamic"];
+  if (rawDynamic === void 0) return true;
+  if (typeof rawDynamic === "boolean") return rawDynamic;
+  logger.warn(
+    `[engine-discovery] engine '${id}': modelCatalog.dynamic=${describeValue(rawDynamic)} invalid (expected boolean) \u2014 defaulting to true`
+  );
+  return true;
+}
+function parseModelCatalogEntry(id, item) {
+  if (typeof item !== "object" || item === null || Array.isArray(item)) {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog entry ${describeValue(item)} is not an object \u2014 dropping entry`);
+    return void 0;
+  }
+  const entryId = item["id"];
+  if (typeof entryId !== "string" || entryId.trim() === "") {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog entry missing string id \u2014 dropping entry`);
+    return void 0;
+  }
+  const aliases = item["aliases"];
+  if (aliases !== void 0 && !Array.isArray(aliases)) {
+    logger.warn(`[engine-discovery] engine '${id}': modelCatalog entry '${entryId}' aliases must be an array \u2014 dropping aliases`);
+  }
+  return {
+    id: entryId,
+    ...Array.isArray(aliases) ? { aliases: aliases.filter((a) => typeof a === "string") } : {},
+    ...item["canonicalRef"] !== void 0 ? { canonicalRef: item["canonicalRef"] } : {}
+  };
+}
+function describeValue(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "object" && value !== null) return Array.isArray(value) ? "array" : "object";
+  return String(value);
+}
+
+// src/execution/engine/engine-inspect-package.ts
+import * as fs from "fs";
+import * as path2 from "path";
+import { isProtocolVersionCompatible as isProtocolVersionCompatible2 } from "@zhushanwen/subagent-engine-sdk";
+
+// src/execution/engine/common/data-dir.ts
+var logger2 = getLogger("subagents");
+var XYZ_DATA_DIR_ENV = "XYZ_AGENT_DATA_DIR";
+var warned = false;
+function getEngineDataDir(env = process.env, warn = defaultWarn) {
+  const fromEnv = env[XYZ_DATA_DIR_ENV]?.trim();
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
+  const fallback = getHostServices().dataRoot();
+  if (!warned) {
+    warned = true;
+    warn(
+      `[engine-data-dir] ${XYZ_DATA_DIR_ENV} is not set; engine journal/pool fall back to the pi agent dir (${fallback}). The xyz-agent host normally injects this env \u2014 if you are running inside xyz-agent, check the runtime spawn env; standalone pi installs intentionally use the pi agent dir.`
+    );
+  }
+  return fallback;
+}
+function defaultWarn(msg) {
+  logger2.warn(msg);
+}
+
+// src/execution/engine/client/engine-client.ts
+import { spawn } from "child_process";
+import {
+  buildEngineChildEnv,
+  CANCEL_SETTLE_GRACE_MS,
+  CRASH_REBUILD_BACKOFF_MS,
+  CRASH_REBUILD_MAX_ATTEMPTS,
+  ENGINE_PROTOCOL_VERSION,
+  EngineSdkError,
+  HANDSHAKE_TIMEOUT_MS,
+  getLogger as getLogger7,
+  isProtocolVersionCompatible,
+  isResponseFrame,
+  isNotificationFrame,
+  isReverseRequestFrame,
+  STDERR_TAIL_CHARS,
+  engineProtocolMismatchError,
+  hostKindOf,
+  resolveEngineNodeLaunch
+} from "@zhushanwen/subagent-engine-sdk";
+
+// src/execution/engine/client/mirror.ts
+import { getLogger as getLogger2 } from "@zhushanwen/subagent-engine-sdk";
+var logger3 = getLogger2("subagents");
+var SpawnedChildrenMirror = class {
+  entries = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  /** `host/childSpawned`：落项（此前该 record 无句柄——失效语义 1）。 */
+  recordSpawned(pid, recordId) {
+    this.entries.set(pid, {
+      pid,
+      recordId,
+      state: "running",
+      killed: false,
+      updatedAt: Date.now()
+    });
+    this.emit({ reason: "childSpawned", pid, recordId });
+  }
+  /** `host/childStateChanged`：更新项（载荷 killed 必含——类型层 required）。 */
+  recordStateChanged(patch) {
+    const existing = this.entries.get(patch.pid);
+    const entry = {
+      pid: patch.pid,
+      recordId: patch.recordId,
+      state: patch.state,
+      killed: patch.killed,
+      exitCode: patch.exitCode ?? existing?.exitCode,
+      signal: patch.signal ?? existing?.signal,
+      updatedAt: Date.now()
+    };
+    this.entries.set(patch.pid, entry);
+    this.emit({ reason: "childStateChanged", pid: patch.pid, recordId: patch.recordId });
+  }
+  /**
+   * 失效语义 2 + 3：全部镜像项整体置死（killed=true + state=exited）→ 逐项广播 →
+   * 清空 Map。调用点 = 引擎进程 exit / 重建 / dispose / killAll（EngineClient 统一编排）。
+   */
+  killAll() {
+    if (this.entries.size === 0) {
+      this.emit({ reason: "killedAll" });
+      return;
+    }
+    for (const entry of this.entries.values()) {
+      entry.killed = true;
+      entry.state = "exited";
+      entry.updatedAt = Date.now();
+      this.emit({ reason: "killedAll", pid: entry.pid, recordId: entry.recordId });
+    }
+    this.entries.clear();
+  }
+  /** 未收 childSpawned / 已被整体置死清空后 → undefined（无句柄等价，失效语义 1）。 */
+  getChildByRecord(recordId) {
+    for (const entry of this.entries.values()) {
+      if (entry.recordId === recordId) return entry;
+    }
+    return void 0;
+  }
+  getEntry(pid) {
+    return this.entries.get(pid);
+  }
+  /** 句柄存活谓词：镜像有项且未被置死（`child !== undefined && !child.killed`）。 */
+  hasLiveProcessHandle(recordId) {
+    const entry = this.getChildByRecord(recordId);
+    return entry !== void 0 && !entry.killed;
+  }
+  /** isResumable 的镜像面（W6 lifecycle-predicates 改读本方法；语义同 hasLiveProcessHandle）。 */
+  isResumable(recordId) {
+    return this.hasLiveProcessHandle(recordId);
+  }
+  /** 快照（诊断/测试）。 */
+  snapshot() {
+    return [...this.entries.values()];
+  }
+  get size() {
+    return this.entries.size;
+  }
+  /** 订阅状态广播（W6 notify/谓词接线点）。返回退订函数。 */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        logger3.debug(
+          `[spawned-children-mirror] listener threw for ${event.reason}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+};
+
+// src/execution/engine/client/pid-file.ts
+import { spawnSync } from "child_process";
+import { readdirSync, readFileSync, renameSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { join as join2 } from "path";
+import { getLogger as getLogger3, resolveEngineDir } from "@zhushanwen/subagent-engine-sdk";
+var logger4 = getLogger3("subagents");
+var CMDLINE_PROBE_TIMEOUT_MS = 3e3;
+var PIDFILE_JSON_INDENT = 2;
+function pidfilePath(engineDataDir, engineId, hostKind, hostPid) {
+  return join2(resolveEngineDir(engineDataDir, engineId), `engine.${hostKind}.${hostPid}.pid`);
+}
+function writePidfileAtomic(path6, content) {
+  mkdirSync(join2(path6, ".."), { recursive: true });
+  const tmp = `${path6}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(content, null, PIDFILE_JSON_INDENT)}
+`, "utf-8");
+  renameSync(tmp, path6);
+}
+function readPidfile(path6) {
+  try {
+    const raw = readFileSync(path6, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.enginePid !== "number" || typeof parsed.hostPid !== "number" || typeof parsed.engineId !== "string" || typeof parsed.hostKind !== "string") {
+      return void 0;
+    }
+    return {
+      enginePid: parsed.enginePid,
+      hostPid: parsed.hostPid,
+      engineStartTime: parsed.engineStartTime === null || typeof parsed.engineStartTime === "string" ? parsed.engineStartTime : null,
+      engineId: parsed.engineId,
+      hostKind: parsed.hostKind,
+      writtenAt: typeof parsed.writtenAt === "string" ? parsed.writtenAt : ""
+    };
+  } catch (err) {
+    logger4.debug(`[pid-file] readPidfile(${path6}) failed, treating as stale: ${err instanceof Error ? err.message : String(err)}`);
+    return void 0;
+  }
+}
+function removePidfile(path6) {
+  try {
+    rmSync(path6, { force: true });
+  } catch (err) {
+    logger4.debug(`[pid-file] removePidfile(${path6}) failed (concurrent sweep = expected): ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function registerEnginePidfile(reg) {
+  const path6 = pidfilePath(reg.engineDataDir, reg.engineId, reg.hostKind, reg.hostPid);
+  try {
+    writePidfileAtomic(path6, {
+      enginePid: reg.enginePid,
+      hostPid: reg.hostPid,
+      engineStartTime: readProcessStartTime(reg.enginePid) ?? null,
+      engineId: reg.engineId,
+      hostKind: reg.hostKind,
+      writtenAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return path6;
+  } catch (err) {
+    logger4.warn(
+      `[pid-file] pidfile write failed for ${reg.engineId} (sweep coverage degraded): ${err instanceof Error ? err.message : String(err)}`
+    );
+    return void 0;
+  }
+}
+function sweepEnginePidfiles(args) {
+  try {
+    return sweepStalePidfiles(args);
+  } catch (err) {
+    logger4.warn(
+      `[pid-file] pidfile sweep failed for ${args.engineId} (conservative skip): ${err instanceof Error ? err.message : String(err)}`
+    );
+    return { killed: [], removed: [], skipped: [] };
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "ESRCH") return false;
+    if (code === "EPERM") return void 0;
+    return void 0;
+  }
+}
+function readProcessCmdline(pid) {
+  try {
+    const r = spawnSync("ps", ["-p", String(pid), "-o", "command="], {
+      encoding: "utf-8",
+      timeout: CMDLINE_PROBE_TIMEOUT_MS
+    });
+    if (r.error || r.status !== 0) return void 0;
+    const out = typeof r.stdout === "string" ? r.stdout.trim() : "";
+    return out.length > 0 ? out : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readProcessStartTime(pid) {
+  try {
+    const r = spawnSync("ps", ["-p", String(pid), "-o", "lstart="], {
+      encoding: "utf-8",
+      timeout: CMDLINE_PROBE_TIMEOUT_MS
+    });
+    if (r.error || r.status !== 0) return void 0;
+    const out = typeof r.stdout === "string" ? r.stdout.trim() : "";
+    return out.length > 0 ? out : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function sweepStalePidfiles(opts) {
+  const result = { killed: [], removed: [], skipped: [] };
+  const platform = opts.platform ?? process.platform;
+  const dir = resolveEngineDir(opts.engineDataDir, opts.engineId);
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".pid"));
+  } catch {
+    return result;
+  }
+  for (const file of files) {
+    sweepOnePidfile(join2(dir, file), file, opts, platform, result);
+  }
+  return result;
+}
+function sweepOnePidfile(path6, file, opts, platform, result) {
+  const content = readPidfile(path6);
+  if (content === void 0) {
+    removePidfile(path6);
+    result.removed.push({ file, reason: "unreadable-or-corrupt" });
+    return;
+  }
+  if (content.hostPid === opts.currentHostPid) {
+    result.skipped.push({ file, reason: "own-pidfile" });
+    return;
+  }
+  const hostAlive = isProcessAlive(content.hostPid);
+  if (hostAlive === void 0) {
+    result.skipped.push({ file, reason: "host-pid-probe-uncertain" });
+    return;
+  }
+  if (hostAlive) {
+    result.skipped.push({ file, reason: "host-pid-alive" });
+    return;
+  }
+  reapDeadHostEngine(path6, file, content, opts, platform, result);
+}
+function reapDeadHostEngine(path6, file, content, opts, platform, result) {
+  if (platform === "win32") {
+    removePidfile(path6);
+    result.removed.push({ file, reason: "stale (host dead); win32 never kills" });
+    return;
+  }
+  const engineAlive = isProcessAlive(content.enginePid);
+  if (engineAlive === void 0) {
+    result.skipped.push({ file, reason: "engine-pid-probe-uncertain" });
+    return;
+  }
+  if (!engineAlive) {
+    removePidfile(path6);
+    result.removed.push({ file, reason: "engine-pid-dead" });
+    return;
+  }
+  const cmdline = readProcessCmdline(content.enginePid);
+  if (cmdline === void 0) {
+    result.skipped.push({ file, reason: "engine-cmdline-probe-uncertain" });
+    return;
+  }
+  if (!opts.matchesEngineCmdline(cmdline)) {
+    removePidfile(path6);
+    result.removed.push({ file, reason: "cmdline-mismatch (pid reused by unrelated process)" });
+    return;
+  }
+  const startTime = readProcessStartTime(content.enginePid);
+  if (startTime === void 0) {
+    result.skipped.push({ file, reason: "engine-start-time-probe-uncertain" });
+    return;
+  }
+  if (content.engineStartTime === null || content.engineStartTime !== startTime) {
+    removePidfile(path6);
+    result.removed.push({ file, reason: "engine-start-time-mismatch (pid reused)" });
+    return;
+  }
+  const killEngine = opts.killEngine ?? defaultKillEngineProcessGroup;
+  killEngine(content.enginePid);
+  removePidfile(path6);
+  result.killed.push(content.enginePid);
+  result.removed.push({ file, reason: "swept after kill (stale orphan)" });
+}
+function defaultKillEngineProcessGroup(enginePid) {
+  try {
+    process.kill(-enginePid, "SIGKILL");
+    return;
+  } catch (groupErr) {
+    logger4.debug(`[pid-file] process-group kill(-${enginePid}) failed, falling back to single kill: ${groupErr instanceof Error ? groupErr.message : String(groupErr)}`);
+  }
+  try {
+    process.kill(enginePid, "SIGKILL");
+  } catch (err) {
+    logger4.debug(`[pid-file] single kill(${enginePid}) failed (already dead = expected): ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// src/execution/engine/client/reverse-router.ts
+import {
+  getLogger as getLogger4,
+  REVERSE_CHANNEL_TIMEOUT_CLASS,
+  REVERSE_REQUEST_TIMEOUT_MS
+} from "@zhushanwen/subagent-engine-sdk";
+var logger5 = getLogger4("subagents");
+function routeReverseRequest(deps, frame) {
+  if (frame.method === "host/askUser") {
+    handleInteractionRequest(deps, frame, deps.uiRequestHandler, (params) => params.request);
+    return;
+  }
+  if (frame.method === "host/permission") {
+    handleInteractionRequest(deps, frame, deps.permissionHandler, (params) => params);
+    return;
+  }
+  const timeoutClass = REVERSE_CHANNEL_TIMEOUT_CLASS[frame.method];
+  if (timeoutClass === "data-plane") {
+    handleDataPlaneRequest(deps, frame);
+    return;
+  }
+  deps.sendResponse(frame.id, { unsupported: true });
+}
+function handleInteractionRequest(deps, frame, handler, extract) {
+  if (handler === void 0) {
+    deps.sendResponse(frame.id, { unsupported: true });
+    return;
+  }
+  deps.sendResponse(frame.id, { ack: true });
+  let input;
+  try {
+    input = extract(frame.params);
+  } catch {
+    deps.sendResponse(frame.id, { cancelled: true });
+    return;
+  }
+  void (async () => {
+    try {
+      const result = await handler(input);
+      if (!deps.isDisposed()) deps.sendResponse(frame.id, result);
+    } catch (err) {
+      logger5.warn(
+        `[engine-client:${deps.engineId}] ${frame.method} handler failed, answering cancelled: ${err instanceof Error ? err.message : String(err)}`
+      );
+      if (!deps.isDisposed()) deps.sendResponse(frame.id, { cancelled: true });
+    }
+  })();
+}
+function handleDataPlaneRequest(deps, frame) {
+  let settled = false;
+  const guardTimer = setTimeout(() => {
+    if (settled) return;
+    logger5.error(
+      `[engine-client:${deps.engineId}] data-plane reverse request ${frame.method} unanswered for ${REVERSE_REQUEST_TIMEOUT_MS}ms \u2014 treating as engine fault`
+    );
+    void deps.failEngine(
+      `data-plane reverse request ${frame.method} unanswered for ${REVERSE_REQUEST_TIMEOUT_MS}ms (engine fault)`
+    );
+  }, REVERSE_REQUEST_TIMEOUT_MS);
+  void Promise.resolve().then(() => dispatchDataPlane(deps, frame.method, frame.params)).then(
+    () => {
+      settled = true;
+      clearTimeout(guardTimer);
+      deps.sendResponse(frame.id, { ok: true });
+    },
+    (err) => {
+      settled = true;
+      clearTimeout(guardTimer);
+      logger5.warn(
+        `[engine-client:${deps.engineId}] ${frame.method} dispatch failed (answering ok, host-side bug): ${err instanceof Error ? err.message : String(err)}`
+      );
+      deps.sendResponse(frame.id, { ok: true });
+    }
+  );
+}
+var DATA_PLANE_HANDLERS = {
+  "host/log": (deps, params) => dispatchLog(deps, params),
+  "host/streamDelta": (deps, params) => dispatchStreamDelta(deps, params),
+  "host/roundLifecycle": (deps, params) => dispatchRoundLifecycle(deps, params),
+  "host/poolResolved": (deps, params) => dispatchPoolResolved(deps, params),
+  "host/handleReady": (deps, params) => dispatchHandleReady(deps, params),
+  "host/childSpawned": (deps, params) => dispatchChildSpawned(deps, params),
+  "host/childStateChanged": (deps, params) => dispatchChildStateChanged(deps, params)
+};
+async function dispatchDataPlane(deps, method, params) {
+  await DATA_PLANE_HANDLERS[method]?.(deps, params);
+}
+function dispatchLog(deps, p) {
+  if (deps.log !== void 0) deps.log(p);
+  else logger5[p.level](`[engine:${p.component}] ${p.message}`, p.data);
+}
+async function dispatchStreamDelta(deps, p) {
+  if (p.recordId !== void 0) {
+    await deps.recordRoutes.get(p.recordId)?.onStreamDelta?.(p.delta);
+    return;
+  }
+  await deps.runRoutes.get(p.runId)?.onStreamDelta?.(p.delta);
+}
+async function dispatchRoundLifecycle(deps, p) {
+  if (p.recordId !== void 0) {
+    await deps.recordRoutes.get(p.recordId)?.onRoundLifecycle?.(p);
+    return;
+  }
+  await deps.runRoutes.get(p.runId)?.onRoundLifecycle?.(p);
+}
+async function dispatchPoolResolved(deps, p) {
+  await deps.runRoutes.get(p.runId)?.onPoolResolved?.(p.poolKey);
+}
+async function dispatchHandleReady(deps, p) {
+  deps.setPartialHandle({ sessionRef: p.sessionRef, poolKey: p.poolKey });
+  await deps.runRoutes.get(p.runId)?.onHandleReady?.({
+    sessionRef: p.sessionRef,
+    poolKey: p.poolKey
+  });
+}
+function dispatchChildSpawned(deps, p) {
+  deps.mirror.recordSpawned(p.pid, p.recordId);
+  if (process.platform !== "win32" && typeof p.pid === "number") {
+    try {
+      process.kill(-p.pid, 0);
+      logger5.warn(
+        `[engine-client:${deps.engineId}] childSpawned pid ${p.pid} leads its own process group (not in the engine harvest group \u2014 one-generation children + in-group descendants only; engine-detached descendants are an accepted cost per design \xA73.9)`
+      );
+    } catch (err) {
+      logger5.debug(
+        `[engine-client:${deps.engineId}] childSpawned pid ${p.pid} group probe settled (${err instanceof Error ? err.message : String(err)})`
+      );
+    }
+  }
+}
+function dispatchChildStateChanged(deps, p) {
+  deps.mirror.recordStateChanged({
+    pid: p.pid,
+    recordId: p.recordId,
+    state: p.state,
+    killed: p.killed,
+    exitCode: p.exitCode,
+    signal: p.signal
+  });
+}
+
+// src/execution/engine/client/client-options.ts
+import { basename } from "path";
+import {
+  getLogger as getLogger5
+} from "@zhushanwen/subagent-engine-sdk";
+var logger6 = getLogger5("subagents");
+function defaultEngineCmdlineMatcher(command) {
+  const base = basename(command);
+  return (cmdline) => {
+    if (cmdline.includes(command)) return true;
+    return cmdline.split(/\s+/).some((arg) => arg === command || arg.endsWith(`/${base}`));
+  };
+}
+function warnOnManifestDiagnostics(engineId, diag, result) {
+  if (diag?.capabilities) {
+    const answered = JSON.stringify(result.capabilities ?? null);
+    const declared = JSON.stringify(diag.capabilities);
+    if (answered !== declared) {
+      logger6.warn(
+        `[engine-client:${engineId}] initialize capabilities differ from manifest (diagnostic only): manifest=${declared} answered=${answered}`
+      );
+    }
+  }
+  if (diag && "models" in diag) {
+    const answered = JSON.stringify(result.models ?? null);
+    const declared = JSON.stringify(diag.models ?? null);
+    if (answered !== declared) {
+      logger6.warn(
+        `[engine-client:${engineId}] initialize models differ from manifest (diagnostic only): manifest=${declared} answered=${answered}`
+      );
+    }
+  }
+}
+
+// src/execution/engine/client/reaper.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { getLogger as getLogger6 } from "@zhushanwen/subagent-engine-sdk";
+var logger7 = getLogger6("subagents");
+var KILL_GRACE_MS = 5e3;
+function killProcessTree(pid, reason, opts) {
+  if (process.platform === "win32") {
+    const r = spawnSync2("taskkill", ["/PID", String(pid), "/T", "/F"], { timeout: 1e4 });
+    if (r.error || r.status !== 0) {
+      logger7.warn(
+        `[engine-client:${opts.engineId}] taskkill failed for pid ${pid} (${reason}): ${r.error?.message ?? `exit ${r.status}`}`
+      );
+    }
+    return;
+  }
+  const signalGroup = (signal) => {
+    try {
+      process.kill(-pid, signal);
+      return true;
+    } catch (err) {
+      logger7.debug(
+        `[engine-client:${opts.engineId}] process.kill(-${pid}, ${signal}) failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return false;
+    }
+  };
+  if (!signalGroup("SIGTERM")) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch (err) {
+      logger7.debug(
+        `[engine-client:${opts.engineId}] single SIGTERM to ${pid} failed (already dead = expected): ${err instanceof Error ? err.message : String(err)}`
+      );
+      return;
+    }
+  }
+  const escalation = setTimeout(
+    () => {
+      if (!signalGroup("SIGKILL")) {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch (err) {
+          logger7.debug(
+            `[engine-client:${opts.engineId}] SIGKILL to ${pid} failed (already dead = expected): ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    },
+    KILL_GRACE_MS
+  );
+  escalation.unref();
+}
+function waitForChildExit(child, timeoutMs) {
+  return new Promise((resolve4) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve4();
+      return;
+    }
+    const timer = setTimeout(() => resolve4(), timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolve4();
+    });
+  });
+}
+
+// src/execution/engine/client/engine-client.ts
+var logger8 = getLogger7("subagents");
+var DISPOSE_GRACE_MS = 3e3;
+var SIGKILL_REAP_TIMEOUT_MS = 1e4;
+var FRAME_ECHO_MAX_CHARS = 200;
+function engineSpawnPlatformOptions() {
+  if (process.platform === "win32") {
+    return { detached: false, windowsHide: true };
+  }
+  return { detached: true, windowsHide: false };
+}
+function engineCrashedError(detail, stderrTail) {
+  const tail = stderrTail.length > 0 ? ` stderr tail: ${stderrTail}` : "";
+  return new EngineSdkError(
+    "engine_crashed",
+    `engine process exited unexpectedly: ${detail}.${tail}`,
+    "The engine will be rebuilt (up to 3 attempts with exponential backoff) on the next run. If it keeps crashing, inspect the engine package installation and its stderr diagnostics.",
+    { stderrTail }
+  );
+}
+var EngineClient = class {
+  engineId;
+  /** spawnedChildren 状态镜像（host/childSpawned / childStateChanged 的落地面）。 */
+  mirror = new SpawnedChildrenMirror();
+  opts;
+  reverseRouterDeps;
+  state = "idle";
+  child;
+  nextRequestId = 1;
+  pending = /* @__PURE__ */ new Map();
+  runRoutes = /* @__PURE__ */ new Map();
+  /** [W3 v1.x] chat 轮次路由（recordId 键，D1-A——续聊轮无 runId）；注册经
+   *  RemoteEngine.registerChatRoundRoute，record 终态注销。 */
+  recordRoutes = /* @__PURE__ */ new Map();
+  stderrTail = "";
+  unavailableReason;
+  connectInFlight;
+  pidfileWritten;
+  pidfileSwept = false;
+  intentionalKill = false;
+  /** run 期 host/handleReady 的最近回填（崩溃时在途 run 的合成 handle 数据源）。 */
+  lastPartialHandle;
+  initializeDiagnostics;
+  stdoutBuffer = "";
+  constructor(opts) {
+    this.opts = opts;
+    this.engineId = opts.engineId;
+    this.reverseRouterDeps = {
+      engineId: opts.engineId,
+      uiRequestHandler: opts.uiRequestHandler,
+      permissionHandler: opts.permissionHandler,
+      log: opts.log,
+      runRoutes: this.runRoutes,
+      recordRoutes: this.recordRoutes,
+      mirror: this.mirror,
+      setPartialHandle: (partial) => {
+        this.lastPartialHandle = partial;
+      },
+      sendResponse: (id, result) => this.sendResponse(id, result),
+      failEngine: (reason) => this.killAll(reason),
+      isDisposed: () => this.disposed
+    };
+    this.mirror.onChange((event) => {
+      opts.onMirrorChanged?.(event);
+    });
+  }
+  get currentState() {
+    return this.state;
+  }
+  /** disposed 判定（getter 形态——TS 不对跨 await 的字段窄化保持，字段直比会在长方法内误窄化）。 */
+  get disposed() {
+    return this.state === "disposed";
+  }
+  /** 引擎 CLI 进程 pid（未连接 = undefined）。 */
+  get enginePid() {
+    return this.child?.pid;
+  }
+  /** stderr 环形缓冲尾（engine_crashed 现场 / 诊断）。 */
+  get stderrTailText() {
+    return this.stderrTail;
+  }
+  /** 最近一次 host/handleReady 回填（RemoteEngine 崩溃合成 handle 用）。 */
+  getPartialHandle() {
+    return this.lastPartialHandle;
+  }
+  /** initialize 应答（诊断面；RemoteEngine 诊断留痕用）。 */
+  getInitializeDiagnostics() {
+    return this.initializeDiagnostics;
+  }
+  /**
+   * 确保引擎 CLI 已连接（spawn + initialize 握手）。幂等；崩溃后按重建状态机重试：
+   * 初建失败 → 退避 1s/2s/4s 各重建一次（共 1 + CRASH_REBUILD_MAX_ATTEMPTS 次
+   * spawn 尝试），全败标记不可用直到宿主重启（unavailable 恒 throw）。
+   * 版本协商越界 → engine_protocol_mismatch + 直接标记不可用（不重试）。
+   */
+  async ensureConnected() {
+    if (this.disposed) {
+      throw new EngineSdkError(
+        "engine_crashed",
+        `engine client for "${this.engineId}" is disposed`,
+        "Create a new engine client / RemoteEngine instance."
+      );
+    }
+    if (this.state === "unavailable") {
+      throw this.unavailableReason ?? new Error(`engine "${this.engineId}" is unavailable`);
+    }
+    if (this.state === "ready") return;
+    if (this.connectInFlight) return this.connectInFlight;
+    this.connectInFlight = this.connectWithRebuild();
+    try {
+      await this.connectInFlight;
+    } finally {
+      this.connectInFlight = void 0;
+    }
+  }
+  async connectWithRebuild() {
+    this.state = "connecting";
+    if (!this.pidfileSwept) {
+      this.pidfileSwept = true;
+      const sweep = sweepEnginePidfiles({
+        engineDataDir: this.opts.dataDir,
+        engineId: this.engineId,
+        currentHostPid: process.pid,
+        matchesEngineCmdline: this.opts.engineCmdlineMatcher ?? defaultEngineCmdlineMatcher(this.opts.command)
+      });
+      if (sweep.killed.length > 0) {
+        logger8.warn(
+          `[engine-client:${this.engineId}] startup sweep killed stale orphan engine pids: ${sweep.killed.join(",")}`
+        );
+      }
+      for (const removed of sweep.removed) {
+        logger8.debug(`[engine-client:${this.engineId}] swept stale pidfile ${removed.file}: ${removed.reason}`);
+      }
+    }
+    let attempt = 0;
+    while (attempt <= CRASH_REBUILD_MAX_ATTEMPTS) {
+      if (attempt > 0) {
+        const backoff = CRASH_REBUILD_BACKOFF_MS[attempt - 1];
+        logger8.warn(
+          `[engine-client:${this.engineId}] rebuild attempt ${attempt}/${CRASH_REBUILD_MAX_ATTEMPTS} after ${backoff}ms backoff`
+        );
+        await delay(backoff);
+        if (this.disposed) return;
+      }
+      try {
+        await this.spawnAndInitialize();
+        this.state = "ready";
+        return;
+      } catch (err) {
+        this.teardownProcess("handshake failed");
+        if (err instanceof EngineSdkError && err.code === "engine_protocol_mismatch") {
+          this.markUnavailable(err);
+          throw err;
+        }
+        attempt += 1;
+        if (attempt > CRASH_REBUILD_MAX_ATTEMPTS) {
+          const failure = err instanceof Error ? err : new Error(String(err));
+          const unavailable = new EngineSdkError(
+            "engine_crashed",
+            `engine "${this.engineId}" failed to start after ${1 + CRASH_REBUILD_MAX_ATTEMPTS} attempts (initial + ${CRASH_REBUILD_MAX_ATTEMPTS} rebuilds): ${failure.message}`,
+            "Fix or reinstall the engine package, then restart the host. The engine stays unavailable until the next host start."
+          );
+          this.markUnavailable(unavailable);
+          throw unavailable;
+        }
+      }
+    }
+  }
+  markUnavailable(reason) {
+    this.state = "unavailable";
+    this.unavailableReason = reason;
+    logger8.error(`[engine-client:${this.engineId}] marked unavailable: ${reason.message}`);
+  }
+  /** spawn 引擎 CLI + initialize 握手 + 版本协商 + 诊断留痕。 */
+  async spawnAndInitialize() {
+    this.intentionalKill = false;
+    const platformOpts = engineSpawnPlatformOptions();
+    const baseEnv = this.opts.baseEnv ?? { ...process.env };
+    const launch = await resolveEngineNodeLaunch({
+      entryPath: this.opts.command,
+      args: this.opts.args,
+      hostKind: hostKindOf(this.opts.hostKind, baseEnv),
+      env: baseEnv
+    });
+    const env = buildEngineChildEnv(baseEnv, {
+      dataDir: this.opts.dataDir,
+      engineNode: this.opts.engineNode ?? launch.command,
+      electronRunAsNode: this.opts.electronRunAsNode ?? launch.electronRunAsNode,
+      relay: this.opts.relay,
+      identityEnv: this.opts.identityEnv,
+      envPrefixes: this.opts.envPrefixes,
+      processEnv: this.opts.processEnv
+    });
+    this.child = spawn(launch.command, launch.args, {
+      cwd: this.opts.cwd,
+      env,
+      ...platformOpts,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const child = this.child;
+    child.on("error", (err) => {
+      logger8.warn(`[engine-client:${this.engineId}] spawn error: ${err.message}`);
+      this.appendStderrTail(`spawn error: ${err.message}
+`);
+    });
+    for (const pipe of ["stdin", "stdout", "stderr"]) {
+      child[pipe]?.on("error", (err) => {
+        logger8.debug(`[engine-client:${this.engineId}] ${pipe} pipe error (engine died concurrently = expected): ${err.message}`);
+      });
+    }
+    child.stdout?.setEncoding("utf-8");
+    child.stdout?.on("data", (chunk) => this.onStdoutData(chunk));
+    child.stderr?.setEncoding("utf-8");
+    child.stderr?.on("data", (chunk) => this.appendStderrTail(chunk));
+    child.on("exit", (code, signal) => this.onEngineExit(code, signal));
+    if (child.pid !== void 0) {
+      this.pidfileWritten = registerEnginePidfile({
+        engineDataDir: this.opts.dataDir,
+        engineId: this.engineId,
+        hostKind: this.opts.hostKind,
+        hostPid: process.pid,
+        enginePid: child.pid
+      });
+    }
+    this.attachFrameReader();
+    const initParams = {
+      protocolVersion: ENGINE_PROTOCOL_VERSION,
+      hostInfo: {
+        name: this.opts.hostKind,
+        version: this.opts.hostVersion ?? process.version,
+        dataRoot: this.opts.dataDir
+      },
+      engineConfig: this.opts.engineConfig ?? {}
+    };
+    let result;
+    try {
+      result = await this.request("initialize", initParams, {
+        timeoutMs: HANDSHAKE_TIMEOUT_MS
+      });
+    } catch (err) {
+      if (err instanceof EngineSdkError && err.code === "engine_handshake_timeout") {
+        throw new EngineSdkError(
+          "engine_handshake_timeout",
+          `engine "${this.engineId}" did not answer initialize within ${HANDSHAKE_TIMEOUT_MS}ms`,
+          "Check that the engine package is executable and speaks engine-protocol v1. The engine is marked unavailable until it answers a handshake."
+        );
+      }
+      throw err;
+    }
+    if (!isProtocolVersionCompatible(result.protocolVersion)) {
+      throw engineProtocolMismatchError(result.protocolVersion);
+    }
+    this.initializeDiagnostics = result;
+    warnOnManifestDiagnostics(this.engineId, this.opts.manifestDiagnostics, result);
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // stdout 行解析与帧路由
+  // ─────────────────────────────────────────────────────────────────────────
+  attachFrameReader() {
+    this.stdoutBuffer = "";
+  }
+  onStdoutData(chunk) {
+    this.stdoutBuffer += chunk;
+    let newlineIndex = this.stdoutBuffer.indexOf("\n");
+    while (newlineIndex >= 0) {
+      const line = this.stdoutBuffer.slice(0, newlineIndex).replace(/\r$/, "");
+      this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+      if (line.trim().length > 0) this.handleLine(line);
+      newlineIndex = this.stdoutBuffer.indexOf("\n");
+    }
+  }
+  handleLine(line) {
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch {
+      logger8.warn(
+        `[engine-client:${this.engineId}] dropped non-NDJSON stdout line (protocol contract: stdout is NDJSON-only): ${truncate(line, FRAME_ECHO_MAX_CHARS)}`
+      );
+      return;
+    }
+    if (isResponseFrame(frame)) {
+      this.onResponseFrame(frame);
+      return;
+    }
+    if (isNotificationFrame(frame)) {
+      this.onEventNotification(frame.params.runId, frame.params.event);
+      return;
+    }
+    if (isReverseRequestFrame(frame)) {
+      this.onReverseRequest(frame);
+      return;
+    }
+    logger8.warn(
+      `[engine-client:${this.engineId}] dropped unrecognized frame: ${truncate(line, FRAME_ECHO_MAX_CHARS)}`
+    );
+  }
+  onResponseFrame(frame) {
+    if (typeof frame.id !== "number") return;
+    const pending = this.pending.get(frame.id);
+    if (!pending) return;
+    this.pending.delete(frame.id);
+    if (pending.timer !== void 0) clearTimeout(pending.timer);
+    const error = frame.error;
+    if (error !== void 0 && typeof error === "object") {
+      pending.reject(
+        new EngineSdkError(
+          typeof error.code === "string" ? error.code : "engine_unknown",
+          typeof error.message === "string" ? error.message : JSON.stringify(error),
+          typeof error.recovery === "string" ? error.recovery : "Inspect the engine error and retry."
+        )
+      );
+      return;
+    }
+    pending.resolve(frame.result);
+  }
+  onEventNotification(runId, event) {
+    this.runRoutes.get(runId)?.onEvent?.(event);
+  }
+  /** 帧④入口（路由实现见 reverse-router.ts——超时域二分的 core 侧语义所在）。 */
+  onReverseRequest(frame) {
+    routeReverseRequest(this.reverseRouterDeps, frame);
+  }
+  // ── 正向请求 ────────────────────────────────────────────────────────────
+  /**
+   * 发帧①并等帧②。opts.timeoutMs = 数据面超时域（initialize 等）；不传 = 任务级
+   * 默认无超时（run，AGENTS.md 规则 19 / ADR-0047）。
+   */
+  request(method, params, opts) {
+    if (this.state === "disposed" || this.state === "unavailable") {
+      return Promise.reject(
+        this.unavailableReason ?? new EngineSdkError(
+          "engine_crashed",
+          `engine client for "${this.engineId}" is ${this.state}`,
+          "Rebuild the connection via ensureConnected or recreate the client."
+        )
+      );
+    }
+    const id = this.nextRequestId++;
+    const frame = { id, method, params };
+    return new Promise((resolve4, reject) => {
+      const pending = { resolve: resolve4, reject, timer: void 0 };
+      if (opts?.timeoutMs !== void 0) {
+        pending.timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(
+            new EngineSdkError(
+              method === "initialize" ? "engine_handshake_timeout" : "engine_request_timeout",
+              `engine "${this.engineId}" did not answer ${method} (id=${id}) within ${opts.timeoutMs}ms`,
+              "Retry the operation; if it persists the engine process is faulted and will be rebuilt."
+            )
+          );
+        }, opts.timeoutMs);
+      }
+      this.pending.set(id, pending);
+      if (!this.writeFrame(frame)) {
+        this.pending.delete(id);
+        if (pending.timer !== void 0) clearTimeout(pending.timer);
+        reject(
+          engineCrashedError(
+            `stdin write failed while sending ${method}`,
+            this.stderrTail
+          )
+        );
+      }
+    });
+  }
+  /** 注册 run 作用域反向通知路由；返回注销函数。 */
+  registerRunRoute(runId, route) {
+    this.runRoutes.set(runId, route);
+    return () => {
+      if (this.runRoutes.get(runId) === route) this.runRoutes.delete(runId);
+    };
+  }
+  /** [W3 v1.x] 注册 chat 轮次路由（recordId 键）；分发见 reverse-router.ts
+   *  （与 runRoutes 同构，键空间互斥：runId=run 帧分配 / recordId=宿主铸造）。 */
+  registerRecordRoute(recordId, route) {
+    this.recordRoutes.set(recordId, route);
+    return () => {
+      if (this.recordRoutes.get(recordId) === route) this.recordRoutes.delete(recordId);
+    };
+  }
+  /** 健康检查（ADR-0047：静默 ≠ 卡死，不据此杀任务）。 */
+  async ping() {
+    await this.ensureConnected();
+    await this.request("ping", {});
+  }
+  /** cancel 受理窗口 = CANCEL_SETTLE_GRACE_MS；终态收敛由调用方（RemoteEngine）等 run 应答。 */
+  async cancelRun(runId, reason) {
+    await this.request("cancel", { runId, reason }, { timeoutMs: CANCEL_SETTLE_GRACE_MS });
+  }
+  // ── 收割 / 停机 ──────────────────────────────────────────────────────────
+  /**
+   * 宿主收割入口（D8 killAllSpawnedChildren 落点）：组杀引擎 CLI（POSIX 负 pid 组杀 /
+   * Windows taskkill /T /F）+ 镜像整体置死 + pidfile 清理。在途请求以 engine_crashed
+   * 失败。「零残留」断言范围 = 一代子进程 + 组内后代（引擎自身 detached 后代不覆盖，
+   * impl-plan §7.2 R9-1 / 设计 §3.9 已接受代价）。
+   */
+  async killAll(reason) {
+    this.intentionalKill = true;
+    const child = this.child;
+    if (child !== void 0 && child.pid !== void 0 && child.exitCode === null) {
+      killProcessTree(child.pid, reason, { engineId: this.engineId });
+      await waitForChildExit(child, SIGKILL_REAP_TIMEOUT_MS);
+    }
+    this.teardownProcess(reason);
+  }
+  /**
+   * 协议 dispose：dispose 帧（3s 上界）→ 组杀兜底 → 清理。幂等。
+   * dispose 后首个 run 的重建由新的连接状态机承担（EnginePort.dispose 契约）。
+   */
+  async dispose() {
+    if (this.state === "disposed") return;
+    if (this.state === "ready" && this.child !== void 0 && this.child.exitCode === null) {
+      try {
+        await this.request("dispose", {}, { timeoutMs: DISPOSE_GRACE_MS });
+      } catch (err) {
+        logger8.debug(
+          `[engine-client:${this.engineId}] dispose frame failed, falling back to kill chain: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    await this.killAll("dispose");
+    this.state = "disposed";
+  }
+  /** 引擎进程 exit：镜像整体置死 + pidfile 清理 + 在途请求失败 + 状态回落。 */
+  onEngineExit(code, signal) {
+    const detail = signal !== null ? `signal ${signal}` : `exit code ${code}`;
+    if (this.intentionalKill) {
+      logger8.debug(`[engine-client:${this.engineId}] engine exited after intentional kill (${detail}) \u2014 expected`);
+    } else {
+      logger8.warn(`[engine-client:${this.engineId}] engine process exited unexpectedly (${detail})`);
+    }
+    this.teardownProcess(detail);
+    this.state = "exited";
+  }
+  /**
+   * 进程死亡 / 失败后的统一清理：镜像整体置死（失效语义 2+3：killed=true 广播后
+   * 清空）→ pidfile 删 → 在途请求 engine_crashed（附 stderr 尾）→ run 路由清空。
+   */
+  teardownProcess(detail) {
+    this.mirror.killAll();
+    if (this.pidfileWritten !== void 0) {
+      removePidfile(this.pidfileWritten);
+      this.pidfileWritten = void 0;
+    }
+    const err = engineCrashedError(detail, this.stderrTail);
+    for (const [, pending] of this.pending) {
+      if (pending.timer !== void 0) clearTimeout(pending.timer);
+      pending.reject(err);
+    }
+    this.pending.clear();
+    this.runRoutes.clear();
+    this.recordRoutes.clear();
+    this.lastPartialHandle = void 0;
+    if (this.child !== void 0) {
+      const child = this.child;
+      this.child = void 0;
+      const alreadyDead = child.exitCode !== null || child.signalCode !== null;
+      if (!alreadyDead && !this.intentionalKill && child.pid !== void 0) {
+        killProcessTree(child.pid, detail, { engineId: this.engineId });
+      }
+      child.removeAllListeners();
+    }
+    if (this.state !== "unavailable" && this.state !== "disposed") {
+      this.state = "exited";
+    }
+  }
+  // ── pidfile ──────────────────────────────────────────────────────────────
+  // ── 帧写出口 ────────────────────────────────────────────────────────────
+  writeFrame(frame) {
+    const stdin = this.child?.stdin;
+    if (stdin === void 0 || stdin === null || this.child === void 0 || this.child.exitCode !== null) {
+      return false;
+    }
+    try {
+      stdin.write(`${JSON.stringify(frame)}
+`);
+      return true;
+    } catch (err) {
+      logger8.debug(
+        `[engine-client:${this.engineId}] stdin write failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return false;
+    }
+  }
+  sendResponse(id, result) {
+    return this.writeFrame({ id, result });
+  }
+  appendStderrTail(chunk) {
+    this.stderrTail = (this.stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+  }
+};
+function delay(ms) {
+  return new Promise((resolve4) => {
+    setTimeout(resolve4, ms);
+  });
+}
+function truncate(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max)}...`;
+}
+
+// src/execution/engine/client/remote-engine.ts
+import {
+  CANCEL_SETTLE_GRACE_MS as CANCEL_SETTLE_GRACE_MS2,
+  EngineSdkError as EngineSdkError2
+} from "@zhushanwen/subagent-engine-sdk";
+
+// src/execution/engine/common/capability-gate.ts
+import { engineConversationUnsupportedError } from "@zhushanwen/subagent-engine-sdk";
+
+// src/execution/engine/common/errors.ts
+var EngineError = class extends Error {
+  code;
+  /** 恢复指引：指向具体下一步（命令 / 配置路径 / 替代方案），非安慰性文案。 */
+  recovery;
+  constructor(code, detail, recovery) {
+    super(`${code}: ${detail}`);
+    this.name = "EngineError";
+    this.code = code;
+    this.recovery = recovery;
+  }
+  /** 结构化投影（InteractResult.code/message 与 GUI 警告条共用形态）。 */
+  toStructured() {
+    return { code: this.code, message: this.message, recovery: this.recovery };
+  }
+};
+
+// src/execution/engine/common/capability-gate.ts
+var MANIFEST_RECOVERY_TAIL = "\u4FEE manifest capabilities / \u5347\u7EA7\u5F15\u64CE\u5305\uFF08\u82E5\u5F15\u64CE\u5B9E\u9645\u652F\u6301\u8BE5\u80FD\u529B\uFF09";
+function assertTaskShapeSupported(engineId, caps, task) {
+  if (task.conversation === true && caps.conversation === "unsupported") {
+    throw engineConversationUnsupportedError(engineId);
+  }
+  if (task.fork === true || task.forkFromSessionFile !== void 0) {
+    if (caps.steer === "unsupported" && caps.conversation === "unsupported") {
+      throw new EngineError(
+        "engine_capability_unsupported",
+        `engine '${engineId}' \u4E0D\u652F\u6301 fork${task.forkFromSessionFile !== void 0 ? "\uFF08fork-from \u540C\u4E3A\u7236 session \u4E0A\u4E0B\u6587\u7EE7\u627F\uFF09" : ""}\uFF08fork \u4F9D\u8D56\u7236 session \u4E0A\u4E0B\u6587\u7EE7\u627F\uFF0Ccapabilities.steer = '${caps.steer}' / conversation = '${caps.conversation}'\u2014\u2014\u5F15\u64CE\u65E0\u7236 session \u5206\u53C9\u901A\u9053\uFF09`,
+        `\u628A\u6240\u9700\u7236\u4E0A\u4E0B\u6587\u5199\u8FDB task \u6B63\u6587\u540E\u4E0D\u4F20 fork\uFF0C\u6216 ${MANIFEST_RECOVERY_TAIL}`
+      );
+    }
+  }
+  if (task.maxTurns !== void 0 && caps.maxTurns === false) {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' \u4E0D\u652F\u6301 maxTurns\uFF08capabilities.maxTurns = false\uFF0C\u8F6E\u6570\u4E0A\u9650\u4F9D\u8D56 turn_end \u4E8B\u4EF6\u6D41\uFF0C\u672C\u5F15\u64CE\u65E0\u6B64\u8BED\u4E49\u2014\u2014\u9759\u9ED8\u4E22\u5F03\u4F1A\u9020\u6210\u300C\u4F20\u4E86\u4E0A\u9650\u5374\u5931\u63A7\u300D\u7684\u5047\u8C61\uFF09`,
+      `\u53BB\u6389 maxTurns \u53C2\u6570\u91CD\u6D3E\uFF0C\u6216 ${MANIFEST_RECOVERY_TAIL}`
+    );
+  }
+  if ((task.worktree === true || typeof task.worktree === "object") && caps.sandbox === "none") {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' \u4E0D\u652F\u6301 worktree \u9694\u79BB\uFF08capabilities.sandbox = 'none'\uFF0C\u5F15\u64CE\u672A\u63A5\u6587\u4EF6\u7CFB\u7EDF\u9694\u79BB\u5C42\uFF09`,
+      `\u53BB\u6389 worktree \u53C2\u6570\uFF08\u5728 parent cwd \u6267\u884C\uFF09\uFF0C\u6216 ${MANIFEST_RECOVERY_TAIL}`
+    );
+  }
+}
+function assertGateCapabilitiesMatched(engineId, manifestCaps, answeredCaps) {
+  if (manifestCaps.conversation !== "unsupported" && answeredCaps.conversation === "unsupported") {
+    throw gateMismatchError(engineId, "conversation", manifestCaps.conversation, answeredCaps.conversation);
+  }
+  const manifestForkCapable = manifestCaps.steer !== "unsupported" || manifestCaps.conversation !== "unsupported";
+  const answeredForkCapable = answeredCaps.steer !== "unsupported" || answeredCaps.conversation !== "unsupported";
+  if (manifestForkCapable && !answeredForkCapable) {
+    throw gateMismatchError(
+      engineId,
+      "fork\uFF08steer/conversation \u901A\u9053\u65CF\uFF09",
+      `steer=${manifestCaps.steer}/conversation=${manifestCaps.conversation}`,
+      `steer=${answeredCaps.steer}/conversation=${answeredCaps.conversation}`
+    );
+  }
+  if (manifestCaps.maxTurns === true && answeredCaps.maxTurns === false) {
+    throw gateMismatchError(engineId, "maxTurns", String(manifestCaps.maxTurns), String(answeredCaps.maxTurns));
+  }
+  if (manifestCaps.sandbox !== "none" && answeredCaps.sandbox === "none") {
+    throw gateMismatchError(engineId, "sandbox\uFF08worktree\uFF09", manifestCaps.sandbox, answeredCaps.sandbox);
+  }
+}
+function gateMismatchError(engineId, cap, declared, answered) {
+  return new EngineError(
+    "engine_capability_mismatch",
+    `engine '${engineId}' manifest \u58F0\u660E\u7684\u80FD\u529B\u4F4D '${cap}'\uFF08${declared}\uFF09\u4E0E\u5F15\u64CE initialize \u5E94\u7B54\u4E0D\u7B26\uFF08${answered}\uFF09\u2014\u2014manifest \u591A\u58F0\u660E\uFF0C\u4EFB\u52A1\u6309 gate \u5224\u636E\u653E\u884C\u540E\u5F15\u64CE\u65E0\u6CD5\u5151\u73B0`,
+    `\u4FEE manifest capabilities\uFF08\u4E0E\u5F15\u64CE\u5B9E\u9645\u80FD\u529B\u5BF9\u9F50\uFF09\u6216\u5347\u7EA7\u5F15\u64CE\u5305\uFF1B\u82E5\u4EFB\u52A1\u4E0D\u518D\u9700\u8981\u8BE5\u80FD\u529B\uFF0C\u8C03\u6574\u4EFB\u52A1\u53C2\u6570\u540E\u91CD\u6D3E`
+  );
+}
+
+// src/execution/engine/client/remote-engine.ts
+function matchCatalogEntry(entries, ref) {
+  return entries.find(
+    (entry) => entry.id === ref || entry.canonicalRef === ref || entry.aliases?.includes(ref) === true
+  );
+}
+var RemoteEngine = class {
+  id;
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+    this.id = opts.engineId;
+    if (opts.manifest.modelCatalog === void 0 || opts.manifest.modelCatalog === null) {
+      this.validateModel = void 0;
+    }
+  }
+  /** 直读 manifest 注册期快照（无缓存——每次调用同值，快照不可变）。 */
+  capabilities() {
+    return this.opts.manifest.capabilities;
+  }
+  /**
+   * listModels 三态映射（必写死）：
+   *   省略 modelCatalog / models null → 返回 null（buildCoreAlignedHint 语义）；
+   *   显式 `models: []` → 返回 []（buildEmptyModelsHint）；
+   *   数组 → 原样返回。
+   */
+  listModels() {
+    const catalog = this.opts.manifest.modelCatalog;
+    if (catalog === void 0 || catalog === null) return null;
+    return catalog.models;
+  }
+  /**
+   * validateModel 同源 manifest 判定（成员在 catalog 省略时已被构造器摘除）：
+   *   命中（id/canonicalRef/alias 全等）→ {canonicalRef: entry.canonicalRef ?? entry.id}；
+   *   未命中且 dynamic:false → throw engine_model_unknown（同步拒，record 不创建）；
+   *   未命中且 dynamic:true → 放行，返回原样 ref（运行期以引擎为权威
+   *   engine_model_mismatch；无斜杠 ref 的 core 侧拆分 = 契约变更④，归 W3）。
+   * modelRef undefined（查引擎缺省）对静态目录恒属未命中：dynamic:true 放行回空串
+   * （缺省模型无静态 canonical 形态，运行期自证）；dynamic:false 同步拒。
+   */
+  validateModel(modelRef) {
+    const catalog = this.opts.manifest.modelCatalog;
+    if (!catalog || modelRef === void 0 || modelRef.trim() === "") {
+      if (catalog?.dynamic === false) {
+        throw new EngineSdkError2(
+          "engine_model_unknown",
+          `engine '${this.id}' declares a static model catalog (dynamic:false) and has no engine-default entry; an explicit \`model\` ref from the catalog is required.`,
+          "Retry with an exact model id from the engine's model list (engine listModels), or declare the engine-default entry in the manifest modelCatalog."
+        );
+      }
+      return { canonicalRef: modelRef ?? "" };
+    }
+    const entry = matchCatalogEntry(catalog.models, modelRef);
+    if (entry !== void 0) {
+      return { canonicalRef: entry.canonicalRef ?? entry.id };
+    }
+    if (catalog.dynamic === false) {
+      throw new EngineSdkError2(
+        "engine_model_unknown",
+        `model '${modelRef}' is not in engine '${this.id}' static model catalog (dynamic:false)`,
+        "Retry with an exact model id from the engine's model list (engine listModels), or fix the manifest modelCatalog / upgrade the engine package."
+      );
+    }
+    return { canonicalRef: modelRef };
+  }
+  async probe(probeOpts) {
+    await this.opts.client.ensureConnected();
+    const report = await this.opts.client.request("probe", {
+      force: probeOpts?.force ?? false
+    });
+    return report;
+  }
+  /**
+   * 协议 run 映射。task 收窄为引擎面子集（model/schemaEnv/cwd/engineFallback 改挂
+   * run.params.ctx，协议层单列——SDK AgentCallOpts 注释的字段裁决）；事件经 run 作用域
+   * 路由分发（event 通知 / streamDelta / poolResolved / handleReady）；abort → cancel
+   * 帧 + 3s 收敛窗口（超时杀链）。运行中失败不 reject——合成 error outcome + 正常
+   * handle 返回（EnginePort 契约：record 必须收尾）；run 帧发出前的失败（连接/握手）
+   * reject。childSpawned/childStateChanged 镜像归 EngineClient（协议形态无
+   * ChildProcess 实例，ctx.onChildSpawned 不调用——W6 起生命周期谓词读镜像）。
+   */
+  async run(task, ctx) {
+    await this.opts.client.ensureConnected();
+    const answeredCaps = this.opts.client.getInitializeDiagnostics()?.capabilities;
+    if (answeredCaps !== void 0) {
+      assertGateCapabilitiesMatched(this.id, this.opts.manifest.capabilities, answeredCaps);
+    }
+    const runId = ctx.taskId;
+    const runParams = buildRunParams(task, ctx, runId);
+    const unregister = this.opts.client.registerRunRoute(runId, buildRunRouteHandlers(ctx));
+    const abort = wireAbortSignal(this.opts.client, runId, ctx);
+    try {
+      const result = await this.opts.client.request("run", runParams);
+      return { handle: { data: result.handle }, outcome: result.outcome };
+    } catch (err) {
+      if (abort.isCancelSent()) {
+        return {
+          handle: { data: this.synthesizeHandle(ctx.poolKey) },
+          outcome: abortedRunOutcome(this.id, runId, err)
+        };
+      }
+      if (isTransientRunFailure(err)) {
+        return {
+          handle: { data: this.synthesizeHandle(ctx.poolKey) },
+          outcome: transientRunOutcome(this.id, err)
+        };
+      }
+      throw err;
+    } finally {
+      abort.dispose();
+      unregister();
+    }
+  }
+  async interact(handle, action) {
+    await this.opts.client.ensureConnected();
+    const result = await this.opts.client.request("interact", {
+      handle: handle.data,
+      action
+    });
+    return result;
+  }
+  /**
+   * [W3 v1.x] chat 轮次反向通道路由注册（recordId 键，EnginePort 可选面实现）：
+   * interact 续聊轮的 streamDelta / roundLifecycle 分发目标。薄委托 EngineClient
+   * 的 recordRoutes（键分发见 reverse-router.ts）。
+   */
+  registerChatRoundRoute(recordId, route) {
+    return this.opts.client.registerRecordRoute(recordId, route);
+  }
+  /** 协议 read（dataDir 必填——引擎数据根，构造注入）。 */
+  async read(handle) {
+    await this.opts.client.ensureConnected();
+    const view = await this.opts.client.request("read", {
+      handle: handle.data,
+      dataDir: this.opts.dataDir
+    });
+    return view;
+  }
+  /** 协议 dispose（幂等）→ EngineClient 停机清理（镜像置死 + pidfile + 组杀兜底）。 */
+  async dispose() {
+    await this.opts.client.dispose();
+  }
+  /** 运行中失败的合成 handle：handleReady 回填优先，缺省回退请求期 ctx。 */
+  synthesizeHandle(poolKey) {
+    const partial = this.opts.client.getPartialHandle();
+    const diag = this.opts.client.getInitializeDiagnostics();
+    return {
+      v: 1,
+      engineId: this.id,
+      sessionRef: partial?.sessionRef ?? {},
+      poolKey: partial?.poolKey ?? poolKey,
+      engineVersion: diag?.engineVersion,
+      adapterVersion: diag?.adapterVersion ?? `remote-engine/${this.id}`
+    };
+  }
+};
+function isTransientRunFailure(err) {
+  if (!(err instanceof EngineSdkError2)) return false;
+  return err.code === "engine_crashed" || err.code === "engine_request_timeout" || err.code === "engine_handshake_timeout";
+}
+function buildRunParams(task, ctx, runId) {
+  const ctxModelRef = ctx.ctxModel ? `${ctx.ctxModel.provider}/${ctx.ctxModel.id}` : void 0;
+  return {
+    runId,
+    task: toSdkTaskSubset(task),
+    ctx: {
+      poolKey: ctx.poolKey,
+      cwd: task.cwd ?? process.cwd(),
+      model: task.model,
+      schemaEnv: ctx.schemaEnv ?? task.schemaEnv,
+      ctxModel: ctxModelRef,
+      engineFallback: ctx.engineFallback,
+      streamMode: ctx.stream !== void 0 ? "stream" : void 0
+    },
+    ...ctx.chat !== void 0 ? { chat: ctx.chat } : {}
+  };
+}
+function buildRunRouteHandlers(ctx) {
+  return {
+    onEvent: (event) => ctx.onEvent?.(event),
+    onStreamDelta: (delta) => ctx.stream?.onDelta(delta),
+    onPoolResolved: (poolKey) => ctx.onPoolResolved?.(poolKey),
+    onHandleReady: (partial) => ctx.onHandleReady?.(partial),
+    // [W3 v1.x] 首轮（run 会话形态）轮次生命周期帧（runId 键）→ 宿主消费口。
+    onRoundLifecycle: (phase) => ctx.onRoundLifecycle?.(phase)
+  };
+}
+function wireAbortSignal(client, runId, ctx) {
+  let cancelSent = false;
+  let settled = false;
+  let settleTimer;
+  const onAbort = () => {
+    if (cancelSent || settled) return;
+    cancelSent = true;
+    void client.cancelRun(runId, "abort").catch(() => {
+    });
+    settleTimer = setTimeout(() => {
+      if (!settled) {
+        void client.killAll(`cancel did not settle within grace for run ${runId}`);
+      }
+    }, CANCEL_SETTLE_GRACE_MS2);
+  };
+  if (ctx.signal !== void 0) {
+    if (ctx.signal.aborted) onAbort();
+    else ctx.signal.addEventListener("abort", onAbort, { once: true });
+  }
+  return {
+    isCancelSent: () => cancelSent,
+    dispose: () => {
+      settled = true;
+      if (settleTimer !== void 0) clearTimeout(settleTimer);
+      if (ctx.signal !== void 0) ctx.signal.removeEventListener("abort", onAbort);
+    }
+  };
+}
+function abortedRunOutcome(engineId, runId, err) {
+  return {
+    content: "",
+    error: `engine_run_failed: run ${runId} aborted before terminal answer${err instanceof Error ? ` (${err.message})` : ""}`,
+    exitCode: null,
+    engineId
+  };
+}
+function transientRunOutcome(engineId, err) {
+  return {
+    content: "",
+    error: err instanceof Error ? err.message : String(err),
+    exitCode: null,
+    engineId
+  };
+}
+function toSdkTaskSubset(task) {
+  return {
+    prompt: task.prompt,
+    schema: task.schema,
+    thinkingLevel: task.thinkingLevel,
+    scene: task.scene,
+    maxTurns: task.maxTurns,
+    graceTurns: task.graceTurns,
+    skill: task.skill,
+    skillPath: task.skillPath,
+    description: task.description,
+    agent: task.agent,
+    appendSystemPrompt: task.appendSystemPrompt,
+    fork: task.fork,
+    // fork-from 源（fork-from 轮次 --fork 的协议载体，W3 断链修复）：host-task-spec
+    // 已把 ExecuteOptions.forkFromSessionFile 改名为 task.forkSource，此处同名透传。
+    // 缺省 undefined 不落 wire（JSON 序列化丢弃，与相邻可选字段同语义）。
+    forkSource: task.forkSource,
+    worktree: task.worktree,
+    conversation: task.conversation,
+    idleTimeoutMs: task.idleTimeoutMs,
+    denyTools: task.denyTools,
+    permissionMode: task.permissionMode
+  };
+}
+
+// src/execution/engine/host/host-ui-endpoint.ts
+var ENDPOINT_SLOT_KEY = /* @__PURE__ */ Symbol.for(
+  "@zhushanwen/pi-subagent-workflow.hostUiRequestEndpoint"
+);
+function endpointSlot() {
+  let slot = Reflect.get(globalThis, ENDPOINT_SLOT_KEY);
+  if (!slot) {
+    slot = { handler: void 0 };
+    Reflect.set(globalThis, ENDPOINT_SLOT_KEY, slot);
+  }
+  return slot;
+}
+function setHostUiRequestEndpoint(handler) {
+  endpointSlot().handler = handler;
+}
+function getHostUiRequestEndpoint() {
+  return endpointSlot().handler;
+}
+
+// src/execution/engine/engine-inspect-package.ts
+var logger9 = getLogger("subagents");
+function readEnginePackageJson(pkgDir) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path2.join(pkgDir, "package.json"), "utf8");
+  } catch (err) {
+    return { status: "skip", reason: `package.json unreadable: ${errorMessage(err)}` };
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch (err) {
+    return { status: "skip", reason: `package.json is not valid JSON: ${errorMessage(err)}` };
+  }
+  if (typeof pkg !== "object" || pkg === null) {
+    return { status: "skip", reason: "package.json is not an object" };
+  }
+  return { pkg };
+}
+function extractEngineManifest(pkg) {
+  const agentNs = pkg["xyz-agent"];
+  if (typeof agentNs !== "object" || agentNs === null) {
+    return { skipReason: "no xyz-agent.subagentEngine manifest (not an engine package)" };
+  }
+  const manifest = agentNs["subagentEngine"];
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+    return { skipReason: "xyz-agent.subagentEngine is not an object" };
+  }
+  return { manifest };
+}
+function validateRequiredManifestFields(m) {
+  const id = m["id"];
+  if (typeof id !== "string" || id.trim() === "") {
+    return { status: "skip", reason: "manifest id is required (non-empty string)" };
+  }
+  const manifestBin = m["bin"];
+  if (typeof manifestBin !== "string" || manifestBin.trim() === "") {
+    return { status: "skip", reason: `engine '${id}': manifest bin is required (non-empty string)` };
+  }
+  const protocol = m["protocol"];
+  if (typeof protocol !== "number" || !Number.isInteger(protocol)) {
+    return {
+      status: "skip",
+      reason: `engine '${id}': manifest protocol is required (integer; got ${describeValue(protocol)})`
+    };
+  }
+  if (!isProtocolVersionCompatible2(protocol)) {
+    return {
+      status: "unusable",
+      id,
+      reason: `engine '${id}': manifest protocol ${protocol} is not compatible (core supports >=1 <2) \u2014 upgrade the engine package or the host core`
+    };
+  }
+  return { id, manifestBin, protocol };
+}
+function resolveVerifiedEngineBin(pkgDir, pkg, manifestBin, id) {
+  const binPath = resolveManifestBin(pkgDir, pkg, manifestBin);
+  if (binPath === void 0) {
+    return {
+      status: "skip",
+      reason: `engine '${id}': manifest bin '${manifestBin}' does not resolve via package.json bin`
+    };
+  }
+  if (!canExecute(binPath)) {
+    return {
+      status: "unusable",
+      id,
+      reason: `engine '${id}': bin not found or not executable: ${binPath}`
+    };
+  }
+  return { binPath };
+}
+function parseOptionalDisplayFields(m, id) {
+  let displayName;
+  const rawDisplayName = m["displayName"];
+  if (rawDisplayName !== void 0) {
+    if (typeof rawDisplayName === "string" && rawDisplayName.trim() !== "") {
+      displayName = rawDisplayName;
+    } else {
+      logger9.warn(`[engine-discovery] engine '${id}': displayName must be a non-empty string \u2014 ignoring`);
+    }
+  }
+  const rawDescription = m["description"];
+  if (rawDescription !== void 0 && typeof rawDescription !== "string") {
+    logger9.warn(`[engine-discovery] engine '${id}': description must be a string \u2014 ignoring`);
+  }
+  return displayName;
+}
+function buildManifestCliDescriptor(params) {
+  const { id, binPath, hostKind, env, caps, envPrefixes, modelCatalog, displayName, manifestSnapshot } = params;
+  return {
+    kind: "cli",
+    command: binPath,
+    args: [],
+    capabilities: caps,
+    portFactory: () => {
+      const dataDir = getEngineDataDir(env);
+      const client = new EngineClient({
+        engineId: id,
+        command: binPath,
+        args: [],
+        hostKind,
+        dataDir,
+        envPrefixes,
+        // [W6 R3 MF-A] host/askUser 应答端：壳侧登记处在 portFactory 惰性执行期取值
+        //（晚于 session_start 注册，未注册 → undefined → 引擎收 {unsupported:true}）。
+        uiRequestHandler: getHostUiRequestEndpoint(),
+        manifestDiagnostics: {
+          capabilities: caps,
+          models: modelCatalog === void 0 || modelCatalog === null ? null : modelCatalog.models
+        }
+      });
+      return new RemoteEngine({
+        engineId: id,
+        client,
+        manifest: manifestSnapshot,
+        dataDir,
+        hostKind
+      });
+    },
+    manifest: {
+      ...modelCatalog !== void 0 ? { modelCatalog } : {},
+      ...displayName !== void 0 ? { displayName } : {}
+    }
+  };
+}
+function inspectEnginePackage(pkgDir, source, hostKind, env) {
+  const pkgStep = readEnginePackageJson(pkgDir);
+  if (!("pkg" in pkgStep)) return pkgStep;
+  const manifestStep = extractEngineManifest(pkgStep.pkg);
+  if (!("manifest" in manifestStep)) return { status: "skip", reason: manifestStep.skipReason };
+  const m = manifestStep.manifest;
+  const fields = validateRequiredManifestFields(m);
+  if ("reason" in fields) return fields;
+  const { id, manifestBin } = fields;
+  const binStep = resolveVerifiedEngineBin(pkgDir, pkgStep.pkg, manifestBin, id);
+  if (!("binPath" in binStep)) return binStep;
+  const caps = parseCapabilities(id, m["capabilities"]);
+  const envPrefixes = parseEnvPrefixes(id, m["envPrefixes"]);
+  const modelCatalog = parseModelCatalog(id, m["modelCatalog"]);
+  const displayName = parseOptionalDisplayFields(m, id);
+  const manifestSnapshot = {
+    capabilities: caps,
+    ...modelCatalog !== void 0 ? { modelCatalog } : {}
+  };
+  const descriptor = buildManifestCliDescriptor({
+    id,
+    binPath: binStep.binPath,
+    hostKind,
+    env,
+    caps,
+    envPrefixes,
+    modelCatalog,
+    displayName,
+    manifestSnapshot
+  });
+  return { status: "ok", entry: { id, source, descriptor } };
+}
+function canExecute(p) {
+  try {
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/execution/engine/engine-discovery-roots.ts
+import * as fs2 from "fs";
+import * as path3 from "path";
+var logger10 = getLogger("subagents");
+var ENGINE_ROOTS_ENV = "XYZ_AGENT_ENGINE_ROOTS";
+function parseEngineRootsEnv(env) {
+  const raw = env[ENGINE_ROOTS_ENV];
+  if (raw === void 0 || raw.trim() === "") return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const part of raw.split(path3.delimiter)) {
+    const dir = part.trim();
+    if (dir === "") continue;
+    if (!path3.isAbsolute(dir)) {
+      logger10.warn(
+        `[engine-discovery] ${ENGINE_ROOTS_ENV} entry '${dir}' is not an absolute path \u2014 dropping entry`
+      );
+      continue;
+    }
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    out.push(dir);
+  }
+  return out;
+}
+function deriveNodeModuleRoots(argvEntry = process.argv[1]) {
+  if (!argvEntry || argvEntry.trim() === "") return [];
+  const roots = [];
+  let dir = path3.dirname(path3.resolve(argvEntry));
+  while (true) {
+    const nm = path3.join(dir, "node_modules");
+    if (isDirectory(nm)) roots.push(nm);
+    const parent = path3.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return roots;
+}
+function scanEngineRoot(root, visit) {
+  let entries;
+  try {
+    entries = fs2.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const item of entries) {
+    if (!item.isDirectory()) continue;
+    const dir = path3.join(root, item.name);
+    if (isFile(path3.join(dir, "package.json"))) {
+      visit(dir);
+      continue;
+    }
+    let sub;
+    try {
+      sub = fs2.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const child of sub) {
+      if (!child.isDirectory()) continue;
+      const subDir = path3.join(dir, child.name);
+      if (isFile(path3.join(subDir, "package.json"))) visit(subDir);
+    }
+  }
+}
+function isDirectory(p) {
+  try {
+    return fs2.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function isFile(p) {
+  try {
+    return fs2.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// src/execution/engine/config.ts
+import * as fs3 from "fs";
+import * as path4 from "path";
+var logger11 = getLogger("subagents");
+function readExplicitEngines(agentDir) {
+  const configPath = path4.join(agentDir, "subagents", "config.json");
+  let parsed;
+  try {
+    parsed = JSON.parse(fs3.readFileSync(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null) return {};
+  const engines = parsed["engines"];
+  if (typeof engines !== "object" || engines === null || Array.isArray(engines)) {
+    if (engines !== void 0) {
+      logger11.warn(
+        `[engine-discovery] config.json engines section must be an object keyed by engine id, got ${jsonKindOf(engines)} \u2014 ignoring L3 explicit engines`
+      );
+    }
+    return {};
+  }
+  const out = {};
+  for (const [id, raw] of Object.entries(engines)) {
+    const entry = sanitizeExplicitEntry(id, raw);
+    if (entry !== void 0) out[id] = entry;
+  }
+  return out;
+}
+function sanitizeExplicitEntry(id, raw) {
+  const v = requireEntryObject(id, raw);
+  if (v === void 0) return void 0;
+  if (v["enabled"] === false) return void 0;
+  const command = requireCommand(id, v["command"]);
+  if (command === void 0) return void 0;
+  return {
+    command,
+    ...normalizeArgs(id, v["args"]),
+    ...normalizeConfig(id, v["config"]),
+    ...normalizeCwd(id, v["cwd"])
+  };
+}
+function requireEntryObject(id, raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    logger11.warn(
+      `[engine-discovery] config.json engines.${id} must be an object, got ${jsonKindOf(raw)} \u2014 skipping entry`
+    );
+    return void 0;
+  }
+  return raw;
+}
+function requireCommand(id, command) {
+  if (typeof command !== "string" || command.trim() === "") {
+    logger11.warn(
+      `[engine-discovery] config.json engines.${id}.command is required (non-empty string) \u2014 skipping entry`
+    );
+    return void 0;
+  }
+  return command;
+}
+function normalizeArgs(id, args) {
+  if (args !== void 0 && !isStringArray(args)) {
+    logger11.warn(
+      `[engine-discovery] config.json engines.${id}.args must be a string array \u2014 ignoring args`
+    );
+  }
+  return { args: isStringArray(args) ? args : [] };
+}
+function normalizeConfig(id, config) {
+  if (config !== void 0 && !isStringRecord(config)) {
+    logger11.warn(
+      `[engine-discovery] config.json engines.${id}.config must be a Record<string, string> \u2014 ignoring config`
+    );
+  }
+  return isStringRecord(config) ? { config } : {};
+}
+function normalizeCwd(id, cwd) {
+  if (cwd !== void 0 && typeof cwd !== "string") {
+    logger11.warn(
+      `[engine-discovery] config.json engines.${id}.cwd must be a string \u2014 ignoring cwd`
+    );
+  }
+  return typeof cwd === "string" ? { cwd } : {};
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isStringRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((item) => typeof item === "string");
+}
+function jsonKindOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+// src/execution/engine/registry.ts
+var logger12 = getLogger("subagents");
+var DEFAULT_ENGINE_ID = "pi";
+function normalizeEngineId(engine) {
+  return engine?.trim() || DEFAULT_ENGINE_ID;
+}
+var EngineNotFoundError = class extends Error {
+  /** 结构化错误码（错误规格表的 code 列，供调用方程序化分流）。 */
+  code = "engine_not_found";
+  /** 请求的（未注册的）引擎 id。 */
+  engineId;
+  /** 请求时刻的已注册清单快照（防错误对象跨时间读 Map 的失真）。 */
+  registered;
+  /** 错误来源定位（agent .md 文件路径 / 配置键等；运行期 getEngine 无来源不传）。 */
+  source;
+  constructor(engineId, registered, source) {
+    super(
+      `engine_not_found: engine '${engineId}' is not registered. Registered engines: ${registered.length > 0 ? registered.join(", ") : "(none)"}. ` + (registered.length === 0 ? `No engine packages were discovered. Recovery: install an engine package (e.g. @zhushanwen/pi-subagent-cli / @zhushanwen/zcode-subagent-cli), or add its location to XYZ_AGENT_ENGINE_ROOTS / subagents/config.json engines section.` : `Recovery: check the engine id in the agent .md frontmatter (engine: field) or the global default engine setting, fix the typo, or install/register the engine first (registered engines are listed above).`) + (source !== void 0 ? ` Source: ${source}.` : "")
+    );
+    this.name = "EngineNotFoundError";
+    this.engineId = engineId;
+    this.registered = registered;
+    this.source = source;
+  }
+};
+var ENGINE_REGISTRY_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/pi-subagent-workflow.engineRegistry");
+function getRegistrySlot() {
+  let slot = Reflect.get(globalThis, ENGINE_REGISTRY_SLOT_KEY);
+  if (!slot) {
+    slot = { descriptors: /* @__PURE__ */ new Map(), singletons: /* @__PURE__ */ new Map() };
+    Reflect.set(globalThis, ENGINE_REGISTRY_SLOT_KEY, slot);
+  }
+  return slot;
+}
+function portFactoryOf(descriptor) {
+  return descriptor.kind === "inproc" ? descriptor.factory : descriptor.portFactory;
+}
+function triggerEngineDispose(engine, source) {
+  if (typeof engine.dispose !== "function") return;
+  try {
+    engine.dispose().then(void 0, (err) => {
+      logger12.warn(
+        `[engine-registry] engine '${engine.id}' dispose rejected (${source}, best-effort continue): ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+  } catch (err) {
+    logger12.warn(
+      `[engine-registry] engine '${engine.id}' dispose threw synchronously (${source}, best-effort continue): ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function registerEngineDescriptor(id, descriptor) {
+  const slot = getRegistrySlot();
+  const previous = slot.singletons.get(id);
+  if (previous) triggerEngineDispose(previous, `registerEngineDescriptor('${id}') overwrite`);
+  slot.descriptors.set(id, descriptor);
+  slot.singletons.delete(id);
+}
+function getEngine(id) {
+  const slot = getRegistrySlot();
+  const cached = slot.singletons.get(id);
+  if (cached) return cached;
+  const descriptor = slot.descriptors.get(id);
+  if (!descriptor) {
+    throw new EngineNotFoundError(id, listEngines());
+  }
+  const engine = portFactoryOf(descriptor)();
+  slot.singletons.set(id, engine);
+  return engine;
+}
+function hasEngine(id) {
+  return getRegistrySlot().descriptors.has(id);
+}
+function listEngines() {
+  return [...getRegistrySlot().descriptors.keys()];
+}
+function listEnginesByDisplayName() {
+  const slot = getRegistrySlot();
+  const keyed = [...slot.descriptors.entries()].map(([id, descriptor]) => {
+    const displayName = descriptor.kind === "cli" ? descriptor.manifest?.displayName ?? id : id;
+    return { id, displayName };
+  });
+  keyed.sort(
+    (a, b) => a.displayName !== b.displayName ? a.displayName < b.displayName ? -1 : 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+  );
+  return keyed.map((k) => k.id);
+}
+
+// src/execution/engine/engine-discovery-scan.ts
+var logger13 = getLogger("subagents");
+function scanEngines(opts) {
+  const env = opts.env ?? process.env;
+  const result = { discovered: [], skipped: [], unusable: [] };
+  const present = (entry) => {
+    const idx = result.discovered.findIndex((d) => d.id === entry.id);
+    if (idx >= 0) {
+      logger13.debug(
+        `[engine-discovery] engine id '${entry.id}' from '${entry.source}' overrides earlier discovery from '${result.discovered[idx].source}' \u2014 same-id override`
+      );
+      result.discovered[idx] = entry;
+      return;
+    }
+    result.discovered.push(entry);
+  };
+  const visitManifestPackage = (pkgDir, source) => {
+    const inspection = inspectEnginePackage(pkgDir, source, opts.hostKind, env);
+    if (inspection.status === "skip") {
+      if (!inspection.reason.includes("not an engine package")) {
+        logger13.warn(`[engine-discovery] skipping ${pkgDir} (${source}): ${inspection.reason}`);
+        result.skipped.push({ pkgDir, reason: inspection.reason });
+      }
+      return;
+    }
+    if (inspection.status === "unusable") {
+      logger13.warn(`[engine-discovery] engine unavailable: ${inspection.reason}`);
+      result.unusable.push({ pkgDir, id: inspection.id, reason: inspection.reason });
+      return;
+    }
+    present(inspection.entry);
+  };
+  for (const dir of parseEngineRootsEnv(env)) {
+    scanEngineRoot(dir, (pkgDir) => visitManifestPackage(pkgDir, ENGINE_ROOTS_ENV));
+  }
+  const hostRoots = [
+    ...getHostServices().discoveryRoots?.().engines ?? [],
+    ...opts.extraRoots ?? []
+  ];
+  for (const root of hostRoots) {
+    scanEngineRoot(root.dir, (pkgDir) => visitManifestPackage(pkgDir, root.source));
+  }
+  const nodeRoots = opts.nodeModuleRoots ?? deriveNodeModuleRoots();
+  for (const dir of nodeRoots) {
+    scanEngineRoot(dir, (pkgDir) => visitManifestPackage(pkgDir, "node-modules"));
+  }
+  if (opts.agentDir !== void 0) {
+    for (const [id, entry] of Object.entries(readExplicitEngines(opts.agentDir))) {
+      const command = resolveExplicitCommand(entry.command, env);
+      if (command === void 0) {
+        const reason = `engine '${id}' (config.json engines.${id}): command '${entry.command}' not found or not executable`;
+        logger13.warn(`[engine-discovery] ${reason} \u2014 not registering`);
+        result.unusable.push({ pkgDir: `config.json engines.${id}`, id, reason });
+        continue;
+      }
+      present(buildExplicitDescriptor(id, command, entry, opts));
+    }
+  }
+  return result;
+}
+var loadedDiscoveryIdSet = /* @__PURE__ */ new Set();
+function discoverAndRegisterEngines(opts) {
+  const result = scanEngines(opts);
+  for (const entry of result.discovered) {
+    const existed = hasEngine(entry.id);
+    registerEngineDescriptor(entry.id, entry.descriptor);
+    loadedDiscoveryIdSet.add(entry.id);
+    if (existed) {
+      logger13.debug(
+        `[engine-discovery] engine '${entry.id}' descriptor overwritten in registry (source '${entry.source}') \u2014 same-id override`
+      );
+    }
+  }
+  return result;
+}
+function loadedDiscoveryIds() {
+  return [...loadedDiscoveryIdSet];
+}
+function ensureEngineDiscovered(id, opts) {
+  if (hasEngine(id)) return true;
+  discoverAndRegisterEngines(opts);
+  return hasEngine(id);
+}
+function resolveExplicitCommand(command, env) {
+  if (command.includes("/") || command.includes("\\")) {
+    const p = path5.isAbsolute(command) ? command : path5.resolve(command);
+    return canExecute(p) ? p : void 0;
+  }
+  const pathVar = env["PATH"] ?? env["Path"] ?? "";
+  for (const dir of pathVar.split(path5.delimiter)) {
+    if (dir === "") continue;
+    const p = path5.join(dir, command);
+    if (canExecute(p)) return p;
+  }
+  return void 0;
+}
+function buildExplicitDescriptor(id, command, entry, opts) {
+  const env = opts.env ?? process.env;
+  logger13.debug(
+    `[engine-discovery] engine '${id}' registered from config.json engines section with conservative capabilities (no manifest)`
+  );
+  const caps = { ...CONSERVATIVE_CAPABILITIES };
+  const descriptor = {
+    kind: "cli",
+    command,
+    args: entry.args,
+    capabilities: caps,
+    portFactory: () => {
+      const dataDir = opts.dataDir ?? getEngineDataDir(env);
+      const client = new EngineClient({
+        engineId: id,
+        command,
+        args: entry.args,
+        ...entry.cwd !== void 0 ? { cwd: entry.cwd } : {},
+        hostKind: opts.hostKind,
+        dataDir,
+        envPrefixes: [],
+        // [W6 R3 MF-A] 同上：host/askUser 应答端经壳侧登记处接线。
+        uiRequestHandler: getHostUiRequestEndpoint(),
+        ...entry.config !== void 0 ? { engineConfig: entry.config } : {},
+        manifestDiagnostics: { capabilities: caps, models: null }
+      });
+      return new RemoteEngine({
+        engineId: id,
+        client,
+        manifest: { capabilities: caps },
+        dataDir,
+        hostKind: opts.hostKind,
+        ...entry.config !== void 0 ? { engineConfig: entry.config } : {}
+      });
+    }
+  };
+  return {
+    id,
+    source: "config.json",
+    ...entry.config !== void 0 ? { engineConfig: entry.config } : {},
+    descriptor
+  };
+}
+
+export {
+  DEFAULT_DATA_ROOT,
+  configureCore,
+  getHostServices,
+  getLogger,
+  EngineError,
+  DEFAULT_ENGINE_ID,
+  normalizeEngineId,
+  EngineNotFoundError,
+  registerEngineDescriptor,
+  getEngine,
+  hasEngine,
+  listEngines,
+  listEnginesByDisplayName,
+  CONSERVATIVE_CAPABILITIES,
+  resolveManifestBin,
+  parseCapabilities,
+  parseEnvPrefixes,
+  parseModelCatalog,
+  getEngineDataDir,
+  EngineClient,
+  assertTaskShapeSupported,
+  RemoteEngine,
+  setHostUiRequestEndpoint,
+  inspectEnginePackage,
+  ENGINE_ROOTS_ENV,
+  parseEngineRootsEnv,
+  deriveNodeModuleRoots,
+  scanEngines,
+  discoverAndRegisterEngines,
+  loadedDiscoveryIds,
+  ensureEngineDiscovered
+};