@zhushanwen/subagent-engine-sdk 0.10.1 → 0.12.0

package/dist/{error-codes-DnFru4L4.d.ts → error-codes-o4rNd1Ee.d.ts}

@@ -1,4 +1,4 @@
-import { A as AgentEvent, d as EngineCapabilities } from './contract-types-jSa1g28F.js';
+import { A as AgentEvent, e as EngineCapabilities } from './contract-types-C1scOS_M.js';
 
 /** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
 interface ProtocolError {
@@ -42,7 +42,7 @@ interface ReverseRequestFrame {
 }
 /** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
 type ReverseResponseResult = 
-/** 数据面类：处理确认。 */
+/** 数据范围类：处理确认。 */
 {
     ok: true;
 }
@@ -63,6 +63,42 @@ declare function isNotificationFrame(frame: unknown): frame is NotificationFrame
 /** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
 declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
 
+/**
+ * 引擎进程侧 spawn/送达窗口错误码（M1/M2 送达回执，设计 D10「engine 侧」）。
+ * 消费方 = pi-subagent-cli（u-m2-engine-ack 接线）：
+ * - prompt_not_delivered：prompt 写入后零 stdout（零输出判定）/ stdin 不可用 / EPIPE——
+ *   任务从未被真实 pi 受理，静默丢失的显式失败形态；
+ * - prompt_rejected：pi 对 prompt 命令回 success:false（已送达但被拒绝）——带 pi 的
+ *   error 文本，与 not_delivered 分型防误诊（D3 不采用合并条目）；
+ * - spawn_handshake_timeout：引擎 spawn 握手窗口超时——runtime/引擎停在
+ *   spawn/handshake 的显式失败（control 侧同类失败码 = engine_open_timeout）。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_CODES: readonly ["engine_prompt_not_delivered", "engine_prompt_rejected", "engine_spawn_handshake_timeout"];
+type EngineSpawnDeliveryErrorCode = (typeof ENGINE_SPAWN_DELIVERY_ERROR_CODES)[number];
+/**
+ * runtime 控制面传输错误码（M3 control 通道，设计 D8/D10「runtime 侧」）。
+ * 消费方 = EngineClient.connectOnce preserve 白名单（u-m3-local：来自
+ * RuntimeEngineTransport 的 EngineSdkError 原样保留 code 与 recovery，不再包装成
+ * engine_crashed——UC-20 的显式失败不被吞掉）。语义（设计 D5/D8）：
+ * - transport_unavailable：control socket connect / hello 失败——托管态 runtime 故障
+ *   显式可见，不静默回退 local spawn；
+ * - transport_lost：control 连接中途丢失（与 engine 自身 crash 区分）——标记不可用、
+ *   fan-out 该连接全部 in-flight，不在同一连接重试；
+ * - open_timeout：engine_open 超时（runtime spawn/归属卡住）；
+ * - frame_too_large：单帧（含 partial-line 缓冲）超 32MB 上限——不截断、按 channel
+ *   归因关闭；
+ * - backpressure_overflow：channel（32MB/4096 帧）或连接聚合（256MB）待写队列溢出——
+ *   不丢帧、不静默，溢出面（channel/connection）标注在 detail。
+ */
+declare const ENGINE_TRANSPORT_ERROR_CODES: readonly ["engine_transport_unavailable", "engine_transport_lost", "engine_open_timeout", "engine_frame_too_large", "engine_backpressure_overflow"];
+type EngineTransportErrorCode = (typeof ENGINE_TRANSPORT_ERROR_CODES)[number];
+/**
+ * 引擎侧 spawn/送达错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。
+ * detail 由消费方拼装（诊断五元组 / pi error 文本），文案只给恢复动作。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY: Record<EngineSpawnDeliveryErrorCode, string>;
+/** runtime 控制面传输错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。 */
+declare const ENGINE_TRANSPORT_ERROR_RECOVERY: Record<EngineTransportErrorCode, string>;
 /**
  * setModel 正向方法的错误码三型（引擎 error 帧给出；宿主消费分型）。
  * 追加进 ENGINE_PROTOCOL_ERROR_CODES 主词表（成员清单单源 = 本数组，主词表 spread）。
@@ -82,7 +118,7 @@ type SetModelErrorCode = (typeof SET_MODEL_ERROR_CODES)[number];
  * 四个竞态窗口内发现子进程已退出——**同一处置**按无活进程形态应答，引擎回本码
  * error 帧）。进主词表的依据与 SET_MODEL_ERROR_CODES 三型相同：宿主消费分型
  * （chat 域转已记账型应答 / run 级聚合落 not-active 成员态，§7.2 处置表），不是
- * 「core 不解释文案」的纯透传面。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
+ * 「core 不解释文案」的纯透传逻辑。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
  * 名单的分型值域只收「转发失败」三型，无活进程是成员三态之一（not-active），
  * 不是失败——两值域语义正交。
  */
@@ -92,7 +128,7 @@ declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine
 type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
 /** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
 declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
-/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+/** 其余引擎自报错误码的前缀契约（透传侧；core 不解释文案）。 */
 declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
 declare function isEngineErrorPassthroughCode(value: string): boolean;
 
@@ -106,7 +142,7 @@ declare class EngineSdkError extends Error {
     readonly recovery: string;
     readonly data?: Record<string, unknown>;
     constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
-    /** 协议 error 帧载荷投影。 */
+    /** 协议 error 帧载荷派生视图。 */
     toStructured(): ProtocolError;
 }
 declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
@@ -147,4 +183,4 @@ declare function engineTimeoutDetail(stdoutTail: string): string;
 /** schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）。 */
 declare function schemaEmulationFailedDetail(error: string, tail: string): string;
 
-export { EngineSdkError as E, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, SET_MODEL_ERROR_CODES as S, ENGINE_ERROR_CODE_PREFIX as a, ENGINE_PROTOCOL_ERROR_CODES as b, ENGINE_TIMEOUT_RECOVERY as c, type EngineProtocolErrorCode as d, type ErrorResponseFrame as e, type EventNotificationParams as f, type ResponseFrame as g, type ReverseRequestFrame as h, type ReverseResponseResult as i, SET_MODEL_NOT_ACTIVE_CODE as j, STDOUT_TAIL_ECHO_CHARS as k, type SetModelErrorCode as l, type SuccessResponseFrame as m, assertChatConversationSupported as n, engineConversationUnsupportedError as o, engineProtocolMismatchError as p, engineSetModelUnsupportedError as q, engineTimeoutDetail as r, isEngineErrorPassthroughCode as s, isEngineProtocolErrorCode as t, isNotificationFrame as u, isRequestFrame as v, isResponseFrame as w, isReverseRequestFrame as x, schemaEmulationFailedDetail as y };
+export { isNotificationFrame as A, isRequestFrame as B, isResponseFrame as C, isReverseRequestFrame as D, EngineSdkError as E, schemaEmulationFailedDetail as F, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, SET_MODEL_ERROR_CODES as S, ENGINE_ERROR_CODE_PREFIX as a, ENGINE_PROTOCOL_ERROR_CODES as b, ENGINE_SPAWN_DELIVERY_ERROR_CODES as c, ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY as d, ENGINE_TIMEOUT_RECOVERY as e, ENGINE_TRANSPORT_ERROR_CODES as f, ENGINE_TRANSPORT_ERROR_RECOVERY as g, type EngineProtocolErrorCode as h, type EngineSpawnDeliveryErrorCode as i, type EngineTransportErrorCode as j, type ErrorResponseFrame as k, type EventNotificationParams as l, type ResponseFrame as m, type ReverseRequestFrame as n, type ReverseResponseResult as o, SET_MODEL_NOT_ACTIVE_CODE as p, STDOUT_TAIL_ECHO_CHARS as q, type SetModelErrorCode as r, type SuccessResponseFrame as s, assertChatConversationSupported as t, engineConversationUnsupportedError as u, engineProtocolMismatchError as v, engineSetModelUnsupportedError as w, engineTimeoutDetail as x, isEngineErrorPassthroughCode as y, isEngineProtocolErrorCode as z };

package/dist/index.cjs

@@ -6574,6 +6574,8 @@ var src_exports = {};
 __export(src_exports, {
   AGENT_EVENT_TYPE_NAMES: () => AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS: () => CANCEL_SETTLE_GRACE_MS,
+  CONTROL_ENV_ROOT_SESSION_ID: () => CONTROL_ENV_ROOT_SESSION_ID,
+  CONTROL_ENV_SOCKET: () => CONTROL_ENV_SOCKET,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS: () => DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   DEFAULT_KILL_GRACE_MS: () => DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS: () => DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
@@ -6589,25 +6591,24 @@ __export(src_exports, {
   ENGINE_PROTOCOL_ERROR_CODES: () => ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS: () => ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION: () => ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES: () => ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY: () => ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY: () => ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES: () => ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY: () => ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError: () => EngineSdkError,
   ExecutionNestingContext: () => ExecutionNestingContext,
+  FAILURE_CAUSE_CLOSED_KINDS: () => FAILURE_CAUSE_CLOSED_KINDS,
+  FAILURE_CAUSE_KINDS_BY_CLASS: () => FAILURE_CAUSE_KINDS_BY_CLASS,
+  FAILURE_CAUSE_KINDS_BY_CLASS_LOCK: () => FAILURE_CAUSE_KINDS_BY_CLASS_LOCK,
+  FAILURE_CAUSE_KIND_VOCAB_LOCK: () => FAILURE_CAUSE_KIND_VOCAB_LOCK,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: () => FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   HANDSHAKE_TIMEOUT_MS: () => HANDSHAKE_TIMEOUT_MS,
   HOST_TIMEOUT_ABORT_REASON: () => HOST_TIMEOUT_ABORT_REASON,
   NESTED_SPAWN_ENV: () => NESTED_SPAWN_ENV,
   NestedSpawnRejectedError: () => NestedSpawnRejectedError,
+  PI_SUBAGENT_TASK_MAX_CHARS: () => PI_SUBAGENT_TASK_MAX_CHARS,
   PROTOCOL_METHODS: () => PROTOCOL_METHODS,
-  RELAY_ENV_NODE: () => RELAY_ENV_NODE,
-  RELAY_ENV_RECORD_ID: () => RELAY_ENV_RECORD_ID,
-  RELAY_ENV_SCRIPT: () => RELAY_ENV_SCRIPT,
-  RELAY_ENV_SESSION_ID: () => RELAY_ENV_SESSION_ID,
-  RELAY_ENV_SOCKET: () => RELAY_ENV_SOCKET,
-  RELAY_EXIT_CODES: () => RELAY_EXIT_CODES,
-  RELAY_FRAME_DIRS: () => RELAY_FRAME_DIRS,
-  RELAY_FRAME_KINDS: () => RELAY_FRAME_KINDS,
-  RELAY_PROTOCOL_VERSION: () => RELAY_PROTOCOL_VERSION,
-  RELAY_REJECT_REASONS: () => RELAY_REJECT_REASONS,
   REVERSE_CHANNELS: () => REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS: () => REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS: () => REVERSE_REQUEST_TIMEOUT_MS,
@@ -6619,14 +6620,20 @@ __export(src_exports, {
   SHARED_POOL_KEY: () => SHARED_POOL_KEY,
   STDERR_TAIL_CHARS: () => STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS: () => STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_CONTROL_CLOSED_REASONS: () => SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS: () => SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION: () => SUBAGENT_CONTROL_PROTOCOL_VERSION,
   SUBAGENT_IDENTITY_ENV: () => SUBAGENT_IDENTITY_ENV,
   SUPPORTED_PROTOCOL_RANGE: () => SUPPORTED_PROTOCOL_RANGE,
   TAIJI_DATA_DIR_ENV: () => TAIJI_DATA_DIR_ENV,
   ZCODE_HOST_DB_SUFFIX: () => ZCODE_HOST_DB_SUFFIX,
   ZCODE_ISOLATED_DB_SEGMENTS: () => ZCODE_ISOLATED_DB_SEGMENTS,
   ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS: () => ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS,
+  _EventVocabSyncLock: () => _EventVocabSyncLock,
   abortWithFallback: () => abortWithFallback,
+  addUsage: () => addUsage,
   aggregateUsage: () => aggregateUsage,
+  appendErrorFact: () => appendErrorFact,
   armEngineSelfDestruct: () => armEngineSelfDestruct,
   assertChatConversationSupported: () => assertChatConversationSupported,
   assertNotNestedSpawn: () => assertNotNestedSpawn,
@@ -6640,6 +6647,7 @@ __export(src_exports, {
   configureLoggerSink: () => configureLoggerSink,
   createReplayRecord: () => createReplayRecord,
   createUiChannelRegistry: () => createUiChannelRegistry,
+  emptyTurn: () => emptyTurn,
   engineConversationUnsupportedError: () => engineConversationUnsupportedError,
   engineProtocolMismatchError: () => engineProtocolMismatchError,
   engineSetModelUnsupportedError: () => engineSetModelUnsupportedError,
@@ -6649,17 +6657,20 @@ __export(src_exports, {
   extractAndValidateStructuredOutput: () => extractAndValidateStructuredOutput,
   getLogger: () => getLogger,
   hostKindOf: () => hostKindOf,
+  isControlEnvActive: () => isControlEnvActive,
   isEngineErrorPassthroughCode: () => isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode: () => isEngineProtocolErrorCode,
   isNotificationFrame: () => isNotificationFrame,
   isPidAlive: () => isPidAlive,
   isProtocolVersionCompatible: () => isProtocolVersionCompatible,
-  isRelayActive: () => isRelayActive,
   isRequestFrame: () => isRequestFrame,
   isResponseFrame: () => isResponseFrame,
   isReverseRequestFrame: () => isReverseRequestFrame,
+  isSubagentControlClosedReason: () => isSubagentControlClosedReason,
+  isSubagentControlFrameKind: () => isSubagentControlFrameKind,
   isUiResponse: () => isUiResponse,
   killChain: () => killChain,
+  killOwnProcessGroup: () => killOwnProcessGroup,
   killPidChain: () => killPidChain,
   notificationFrameSchema: () => notificationFrameSchema,
   parseChannel: () => parseChannel,
@@ -6668,7 +6679,6 @@ __export(src_exports, {
   probePidAlive: () => probePidAlive,
   protocolErrorSchema: () => protocolErrorSchema,
   pumpNdjsonLines: () => pumpNdjsonLines,
-  readRelayForwardEnv: () => readRelayForwardEnv,
   replayJournal: () => replayJournal,
   requestFrameSchema: () => requestFrameSchema,
   resetDataDirWarnForTests: () => resetDataDirWarnForTests,
@@ -6768,6 +6778,30 @@ var REVERSE_CHANNEL_TIMEOUT_CLASS = {
 };
 
 // src/protocol/error-codes.ts
+var ENGINE_SPAWN_DELIVERY_ERROR_CODES = [
+  "engine_prompt_not_delivered",
+  "engine_prompt_rejected",
+  "engine_spawn_handshake_timeout"
+];
+var ENGINE_TRANSPORT_ERROR_CODES = [
+  "engine_transport_unavailable",
+  "engine_transport_lost",
+  "engine_open_timeout",
+  "engine_frame_too_large",
+  "engine_backpressure_overflow"
+];
+var ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY = {
+  engine_prompt_not_delivered: "The task never reached the child pi (zero stdout after the prompt write, or the engine stdin was unavailable). Re-run the task; if it recurs, inspect the engine/pi logs (the failure carries the delivery diagnostics) and the runtime log.",
+  engine_prompt_rejected: "The child pi explicitly rejected the prompt command (success:false). Check the pi-side reason carried in the error detail (busy/queue/extension takeover states are reported by pi itself), then re-run.",
+  engine_spawn_handshake_timeout: "The engine spawn handshake did not complete in time. Check the runtime log for a spawn/handshake stall, then restart taiji and re-run the task."
+};
+var ENGINE_TRANSPORT_ERROR_RECOVERY = {
+  engine_transport_unavailable: "The runtime control socket is unreachable (connect or hello failed). The runtime side is failing explicitly instead of silently falling back to local spawn \u2014 restart taiji and re-run the task.",
+  engine_transport_lost: "The control connection to the runtime was lost mid-flight (runtime restart or crash). In-flight requests were rejected; restart taiji (or wait for the runtime to come back) and re-run the task \u2014 the connection is not retried in place.",
+  engine_open_timeout: "The runtime did not finish opening the engine channel in time (spawn/attribution stalled). Check the runtime log (engine opened / kill decision lines), then re-run the task.",
+  engine_frame_too_large: "A single frame exceeded the control-plane size limit and the channel was closed without truncation. Shrink the task/result payload (e.g. point the agent at files instead of inlining them) and re-run.",
+  engine_backpressure_overflow: "The control-plane write queue overflowed (engine consumed frames too slowly) and the overflowed scope was torn down without dropping frames silently. Re-run the task; if it recurs, reduce concurrent subagent fan-out."
+};
 var SET_MODEL_ERROR_CODES = [
   /** 目标模型不在当前进程快照（子进程模型快照冻结于 spawn 时刻——模型本身有效，
    *  下一轮 spawn 现取目录即可用；宿主按「写覆盖意图」处置，设计 §7.2 快照型失败行）。 */
@@ -6812,7 +6846,7 @@ var EngineSdkError = class extends Error {
     this.recovery = recovery;
     this.data = data;
   }
-  /** 协议 error 帧载荷投影。 */
+  /** 协议 error 帧载荷派生视图。 */
   toStructured() {
     return { code: this.code, message: this.message, recovery: this.recovery, data: this.data };
   }
@@ -6863,12 +6897,39 @@ function schemaEmulationFailedDetail(error, tail) {
   return `structured output emulation failed after tolerant extraction and one host-side retry: ${error}. Raw output tail: ${truncate(tail, DETAIL_ECHO_MAX_CHARS)}. Recovery: retry with a strengthened prompt or relax the schema; if it still fails switch to a schema-native engine (engine: pi).`;
 }
 
+// src/protocol/control-protocol.ts
+var SUBAGENT_CONTROL_PROTOCOL_VERSION = 1;
+var SUBAGENT_CONTROL_FRAME_KINDS = {
+  hello: "hello",
+  helloOk: "hello_ok",
+  helloReject: "hello_reject",
+  engineOpen: "engine_open",
+  engineOpened: "engine_opened",
+  engineOpenFailed: "engine_open_failed",
+  engineFrame: "engine_frame",
+  engineClose: "engine_close",
+  engineClosed: "engine_closed",
+  error: "error"
+};
+function isSubagentControlFrameKind(value) {
+  return typeof value === "string" && Object.values(SUBAGENT_CONTROL_FRAME_KINDS).includes(value);
+}
+var SUBAGENT_CONTROL_CLOSED_REASONS = {
+  engineExit: "engine_exit",
+  engineSignal: "engine_signal",
+  killedByControl: "killed_by_control",
+  openTimeout: "open_timeout"
+};
+function isSubagentControlClosedReason(value) {
+  return typeof value === "string" && Object.values(SUBAGENT_CONTROL_CLOSED_REASONS).includes(value);
+}
+
 // src/protocol/contract-types.ts
 var AGENT_EVENT_TYPE_NAMES = [
   "tool_start",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 tool 起始占位（显示降级），turn 结构不受损
   "tool_end",
-  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 result，turn 收口由 turn_end/message_end 承担
+  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 result，turn 收尾由 turn_end/message_end 承担
   "text_delta",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺正文增量，不产生半解析状态
   "thinking_delta",
@@ -6876,16 +6937,35 @@ var AGENT_EVENT_TYPE_NAMES = [
   "turn_end",
   // noop-safe: 旧宿主 default 分支零写入——丢弃则该 turn 滞留进行态，journal 重放仍按序重建
   "message_end",
-  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 usage 聚合与闭合计量，已累积内容不回滚
+  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 usage 聚合与结束计量，已累积内容不回滚
   "compaction",
   // noop-safe: 事件无载荷且现行 reducer 即直接 return——丢弃与处理零差异
   "activity",
   // noop-safe: 纯活性信号，双侧 reducer 恒 no-op（协议语义见 AgentEvent 头注），丢弃零差异
   "error",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 lastError 诊断留痕，已写状态不回滚
-  "armed"
+  "armed",
   // noop-safe: 旧宿主无武装等待窗消费点（fail-fast 属宿主新增逻辑），丢弃仅缺武装留痕，schema 强制第一道防线（引擎自查断言）不受损
+  "auto_retry"
+  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺重试边界留痕（journal 不可查失败尝试轨迹），轮成败判定与 turns/usage 计账不受损（P5 计账锚在引擎侧收尾快照，不依赖宿主消费本帧）
 ];
+var _EventVocabSyncLock = true;
+var FAILURE_CAUSE_CLOSED_KINDS = [
+  "rate_limited",
+  "protocol_unsupported",
+  "turn_budget_exhausted",
+  "timeout",
+  "no_deliverable",
+  "cancelled"
+];
+var FAILURE_CAUSE_KIND_VOCAB_LOCK = true;
+var FAILURE_CAUSE_KINDS_BY_CLASS = {
+  provider: ["rate_limited", "protocol_unsupported"],
+  harness: ["turn_budget_exhausted", "timeout"],
+  agent: ["no_deliverable"],
+  user: ["cancelled"]
+};
+var FAILURE_CAUSE_KINDS_BY_CLASS_LOCK = true;
 
 // src/protocol/schema.ts
 var ANY_JSON = {};
@@ -6958,7 +7038,7 @@ var notificationFrameSchema = {
             type: {
               type: "string",
               // 事件 enum 从词表 SSOT 派生（U2 词表锁：union⟷词表互证后，此处不再
-              // 手写字面量集合——手写即漂移面，病灶 1 的第三处同步点）
+              // 手写字面量集合——手写即漂移点，问题点 1 的第三处同步点）
               enum: [...AGENT_EVENT_TYPE_NAMES]
             }
           }
@@ -7422,7 +7502,8 @@ function createReplayRecord() {
     turns: [emptyTurn()],
     turnCount: 0,
     totalTokens: 0,
-    lastError: void 0
+    lastError: void 0,
+    errors: []
   };
 }
 function currentTurn(record) {
@@ -7516,7 +7597,11 @@ function applyTurnEnd(record) {
   turn.closed = true;
   turn.closedTs = Date.now();
   record.turnCount += 1;
-  record.lastError = void 0;
+}
+function appendErrorFact(record, message) {
+  if (!message) return;
+  (record.errors ??= []).push({ message, at: Date.now() });
+  record.lastError = message;
 }
 function applyMessageEnd(record, event) {
   if (event.usage) {
@@ -7525,11 +7610,11 @@ function applyMessageEnd(record, event) {
     record.totalTokens += (event.usage.input ?? 0) + (event.usage.output ?? 0) + (event.usage.cacheRead ?? 0) + (event.usage.cacheWrite ?? 0);
   }
   if (event.error) {
-    record.lastError = event.error;
+    appendErrorFact(record, event.error);
   }
 }
 function applyErrorEvent(record, event) {
-  record.lastError = event.message;
+  appendErrorFact(record, event.message);
 }
 function updateFromEvent(record, event) {
   switch (event.type) {
@@ -7543,13 +7628,13 @@ function updateFromEvent(record, event) {
       return applyToolStart(record, event);
     case "tool_end":
       return applyToolEnd(record, event);
-    // ── turn_end：闭合当前 turn ──
+    // ── turn_end：结束当前 turn ──
     case "turn_end":
       return applyTurnEnd(record);
     // ── message_end：usage 增量累加 + totalTokens 累加 ──
     case "message_end":
       return applyMessageEnd(record, event);
-    // ── error：存 record.lastError ──
+    // ── error：appendErrorFact 入账（errors 只追加 + lastError 派生）──
     case "error":
       return applyErrorEvent(record, event);
     // ── compaction：不产生数据（不变）──
@@ -7559,10 +7644,16 @@ function updateFromEvent(record, event) {
     case "activity":
       return;
     // ── armed：武装确认回执（[D3 协议版 P6]，协议语义见 contract-types）——监控
-    //    信号不进 record 投影，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
+    //    信号不进 record 派生视图，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
     //    双侧 reducer no-op 义务的 SDK 侧）
     case "armed":
       return;
+    // ── auto_retry：pi 原生重试边界帧（[subagent-observability §3.3.1 P5]）——
+    //    观测面（journal 留痕失败尝试轨迹），不进 record 派生视图：失败尝试的
+    //    turns/usage 切片与 retryAttempts 计数由引擎收尾快照一次产出（outcome
+    //    字段承载），reducer 写入会让失败尝试静默混进 turns 聚合，恰违背 P5 计账。
+    case "auto_retry":
+      return;
     default: {
       const _exhaustive = event;
       return _exhaustive;
@@ -7782,8 +7873,6 @@ var ENGINE_ENV_DENY_LIST = [
   "TAIJI_AGENT_PACKAGED",
   "TAIJI_RUNTIME_TOKEN",
   "TAIJI_AGENT_API_KEY",
-  "TAIJI_SUBAGENT_RELAY_SESSION_ID",
-  "TAIJI_SUBAGENT_RELAY_RECORD_ID",
   // 预设回落事实（env 名 SSOT = shared PRESET_FALLBACK_ENV_KEYS）：「本进程本次运行」
   // 事实只对 runtime 直接 spawn 的 pi 成立，引擎一跳继承会造成子 agent pi 假披露
   "TAIJI_PRESET_FALLBACK_FROM",
@@ -7794,9 +7883,11 @@ var ENGINE_ENV_L0_INFRA_KEYS = [
   "TAIJI_AGENT_ENGINE_NODE",
   "ELECTRON_RUN_AS_NODE",
   "TAIJI_AGENT_SUBAGENT",
-  "TAIJI_SUBAGENT_RELAY_SOCKET",
-  "TAIJI_SUBAGENT_RELAY_NODE",
-  "TAIJI_SUBAGENT_RELAY_SCRIPT"
+  // [M3] control 两键（键名 SSOT = src/control-env.ts）：runtime 注入主 pi 与引擎的
+  // L0 基础设施键，嵌套 task pi 经引擎出站 env 继承同值。刻意不进 ENGINE_ENV_DENY_LIST：
+  // 引擎/嵌套 extension 是合法读者（transport 选择谓词 + engine_open 归属键）。
+  "TAIJI_SUBAGENT_CONTROL_SOCKET",
+  "TAIJI_SUBAGENT_CONTROL_ROOT_SESSION_ID"
 ];
 var ENV_PREFIX_SHAPE_RE = /^[A-Za-z0-9_]+$/;
 function deleteEnvKeysCaseInsensitive(env, names) {
@@ -7850,11 +7941,6 @@ function injectL0InfraKeys(env, opts) {
   if (opts.engineNode !== void 0) env.TAIJI_AGENT_ENGINE_NODE = opts.engineNode;
   if (opts.electronRunAsNode === true) env.ELECTRON_RUN_AS_NODE = "1";
   env.TAIJI_AGENT_SUBAGENT = "1";
-  if (opts.relay !== void 0) {
-    env.TAIJI_SUBAGENT_RELAY_SOCKET = opts.relay.socket;
-    env.TAIJI_SUBAGENT_RELAY_NODE = opts.relay.node;
-    env.TAIJI_SUBAGENT_RELAY_SCRIPT = opts.relay.script;
-  }
   if (opts.identityEnv !== void 0) {
     for (const [key, value] of Object.entries(opts.identityEnv)) {
       if (value !== void 0) env[key] = value;
@@ -7920,6 +8006,7 @@ var SUBAGENT_IDENTITY_ENV = {
   /** worktree 隔离标志（"true" = 是）。 */
   worktree: "PI_SUBAGENT_WORKTREE"
 };
+var PI_SUBAGENT_TASK_MAX_CHARS = 2e3;
 
 // src/spawn.ts
 var import_node_child_process = require("child_process");
@@ -7973,13 +8060,40 @@ function resolveHostRequestTimeoutMs(opts) {
   }
   return parsed;
 }
-function killOwnProcessGroup() {
+function killOwnProcessGroup(deps = {}) {
   const pid = process.pid;
+  const kill = deps.killFn ?? ((targetPid, signal) => process.kill(targetPid, signal));
+  if ((deps.platform ?? process.platform) === "win32") {
+    const fallbackSelfKill = (reason) => {
+      logger4.warn(`taskkill self-tree failed (${reason}); falling back to self SIGKILL`);
+      try {
+        kill(pid, "SIGKILL");
+      } catch (err) {
+        logger4.warn(
+          `self SIGKILL fallback failed (${String(err)}); descendant pi may linger until runtime sweep`
+        );
+      }
+    };
+    const spawnFn = deps.spawnFn ?? ((command, args, options) => (0, import_node_child_process.spawn)(command, [...args], options));
+    try {
+      const child = spawnFn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true
+      });
+      child.on("error", (err) => {
+        fallbackSelfKill(String(err));
+      });
+      child.unref?.();
+    } catch (err) {
+      fallbackSelfKill(`spawn threw: ${String(err)}`);
+    }
+    return;
+  }
   try {
-    process.kill(-pid, "SIGKILL");
+    kill(-pid, "SIGKILL");
   } catch (err) {
     logger4.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
-    process.kill(pid, "SIGKILL");
+    kill(pid, "SIGKILL");
   }
 }
 function armEngineSelfDestruct(opts) {
@@ -8275,62 +8389,13 @@ var ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS = [
   "pi-synced-provider-config.json"
 ];
 
-// src/relay-env.ts
-var RELAY_ENV_SOCKET = "TAIJI_SUBAGENT_RELAY_SOCKET";
-var RELAY_ENV_NODE = "TAIJI_SUBAGENT_RELAY_NODE";
-var RELAY_ENV_SCRIPT = "TAIJI_SUBAGENT_RELAY_SCRIPT";
-var RELAY_ENV_SESSION_ID = "TAIJI_SUBAGENT_RELAY_SESSION_ID";
-var RELAY_ENV_RECORD_ID = "TAIJI_SUBAGENT_RELAY_RECORD_ID";
-var RELAY_PROTOCOL_VERSION = 1;
-var RELAY_EXIT_CODES = {
-  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
-  VERSION_MISMATCH: 10,
-  /** relay socket 不可达（runtime 未运行或已重启）。 */
-  SOCKET_UNREACHABLE: 11,
-  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
-  SOCKET_CLOSED: 12,
-  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
-  MISSING_IDENTITY: 13
-};
-function isRelayActive(env) {
-  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
-}
-function readRelayForwardEnv(env) {
-  const socket = env[RELAY_ENV_SOCKET];
-  const node = env[RELAY_ENV_NODE];
-  const script = env[RELAY_ENV_SCRIPT];
-  if (!isRelayActive(env)) return void 0;
-  return { socket, node, script };
+// src/control-env.ts
+var CONTROL_ENV_SOCKET = "TAIJI_SUBAGENT_CONTROL_SOCKET";
+var CONTROL_ENV_ROOT_SESSION_ID = "TAIJI_SUBAGENT_CONTROL_ROOT_SESSION_ID";
+function isControlEnvActive(env) {
+  return Boolean(env[CONTROL_ENV_SOCKET]);
 }
 
-// src/relay-frames.ts
-var RELAY_FRAME_KINDS = {
-  handshake: "handshake",
-  accept: "accept",
-  reject: "reject",
-  data: "data",
-  exit: "exit",
-  /**
-   * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
-   * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
-   * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
-   * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
-   * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
-   */
-  goodbye: "goodbye"
-};
-var RELAY_FRAME_DIRS = {
-  down: "down",
-  up: "up",
-  upStderr: "up-stderr"
-};
-var RELAY_REJECT_REASONS = {
-  version: "version",
-  identity: "identity",
-  duplicate: "duplicate",
-  malformed: "malformed"
-};
-
 // src/best-effort.ts
 var logger5 = getLogger("subagents");
 function bestEffort(err, context, level = "debug") {
@@ -8430,6 +8495,8 @@ function runEngineCliEntry(opts) {
 0 && (module.exports = {
   AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS,
+  CONTROL_ENV_ROOT_SESSION_ID,
+  CONTROL_ENV_SOCKET,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
@@ -8445,25 +8512,24 @@ function runEngineCliEntry(opts) {
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError,
   ExecutionNestingContext,
+  FAILURE_CAUSE_CLOSED_KINDS,
+  FAILURE_CAUSE_KINDS_BY_CLASS,
+  FAILURE_CAUSE_KINDS_BY_CLASS_LOCK,
+  FAILURE_CAUSE_KIND_VOCAB_LOCK,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   HANDSHAKE_TIMEOUT_MS,
   HOST_TIMEOUT_ABORT_REASON,
   NESTED_SPAWN_ENV,
   NestedSpawnRejectedError,
+  PI_SUBAGENT_TASK_MAX_CHARS,
   PROTOCOL_METHODS,
-  RELAY_ENV_NODE,
-  RELAY_ENV_RECORD_ID,
-  RELAY_ENV_SCRIPT,
-  RELAY_ENV_SESSION_ID,
-  RELAY_ENV_SOCKET,
-  RELAY_EXIT_CODES,
-  RELAY_FRAME_DIRS,
-  RELAY_FRAME_KINDS,
-  RELAY_PROTOCOL_VERSION,
-  RELAY_REJECT_REASONS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -8475,14 +8541,20 @@ function runEngineCliEntry(opts) {
   SHARED_POOL_KEY,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
   SUBAGENT_IDENTITY_ENV,
   SUPPORTED_PROTOCOL_RANGE,
   TAIJI_DATA_DIR_ENV,
   ZCODE_HOST_DB_SUFFIX,
   ZCODE_ISOLATED_DB_SEGMENTS,
   ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS,
+  _EventVocabSyncLock,
   abortWithFallback,
+  addUsage,
   aggregateUsage,
+  appendErrorFact,
   armEngineSelfDestruct,
   assertChatConversationSupported,
   assertNotNestedSpawn,
@@ -8496,6 +8568,7 @@ function runEngineCliEntry(opts) {
   configureLoggerSink,
   createReplayRecord,
   createUiChannelRegistry,
+  emptyTurn,
   engineConversationUnsupportedError,
   engineProtocolMismatchError,
   engineSetModelUnsupportedError,
@@ -8505,17 +8578,20 @@ function runEngineCliEntry(opts) {
   extractAndValidateStructuredOutput,
   getLogger,
   hostKindOf,
+  isControlEnvActive,
   isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode,
   isNotificationFrame,
   isPidAlive,
   isProtocolVersionCompatible,
-  isRelayActive,
   isRequestFrame,
   isResponseFrame,
   isReverseRequestFrame,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   isUiResponse,
   killChain,
+  killOwnProcessGroup,
   killPidChain,
   notificationFrameSchema,
   parseChannel,
@@ -8524,7 +8600,6 @@ function runEngineCliEntry(opts) {
   probePidAlive,
   protocolErrorSchema,
   pumpNdjsonLines,
-  readRelayForwardEnv,
   replayJournal,
   requestFrameSchema,
   resetDataDirWarnForTests,