@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/orchestration/lifecycle.ts

@@ -24,7 +24,7 @@
  * 「releaseRuntime → 改 status」原子顺序。
  *
  * **G3-001**（run 一次性生命周期）：AbortController 一次性无法复用，runtime 释放后
- * 只有两类重建——rebuildRuntime（error-recovery，崩溃重试路径，run 保持 running、
+ * 只有两类重建——rebuildRuntime（worker-message-pump，崩溃重试路径，run 保持 running、
  * replaceRuntime 原子换新）与 abort/terminate 的终态释放（transition("done") 内
  * releaseRuntime，run 不再恢复）。
  * （旧并发门闩 gate 抽象已删——no-op 无生产语义，实际并发由 SubagentService
@@ -42,12 +42,11 @@ import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
 import { validateRunArgs } from "./args-validator.ts";
 import {
   closeOutInFlightCalls,
-  emitPendingUnregister,
-  emitTerminalSideEffects,
+  finalizeRun,
   handleWorkerError,
   handleWorkerExit,
   handleWorkerMessage,
-} from "./error-recovery.ts";
+} from "./worker-message-pump.ts";
 import { Budget } from "./models/budget.ts";
 import type { LifecycleDeps, RunStore, WorkerHandlers } from "./models/ports.ts";
 import { RunRuntime } from "./models/run-runtime.ts";
@@ -56,6 +55,7 @@ import { Trace } from "./models/trace.ts";
 import type { DoneReason } from "./models/types.ts";
 import { WorkflowRun } from "./models/workflow-run.ts";
 import type { WorkerHandle } from "./worker-handle.ts";
+import { toErrorMessage } from "../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -118,24 +118,24 @@ function broadcastAbortToWorker(run: WorkflowRun, reason: string): void {
   try {
     run.runtime?.worker.postMessage({ type: "abort", reason });
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = toErrorMessage(err);
     logger.debug(
       `[workflow] abort broadcast to worker failed (runId=${run.runId}, worker likely already exited): ${msg}`,
     );
   }
 }
 
-// ── makeHandlers（路由 worker 事件到 error-recovery handle* 函数） ──────
+// ── makeHandlers（路由 worker 事件到 worker-message-pump handle* 函数） ──────
 
 /**
  * 构造 WorkerHandlers——将 worker 的 onMessage/onError/onExit 事件路由到
- * error-recovery 的 handleWorker* 函数。
+ * worker-message-pump 的 handleWorker* 函数。
  *
  * 闭包捕获 run + deps。runtime 重建（replaceRuntime）后 run 实例不变、deps 不变，
- * 故 handlers 对新 worker 仍有效（lifecycle 与 error-recovery 共用 handlers）。
+ * 故 handlers 对新 worker 仍有效（lifecycle 与 worker-message-pump 共用 handlers）。
  *
  * **onExit G-025**：handleWorkerExit 内部检查 handle.isCurrent（stale exit 丢弃）。
- * 本函数不在 onExit 里重复检查——error-recovery.handleWorkerExit 是单一守卫点。
+ * 本函数不在 onExit 里重复检查——worker-message-pump.handleWorkerExit 是单一守卫点。
  *
  * **workerErrorCount**：onError 触发时递增（C.5 跨 runtime 存活的重试计数载体）。
  * 注意 handleWorkerError 内部也会递增——这里 onError 递增是 worker 事件层面的
@@ -144,10 +144,10 @@ function broadcastAbortToWorker(run: WorkflowRun, reason: string): void {
  */
 function makeHandlers(run: WorkflowRun, deps: LifecycleDeps): WorkerHandlers {
   // [OR-7] per-run deps 视图：包装 onRunDone，把「run 终态」转译为「移除 signal abort
-  // listener」。error-recovery 全部终态路径（handleReturn / handleWorkerError /
+  // listener」。worker-message-pump 全部终态路径（handleReturn / handleWorkerError /
   // handleScriptError / handleWorkerExit / 预算终止 / time_limited / [OR-2] rebuild
-  // 失败收敛）都经 handlers 调用链消费本视图——消息面终态在此统一收口；
-  // abortRun / terminateRunningRuns 两个 lifecycle 自有终态路径另行显式 dispose。
+  // 失败收敛——均经 finalizeRun）都经 handlers 调用链消费本视图——消息面终态在此
+  // 统一收口；abortRun / terminateRunningRuns 两个 lifecycle 自有终态路径另行显式 dispose。
   const depsWithTerminalCleanup: LifecycleDeps = {
     ...deps,
     onRunDone: (doneRun: WorkflowRun): void => {
@@ -155,7 +155,7 @@ function makeHandlers(run: WorkflowRun, deps: LifecycleDeps): WorkerHandlers {
       deps.onRunDone?.(doneRun);
     },
   };
-  // 自引用——error-recovery rebuildRuntime 需要 handlers 参数（handlers 引用自身）
+  // 自引用——worker-message-pump rebuildRuntime 需要 handlers 参数（handlers 引用自身）
   const handlers: WorkerHandlers = {
     async onMessage(raw: unknown): Promise<void> {
       await handleWorkerMessage(run, raw, depsWithTerminalCleanup, handlers);
@@ -198,7 +198,7 @@ export function scheduleTimeBudget(
   const timer = setTimeout(() => {
     void abortRun(runId, deps, "Time budget exceeded", "time_limited").catch(
       (err: unknown) => {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         logger.error(`[workflow] time budget abort failed: ${msg}`);
       },
     );
@@ -213,7 +213,7 @@ export function scheduleTimeBudget(
 /**
  * rfl 仪表（tier-1 §7.1）：向 spec.args 原地注入稳定 _runId。runAndWait 与
  * executeNestedWorkflow 两个 args 入口都经 runWorkflow 这一 choke point；
- * rebuildRuntime 复用 run.spec.args 同一对象（error-recovery.ts），worker rebuild
+ * rebuildRuntime 复用 run.spec.args 同一对象（worker-message-pump.ts），worker rebuild
  * 后脚本侧 $ARGS._runId 不漂移——修复「rebuild 回退 run-<Date.now()> 导致同一
  * 逻辑 run 碎裂到多个 state 目录」。注入在 validateRunArgs 之后，不参与脚本
  * 参数 schema 校验（引擎内部字段）。
@@ -307,7 +307,7 @@ function registerSignalAbortListener(
   const onAbort = (): void => {
     disposeSignalAbortListener(run);
     void abortRun(runId, deps, "External signal aborted").catch((err: unknown) => {
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = toErrorMessage(err);
       logger.error(`[workflow] abortRun on signal failed: ${msg}`);
     });
   };
@@ -426,20 +426,16 @@ export async function abortRun(
   // [OR-3] 先广播 abort 再 transition（transition 内 releaseRuntime→terminate，
   // terminate 之后广播发不进去）——worker 侧 pending 优雅解阻
   broadcastAbortToWorker(run, reason ?? `Workflow aborted (${doneReason})`);
-  // A4: transition 内部 releaseRuntime（cleanup before mutate）
-  run.transition("done", doneReason);
   // [OR-7] run 终态：移除 signal abort listener（幂等；abort 由 signal 触发时
-  // listener 已在 onAbort 内自移除，此处为其余 abort 入口的收口）
+  // listener 已在 onAbort 内自移除，此处为其余 abort 入口的收口；即使 finalizeRun
+  // 因并发终态化让位，WeakMap 条目也应清除，不依赖 transition 成败）
   disposeSignalAbortListener(run);
-  // [OR-8] 终态收口残留 in-flight call（先收口再落盘——快照不再含 running 节点）
-  closeOutInFlightCalls(run);
-  await deps.store.save(run);
-  deps.log?.("debug", "workflow:lifecycle", "abortRun transition done", { runId, reason: run.state.reason });
-  // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
-  // [OR-4][B-4] M12 同款围栏（emit pending:unregister + onRunDone 各自独立 try）——
-  // listener 同步抛错不再跳过 onRunDone 或把错误抛给 abort 调用方；错误 error 留痕后
-  // 本函数仍按 abort 成功语义正常返回（内存态已终态）。
-  emitTerminalSideEffects(run, deps, `abortRun (done,${doneReason})`);
+  // A4 + C-4: transition 内部 releaseRuntime（cleanup before mutate）；到达 done 终态
+  // → 注销 pending-notification + 通知 Interface 层（D5-② 终态 coda 收敛为
+  // worker-message-pump 的 finalizeRun 单写点——OR-8 in-flight 收口 + save best-effort
+  // （SW-DATA-3）不再向上抛，内存态已终态，调用方无需因落盘失败收到 abort 异常；
+  // OR-4/B-4 unregister 与 onRunDone 各自独立围栏）
+  await finalizeRun(run, deps, doneReason, { context: `abortRun (${doneReason})` });
 }
 
 // ── terminateRunningRuns（session 切换/关闭：终止全部 running run） ────────
@@ -451,11 +447,12 @@ export async function abortRun(
  * done,failed 持久化落盘——重启后 kill-9 恢复不误判，也不再存在「挂起待恢复」
  * 的中间态。
  *
- * per-run 行为：`state.error = reason` → `transition("done","failed")`（内部先
- * releaseRuntime，A4）→ `await store.save(run)` → `eventBus.emit("pending:unregister",
- * {reason:"failed"})`。
+ * per-run 行为：`state.error = reason` → `finalizeRun(run, deps, "failed",
+ * {notifyDone:false})`（transition("done","failed") 内部先 releaseRuntime，A4 →
+ * save best-effort → `eventBus.emit("pending:unregister", {reason:"failed"})`）。
  *
- * **不调 deps.onRunDone**：对齐 session_start 恢复先例（index.ts kill-9 恢复只发
+ * **不调 deps.onRunDone**（经 finalizeRun 的 notifyDone:false 承载，D5-②）：
+ * 对齐 session_start 恢复先例（index.ts kill-9 恢复只发
  * unregister、不发 onRunDone）——session 切换/关闭语境下主 agent 已离开本 session，
  * 注入完成通知只会把消息发给已离开的 session。
  *
@@ -480,21 +477,22 @@ export async function terminateRunningRuns(
       run.state.error = reason;
       // [OR-3] 同 abortRun：先广播 abort 再 transition（worker 侧 pending 优雅解阻）
       broadcastAbortToWorker(run, reason);
-      // A4: transition 内部先 releaseRuntime（cleanup before mutate）
-      run.transition("done", "failed");
       // [OR-7] run 终态：移除 signal abort listener（terminateRunningRuns 不走
-      // onRunDone——本路径显式收口）
+      // onRunDone——本路径显式收口，不依赖 finalizeRun 的 notifyDone 分支）
       disposeSignalAbortListener(run);
-      // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
-      closeOutInFlightCalls(run);
-      await deps.store.save(run);
-      // C-4: run 到达 done 终态 → 注销 pending-notification（reason 固定 "failed"）。
-      // [B-4] M12 同款围栏：emit 单独 try（listener 同步抛错 error 留痕不中断本 run
-      // 收尾日志与其余 run 的终止；本路径不调 onRunDone——session 离开语境不发完成通知）。
-      emitPendingUnregister(run, deps, "terminateRunningRuns");
+      // A4 + C-4: transition 内部 releaseRuntime（cleanup before mutate）；done 终态 →
+      // 注销 pending-notification（D5-② 终态 coda 收敛为 finalizeRun 单写点）。
+      // notifyDone: false——**不调 deps.onRunDone**（真差异经参数承载）：对齐
+      // session_start 恢复先例（index.ts kill-9 恢复只发 unregister、不发
+      // onRunDone）——session 切换/关闭语境下主 agent 已离开本 session，注入完成
+      // 通知只会把消息发给已离开的 session。OR-8 in-flight 收口由 finalizeRun 承载。
+      await finalizeRun(run, deps, "failed", {
+        context: "terminateRunningRuns",
+        notifyDone: false,
+      });
       deps.log?.("debug", "workflow:lifecycle", "run terminated", { runId: run.runId, reason: run.state.reason });
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = toErrorMessage(err);
       logger.error(
         `[workflow] terminateRunningRuns failed for run ${run.runId}: ${msg} (reason: ${reason})`,
       );
@@ -644,7 +642,7 @@ export async function recoverCrashedRuns(
       try {
         hooks?.onRunRecovered?.({ id: run.runId, reason: "failed" });
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         logger.warn(
           `[workflow] recoverCrashedRuns onRunRecovered hook failed for run ${run.runId} (recovery continues): ${msg}`,
         );
@@ -653,7 +651,7 @@ export async function recoverCrashedRuns(
       try {
         await store.save(run);
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         logger.error(
           `[workflow] recoverCrashedRuns store.save failed for run ${run.runId}: ${msg} (reason: ${reason})`,
         );

package/src/orchestration/models/ports.ts

@@ -5,7 +5,7 @@
  * 是真需要 mock 测试的依赖（子进程/文件系统/线程）。
  *
  * 编排层共享类型（WorkerHandlers / LifecycleDeps）——打破 lifecycle ↔
- * error-recovery 循环依赖：2 个 engine 函数文件各自独立，共用同一组
+ * worker-message-pump 循环依赖：2 个 engine 函数文件各自独立，共用同一组
  * 依赖签名（D-12）。
  *
  * 层归属：Engine。零 infra 依赖（AC-1）。
@@ -71,7 +71,7 @@ export interface WorkerHost {
 
 /**
  * Worker 线程事件回调集合——WorkerHost.start 的入参，由 lifecycle
- * 构造并注入。2 个 engine 文件（lifecycle / error-recovery）共用此签名，
+ * 构造并注入。2 个 engine 文件（lifecycle / worker-message-pump）共用此签名，
  * 避免各自定义形状不一致的 handler bag（打破循环依赖）。
  *
  * 所有回调返回 Promise——允许 engine 层在回调内做 await persistState 等异步操作。
@@ -88,7 +88,7 @@ export interface WorkerHandlers {
 // ── 编排层共享类型 2: LifecycleDeps ────────────────────────────
 
 /**
- * lifecycle / error-recovery 2 个 engine 函数文件的共同依赖 bag。
+ * lifecycle / worker-message-pump 2 个 engine 函数文件的共同依赖 bag。
  *
  * 取代旧 4 个 Context factory（errorHandlerContext / agentCallContext /
  * budgetCallbacks / 旧 terminate bag，AC-2 目标）。函数签名 `(deps: LifecycleDeps, ...)`
@@ -142,7 +142,7 @@ export interface LifecycleDeps {
  * workflow() 嵌套调用回调（可选）。Worker 脚本内调 workflow(name, args) 时触发。
  *
  * 由 Interface 层 makeDeps 注入（闭包捕获 registry + deps）。Engine 层的
- * error-recovery.handleWorkerMessage 收到 workflow-call 消息后调本回调，
+ * worker-message-pump.handleWorkerMessage 收到 workflow-call 消息后调本回调，
  * 拿到子 workflow 执行结果后 postMessage(workflow-result) 回 worker。
  *
  * 不注入时 workflow() 返回 error result（向后兼容，不影响非嵌套场景）。

package/src/orchestration/models/run-runtime.ts

@@ -7,11 +7,11 @@
  * 职责：封装一次 running-segment 的所有技术资源（worker 线程 +
  * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
  * （旧并发门闩 gate 抽象已删——no-op，实际并发由 SubagentService ConcurrencyPool 管理；
- * 原 withSlot 的 pre-abort 检查内联到 error-recovery dispatchAgentCall。）
+ * 原 withSlot 的 pre-abort 检查内联到 worker-message-pump dispatchAgentCall。）
  *
  * 一次性生命周期（G3-001）：runtime 释放后不再复用——AbortController 一次性
  * 语义决定 controller 无法跨释放复用，所以整个 RunRuntime 重建。唯一注入路径：
- * assignRuntime（runWorkflow 创建）与 replaceRuntime（error-recovery 崩溃重试）。
+ * assignRuntime（runWorkflow 创建）与 replaceRuntime（worker-message-pump 崩溃重试）。
  *
  * 参考：domain-models.md §10、clarification.md G3-001。
  */

package/src/orchestration/models/trace.ts

@@ -153,7 +153,7 @@ export class Trace {
   /**
  * 按 stepIndex 移除节点（崩溃重建清理在飞 call 用）。
  *
- * 正常运行不调用（append-only 不变式）。仅 error-recovery 的 discardInFlightCalls
+ * 正常运行不调用（append-only 不变式）。仅 worker-message-pump 的 discardInFlightCalls
  * （rebuildRuntime 内，F2）清理被旧 runtime abort 的在飞 call 时用——移除其 trace
  * 节点，让重跑重发 agent-call 时 append 全新节点走全新执行路径（避免 stale
  * "running" 节点残留 + trace.update 命中旧节点导致新节点 orphan）。

package/src/orchestration/models/types.ts

@@ -13,7 +13,7 @@
  * 层归属：Engine（数据结构 + 不变式守卫）。
  */
 
-import type { ExecutionRecord } from "../../execution/types.ts";
+import type { ExecutionRecord, WorktreeHandle } from "../../execution/types.ts";
 
 // ── 状态机 ────────────────────────────────────────────────────
 
@@ -65,7 +65,37 @@ export function canRunTransition(from: RunStatus, to: RunStatus): boolean {
 // ── Agent 调用 ────────────────────────────────────────────────
 
 /**
- * 单次 agent 调用的输入选项。
+ * slug 最大长度（D6 合流迁入本文件，原权威定义在已删除的 execution/execute-options-mapper.ts）。
+ * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/ "fix-subagent-wf-tools"（21）
+ * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
+ * 放本文件的原因：约束对象是 AgentCallOpts.description（slug 的源字段，见下方 slug 派生说明），
+ * 与字段同文件；worker-message-pump（live record slug 截断）与壳侧 tool schema maxLength 共享引用。
+ */
+export const SLUG_MAX_LENGTH = 35;
+
+/**
+ * 单次 agent 调用的任务声明（D6 任务形状合流后的单一形状）。
+ *
+ * [D6 合流裁决] 本类型 = 原 AgentCallOpts（workflow 调用方声明，18 字段）与原
+ * AgentTaskSpec（engine 中立任务声明，已删除）的合流形态，从模型脚本 agent() API
+ * 到 EnginePort.run 直达 pi 边界一次映射——SAR 链路上的 ExecuteOptions/AgentTaskSpec
+ * 中间态消除（设计 docs/design/subagent-dual-track-convergence.md §3.3 D6 / 终态四）。
+ *
+ * 终态命名按变化轴裁定为 AgentCallOpts，理由：
+ *   - 字段演进的首要驱动轴是「调用方要表达的任务语义」（agent() API 是唯一生产写入方，
+ *     合流字段中 prompt/description/skill/skillPath/schemaEnv/thinkingLevel 等多数派
+ *     已是调用方命名）；
+ *   - 原 AgentTaskSpec 的中立重命名层（task/slug/effort/persona）与调用方命名是
+ *     形式同构、语义同构的假差异（prompt≡task、slug=description 截断、effort≡thinkingLevel、
+ *     persona≡skillPath+appendSystemPrompt 平铺），按「消假差异」原则并入调用方命名；
+ *   - 持久化兼容反向锁定 prompt 形态：jsonl run 快照的 AgentCall.opts 与 worker 消息
+ *     opts 均以 prompt 字段落盘，改名会破坏旧快照重水合。
+ *
+ * 引擎中立字段的并入方式（可选字段，原 AgentTaskSpec 独有字段去向）：
+ *   - graceTurns / conversation / idleTimeoutMs / denyTools / permissionMode：可选并入；
+ *   - persona.agentRef：裁撤（无生产写入方、无消费者——pi 走 agent 字段解析身份）；
+ *   - requires：裁撤（P4 形状预留、无生产写入方；且并入需 import EngineCapabilities
+ *     形成 orchestration↔engine 类型环）。将来能力依赖声明下钻时在本形状上加回。
  *
  * D-12 仅重组执行编排，AgentCallOpts 形状保持兼容。
  */
@@ -101,14 +131,20 @@ export interface AgentCallOpts {
  */
   timeoutMs?: number;
  /**
- * Turn 上限（turn limiter 用）。
- *
- * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
- * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
- * session-runner.resolveSpawnWatchdogMs）。mapToExecuteOptions 原样透传到
- * ExecuteOptions.maxTurns → 引擎 task-spec → runSpawn。
- */
+  * Turn 上限（turn limiter 用）。
+  *
+  * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
+  * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
+  * session-runner.resolveSpawnWatchdogMs）。pi 边界直出为 ExecuteOptions.maxTurns
+  * → runSpawn（D6 合流后无中间映射层）。
+  */
   maxTurns?: number;
+ /**
+  * Turn limiter 的宽限轮数（原 AgentTaskSpec.graceTurns 并入）：超 maxTurns 后
+  * 允许继续的轮数（等待在途工具收尾）。pi 引擎消费；workflow agent() 无写入方，
+  * chat 域（ExecuteOptions.graceTurns 同名透传）经 host-task-spec 填充。
+  */
+  graceTurns?: number;
  /**
  * Skill name to load (e.g. "code-review"). Resolved to SKILL.md path
  * and injected via --skill flag in the subprocess.
@@ -129,18 +165,18 @@ export interface AgentCallOpts {
  */
   agent?: string;
  /**
- * System prompt injection CONTENT (not file paths).
- * Set by agent-opts-resolver: schema structured-output instruction string.
- * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
- * mapToExecuteOptions passes this through to ExecuteOptions.appendSystemPrompt
- * (same name/semantics, transparent passthrough).
- */
+  * System prompt injection CONTENT (not file paths).
+  * Set by agent-opts-resolver: schema structured-output instruction string.
+  * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
+  * pi 边界直出为 ExecuteOptions.appendSystemPrompt（同名同义透传，D6 合流后无中间映射层）。
+  */
   appendSystemPrompt?: string[];
  /**
- * Schema JSON for PI_WORKFLOW_SCHEMA env var.
- * Set by agent-opts-resolver when opts.schema is present; passed as env var
- * to activate the structured-output tool + hook.
- */
+  * Schema JSON for PI_WORKFLOW_SCHEMA env var.
+  * Set by agent-opts-resolver when opts.schema is present (值 = stringifySchemaCached
+  * compact，与 schema 派生等值); passed as env var to activate the structured-output
+  * tool + hook. pi 边界直出时 schema 派生优先、本字段兜底（解耦形态通道，生产不可达）。
+  */
   schemaEnv?: string;
  /**
  * Per-call 工作目录（ADR-029 决策 1）。传给 child_process.spawn 的 cwd option。
@@ -159,11 +195,36 @@ export interface AgentCallOpts {
    * agent() → execute-agent-call → SAR 路由层。
    */
   engine?: string;
-  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
-  worktree?: boolean;
+  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork.
+   * [D6 合流] 类型扩展为 boolean | WorktreeHandle（原 AgentTaskSpec.worktree 的超集）——
+   * WorktreeHandle 形态仅在 chat 域（复用外部已创建的 worktree）出现，workflow agent()
+   * 恒传 boolean。 */
+  worktree?: boolean | WorktreeHandle;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
-   * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */
+   * Worker-layer flag only — not consumed by any engine (dropped at the pi boundary). */
   returnMeta?: boolean;
+ /**
+  * 可持续对话模式（原 AgentTaskSpec.conversation 并入）：true = record 标记 chatMode，
+  * 轮次完成进 idle 态等待 message 续聊。chat 域（ExecuteOptions.conversation 同名）经
+  * host-task-spec 填充；workflow agent() 无写入方。
+  */
+  conversation?: boolean;
+ /**
+  * 空闲超时毫秒数（原 AgentTaskSpec.idleTimeoutMs 并入，仅 conversation 模式有意义）。
+  * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms；显式 0/负 = 禁用
+  * idle GC。chat 域经 host-task-spec 填充。
+  */
+  idleTimeoutMs?: number;
+ /**
+  * 工具 denylist（原 AgentTaskSpec.denyTools 并入，中立新增面）：各引擎做语法映射
+  * （zcode buildZcodeArgv 消费；pi 链路暂无对应面）。无 workflow 写入方，预留形状。
+  */
+  denyTools?: string[];
+ /**
+  * 中立权限模式（原 AgentTaskSpec.permissionMode 并入，预留形状）：映射按各引擎
+  * capabilities.permissionMode。无生产写入方/消费者。
+  */
+  permissionMode?: string;
 }
 
 /**
@@ -189,6 +250,24 @@ export interface ToolCallEntry {
   input: string;
 }
 
+/**
+ * 失败分诊结构化标签（D5-③，r1 MF4 钉正语义）。
+ *
+ * - stale_context：pi session context 被 compact/cancel/替换——重试无意义（同 call
+ *   再次失败），不重试。
+ * - schema_deterministic：确定性 schema 失败（SO tool 从未调用 / gate 终止 /
+ *   不可满足 schema）——同 schema 重试必同结果，不重试。
+ * - unknown：其余一切失败（瞬态 provider 错误、spawn 失败等）——**默认可重试**。
+ *
+ * **语义守恒（最高优先约束）**：unknown（含字段缺省）= 可重试——保持收敛前的
+ * 默认重试语义；仅 stale_context 与 schema_deterministic 两态维持不重试特判。
+ * 词表归属（产出侧单点识别）：stale_context / schema_deterministic 的识别词表
+ * （stale 词表与确定性 schema 失败标记前缀）保留在产出侧
+ * execution/engine/engines/pi/output-collector.ts 包内——词表漂移的失效模式是
+ * failureKind=unknown → 保守重试（安全默认），不再是静默漏诊。
+ */
+export type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
+
 /**
  * 单次 agent 调用的结果（统一形态）。
  *
@@ -199,6 +278,16 @@ export interface AgentResult {
  /** Raw text output from the agent. */
   content: string;
  /**
+ * [D5-③] 失败分诊结构化标签（AgentFailureKind）。产出侧唯一识别点 =
+ * execution/engine/engines/pi/output-collector.ts（collectResult 对最终 error
+ * 分类后写入，经 agent-result-mapper / AgentOutcome 透传到本形态）；消费侧
+ * execute-agent-call 读本字段分诊，不再扫 error 文案子串。
+ *
+ * 仅在 error !== undefined 时有意义（成功时缺省）；缺省视为 unknown = 可重试
+ * （语义守恒，见 AgentFailureKind）。
+ */
+  failureKind?: AgentFailureKind;
+ /**
  * Parsed structured output.
  * Present when `schema` was provided and the output was valid JSON.
  * Source: tool_execution_end.result.details（validated data object）。

package/src/orchestration/models/workflow-run.ts

@@ -39,7 +39,7 @@ import { canRunTransition } from "./types.ts";
 /**
  * 聚合根级 meta（非 RunState 的一部分，不随 trace 持久化到 worker JSONL）。
  *
- * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：error-recovery 重试计数载体），
+ * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：worker-message-pump 重试计数载体），
  * 因为 retry 会 replaceRuntime，但计数是 run 级而非 runtime 级。
  */
 export interface WorkflowRunMeta {