@zhushanwen/subagent-core 0.2.0

package/src/execution/output-collector.ts

@@ -0,0 +1,228 @@
+// src/core/output-collector.ts
+//
+// 结果收集器（Record + CollectResultArgs → AgentResult）。
+//
+// 收口设计（2026-06-22）：collectResult 全部从 record 读——
+//   text ← getFullText(record)（聚合 turns[].text，不再读 session.messages）
+//   turns ← record.turnCount
+//   toolCalls ← getAllToolCalls(record)（扁平化 turns[].toolCalls）
+//   usage ← getTotalUsage(record)（聚合 turns[].usageDelta）
+//
+// 基础层模块：依赖 execution-record（派生函数）+ types。
+
+import type {
+  AgentResult,
+  ExecutionRecord,
+  ToolCall,
+} from "./types.ts";
+import {
+  getAllToolCalls,
+  getFullText,
+  getTotalUsage,
+} from "./execution-record.ts";
+// [F-R1] 值引用 stale-context 分诊 pattern 表（SSOT 在 execute-agent-call，消费点
+// isStaleContextErrorMsg 同源）。execution → orchestration 值引用有先例
+// （agent-registry.ts → script-lint.ts），且 execute-agent-call 对 execution 仅剩
+// type-only import（已擦除），无运行时循环。
+// [MF-1] 同向引用确定性失败标记前缀（SSOT 同在 execute-agent-call，同一布局理由）。
+import {
+  DETERMINISTIC_SCHEMA_FAILURE_PREFIX,
+  STALE_CONTEXT_PATTERNS,
+} from "../orchestration/execute-agent-call.ts";
+
+// ============================================================
+// Result 收集
+// ============================================================
+
+/** collectResult 的入参（session 身份 + 执行控制字段，执行内容从 record 读）。 */
+export interface CollectResultArgs {
+  startTime: number;
+  success: boolean;
+  error: string | undefined;
+  sessionId: string;
+  sessionFile: string | undefined;
+  /**
+   * [F-1] 本次执行是否要求结构化产出（opts.schema 或 opts.schemaEnv 任一存在）。
+   * true 且 run 结束仍无有效 parsedOutput 时：结果不得静默 success——置 success=false
+   * 并把三态失败归因写进 error（上层 executeAgentCall 只看 error 判 completed/failed）。
+   * 缺省 false（非 schema 模式 parsedOutput===undefined 是正常态，不动成败）。
+   */
+  schemaExpected?: boolean;
+}
+
+/** structured-output tool 名（与 structured-output 扩展 TOOL_NAME 一致，见 session-runner.ts）。 */
+const STRUCTURED_OUTPUT_TOOL = "structured-output";
+
+/** F-1 失败摘要截断长度（字符）：错误详情拼进 run 结果 error 字段，防大 payload 撑爆。 */
+const FAILED_SO_SUMMARY_MAX_CHARS = 300;
+
+/**
+ * 从 toolCalls 提取 structured-output 的 result.details（schema 模式产出）。
+ * schema enforcement 保证 agent 调过该 tool（漏调会 steer 重试）；这里只做逆向提取。
+ * 未调或无 details 返回 undefined。
+ *
+ * [F-1 失败吞没修复] isError:true 的调用一律跳过——失败调用的 details（pi 失败
+ * 路径默认 {}）不是通过 schema 校验的产出，把它当 parsedOutput 会让 gate 终止/
+ * 模型自弃的 run 以 parsedOutput={} 静默 completed。isError 字段缺失（旧 record/
+ * 进行中调用）不误伤——仅显式 true 跳过。
+ *
+ * 导出以便直接单测（纯函数契约）。
+ */
+export function extractParsedOutput(toolCalls: ToolCall[]): unknown {
+  for (let i = toolCalls.length - 1; i >= 0; i--) {
+    const tc = toolCalls[i]!;
+    if (tc.toolName === STRUCTURED_OUTPUT_TOOL && tc.isError !== true && tc.result?.details !== undefined) {
+      return tc.result.details;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * [F-R1] 中和动态错误摘要中的 stale-context 命中词：对每个 STALE_CONTEXT_PATTERNS
+ * 做大小写不敏感的子串替换为 "[redacted]"（分诊 isStaleContextErrorMsg 是
+ * toLowerCase 后的子串匹配，故中和也必须大小写不敏感）。
+ *
+ * 为何只中和动态段（summarizeToolContent 产物）、不中和固定前缀：前缀是本模块
+ * 静态文案，已逐字核对无任何 pattern 命中，且由 output-collector.test.ts 的
+ * "messages avoid STALE_CONTEXT_PATTERNS substrings" 用例锁定；动态段是
+ * 模型/provider 的原始错误文本（可含 "aborted"/"ctx is stale" 等），不受本模块
+ * 控制。不中和的话，拼接结果经 collectResult → result.error 流到
+ * execute-agent-call 的 isStaleContextErrorMsg 分诊，SO 失败归因被误诊为
+ * stale-context → 跳过重试。
+ *
+ * 导出以便直接单测（纯函数契约）。
+ */
+export function neutralizeStalePatterns(text: string): string {
+  let out = text;
+  for (const pattern of STALE_CONTEXT_PATTERNS) {
+    // pattern 当前均为纯小写词/短语（无 regex 元字符），escape 仅为防未来 pattern
+    // 演化引入元字符时静默改变语义。
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    out = out.replace(new RegExp(escaped, "gi"), "[redacted]");
+  }
+  return out;
+}
+
+/**
+ * schema 模式下无有效 parsedOutput 时的三态失败归因（F-1）。
+ *
+ * 返回 undefined 表示 toolCalls 里有可用的 parsedOutput（无需归因）。
+ * 三态判定优先级：校验失败（有 isError 调用）> 从未调用 SO tool > 调用过但无 details。
+ *
+ * [MF-1] 三态可重试性矩阵（标记 SSOT 与消费端判定见 execute-agent-call 的
+ * DETERMINISTIC_SCHEMA_FAILURE_PREFIX / isDeterministicSchemaFailureMsg）：
+ * | 归因态                        | 带标记 | 可重试性 | 理由 |
+ * |------------------------------|-------|---------|------|
+ * | ① 从未调用 SO tool            | 是    | 不可重试 | 缺 extension 是环境确定性（C1 安装盲区），同环境重试必同结果 |
+ * | ② SO 调用 isError（gate 终止/不可满足 schema） | 是 | 不可重试 | 同 schema 重试必同结果（第五轮实测 retry 放大回归：3 attempts/4 子进程/235s） |
+ * | ③ 调用过但无 details           | 否    | 可重试   | 可能瞬态（details 提取/序列化异常），保留既有重试语义 |
+ *
+ * 文案约束：不得命中 execute-agent-call 的 STALE_CONTEXT_PATTERNS（"aborted" 等
+ * 子串）——命中会被误诊为 stale-context 跳过重试。固定前缀（含 MF-1 标记词）静态
+ * 无命中（测试锁定）；动态段经 neutralizeStalePatterns 中和（F-R1）。
+ *
+ * 导出以便直接单测（纯函数契约）。
+ */
+export function describeMissingParsedOutput(toolCalls: ToolCall[]): string | undefined {
+  if (extractParsedOutput(toolCalls) !== undefined) return undefined;
+  const soCalls = toolCalls.filter((tc) => tc.toolName === STRUCTURED_OUTPUT_TOOL);
+  if (soCalls.length === 0) {
+    // 覆盖独立安装盲区（C1）：schema enforcement 依赖 SO extension 注册 tool，
+    // 未安装时 agent 无工具可调、steer 无法生效——只能在这里事后暴露。
+    // [MF-1] 态① 带确定性标记：缺 extension 是环境确定性，不重试。
+    return (
+      `${DETERMINISTIC_SCHEMA_FAILURE_PREFIX} ` +
+      "Agent finished without producing a structured output: the structured-output tool was never called. " +
+      "Recovery: verify the structured-output extension is installed and enabled for this agent, " +
+      "and that the agent's final answer conforms to the requested schema."
+    );
+  }
+  const failed = soCalls.filter((tc) => tc.isError === true);
+  if (failed.length > 0) {
+    const last = failed[failed.length - 1]!;
+    // [F-R1] 先截断后中和：截断边界把 pattern 切断时不产生新命中（半截词本就
+    // 匹配不到分诊子串），完整落入截断窗口的 pattern 一定被中和。
+    const lastErrorSummary = neutralizeStalePatterns(summarizeToolContent(last.result?.content));
+    // [F-R4] 失败原因分类：isError 只说明「调用失败」，原因未必是 schema 校验
+    // （provider 错误/pi abort/扩展内部错误同样走 isError），硬编码
+    // "(schema validation)" 会误导排障。按最后错误的实际内容分类——权威锚点是
+    // structured-output 扩展校验失败的固定文案前缀 "Schema validation failed: ..."
+    //（structured-output/src/execute.ts），大小写不敏感匹配；其余归为 execution
+    // failure。在已中和的摘要上分类：中和仅替换 stale 词，与校验词无交集。
+    const failureKind = lastErrorSummary.toLowerCase().includes("validation failed")
+      ? "schema validation"
+      : "execution failure";
+    // [MF-1] 态② 带确定性标记：gate 终止/不可满足 schema 同 schema 重试必同结果。
+    // 注：failureKind=execution failure（provider 瞬态错误）同样不重试——isError 态
+    // 整体从重试面摘除（实测回归即此态循环烧钱），瞬态恢复交由上层 workflow 编排。
+    return (
+      `${DETERMINISTIC_SCHEMA_FAILURE_PREFIX} ` +
+      `Agent finished without a valid structured output: ${failed.length} structured-output call(s) failed ` +
+      `(${failureKind}). Last error: ${lastErrorSummary}`
+    );
+  }
+  return (
+    "Agent finished without a valid structured output: structured-output was called but none of the " +
+    "successful calls carried result details."
+  );
+}
+
+/** 从 tool result.content 提取可读错误文本（[{type:"text",text}] 形态，防御未知形状）。 */
+function summarizeToolContent(content: unknown): string {
+  let summary = "(no detail)";
+  if (Array.isArray(content)) {
+    const texts = content
+      .map((item) => (item && typeof item === "object" && "text" in item ? String((item as { text: unknown }).text) : ""))
+      .filter((t) => t !== "");
+    if (texts.length > 0) summary = texts.join(" ");
+  } else if (typeof content === "string" && content !== "") {
+    summary = content;
+  }
+  return summary.length > FAILED_SO_SUMMARY_MAX_CHARS
+    ? `${summary.slice(0, FAILED_SO_SUMMARY_MAX_CHARS)}...`
+    : summary;
+}
+
+/**
+ * 从 record + args 组装 AgentResult。每个字段来源单一且收口于 record：
+ *   text      ← getFullText(record)（聚合 turns[].text，单一数据源）
+ *   turns     ← record.turnCount
+ *   toolCalls ← getAllToolCalls(record)（扁平化 turns[].toolCalls）
+ *   usage     ← getTotalUsage(record)（聚合 turns[].usageDelta，全零则 undefined）
+ *   parsedOutput ← extractParsedOutput(toolCalls)
+ *
+ * startTime 算 durationMs。
+ *
+ * success 双来源判定（调用方传入）：
+ *   ① session.prompt() 抛错 → args.success=false
+ *   ② prompt 成功但 record.lastError 非空（message_end stopReason=error）→ success=false
+ */
+export function collectResult(
+  record: ExecutionRecord,
+  args: CollectResultArgs,
+): AgentResult {
+  const toolCalls = getAllToolCalls(record);
+  const parsedOutput = extractParsedOutput(toolCalls);
+  const result: AgentResult = {
+    text: getFullText(record),
+    turns: record.turnCount,
+    durationMs: Date.now() - args.startTime,
+    success: args.success,
+    error: args.error,
+    sessionId: args.sessionId,
+    toolCalls,
+    usage: getTotalUsage(record),
+    sessionFile: args.sessionFile,
+    parsedOutput,
+  };
+  // [F-1 失败吞没修复] schema 模式下 run 结束仍无有效 parsedOutput 时不得静默
+  // success：只在「本将成功」的路径上标注（success=false 的路径已有真实 error/
+  // abort 语义，不覆写）。error 经 mapToWorkflowAgentResult（仅 !success 透传）
+  // → executeAgentCall（error!==undefined 即 failed）逐层可见。
+  if (args.schemaExpected === true && result.success && parsedOutput === undefined) {
+    result.success = false;
+    result.error = describeMissingParsedOutput(toolCalls) ?? result.error;
+  }
+  return result;
+}

package/src/execution/path-encoding.ts

@@ -0,0 +1,60 @@
+// src/core/path-encoding.ts
+//
+// cwd → 安全目录名的编码逻辑。Core 叶子原语（零依赖）。
+//
+// 被 session-runner（subagent session 持久化目录）与 session-file-gc（清理过期
+// session 文件）共用——两处需要相同的编码，否则同一 cwd 会落到两个不同目录。
+
+import * as path from "node:path";
+
+/**
+ * cwd → 安全目录名。复用 Pi SDK getDefaultSessionDir 的编码逻辑：
+ * 去开头单个分隔符，全量替换剩余分隔符/冒号为 `-`，首尾补 `--`。
+ * 例：`/Users/x/proj` → `--Users-x-proj--`。
+ */
+export function encodeCwd(cwd: string): string {
+  return "--" + cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-") + "--";
+}
+
+/**
+ * 获取 subagent session 持久化目录路径。
+ *
+ * D-004: 用主 cwd 编码——保证同一主 cwd 下所有 subagent 的 session 文件
+ * 存放在同一目录，便于 session-file-gc 统一清理。
+ * [MF-3] worktree 模式下调用方必须传树根 cwd（ROOT mainCwd，经 PI_SUBAGENT_ROOT_CWD
+ * 贯穿），不能传子进程自身的 checkout 路径——否则深层 record 落盘到 enc(worktree) 段，
+ * ROOT 磁盘重建扫不到（全树可见性断裂）。根进程传自身 cwd（行为不变）。
+ *
+ * @param agentDir agent 配置目录（如 ~/.pi/agent）
+ * @param mainCwd 树根主 agent 的工作目录（非 subagent 的 effectiveCwd；worktree 模式下
+ *   是 ROOT 的 cwd，不是 checkout 路径）
+ * @returns session 持久化目录绝对路径
+ */
+export function getSubagentSessionDir(agentDir: string, mainCwd: string): string {
+  // [MF#1] 保持既有布局 subagents/<enc>/sessions/——曾改为 subagents/sessions/<enc>/ 会让
+  // 升级用户的既有 session 文件全部落到扫描目录外（历史记录消失 + GC 扫不到，双重 orphan）。
+  // 本分支未发布，回退到既有布局即无需迁移、无数据丢失。
+  return path.join(agentDir, "subagents", encodeCwd(mainCwd), "sessions");
+}
+
+/**
+ * 获取 subagent records（manifest）持久化目录路径。
+ *
+ * 与 getSubagentSessionDir 同用 encodeCwd(mainCwd)，保证 records 与 sessions 在同一
+ * <enc> 段下物理相邻。
+ * [MF-3] 调用方必须与 getSubagentSessionDir 传同一编码键（进程内 init.cwd /
+ * buildSessionRunnerContext.mainCwd / record.worktreeHandle.mainCwd 恒等；worktree 模式
+ * 跨进程时统一用贯穿的 ROOT cwd）——sessions 与 records 两套目录同段，GC/重建才不会
+ * 互相找不到（enc 段不变量）。
+ *
+ * D-004 同源：用主 cwd 编码做物理隔离，使 session-file-gc 按 <enc>/records/ 子目录
+ * 匹配 manifest .json 时天然限定在当前 cwd 范围内，不会越界清理其他 cwd 的 manifest。
+ *
+ * @param agentDir agent 配置目录（如 ~/.pi/agent）
+ * @param mainCwd 树根主 agent 的工作目录（非 subagent 的 effectiveCwd；worktree 模式下
+ *   是 ROOT 的 cwd，不是 checkout 路径）
+ * @returns records 持久化目录绝对路径
+ */
+export function getSubagentRecordsDir(agentDir: string, mainCwd: string): string {
+  return path.join(agentDir, "subagents", encodeCwd(mainCwd), "records");
+}

package/src/execution/pi-invocation.ts

@@ -0,0 +1,120 @@
+// src/execution/pi-invocation.ts
+//
+// 定位 pi 二进制并组装 spawn 调用。Core 叶子原语（仅依赖 node 内置）。
+//
+// spawn 改造（in-process → spawn pi --mode json）的基座模块。
+// 被 runSpawn（session-runner）调用，决定子进程用哪个命令启动。
+//
+// 移植自 nicobailon subagent example 的 getPiInvocation，处理三种运行时：
+//   1. bun bundle（/$bunfs/root/ 虚拟脚本）→ 退化到 pi-in-PATH
+//   2. 有真实脚本路径（node + script）→ node <script> <args>
+//   3. node/bun generic runtime（无脚本）→ pi <args>（依赖 PATH）
+//
+// 注意：pi 在扩展进程内运行时 process.execPath 是 node/bun，process.argv[1]
+// 是 pi 的入口脚本。子进程需要复现同样的启动方式才能保证扩展/配置一致加载。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { isRelayActive, RELAY_ENV_NODE, RELAY_ENV_SCRIPT } from "./relay-env.ts";
+
+/** spawn 调用描述符：command + args（透传给 child_process.spawn）。 */
+export interface PiInvocation {
+  /** 可执行文件路径（node/bun/pi 二进制）。 */
+  command: string;
+  /** 命令行参数（可能含 [scriptPath, ...userArgs] 或直接 [...userArgs]）。 */
+  args: string[];
+}
+
+/** getPiInvocation 可选项。 */
+export interface PiInvocationOptions {
+  /**
+   * false = 强制直连 spawn 真实 pi（不经 relay 代理）。唯一现役消费点是 PiEngine.probe
+   * ——探针意图是 pi 本体可解析性，经 relay 探到的是 runtime 健康，语义错位（E 方案 §5.1）。
+   * 缺省（undefined / true）时按 relay env 激活判定走代理。
+   */
+  relay?: boolean;
+}
+
+/**
+ * bun 虚拟文件系统前缀。bun bundle 模式下 process.argv[1] 形如
+ * /$bunfs/root/pi——这不是磁盘上的真实文件，不能直接 spawn。
+ */
+const BUN_VIRTUAL_PREFIX = "/$bunfs/root/";
+
+/**
+ * 判断 execPath 的 basename 是否为通用运行时（node/bun）。
+ * 通用运行时需要脚本路径才能启动 pi；非通用（如 pi 的 standalone binary）可直接执行。
+ */
+function isGenericRuntime(execPath: string): boolean {
+  const execName = path.basename(execPath).toLowerCase();
+  return /^(node|bun)(\.exe)?$/.test(execName);
+}
+
+/**
+ * 组装 pi 子进程的 spawn 调用。
+ *
+ * @param userArgs pi CLI 参数（如 ["--mode", "rpc", "--session-dir", "..."]）
+ * @param opts 可选项（relay:false 强制直连——probe 用，见 PiInvocationOptions）
+ * @returns spawn 描述符（command + 完整 args）
+ *
+ * 决策链（按优先级）：
+ *   0. relay 激活（三 env 齐备且未显式禁用）→ <RELAY_NODE> <RELAY_SCRIPT> <userArgs>
+ *      （E 方案 §5.1：xyz-agent runtime 存在时经代理 spawn，改的是进程拓扑不是 pi 语义）
+ *   1. process.argv[1] 是真实磁盘文件且非 bun 虚拟路径 → <execPath> <argv[1]> <userArgs>
+ *      （复现当前 pi 进程的启动方式，确保扩展/配置/版本一致）
+ *   2. execPath 非通用运行时（pi standalone binary）→ <execPath> <userArgs>
+ *   3. 通用运行时但无可用脚本路径 → "pi" <userArgs>（依赖 PATH 中可找到 pi）
+ */
+// [perf] 决策链只依赖 process.argv[1] / process.execPath（进程内恒定），其中唯一的
+// 磁盘探测（existsSync）结果 memo 一次——每次 spawn 免重复 syscall。memo 键含
+// argv[1] 值：测试 mock 切换 argv[1] 模拟不同运行时时自动失效重算。
+let scriptExistsCache: { script: string | undefined; exists: boolean } | undefined;
+
+/** process.argv[1] 是真实磁盘脚本（非 bun 虚拟路径）且存在。 */
+function currentScriptExists(): boolean {
+  const currentScript = process.argv[1];
+  if (scriptExistsCache === undefined || scriptExistsCache.script !== currentScript) {
+    scriptExistsCache = {
+      script: currentScript,
+      exists:
+        currentScript !== undefined &&
+        !currentScript.startsWith(BUN_VIRTUAL_PREFIX) &&
+        fs.existsSync(currentScript),
+    };
+  }
+  return scriptExistsCache.exists;
+}
+
+export function getPiInvocation(userArgs: string[], opts?: PiInvocationOptions): PiInvocation {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith(BUN_VIRTUAL_PREFIX);
+
+  // 分支 0（前置）：relay 激活（E 方案 §5.1）——runtime 注入三 env 齐备且未显式禁用时，
+  // spawn 目标切换为 <RELAY_NODE> <RELAY_SCRIPT> <原 pi spawnArgs>，形态与分支 1「node +
+  // script」同构（command 是执行器、args[0] 是脚本）。ELECTRON_RUN_AS_NODE 不在此补：
+  // 打包态执行器为 Electron 时由 runtime 与三 env 同点注入主 pi 进程 env（E-2
+  // getRelaySpawnEnv），本进程 {...process.env} 继承即达代理进程，extension 不重复判定。
+  // isRelayActive 已保证三 env 非空，下方取局部变量仅为 TS 收窄（isRelayActive 的
+  // 收窄不跨函数边界传导）。
+  if (opts?.relay !== false && isRelayActive(process.env)) {
+    const relayNode = process.env[RELAY_ENV_NODE];
+    const relayScript = process.env[RELAY_ENV_SCRIPT];
+    if (relayNode !== undefined && relayScript !== undefined) {
+      return { command: relayNode, args: [relayScript, ...userArgs] };
+    }
+  }
+
+  // 分支 1：有真实脚本路径 → 复现启动方式（node <pi-script> <args>）
+  if (currentScript && !isBunVirtualScript && currentScriptExists()) {
+    return { command: process.execPath, args: [currentScript, ...userArgs] };
+  }
+
+  // 分支 2：非通用运行时（pi 自带 binary）→ 直接执行
+  if (!isGenericRuntime(process.execPath)) {
+    return { command: process.execPath, args: userArgs };
+  }
+
+  // 分支 3：通用运行时但脚本不可用 → 依赖 PATH
+  return { command: "pi", args: userArgs };
+}

package/src/execution/record-entry.ts

@@ -0,0 +1,132 @@
+// src/execution/record-entry.ts
+//
+// W16 [D4]：subagent record 自描述持久化 entry 的形态权威。
+//
+// pi 文件（session JSONL）是扩展数据持久化权威：record 状态每次迁移都经
+// pi.appendEntry 落一条自描述完整快照（字段即 SubagentRecord），读取方无需
+// 逆向解析 toolCall/toolResult。内存 record-store 保持运行时权威，entry 是
+// 重建源（两者不冲突）。
+//
+// customType 与既有 `subagent-identity`（session 文件首行身份 entry）同族命名
+//（连字符风格）；写点见 record-store.ts 的状态迁移点（register/archive/
+// reportRecordTransition），custom entry 由 pi 写进 session JSONL，不进 LLM context。
+
+import type {
+  AgentEventLogEntry,
+  ClosedReason,
+  DisplayItem,
+  ExecutionMode,
+  ExecutionStatus,
+  SubagentRecord,
+} from "./types.ts";
+
+/** 自描述 record entry 的 customType。写点字面量与本常量的等值由
+ *  __tests__/record-store.test.ts 断言钉住（消费方引用本常量，勿用裸字符串）。 */
+export const SUBAGENT_RECORD_CUSTOM_TYPE = "subagent-record";
+
+/**
+ * `subagent-record` entry 的 data schema（v1）。
+ *
+ * = 完整 SubagentRecord 快照（GUI 侧列表/详情需要的全部持久化字段）+ 版本号。
+ * 显式排除三个非持久化字段（与 SubagentRecord 的差集）：
+ *   - currentActivity：running 时的瞬时流态，重开 session 无重建价值；
+ *   - externalInstance：跨重启探活态（pid/startedAt），由 .alive sidecar 重建；
+ *   - worktreeHandle：不可 JSON 序列化的运行时句柄（布尔投影 worktree 保留）。
+ *
+ * undefined 字段经 JSON.stringify 自然缺省（与 SubagentRecord 重建侧语义一致）。
+ */
+export interface SubagentRecordEntryData {
+  /** schema 版本（W16 起 v1）。消费方按 v 判别解析，不认识的版本跳过而非猜测。 */
+  v: 1;
+  id: string;
+  agent: string;
+  /** 任务提示词（详情面板置顶展示）。 */
+  task: string;
+  /** 短标签（≤35 字符）。 */
+  slug: string;
+  status: ExecutionStatus;
+  /** L2 关闭原因（仅 status="closed" 时有意义）。 */
+  closedReason?: ClosedReason;
+  mode: ExecutionMode;
+  startedAt: number;
+  /** 根 Pi session ID（session 隔离过滤用）。 */
+  rootSessionId: string | undefined;
+  /** 直接父 subagent record ID（层级树构建用）。顶层为 undefined。 */
+  parentRecordId: string | undefined;
+  /** subagent 递归深度。顶层 = 0。 */
+  depth: number;
+  endedAt: number | undefined;
+  /** turn 计数。 */
+  turns: number;
+  totalTokens: number;
+  model: string;
+  thinkingLevel: string | undefined;
+  /** 详情事件日志（/subagents 详情面板）。 */
+  eventLog: AgentEventLogEntry[];
+  /** 从 turns[] 派生的展示项。 */
+  displayItems: DisplayItem[];
+  result?: string;
+  error?: string;
+  sessionFile?: string;
+  /** [MF#3] worktree 模式改动 patch 文件路径。 */
+  patchFile?: string;
+  /** 创建时是否启用 worktree 隔离。 */
+  worktree?: boolean;
+  /** 对话轮次计数（仅 chatMode 有意义；round+1 由轮终迁移写点携带）。 */
+  round?: number;
+  /**
+   * 对话模式标志（residual-fixes）：chat 与否——GUI 侧 done/waiting 细分判据
+   * （one-shot 轮终 chatMode=false + result 有值 → 完成态）。register 起写入显式值
+   * （one-shot 为显式 false）；v1 前存量 entry 缺省，消费端按保守方向处理。
+   */
+  chatMode?: boolean;
+  /** 执行态信号（residual-fixes）：true = 无活进程驱动的 running（轮终/孤儿兜底）。 */
+  resumable?: boolean;
+  /**
+   * 实际执行引擎 id（P4 路由留痕，D9①）。缺省（存量 entry）= pi 投影，消费方零迁移。
+   */
+  engine?: string;
+  /** 引擎 fallback 留痕（probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+  engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U1：read 降级链①②级数据源）。引擎无关——sessionRef 整体
+   * 透传不枚举内部键（zcode = { sessionId, dbPath }）；缺省 = pi（存量 entry 零迁移）。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
+}
+
+/** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。 */
+export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEntryData {
+  return {
+    v: 1,
+    id: record.id,
+    agent: record.agent,
+    task: record.task,
+    slug: record.slug,
+    status: record.status,
+    closedReason: record.closedReason,
+    mode: record.mode,
+    startedAt: record.startedAt,
+    rootSessionId: record.rootSessionId,
+    parentRecordId: record.parentRecordId,
+    depth: record.depth,
+    endedAt: record.endedAt,
+    turns: record.turns,
+    totalTokens: record.totalTokens,
+    model: record.model,
+    thinkingLevel: record.thinkingLevel,
+    eventLog: record.eventLog,
+    displayItems: record.displayItems,
+    result: record.result,
+    error: record.error,
+    sessionFile: record.sessionFile,
+    patchFile: record.patchFile,
+    worktree: record.worktree,
+    round: record.round,
+    chatMode: record.chatMode,
+    resumable: record.resumable,
+    engine: record.engine,
+    engineFallback: record.engineFallback,
+    engineHandle: record.engineHandle,
+  };
+}