@zhushanwen/subagent-engine-sdk 0.10.0 → 0.11.0

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

@@ -13,8 +13,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",
@@ -25,9 +23,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) {
@@ -81,11 +81,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;

package/dist/{chunk-HSNDUHFH.js → chunk-3MCOZY3Z.js}

@@ -1,7 +1,7 @@
 import {
   killChain,
   safeKill
-} from "./chunk-CNCFMPEH.js";
+} from "./chunk-TJMS3YOR.js";
 import {
   getLogger
 } from "./chunk-NXNNXGTY.js";
@@ -58,13 +58,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) => {
+      logger.warn(`taskkill self-tree failed (${reason}); falling back to self SIGKILL`);
+      try {
+        kill(pid, "SIGKILL");
+      } catch (err) {
+        logger.warn(
+          `self SIGKILL fallback failed (${String(err)}); descendant pi may linger until runtime sweep`
+        );
+      }
+    };
+    const spawnFn = deps.spawnFn ?? ((command, args, options) => 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) {
     logger.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
-    process.kill(pid, "SIGKILL");
+    kill(pid, "SIGKILL");
   }
 }
 function armEngineSelfDestruct(opts) {
@@ -133,6 +160,7 @@ export {
   spawnEngineChild,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
+  killOwnProcessGroup,
   armEngineSelfDestruct,
   pumpNdjsonLines
 };

package/dist/{chunk-JZN76I3S.js → chunk-NVF3PADP.js}

@@ -12,6 +12,30 @@ var SET_MODEL_REQUEST_TIMEOUT_MS = 1e4;
 var STDERR_TAIL_CHARS = 400;
 
 // 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 快照型失败行）。 */
@@ -56,7 +80,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 };
   }
@@ -117,6 +141,10 @@ export {
   SET_MODEL_STAGE_TIMEOUT_MS,
   SET_MODEL_REQUEST_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   SET_MODEL_ERROR_CODES,
   SET_MODEL_NOT_ACTIVE_CODE,
   ENGINE_PROTOCOL_ERROR_CODES,

package/dist/{chunk-LM7P7OTA.js → chunk-QBXDEF4N.js}

@@ -30,12 +30,39 @@ var REVERSE_CHANNEL_TIMEOUT_CLASS = {
   "host/askUser": "interaction"
 };
 
+// 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",
@@ -43,7 +70,7 @@ 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",
@@ -125,7 +152,7 @@ var notificationFrameSchema = {
             type: {
               type: "string",
               // 事件 enum 从词表 SSOT 派生（U2 词表锁：union⟷词表互证后，此处不再
-              // 手写字面量集合——手写即漂移面，病灶 1 的第三处同步点）
+              // 手写字面量集合——手写即漂移点，问题点 1 的第三处同步点）
               enum: [...AGENT_EVENT_TYPE_NAMES]
             }
           }
@@ -187,6 +214,11 @@ export {
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  isSubagentControlFrameKind,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  isSubagentControlClosedReason,
   AGENT_EVENT_TYPE_NAMES,
   protocolErrorSchema,
   requestFrameSchema,

package/dist/{chunk-NTOLHLCL.js → chunk-QGXILDWB.js}

@@ -1,6 +1,6 @@
 import {
   EngineSdkError
-} from "./chunk-JZN76I3S.js";
+} from "./chunk-NVF3PADP.js";
 
 // src/node-executor.ts
 import { spawn } from "child_process";

package/dist/{chunk-CT3FEBDO.js → chunk-QOFFM5YW.js}

@@ -1,8 +1,14 @@
 // src/zcode-db-paths.ts
 var ZCODE_HOST_DB_SUFFIX = [".zcode", "cli", "db", "db.sqlite"];
 var ZCODE_ISOLATED_DB_SEGMENTS = ["engines", "zcode", "session-db", "db.sqlite"];
+var ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS = [
+  "engines",
+  "zcode",
+  "pi-synced-provider-config.json"
+];
 
 export {
   ZCODE_HOST_DB_SUFFIX,
-  ZCODE_ISOLATED_DB_SEGMENTS
+  ZCODE_ISOLATED_DB_SEGMENTS,
+  ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS
 };

package/dist/{chunk-CNCFMPEH.js → chunk-TJMS3YOR.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-PYO3YR7W.js";
 import {
   engineTimeoutDetail
-} from "./chunk-JZN76I3S.js";
+} from "./chunk-NVF3PADP.js";
 import {
   getLogger
 } from "./chunk-NXNNXGTY.js";

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

@@ -152,7 +152,7 @@ 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 累加 ──
@@ -168,7 +168,7 @@ 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;

package/dist/cli-entry.d.cts

@@ -5,7 +5,7 @@
 interface CliProtocolServerSink {
     /** 入站协议帧处理（readline 已拆行 + JSON.parse 后的帧）。 */
     handleFrame(frame: unknown): void;
-    /** 数据面反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
+    /** 数据范围反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
     reverseRequest(method: string, params: unknown): Promise<unknown>;
 }
 /** runEngineCliEntry 参数。 */

package/dist/cli-entry.d.ts

@@ -5,7 +5,7 @@
 interface CliProtocolServerSink {
     /** 入站协议帧处理（readline 已拆行 + JSON.parse 后的帧）。 */
     handleFrame(frame: unknown): void;
-    /** 数据面反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
+    /** 数据范围反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
     reverseRequest(method: string, params: unknown): Promise<unknown>;
 }
 /** runEngineCliEntry 参数。 */

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

@@ -17,7 +17,7 @@ interface AgentUsage {
     cost?: number;
 }
 interface AgentUsageTotal extends AgentUsage {
-    /** 四项之和。投影时不再手工求和。 */
+    /** 四项之和。派生时不再手工求和。 */
     total: number;
     /** 累计成本（USD）。无成本数据时为 0。 */
     cost: number;
@@ -50,14 +50,14 @@ interface Turn {
     toolCalls: InternalToolCall[];
     /** 本 turn message_end 的 token 增量（聚合得 usage 总量）。 */
     usageDelta?: AgentUsage;
-    /** turn_end 是否已到达。false=正在进行；true=已闭合。 */
+    /** turn_end 是否已到达。false=正在进行；true=已结束。 */
     closed: boolean;
     /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。 */
     closedTs?: number;
 }
 /**
  * 引擎事件（10 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
- * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
+ * 兼容」不变量 3 的类型范围）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
  *
  * activity = 纯活性信号：双侧 reducer no-op、不开 turn、不写状态、不落 journal
  * （core event-journal-wiring 对其豁免 append），只承诺「引擎活跃时周期性出现」——供宿主
@@ -115,7 +115,7 @@ type AgentEvent = {
  * 每个成员必须带一行 `// noop-safe: <论证>`：未知成员宽容语义四行①（ADR-0071）的
  * 逐变体登记——旧宿主 reducer 遇未知 event.type 走 default 分支零写入，标记后写
  * 「本变体被丢弃时状态无损」的一行论证（no-op 安全性属运行时消费语义，不可静态
- * 判定——守卫只查标记存在不查内容，落点 contract-closure.test.ts「noop-safe 标记守卫」）。
+ * 判定——检查只查标记存在不查内容，落点 contract-closure.test.ts「noop-safe 标记检查」）。
  *
  * 编译锁（漏改任一侧 typecheck 红，且错误指向漏点）：
  *   ① union 侧——成员 type 必须经 `EventName<"x">` 取名（约束 = 本词表）：union 加
@@ -123,9 +123,9 @@ type AgentEvent = {
  *   ② 词表侧——`satisfies readonly AgentEvent["type"][]`：词表加成员不加 union
  *      → 错误直接落在词表漏改的成员行；
  *   ③ 兜底——成员绕过 EventName 约束裸加字面量 → _EventVocabSyncLock 爆红。
- * 新增事件变体的同步面分两层，漏改任一处 typecheck 均红且精确指路（验收 A1 演练
- * 实证）：协议面两笔（词表 + union）即协议面全同步——schema enum 与遍历型测试断言
- * 自动跟随；同仓消费面另有两处编译期同步点——journal-replay reducer case（穷尽
+ * 新增事件变体的同步点分两层，漏改任一处 typecheck 均红且精确指路（验收 A1 演练
+ * 实证）：协议范围两笔（词表 + union）即协议范围全同步——schema enum 与遍历型测试断言
+ * 自动跟随；同仓消费方另有两处编译期同步点——journal-replay reducer case（穷尽
  * switch never 检查）与 contract-closure 构造冒烟（Record<AgentEventTypeName,…>
  * 漏键爆红）。不 bump 版本、不改任何引擎（演进政策 additive 面，判据全文见头注）。
  */
@@ -160,7 +160,7 @@ interface EngineHandleData {
     adapterVersion: string;
 }
 /**
- * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的投影子集（诊断字段
+ * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的派生子集（诊断字段
  * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。消费点：
  *   - run.params.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
  *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）。
@@ -199,7 +199,7 @@ interface SessionView {
  * 用户覆盖记账共用的模型指向形状（设计 subagent-model-switch §6.2/§7.3）。
  *
  * 刻意用结构化对象而非现役 wire 的字符串 canonical ref（`ctx.model` = "provider/id"）：
- * 切换操作的原生输入面就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
+ * 切换操作的原生输入范围就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
  * runtime `model.switch` 均平铺 provider/modelId），字符串拼接形态会在协议两侧各做一次
  * 拆/拼（拆分规则 = provider 含 '/' 时无法无歧义反转），结构化形状让拆装只发生在宿主
  * 编排层单点（U2 组帧时拼 canonical ref、读回执时拆 ref）。
@@ -230,7 +230,7 @@ type EngineProcessModel = "per-window" | "shared-service";
  * 引擎能力声明（11 必填位 + 1 可选位 setModel）。三级：native / emulated / unsupported。
  * 声明的是本仓 subagent 链路实际接通的能力，不是引擎 RPC 层的理论能力。
  * 同步权威 = manifest（注册期直读）；握手应答仅诊断（§3.3「同步成员清单」）。
- * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约面，不在本
+ * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约范围，不在本
  * 接口内），两套字段服务不同裁决（任务能力 vs 宿主实例管理）。
  */
 interface EngineCapabilities {
@@ -242,7 +242,7 @@ interface EngineCapabilities {
      * [H1 D5 语义收窄 + modeless] 「怎么续」形态轴兼 message 资格轴：
      * 位非 'unsupported' = 引擎可续聊（core capability-gate 的 message 资格门消费），
      * 值区分续聊形态——native（原地续写）/ cold（冷恢复重建 + 新 run + resume 锚点）。
-     * 原名字沿用——conversation 位保留、语义从「interact 长驻控制面」收窄为
+     * 原名字沿用——conversation 位保留、语义从「interact 长驻控制范围」收窄为
      * 「resume 续聊能力」。[modeless 波2] 会话形态键只剩 run.params.resume（协议
      * task.conversation 已删），本轴不再是 per-run 模式开关——描述各引擎的真实
      * 续聊差异（gate 判据仍是 `=== "unsupported"` 拒绝，"cold" 与 "native" 等价
@@ -354,7 +354,7 @@ interface AgentOutcome {
     /** null = 被信号杀死（杀链/abort 合成终态的判据）。 */
     exitCode?: number | null;
     /**
-     * [D5 诊断引用落账] 失败时子进程 stderr tee 文件绝对路径（引擎侧 W11 已有落盘）。
+     * [D5 诊断引用写入记录] 失败时子进程 stderr tee 文件绝对路径（引擎侧 W11 已有落盘）。
      *
      * 通道裁决（协议演进宪法 ADR-0071 判据链，2026-09-22 一致性审查 P1 修复登记）：stderr
      * tee 路径是引擎产生的诊断事实，宿主不可靠推导（文件名格式/dataDir 解析/轮转
@@ -375,7 +375,7 @@ interface AgentOutcome {
 }
 /**
  * 引擎模型目录条目（manifest `modelCatalog.models` 条目形态，设计 §3.4 示例）。
- * 协议面 = initialize 应答 models? 与 listModels 应答 models 的元素型；
+ * 协议范围 = initialize 应答 models? 与 listModels 应答 models 的元素型；
  * manifest 解析与生成（gen:model-catalog）归 W4/W5 实装。
  */
 interface ModelCatalogEntry {
@@ -384,15 +384,15 @@ interface ModelCatalogEntry {
     canonicalRef?: string;
 }
 /**
- * 单次 agent 调用的任务声明——引擎面子集（协议 run.params.task；core 全量
- * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费面）。
+ * 单次 agent 调用的任务声明——引擎侧子集（协议 run.params.task；core 全量
+ * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费方）。
  *
  * 字段归属判据（协议演进宪法 ADR-0071 成文，权威源
  * docs/architecture/subagent-engine-protocolization.md §3.3「协议演进宪法」与
  * docs/adr/decisions.md ADR-0071；
- * 本注释是判据与存量结论的投影，新增字段按决策树依序裁决后在此登记）：
+ * 本注释是判据与存量结论的派生整理，新增字段按决策树依序裁决后在此登记）：
  *   ① 引擎不消费它任务能否正确完成？能 → 宿主自持不上协议（「正确」含满足字段
- *      声明携带的约束面——轮次预算/超时等约束被引擎忽略即任务语义受损，视为消费）；
+ *      声明携带的约束侧——轮次预算/超时等约束被引擎忽略即任务语义受损，视为消费）；
  *   ② 描述「任务是什么」(what) 还是「在什么环境跑/怎么跑」(where/how)？
  *      what → task（预算/验收类约束 = 任务自带语义归 task，宿主偏好参数走③）；
  *   ③ 引擎能否自行推导该环境值且与宿主恒等？能 → 不上协议（推导权归引擎，设计期

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

@@ -17,7 +17,7 @@ interface AgentUsage {
     cost?: number;
 }
 interface AgentUsageTotal extends AgentUsage {
-    /** 四项之和。投影时不再手工求和。 */
+    /** 四项之和。派生时不再手工求和。 */
     total: number;
     /** 累计成本（USD）。无成本数据时为 0。 */
     cost: number;
@@ -50,14 +50,14 @@ interface Turn {
     toolCalls: InternalToolCall[];
     /** 本 turn message_end 的 token 增量（聚合得 usage 总量）。 */
     usageDelta?: AgentUsage;
-    /** turn_end 是否已到达。false=正在进行；true=已闭合。 */
+    /** turn_end 是否已到达。false=正在进行；true=已结束。 */
     closed: boolean;
     /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。 */
     closedTs?: number;
 }
 /**
  * 引擎事件（10 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
- * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
+ * 兼容」不变量 3 的类型范围）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
  *
  * activity = 纯活性信号：双侧 reducer no-op、不开 turn、不写状态、不落 journal
  * （core event-journal-wiring 对其豁免 append），只承诺「引擎活跃时周期性出现」——供宿主
@@ -115,7 +115,7 @@ type AgentEvent = {
  * 每个成员必须带一行 `// noop-safe: <论证>`：未知成员宽容语义四行①（ADR-0071）的
  * 逐变体登记——旧宿主 reducer 遇未知 event.type 走 default 分支零写入，标记后写
  * 「本变体被丢弃时状态无损」的一行论证（no-op 安全性属运行时消费语义，不可静态
- * 判定——守卫只查标记存在不查内容，落点 contract-closure.test.ts「noop-safe 标记守卫」）。
+ * 判定——检查只查标记存在不查内容，落点 contract-closure.test.ts「noop-safe 标记检查」）。
  *
  * 编译锁（漏改任一侧 typecheck 红，且错误指向漏点）：
  *   ① union 侧——成员 type 必须经 `EventName<"x">` 取名（约束 = 本词表）：union 加
@@ -123,9 +123,9 @@ type AgentEvent = {
  *   ② 词表侧——`satisfies readonly AgentEvent["type"][]`：词表加成员不加 union
  *      → 错误直接落在词表漏改的成员行；
  *   ③ 兜底——成员绕过 EventName 约束裸加字面量 → _EventVocabSyncLock 爆红。
- * 新增事件变体的同步面分两层，漏改任一处 typecheck 均红且精确指路（验收 A1 演练
- * 实证）：协议面两笔（词表 + union）即协议面全同步——schema enum 与遍历型测试断言
- * 自动跟随；同仓消费面另有两处编译期同步点——journal-replay reducer case（穷尽
+ * 新增事件变体的同步点分两层，漏改任一处 typecheck 均红且精确指路（验收 A1 演练
+ * 实证）：协议范围两笔（词表 + union）即协议范围全同步——schema enum 与遍历型测试断言
+ * 自动跟随；同仓消费方另有两处编译期同步点——journal-replay reducer case（穷尽
  * switch never 检查）与 contract-closure 构造冒烟（Record<AgentEventTypeName,…>
  * 漏键爆红）。不 bump 版本、不改任何引擎（演进政策 additive 面，判据全文见头注）。
  */
@@ -160,7 +160,7 @@ interface EngineHandleData {
     adapterVersion: string;
 }
 /**
- * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的投影子集（诊断字段
+ * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的派生子集（诊断字段
  * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。消费点：
  *   - run.params.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
  *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）。
@@ -199,7 +199,7 @@ interface SessionView {
  * 用户覆盖记账共用的模型指向形状（设计 subagent-model-switch §6.2/§7.3）。
  *
  * 刻意用结构化对象而非现役 wire 的字符串 canonical ref（`ctx.model` = "provider/id"）：
- * 切换操作的原生输入面就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
+ * 切换操作的原生输入范围就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
  * runtime `model.switch` 均平铺 provider/modelId），字符串拼接形态会在协议两侧各做一次
  * 拆/拼（拆分规则 = provider 含 '/' 时无法无歧义反转），结构化形状让拆装只发生在宿主
  * 编排层单点（U2 组帧时拼 canonical ref、读回执时拆 ref）。
@@ -230,7 +230,7 @@ type EngineProcessModel = "per-window" | "shared-service";
  * 引擎能力声明（11 必填位 + 1 可选位 setModel）。三级：native / emulated / unsupported。
  * 声明的是本仓 subagent 链路实际接通的能力，不是引擎 RPC 层的理论能力。
  * 同步权威 = manifest（注册期直读）；握手应答仅诊断（§3.3「同步成员清单」）。
- * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约面，不在本
+ * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约范围，不在本
  * 接口内），两套字段服务不同裁决（任务能力 vs 宿主实例管理）。
  */
 interface EngineCapabilities {
@@ -242,7 +242,7 @@ interface EngineCapabilities {
      * [H1 D5 语义收窄 + modeless] 「怎么续」形态轴兼 message 资格轴：
      * 位非 'unsupported' = 引擎可续聊（core capability-gate 的 message 资格门消费），
      * 值区分续聊形态——native（原地续写）/ cold（冷恢复重建 + 新 run + resume 锚点）。
-     * 原名字沿用——conversation 位保留、语义从「interact 长驻控制面」收窄为
+     * 原名字沿用——conversation 位保留、语义从「interact 长驻控制范围」收窄为
      * 「resume 续聊能力」。[modeless 波2] 会话形态键只剩 run.params.resume（协议
      * task.conversation 已删），本轴不再是 per-run 模式开关——描述各引擎的真实
      * 续聊差异（gate 判据仍是 `=== "unsupported"` 拒绝，"cold" 与 "native" 等价
@@ -354,7 +354,7 @@ interface AgentOutcome {
     /** null = 被信号杀死（杀链/abort 合成终态的判据）。 */
     exitCode?: number | null;
     /**
-     * [D5 诊断引用落账] 失败时子进程 stderr tee 文件绝对路径（引擎侧 W11 已有落盘）。
+     * [D5 诊断引用写入记录] 失败时子进程 stderr tee 文件绝对路径（引擎侧 W11 已有落盘）。
      *
      * 通道裁决（协议演进宪法 ADR-0071 判据链，2026-09-22 一致性审查 P1 修复登记）：stderr
      * tee 路径是引擎产生的诊断事实，宿主不可靠推导（文件名格式/dataDir 解析/轮转
@@ -375,7 +375,7 @@ interface AgentOutcome {
 }
 /**
  * 引擎模型目录条目（manifest `modelCatalog.models` 条目形态，设计 §3.4 示例）。
- * 协议面 = initialize 应答 models? 与 listModels 应答 models 的元素型；
+ * 协议范围 = initialize 应答 models? 与 listModels 应答 models 的元素型；
  * manifest 解析与生成（gen:model-catalog）归 W4/W5 实装。
  */
 interface ModelCatalogEntry {
@@ -384,15 +384,15 @@ interface ModelCatalogEntry {
     canonicalRef?: string;
 }
 /**
- * 单次 agent 调用的任务声明——引擎面子集（协议 run.params.task；core 全量
- * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费面）。
+ * 单次 agent 调用的任务声明——引擎侧子集（协议 run.params.task；core 全量
+ * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费方）。
  *
  * 字段归属判据（协议演进宪法 ADR-0071 成文，权威源
  * docs/architecture/subagent-engine-protocolization.md §3.3「协议演进宪法」与
  * docs/adr/decisions.md ADR-0071；
- * 本注释是判据与存量结论的投影，新增字段按决策树依序裁决后在此登记）：
+ * 本注释是判据与存量结论的派生整理，新增字段按决策树依序裁决后在此登记）：
  *   ① 引擎不消费它任务能否正确完成？能 → 宿主自持不上协议（「正确」含满足字段
- *      声明携带的约束面——轮次预算/超时等约束被引擎忽略即任务语义受损，视为消费）；
+ *      声明携带的约束侧——轮次预算/超时等约束被引擎忽略即任务语义受损，视为消费）；
  *   ② 描述「任务是什么」(what) 还是「在什么环境跑/怎么跑」(where/how)？
  *      what → task（预算/验收类约束 = 任务自带语义归 task，宿主偏好参数走③）；
  *   ③ 引擎能否自行推导该环境值且与宿主恒等？能 → 不上协议（推导权归引擎，设计期

package/dist/env.cjs

@@ -94,8 +94,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",
@@ -106,9 +104,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) {
@@ -162,11 +162,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;

package/dist/env.d.cts

@@ -1,18 +1,9 @@
 /** L2 manifest 放行的保留前缀拒绝表（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_PREFIXES: readonly string[];
-/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。
- *  互引（场景域分化，勿互混）：dev 装配器（apps/electron/scripts/dev-instance-lib.mjs
- *  `LEAK_ENV_KEYS`）仍剥 RELAY_STD* 三键——dev 宿主进程环境防泄漏口径独立于引擎
- *  spawn 面；本清单（引擎侧）已退役同名三键，写入方已清零。 */
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_DENY_LIST: readonly string[];
-/** L0 注入的全部基础设施键（守卫断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
+/** L0 注入的全部基础设施键（检查断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
 declare const ENGINE_ENV_L0_INFRA_KEYS: readonly string[];
-/** relay 三键形态（宿主 relay 激活时三值同时非空，全有或全无）。 */
-interface EngineRelayEnv {
-    socket: string;
-    node: string;
-    script: string;
-}
 /** buildEngineChildEnv 入参。 */
 interface EngineChildEnvOptions {
     /** L0：引擎数据根（隔离库/池/journal 都相对它推导；缺 env 且无注入引擎侧须显式报错） */
@@ -21,8 +12,6 @@ interface EngineChildEnvOptions {
     engineNode?: string;
     /** L0：执行器为 Electron 二进制 → 注入 ELECTRON_RUN_AS_NODE=1 */
     electronRunAsNode?: boolean;
-    /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 TAIJI_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
-    relay?: EngineRelayEnv;
     /**
      * L0：引擎宿主（engine-host）进程的 env 透传通道。**注意它不是子代理身份通道**：
      * 引擎宿主是长驻进程（每窗口一个），而子代理身份（recordId / depth 等）是 per-run 的
@@ -46,9 +35,9 @@ interface EngineChildEnvOptions {
  *
  * 层规格（impl-plan §2.12 三层表）：
  * - L0 基础设施键：TAIJI_AGENT_DATA_DIR / TAIJI_AGENT_ENGINE_NODE / ELECTRON_RUN_AS_NODE
- *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / relay 三键 / identityEnv（injectL0InfraKeys）；
+ *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / identityEnv（injectL0InfraKeys）；
  * - L1 deny + 显式剥除（恒高于 manifest 放行）：ENGINE_ENV_DENY_LIST
- *   （deny 两键 + 凭证键 + 父身份键 + 防御性剥除三死名）；
+ *   （deny 两键 + 凭证键 + 预设回落两键）；
  * - L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键（保留前缀拒绝、
  *   形态校验、未声明前缀不放行 + warn）（applyManifestAllowlist）。
  *
@@ -70,7 +59,7 @@ interface BuildOutboundChildEnvOptions {
  * 消费生命周期标志 / WS 令牌。
  *
  * 与 @taiji/shared 版 buildOutboundChildEnv 的刻意差异：**缺省不做白名单过滤**
- * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费面（zsw 宿主 /
+ * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费方（zsw 宿主 /
  * 引擎 CLI）不可 import shared 的 ENV_WHITELIST_PREFIXES；引擎 spawn 的基座由
  * 调用方先经 buildEngineChildEnv 组装（其 baseEnv 已是 core 过滤后的），而
  * ambient 场景（git 需要 GIT_* / proxy / ssh 等）必须保留继承面——deny-by-default
@@ -80,4 +69,4 @@ interface BuildOutboundChildEnvOptions {
  */
 declare function buildOutboundChildEnv(opts: BuildOutboundChildEnvOptions): Record<string, string>;
 
-export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, type EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv };
+export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, buildEngineChildEnv, buildOutboundChildEnv };