@zhushanwen/subagent-engine-sdk 0.11.0 → 0.12.1

package/dist/{chunk-2L3I2TWJ.js → chunk-2JLFRKHK.js}

@@ -16,7 +16,11 @@ var ENGINE_ENV_DENY_LIST = [
   // 预设回落事实（env 名 SSOT = shared PRESET_FALLBACK_ENV_KEYS）：「本进程本次运行」
   // 事实只对 runtime 直接 spawn 的 pi 成立，引擎一跳继承会造成子 agent pi 假披露
   "TAIJI_PRESET_FALLBACK_FROM",
-  "TAIJI_PRESET_FALLBACK_TO"
+  "TAIJI_PRESET_FALLBACK_TO",
+  // runtime 实例标识（connection-datasync-ssot §6.1，env 名 SSOT = shared
+  // RUNTIME_ID_ENV）：supervisor 每次 spawn 签发的生命周期标志，只有 runtime 自身
+  // 消费；引擎一跳继承陈旧值 = 后代进程持有已死实例标识，出站剥除
+  "TAIJI_RUNTIME_ID"
 ];
 var ENGINE_ENV_L0_INFRA_KEYS = [
   "TAIJI_AGENT_DATA_DIR",

package/dist/{chunk-QBXDEF4N.js → chunk-7R6HYT2A.js}

@@ -77,9 +77,28 @@ var AGENT_EVENT_TYPE_NAMES = [
   // 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 = {};
@@ -220,6 +239,11 @@ export {
   SUBAGENT_CONTROL_CLOSED_REASONS,
   isSubagentControlClosedReason,
   AGENT_EVENT_TYPE_NAMES,
+  _EventVocabSyncLock,
+  FAILURE_CAUSE_CLOSED_KINDS,
+  FAILURE_CAUSE_KIND_VOCAB_LOCK,
+  FAILURE_CAUSE_KINDS_BY_CLASS,
+  FAILURE_CAUSE_KINDS_BY_CLASS_LOCK,
   protocolErrorSchema,
   requestFrameSchema,
   successResponseFrameSchema,

package/dist/{chunk-YFSNX3N3.js → chunk-U5MBAKS5.js}

@@ -31,7 +31,8 @@ function createReplayRecord() {
     turns: [emptyTurn()],
     turnCount: 0,
     totalTokens: 0,
-    lastError: void 0
+    lastError: void 0,
+    errors: []
   };
 }
 function currentTurn(record) {
@@ -125,7 +126,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) {
@@ -134,11 +139,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) {
@@ -158,7 +163,7 @@ function updateFromEvent(record, event) {
     // ── 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：不产生数据（不变）──
@@ -172,6 +177,12 @@ function updateFromEvent(record, event) {
     //    双侧 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;
@@ -226,7 +237,10 @@ function sessionIdFromHandle(handle) {
 }
 
 export {
+  addUsage,
+  emptyTurn,
   createReplayRecord,
+  appendErrorFact,
   updateFromEvent,
   toReplayedTurn,
   aggregateUsage,

package/dist/{contract-types-BUHUMF9R.d.ts → contract-types-C1scOS_M.d.cts}

@@ -106,6 +106,20 @@ type AgentEvent = {
     type: EventName<"armed">;
     schemaEnvVar: string;
     extensionPkg: string;
+} | {
+    type: EventName<"auto_retry">;
+    /** start = 失败尝试结束即将重跑；end = 重试波次收束（成功或最终失败）。 */
+    phase: "start" | "end";
+    /** 重试波次序号（pi 原生 _retryAttempt，1 起）。 */
+    attempt: number;
+    /** start 独有：重试上限与退避等待（pi _prepareRetry 发射事实）。 */
+    maxAttempts?: number;
+    delayMs?: number;
+    /** start 携带被重试的错误文本；end 失败波携带最终错误（成功波缺省）。 */
+    errorMessage?: string;
+    /** end 独有：该波重试最终是否恢复（true = 后续尝试成功，false = 重试耗尽）。 */
+    success?: boolean;
+    finalError?: string;
 };
 /**
  * 事件类型词表（协议事件全集 10 种，运行时 SSOT）：schema 事件 `type.enum` 从本表
@@ -129,7 +143,7 @@ type AgentEvent = {
  * switch never 检查）与 contract-closure 构造冒烟（Record<AgentEventTypeName,…>
  * 漏键爆红）。不 bump 版本、不改任何引擎（演进政策 additive 面，判据全文见头注）。
  */
-declare const AGENT_EVENT_TYPE_NAMES: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed"];
+declare const AGENT_EVENT_TYPE_NAMES: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed", "auto_retry"];
 /** 词表派生的事件名联合（编译锁②/③的词表侧源；schema enum 与测试取值同源）。 */
 type AgentEventTypeName = (typeof AGENT_EVENT_TYPE_NAMES)[number];
 /**
@@ -138,6 +152,7 @@ type AgentEventTypeName = (typeof AGENT_EVENT_TYPE_NAMES)[number];
  * 结构与运行时语义零变化。
  */
 type EventName<T extends AgentEventTypeName> = T;
+declare const _EventVocabSyncLock: AssertMutuallyAssignable<AgentEvent["type"], AgentEventTypeName>;
 /**
  * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / read 的
  * handle 载荷（引擎不持有宿主运行时引用，data 即全部）。
@@ -298,7 +313,139 @@ interface ProbeReport {
         recovery: string;
     };
 }
-/** 失败分诊结构化标签。unknown（含缺省）= 可重试（语义守恒）。 */
+/**
+ * [subagent-observability §3.3.2] 失败分类权威契约（五维正交，原位替换
+ * AgentFailureKind 三值词表——本文件是引擎协议词表家址）。
+ *
+ * 由收尾边沿（判定链）一次产出并写入轮收条，下游只读不可替换（三硬规则①②——
+ * 只有知道事实的层能填 class；写入后观察性事实降级 observations，不改写 cause）。
+ * 跨进程 wire 载体 = shared `SubagentRecord.lastRound.failure`（type-only re-export，
+ * 判别联合逐字序列化）。消费锚：轮应答恢复指引（§3.3.7）、run 终局 failedMembers[].cause
+ * （§3.3.8——序列化为 `"<class>.<kind>"` 点拼字符串，retryable/retryAfterMs 不进终局
+ * 事件、由成员轮收条承载）。
+ *
+ * cause 优先级（分类边沿裁决序，严格递减）：provider 事实 > harness 预算/契约 >
+ * agent 行为 > engine 崩溃 > unknown（未分类形态不产 FailureCause，落引擎停因原值）。
+ */
+type FailureCauseClass = "provider" | "harness" | "agent" | "engine" | "user";
+/**
+ * retryable 三态（§3.3.2 硬规则③，与重试规则 extension 的 verdict 同词表）：
+ *   true         = 等待后重发可恢复；
+ *   false        = 重发必然同样失败；
+ *   "conditional" = 条件恢复——等限额重置窗口或人/账户先动作（执行层对 conditional
+ *                   不自动重试，呈现层如实展示）。
+ */
+type FailureRetryability = true | false | "conditional";
+/**
+ * FailureCause 公共字段面（class×kind 判别联合各成员共享）。
+ *   retryable    — 三态（{@link FailureRetryability}）；429 不全可重试，禁止仅按
+ *                  HTTP 状态码判可重试（provider 业务码层裁决，§3.3.2 码表硬约束）；
+ *   retryAfterMs — 恢复等待毫秒（错误文本内重置时间字样提取——pi 消息模型不暴露
+ *                  HTTP 头，头通道结构性不可得，设计 §3.3.2 单文本通道），
+ *                  皆无 → 缺省 unknown（undefined，不产假 0）；
+ *   raw          — 分类输入的原始错误文本（取证链：分类不丢原文）。
+ */
+interface FailureCauseFields {
+    retryable: FailureRetryability;
+    retryAfterMs?: number;
+    raw: string;
+}
+/**
+ * class×kind 合法组合矩阵（判别联合构造性成立——非法组合写不出来）：
+ *   provider.rate_limited / provider.protocol_unsupported / harness.turn_budget_exhausted /
+ *   harness.timeout / agent.no_deliverable / user.cancelled / engine.*（`engine_${string}`
+ *   引擎自报透传族，开放前缀面——对齐 RunErrorCode 的 engine_ 透传契约，core 不解释文案）。
+ *
+ * kind 是封闭登记词表：新增成员同 commit 登记下方 {@link FAILURE_CAUSE_CLOSED_KINDS}
+ * （解析词表纪律），漏登记由 {@link FAILURE_CAUSE_KIND_VOCAB_LOCK} 编译锁拦截。
+ */
+type FailureCause = (FailureCauseFields & {
+    class: "provider";
+    kind: "rate_limited" | "protocol_unsupported";
+}) | (FailureCauseFields & {
+    class: "harness";
+    kind: "turn_budget_exhausted" | "timeout";
+    /**
+     * [subagent-observability §3.3.9/UC-10] turn 预算耗尽事实（limiter abort 边沿
+     * 一次产出）：used = abort 时轮数、limit = 显式 maxTurns 上界。undefined =
+     * 极端竞窗下收尾边沿只有 aborted 停因而 limiter 快照缺席（防御性同判形态，
+     * 事实不足不产结构——轮失败事实不受影响）。与 §3.3.6 查询侧 budget 分轴
+     * 结构（{maxTurns, ...}）同构的 {used, limit} 形态。仅 turn_budget_exhausted
+     * 承载；timeout（§3.3.6 超时轮失败分类，宿主结算点产出——timeoutMs 墙钟预算
+     * 耗尽是宿主独有事实，引擎收尾边沿只有「宿主取消 vs 引擎异常」两源判别）
+     * 不落本字段。
+     */
+    budget?: {
+        used: number;
+        limit: number;
+    };
+}) | (FailureCauseFields & {
+    class: "agent";
+    kind: "no_deliverable";
+}) | (FailureCauseFields & {
+    class: "user";
+    kind: "cancelled";
+}) | (FailureCauseFields & {
+    class: "engine";
+    kind: `engine_${string}`;
+});
+/**
+ * FailureCause.kind 闭合成员词表（运行时枚举完整性测试锚；engine 透传族
+ * `engine_${string}` 开放前缀面不进闭合表——逐成员断言见 failure-cause-vocabulary.test.ts）。
+ * 新增 kind 成员 = 联合与本元组同 commit 同批（编译锁双向拦截漏改）。
+ */
+declare const FAILURE_CAUSE_CLOSED_KINDS: readonly ["rate_limited", "protocol_unsupported", "turn_budget_exhausted", "timeout", "no_deliverable", "cancelled"];
+/**
+ * 词表编译锁（双向）：kind 联合闭合面 ⊆ 且 ⊇ FAILURE_CAUSE_CLOSED_KINDS。
+ * 联合扩值漏登元组（或元组多配联合外值）→ 本赋值 tsc 红，错误指向漏改侧。
+ */
+declare const FAILURE_CAUSE_KIND_VOCAB_LOCK: AssertMutuallyAssignable<Exclude<FailureCause["kind"], `engine_${string}`>, (typeof FAILURE_CAUSE_CLOSED_KINDS)[number]>;
+/**
+ * per-class kind 合法值域（运行时可用——重试规则条目的 kind 字段按 class 校验的
+ * 唯一依据；消费方 = shared validateRetryRuleFields / retry-rules extension 侧镜像）。
+ * engine 透传族是 `engine_${string}` 开放前缀面（无闭合枚举），不进本表——engine 规则
+ * 的 kind 校验走前缀形态判定，由各消费方按 {@link FailureCause} 的 `engine_${string}`
+ * 契约自行落地。
+ *
+ * 词表编译锁：每个 class 的成员元组与 {@link FailureCause} 判别联合的对应 kind 联合
+ * 双向可赋值——判别联合扩值漏登本表（或本表多配联合外值）→ 对应行 tsc 红。
+ */
+declare const FAILURE_CAUSE_KINDS_BY_CLASS: {
+    readonly provider: readonly ["rate_limited", "protocol_unsupported"];
+    readonly harness: readonly ["turn_budget_exhausted", "timeout"];
+    readonly agent: readonly ["no_deliverable"];
+    readonly user: readonly ["cancelled"];
+};
+/**
+ * per-class 词表编译锁（双向）：本表各 class 成员元组 ↔ 判别联合对应 kind 联合。
+ * 任一 class 漏登/多配 → 本赋值 tsc 红，错误指向漏改侧。
+ */
+declare const FAILURE_CAUSE_KINDS_BY_CLASS_LOCK: AssertMutuallyAssignable<{
+    provider: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["provider"][number];
+    harness: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["harness"][number];
+    agent: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["agent"][number];
+    user: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["user"][number];
+}, {
+    provider: Extract<FailureCause, {
+        class: "provider";
+    }>["kind"];
+    harness: Extract<FailureCause, {
+        class: "harness";
+    }>["kind"];
+    agent: Extract<FailureCause, {
+        class: "agent";
+    }>["kind"];
+    user: Extract<FailureCause, {
+        class: "user";
+    }>["kind"];
+}>;
+/**
+ * @deprecated [subagent-observability §3.3.2，ADR-0158 终态] 三值分诊词表已由
+ * {@link FailureCause} 取代（class×kind 封闭矩阵 + retryable 三态）。本类型保留为
+ * 历史解析兼容、不删——旧 record 帧与历史 journal 的 failureKind 解析仍依赖该
+ * 通道（设计 §3.4「历史解析兼容保留项」）；新写入方失败分类一律产 FailureCause，
+ * 产出侧分类器 classifyFailureKind 已退役。
+ */
 type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
 /**
  * AgentOutcome.usage 字段型（← core orchestration/models/types.ts AgentUsage 结构等价；
@@ -333,10 +480,28 @@ interface WorktreeHandle {
  * 一次引擎执行的终态（协议 run 终态应答的 outcome 载荷）。锚定 core
  * orchestration AgentResult 并追加引擎层字段（engineId / exitCode）。
  */
+/** [subagent-observability §3.3.3] 轮终停因引擎原值三态（引擎收尾边沿事实；宿主
+ *  ROUND_TERMINAL_STOP_REASONS 词表的协议侧同源镜像）。 */
+type EngineStopReason = "stop" | "error" | "aborted";
 interface AgentOutcome {
     content: string;
-    /** 失败分诊标签。产出侧 = 引擎；缺省 = unknown = 可重试。 */
+    /**
+     * 失败分诊标签（历史解析兼容残留）。
+     * @deprecated [subagent-observability §3.4，ADR-0158] 新写入方失败分类一律产
+     * {@link FailureCause}（下方 failure 字段）；本字段随 {@link AgentFailureKind} 保留为
+     * 旧 record 帧与历史 journal 的解析兼容。产出侧残留仅引擎送达错误码前缀确定性分诊
+     * （pi 引擎 output-collector，[D5-③ 改轨]）；缺省 = undefined（字段缺位），
+     * 不承载重试判定（重试判定在 FailureCause.retryable 三态）。
+     */
     failureKind?: AgentFailureKind;
+    /**
+     * [subagent-observability §3.3.8] 失败分类（收尾边沿一次产出——CollectedOutcome.failure
+     * 经引擎适配层 toOutcome 透传上协议）。run 终局成员交付结算消费本字段点拼
+     * `"<class>.<kind>"` 进 failedMembers[].cause；缺省 = 未分类（cause 回落
+     * error 前缀协议码 / "unknown"）。可选 = 读取面对旧格式应答放行（字段落地前
+     * 的引擎缺省，写侧契约由引擎适配层承担）。
+     */
+    failure?: FailureCause;
     /** native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：native 路径宿主不做二次校验）。 */
     parsedOutput?: unknown;
     usage?: AgentOutcomeUsage;
@@ -372,6 +537,38 @@ interface AgentOutcome {
      * 仅诊断引用——文件受引擎侧尺寸轮转与过期清理管辖，读侧不得假设其永存。
      */
     stderrTeePath?: string;
+    /**
+     * [subagent-observability §3.3.3] 轮终停因引擎原值（收尾边沿事实一次产出，值域
+     * 三态与宿主 ROUND_TERMINAL_STOP_REASONS 同源）。宿主 one-shot 轮收条
+     * rec.lastRound.engineStopReason 的数据源——「正常收尾」派生判据（stop 且无失败
+     * 分类 = completed）依赖本事实。additive 可选（宪法判据③同 stderrTeePath 先例）：
+     * 旧引擎缺省 = 宿主回落派生展示词，零行为差。
+     */
+    engineStopReason?: EngineStopReason;
+    /**
+     * [subagent-observability §3.3.3 P5] 本 run 内 pi 原生重试的失败尝试计数
+     * （auto_retry_start 帧数；引擎 >0 时上报）。宿主轮收条 lastRound.retryAttempts
+     * 的数据源——重试轨迹可观测（失败尝试不静默计入 turns/usage）。additive 可选：
+     * 旧引擎/无重试缺省不落键。
+     */
+    retryAttempts?: number;
+    /**
+     * [subagent-observability §3.3.1/§3.3.3] 本轮被人类接管收尾的标注（引擎判定链
+     * prompt-ack 命中 handled 时产出，值恒 "handled"）。宿主轮收条
+     * lastRound.promptDisposition 的数据源——被接管轮不产失败分类、结清走 no_result、
+     * 通知走接管分支、run 聚合按未交付非失败计。additive 可选（宪法判据③同
+     * engineStopReason 先例）：旧引擎缺省 = 无接管标注，零行为差。
+     */
+    promptDisposition?: "handled";
+    /**
+     * [subagent-observability §3.3.2/§3.3.10] 观察性事实数组（引擎产出侧摘要，如
+     * 「结构化输出未调用」）。宿主轮收条 lastRound.observations 的
+     * 数据源——查询出口 list lastRound.observations 直读。additive 可选：旧引擎
+     * 缺省不落键。注意承载分源：交付谓词缺项（deliverables 未满足）在 worker 脚本
+     * 侧执行，不经本字段——落脚本结果 observations / run 终局帧 partialMembers /
+     * workflow_control 成员行 missingDeliverables 三面（§3.3.10 分源表述）。
+     */
+    observations?: string[];
 }
 /**
  * 引擎模型目录条目（manifest `modelCatalog.models` 条目形态，设计 §3.4 示例）。
@@ -464,4 +661,4 @@ interface AgentCallOpts {
     permissionMode?: string;
 }
 
-export { type AgentEvent as A, type EngineHandleData as E, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, type AgentUsageTotal as a, type AgentCallOpts as b, type AgentOutcome as c, type EngineCapabilities as d, type ResumeAnchor as e, type ModelCatalogEntry as f, AGENT_EVENT_TYPE_NAMES as g, type AgentEventTypeName as h, type AgentFailureKind as i, type AgentOutcomeUsage as j, type AgentUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type ToolCall as n, type ToolCallEntry as o, type ToolCallResult as p };
+export { type AgentEvent as A, type EngineHandleData as E, FAILURE_CAUSE_CLOSED_KINDS as F, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, _EventVocabSyncLock as _, type AgentUsage as a, type AgentUsageTotal as b, type AgentCallOpts as c, type AgentOutcome as d, type EngineCapabilities as e, type ResumeAnchor as f, type ModelCatalogEntry as g, AGENT_EVENT_TYPE_NAMES as h, type AgentEventTypeName as i, type AgentFailureKind as j, type AgentOutcomeUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type EngineStopReason as n, FAILURE_CAUSE_KINDS_BY_CLASS as o, FAILURE_CAUSE_KINDS_BY_CLASS_LOCK as p, FAILURE_CAUSE_KIND_VOCAB_LOCK as q, type FailureCause as r, type FailureCauseClass as s, type FailureRetryability as t, type ToolCall as u, type ToolCallEntry as v, type ToolCallResult as w };

package/dist/{contract-types-BUHUMF9R.d.cts → contract-types-C1scOS_M.d.ts}

@@ -106,6 +106,20 @@ type AgentEvent = {
     type: EventName<"armed">;
     schemaEnvVar: string;
     extensionPkg: string;
+} | {
+    type: EventName<"auto_retry">;
+    /** start = 失败尝试结束即将重跑；end = 重试波次收束（成功或最终失败）。 */
+    phase: "start" | "end";
+    /** 重试波次序号（pi 原生 _retryAttempt，1 起）。 */
+    attempt: number;
+    /** start 独有：重试上限与退避等待（pi _prepareRetry 发射事实）。 */
+    maxAttempts?: number;
+    delayMs?: number;
+    /** start 携带被重试的错误文本；end 失败波携带最终错误（成功波缺省）。 */
+    errorMessage?: string;
+    /** end 独有：该波重试最终是否恢复（true = 后续尝试成功，false = 重试耗尽）。 */
+    success?: boolean;
+    finalError?: string;
 };
 /**
  * 事件类型词表（协议事件全集 10 种，运行时 SSOT）：schema 事件 `type.enum` 从本表
@@ -129,7 +143,7 @@ type AgentEvent = {
  * switch never 检查）与 contract-closure 构造冒烟（Record<AgentEventTypeName,…>
  * 漏键爆红）。不 bump 版本、不改任何引擎（演进政策 additive 面，判据全文见头注）。
  */
-declare const AGENT_EVENT_TYPE_NAMES: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed"];
+declare const AGENT_EVENT_TYPE_NAMES: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed", "auto_retry"];
 /** 词表派生的事件名联合（编译锁②/③的词表侧源；schema enum 与测试取值同源）。 */
 type AgentEventTypeName = (typeof AGENT_EVENT_TYPE_NAMES)[number];
 /**
@@ -138,6 +152,7 @@ type AgentEventTypeName = (typeof AGENT_EVENT_TYPE_NAMES)[number];
  * 结构与运行时语义零变化。
  */
 type EventName<T extends AgentEventTypeName> = T;
+declare const _EventVocabSyncLock: AssertMutuallyAssignable<AgentEvent["type"], AgentEventTypeName>;
 /**
  * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / read 的
  * handle 载荷（引擎不持有宿主运行时引用，data 即全部）。
@@ -298,7 +313,139 @@ interface ProbeReport {
         recovery: string;
     };
 }
-/** 失败分诊结构化标签。unknown（含缺省）= 可重试（语义守恒）。 */
+/**
+ * [subagent-observability §3.3.2] 失败分类权威契约（五维正交，原位替换
+ * AgentFailureKind 三值词表——本文件是引擎协议词表家址）。
+ *
+ * 由收尾边沿（判定链）一次产出并写入轮收条，下游只读不可替换（三硬规则①②——
+ * 只有知道事实的层能填 class；写入后观察性事实降级 observations，不改写 cause）。
+ * 跨进程 wire 载体 = shared `SubagentRecord.lastRound.failure`（type-only re-export，
+ * 判别联合逐字序列化）。消费锚：轮应答恢复指引（§3.3.7）、run 终局 failedMembers[].cause
+ * （§3.3.8——序列化为 `"<class>.<kind>"` 点拼字符串，retryable/retryAfterMs 不进终局
+ * 事件、由成员轮收条承载）。
+ *
+ * cause 优先级（分类边沿裁决序，严格递减）：provider 事实 > harness 预算/契约 >
+ * agent 行为 > engine 崩溃 > unknown（未分类形态不产 FailureCause，落引擎停因原值）。
+ */
+type FailureCauseClass = "provider" | "harness" | "agent" | "engine" | "user";
+/**
+ * retryable 三态（§3.3.2 硬规则③，与重试规则 extension 的 verdict 同词表）：
+ *   true         = 等待后重发可恢复；
+ *   false        = 重发必然同样失败；
+ *   "conditional" = 条件恢复——等限额重置窗口或人/账户先动作（执行层对 conditional
+ *                   不自动重试，呈现层如实展示）。
+ */
+type FailureRetryability = true | false | "conditional";
+/**
+ * FailureCause 公共字段面（class×kind 判别联合各成员共享）。
+ *   retryable    — 三态（{@link FailureRetryability}）；429 不全可重试，禁止仅按
+ *                  HTTP 状态码判可重试（provider 业务码层裁决，§3.3.2 码表硬约束）；
+ *   retryAfterMs — 恢复等待毫秒（错误文本内重置时间字样提取——pi 消息模型不暴露
+ *                  HTTP 头，头通道结构性不可得，设计 §3.3.2 单文本通道），
+ *                  皆无 → 缺省 unknown（undefined，不产假 0）；
+ *   raw          — 分类输入的原始错误文本（取证链：分类不丢原文）。
+ */
+interface FailureCauseFields {
+    retryable: FailureRetryability;
+    retryAfterMs?: number;
+    raw: string;
+}
+/**
+ * class×kind 合法组合矩阵（判别联合构造性成立——非法组合写不出来）：
+ *   provider.rate_limited / provider.protocol_unsupported / harness.turn_budget_exhausted /
+ *   harness.timeout / agent.no_deliverable / user.cancelled / engine.*（`engine_${string}`
+ *   引擎自报透传族，开放前缀面——对齐 RunErrorCode 的 engine_ 透传契约，core 不解释文案）。
+ *
+ * kind 是封闭登记词表：新增成员同 commit 登记下方 {@link FAILURE_CAUSE_CLOSED_KINDS}
+ * （解析词表纪律），漏登记由 {@link FAILURE_CAUSE_KIND_VOCAB_LOCK} 编译锁拦截。
+ */
+type FailureCause = (FailureCauseFields & {
+    class: "provider";
+    kind: "rate_limited" | "protocol_unsupported";
+}) | (FailureCauseFields & {
+    class: "harness";
+    kind: "turn_budget_exhausted" | "timeout";
+    /**
+     * [subagent-observability §3.3.9/UC-10] turn 预算耗尽事实（limiter abort 边沿
+     * 一次产出）：used = abort 时轮数、limit = 显式 maxTurns 上界。undefined =
+     * 极端竞窗下收尾边沿只有 aborted 停因而 limiter 快照缺席（防御性同判形态，
+     * 事实不足不产结构——轮失败事实不受影响）。与 §3.3.6 查询侧 budget 分轴
+     * 结构（{maxTurns, ...}）同构的 {used, limit} 形态。仅 turn_budget_exhausted
+     * 承载；timeout（§3.3.6 超时轮失败分类，宿主结算点产出——timeoutMs 墙钟预算
+     * 耗尽是宿主独有事实，引擎收尾边沿只有「宿主取消 vs 引擎异常」两源判别）
+     * 不落本字段。
+     */
+    budget?: {
+        used: number;
+        limit: number;
+    };
+}) | (FailureCauseFields & {
+    class: "agent";
+    kind: "no_deliverable";
+}) | (FailureCauseFields & {
+    class: "user";
+    kind: "cancelled";
+}) | (FailureCauseFields & {
+    class: "engine";
+    kind: `engine_${string}`;
+});
+/**
+ * FailureCause.kind 闭合成员词表（运行时枚举完整性测试锚；engine 透传族
+ * `engine_${string}` 开放前缀面不进闭合表——逐成员断言见 failure-cause-vocabulary.test.ts）。
+ * 新增 kind 成员 = 联合与本元组同 commit 同批（编译锁双向拦截漏改）。
+ */
+declare const FAILURE_CAUSE_CLOSED_KINDS: readonly ["rate_limited", "protocol_unsupported", "turn_budget_exhausted", "timeout", "no_deliverable", "cancelled"];
+/**
+ * 词表编译锁（双向）：kind 联合闭合面 ⊆ 且 ⊇ FAILURE_CAUSE_CLOSED_KINDS。
+ * 联合扩值漏登元组（或元组多配联合外值）→ 本赋值 tsc 红，错误指向漏改侧。
+ */
+declare const FAILURE_CAUSE_KIND_VOCAB_LOCK: AssertMutuallyAssignable<Exclude<FailureCause["kind"], `engine_${string}`>, (typeof FAILURE_CAUSE_CLOSED_KINDS)[number]>;
+/**
+ * per-class kind 合法值域（运行时可用——重试规则条目的 kind 字段按 class 校验的
+ * 唯一依据；消费方 = shared validateRetryRuleFields / retry-rules extension 侧镜像）。
+ * engine 透传族是 `engine_${string}` 开放前缀面（无闭合枚举），不进本表——engine 规则
+ * 的 kind 校验走前缀形态判定，由各消费方按 {@link FailureCause} 的 `engine_${string}`
+ * 契约自行落地。
+ *
+ * 词表编译锁：每个 class 的成员元组与 {@link FailureCause} 判别联合的对应 kind 联合
+ * 双向可赋值——判别联合扩值漏登本表（或本表多配联合外值）→ 对应行 tsc 红。
+ */
+declare const FAILURE_CAUSE_KINDS_BY_CLASS: {
+    readonly provider: readonly ["rate_limited", "protocol_unsupported"];
+    readonly harness: readonly ["turn_budget_exhausted", "timeout"];
+    readonly agent: readonly ["no_deliverable"];
+    readonly user: readonly ["cancelled"];
+};
+/**
+ * per-class 词表编译锁（双向）：本表各 class 成员元组 ↔ 判别联合对应 kind 联合。
+ * 任一 class 漏登/多配 → 本赋值 tsc 红，错误指向漏改侧。
+ */
+declare const FAILURE_CAUSE_KINDS_BY_CLASS_LOCK: AssertMutuallyAssignable<{
+    provider: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["provider"][number];
+    harness: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["harness"][number];
+    agent: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["agent"][number];
+    user: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["user"][number];
+}, {
+    provider: Extract<FailureCause, {
+        class: "provider";
+    }>["kind"];
+    harness: Extract<FailureCause, {
+        class: "harness";
+    }>["kind"];
+    agent: Extract<FailureCause, {
+        class: "agent";
+    }>["kind"];
+    user: Extract<FailureCause, {
+        class: "user";
+    }>["kind"];
+}>;
+/**
+ * @deprecated [subagent-observability §3.3.2，ADR-0158 终态] 三值分诊词表已由
+ * {@link FailureCause} 取代（class×kind 封闭矩阵 + retryable 三态）。本类型保留为
+ * 历史解析兼容、不删——旧 record 帧与历史 journal 的 failureKind 解析仍依赖该
+ * 通道（设计 §3.4「历史解析兼容保留项」）；新写入方失败分类一律产 FailureCause，
+ * 产出侧分类器 classifyFailureKind 已退役。
+ */
 type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
 /**
  * AgentOutcome.usage 字段型（← core orchestration/models/types.ts AgentUsage 结构等价；
@@ -333,10 +480,28 @@ interface WorktreeHandle {
  * 一次引擎执行的终态（协议 run 终态应答的 outcome 载荷）。锚定 core
  * orchestration AgentResult 并追加引擎层字段（engineId / exitCode）。
  */
+/** [subagent-observability §3.3.3] 轮终停因引擎原值三态（引擎收尾边沿事实；宿主
+ *  ROUND_TERMINAL_STOP_REASONS 词表的协议侧同源镜像）。 */
+type EngineStopReason = "stop" | "error" | "aborted";
 interface AgentOutcome {
     content: string;
-    /** 失败分诊标签。产出侧 = 引擎；缺省 = unknown = 可重试。 */
+    /**
+     * 失败分诊标签（历史解析兼容残留）。
+     * @deprecated [subagent-observability §3.4，ADR-0158] 新写入方失败分类一律产
+     * {@link FailureCause}（下方 failure 字段）；本字段随 {@link AgentFailureKind} 保留为
+     * 旧 record 帧与历史 journal 的解析兼容。产出侧残留仅引擎送达错误码前缀确定性分诊
+     * （pi 引擎 output-collector，[D5-③ 改轨]）；缺省 = undefined（字段缺位），
+     * 不承载重试判定（重试判定在 FailureCause.retryable 三态）。
+     */
     failureKind?: AgentFailureKind;
+    /**
+     * [subagent-observability §3.3.8] 失败分类（收尾边沿一次产出——CollectedOutcome.failure
+     * 经引擎适配层 toOutcome 透传上协议）。run 终局成员交付结算消费本字段点拼
+     * `"<class>.<kind>"` 进 failedMembers[].cause；缺省 = 未分类（cause 回落
+     * error 前缀协议码 / "unknown"）。可选 = 读取面对旧格式应答放行（字段落地前
+     * 的引擎缺省，写侧契约由引擎适配层承担）。
+     */
+    failure?: FailureCause;
     /** native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：native 路径宿主不做二次校验）。 */
     parsedOutput?: unknown;
     usage?: AgentOutcomeUsage;
@@ -372,6 +537,38 @@ interface AgentOutcome {
      * 仅诊断引用——文件受引擎侧尺寸轮转与过期清理管辖，读侧不得假设其永存。
      */
     stderrTeePath?: string;
+    /**
+     * [subagent-observability §3.3.3] 轮终停因引擎原值（收尾边沿事实一次产出，值域
+     * 三态与宿主 ROUND_TERMINAL_STOP_REASONS 同源）。宿主 one-shot 轮收条
+     * rec.lastRound.engineStopReason 的数据源——「正常收尾」派生判据（stop 且无失败
+     * 分类 = completed）依赖本事实。additive 可选（宪法判据③同 stderrTeePath 先例）：
+     * 旧引擎缺省 = 宿主回落派生展示词，零行为差。
+     */
+    engineStopReason?: EngineStopReason;
+    /**
+     * [subagent-observability §3.3.3 P5] 本 run 内 pi 原生重试的失败尝试计数
+     * （auto_retry_start 帧数；引擎 >0 时上报）。宿主轮收条 lastRound.retryAttempts
+     * 的数据源——重试轨迹可观测（失败尝试不静默计入 turns/usage）。additive 可选：
+     * 旧引擎/无重试缺省不落键。
+     */
+    retryAttempts?: number;
+    /**
+     * [subagent-observability §3.3.1/§3.3.3] 本轮被人类接管收尾的标注（引擎判定链
+     * prompt-ack 命中 handled 时产出，值恒 "handled"）。宿主轮收条
+     * lastRound.promptDisposition 的数据源——被接管轮不产失败分类、结清走 no_result、
+     * 通知走接管分支、run 聚合按未交付非失败计。additive 可选（宪法判据③同
+     * engineStopReason 先例）：旧引擎缺省 = 无接管标注，零行为差。
+     */
+    promptDisposition?: "handled";
+    /**
+     * [subagent-observability §3.3.2/§3.3.10] 观察性事实数组（引擎产出侧摘要，如
+     * 「结构化输出未调用」）。宿主轮收条 lastRound.observations 的
+     * 数据源——查询出口 list lastRound.observations 直读。additive 可选：旧引擎
+     * 缺省不落键。注意承载分源：交付谓词缺项（deliverables 未满足）在 worker 脚本
+     * 侧执行，不经本字段——落脚本结果 observations / run 终局帧 partialMembers /
+     * workflow_control 成员行 missingDeliverables 三面（§3.3.10 分源表述）。
+     */
+    observations?: string[];
 }
 /**
  * 引擎模型目录条目（manifest `modelCatalog.models` 条目形态，设计 §3.4 示例）。
@@ -464,4 +661,4 @@ interface AgentCallOpts {
     permissionMode?: string;
 }
 
-export { type AgentEvent as A, type EngineHandleData as E, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, type AgentUsageTotal as a, type AgentCallOpts as b, type AgentOutcome as c, type EngineCapabilities as d, type ResumeAnchor as e, type ModelCatalogEntry as f, AGENT_EVENT_TYPE_NAMES as g, type AgentEventTypeName as h, type AgentFailureKind as i, type AgentOutcomeUsage as j, type AgentUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type ToolCall as n, type ToolCallEntry as o, type ToolCallResult as p };
+export { type AgentEvent as A, type EngineHandleData as E, FAILURE_CAUSE_CLOSED_KINDS as F, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, _EventVocabSyncLock as _, type AgentUsage as a, type AgentUsageTotal as b, type AgentCallOpts as c, type AgentOutcome as d, type EngineCapabilities as e, type ResumeAnchor as f, type ModelCatalogEntry as g, AGENT_EVENT_TYPE_NAMES as h, type AgentEventTypeName as i, type AgentFailureKind as j, type AgentOutcomeUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type EngineStopReason as n, FAILURE_CAUSE_KINDS_BY_CLASS as o, FAILURE_CAUSE_KINDS_BY_CLASS_LOCK as p, FAILURE_CAUSE_KIND_VOCAB_LOCK as q, type FailureCause as r, type FailureCauseClass as s, type FailureRetryability as t, type ToolCall as u, type ToolCallEntry as v, type ToolCallResult as w };

package/dist/env.cjs

@@ -97,7 +97,11 @@ var ENGINE_ENV_DENY_LIST = [
   // 预设回落事实（env 名 SSOT = shared PRESET_FALLBACK_ENV_KEYS）：「本进程本次运行」
   // 事实只对 runtime 直接 spawn 的 pi 成立，引擎一跳继承会造成子 agent pi 假披露
   "TAIJI_PRESET_FALLBACK_FROM",
-  "TAIJI_PRESET_FALLBACK_TO"
+  "TAIJI_PRESET_FALLBACK_TO",
+  // runtime 实例标识（connection-datasync-ssot §6.1，env 名 SSOT = shared
+  // RUNTIME_ID_ENV）：supervisor 每次 spawn 签发的生命周期标志，只有 runtime 自身
+  // 消费；引擎一跳继承陈旧值 = 后代进程持有已死实例标识，出站剥除
+  "TAIJI_RUNTIME_ID"
 ];
 var ENGINE_ENV_L0_INFRA_KEYS = [
   "TAIJI_AGENT_DATA_DIR",

package/dist/env.js

@@ -4,7 +4,7 @@ import {
   ENGINE_ENV_PREFIXES,
   buildEngineChildEnv,
   buildOutboundChildEnv
-} from "./chunk-2L3I2TWJ.js";
+} from "./chunk-2JLFRKHK.js";
 import "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {