@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/index.ts

@@ -16,7 +16,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
+import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, SessionCompactEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
@@ -24,12 +24,22 @@ import { bestEffort } from "./execution/best-effort.ts";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
 import { getOrCreateChannelRegistry } from "./execution/channel-registry-access.ts";
 import { DialogGlobalQueue } from "./execution/dialog-queue.ts";
+// [U7] 引擎列表状态文件（registry → engines.json，GUI 引擎选择器数据源）
+import { syncEnginesFile } from "./execution/engine/engine-discovery.ts";
+// [U7] 引擎模型段注入（defaultEngine 非 pi 时 system prompt 补 <available_<engine>_models>）
+import { buildEngineModelsPromptAppend } from "./execution/engine/model-prompt.ts";
+// [P1 引擎接线] 组合根登记 'pi' 引擎进 registry（引擎获取统一经 getEngine，缺省 id 'pi'）
+import { registerPiEngine } from "./execution/engine/engines/pi/registration.ts";
+// [P3 引擎接线] 组合根登记 'zcode' 引擎（spawn 单轮模式；engineDataDir 默认走
+// common/data-dir SSOT，见 engines/zcode/registration.ts）
+import { registerZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
 import { createUiRequestHandlerForMode } from "./execution/ui-request-handler-factory.ts";
 import {
   getModelConfigService,
   ModelConfigService,
   setModelConfigService,
 } from "./execution/model-config-service.ts";
+import { bindNotifyLedgerHost, getBoundNotifyLedger, type NotifyLedgerHost } from "./execution/notify-ledger.ts";
 import { IDENTITY_CUSTOM_TYPE, type SubagentIdentityData } from "./execution/session-reconstructor.ts";
 import type { ExecutionMode, SubagentRecord } from "./execution/types.ts";
 import { maybeCleanupExpiredSessionFiles } from "./execution/session-file-gc.ts";
@@ -160,6 +170,22 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // 的 getLogger("subagents") 也能走 appendEntry。
   setPiHandle(pi);
 
+  // [P1 引擎接线] 组合根登记缺省引擎：进程级 SubagentService 单例（session_start 注入）
+  // 经 registry 以 'pi' 暴露——引擎获取从此统一走 getEngine(DEFAULT_ENGINE_ID)，上层
+  // 不再硬编码「spawn pi」。幂等（registerEngine 覆盖语义），工厂惰性解析服务单例。
+  // P4 配置路由（agent frontmatter engine 字段 + 三层优先级）在本登记之上消费。
+  registerPiEngine();
+
+  // [P3 引擎接线] 登记 'zcode'（幂等同上）。惰性工厂：不触发 CLI/凭据探测，引擎被
+  // 实际选用（P4 路由或显式 getEngine('zcode')）才解析 deps。
+  registerZcodeEngine();
+
+  // [U7b] 引擎列表在 extension 模块加载时即同步 engines.json（不等 session_start——
+  // 用户体验拍板 2026-08-25：xyz-agent 打开后激活任意 session 的第一时间（含 TUI 等价
+  // 场景）GUI 引擎选择器就该有数据；session_start 处保留幂等重写兜底 jiti 双路径/
+  // 模块重载场景的刷新）。
+  syncEnginesFile(getAgentDir());
+
   // ════════════════════════════════════════════════════════════
   //  subagents 域：tool + command + messageRenderer
   // ════════════════════════════════════════════════════════════
@@ -332,6 +358,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     const sessionId = ctx.sessionManager.getSessionId();
     lsRef.lastSessionId = sessionId;
 
+    // [U7] 引擎列表同步 engines.json（幂等零写 + fail-safe；组合根注册已在
+    // extension 工厂体完成，此处 registry 已含全部引擎）
+    syncEnginesFile(agentDir);
+
     // skill 路径两级缓存 session 级失效：pi 同进程可能有多个 session（TUI /new、/fork），
     // 运行中安装的 skill 需对新 session 可见（含曾 miss 缓存的 undefined 条目与 npm 新装
     // 包的候选目录）。session 内复用收益不变（IF8/DM3 消重发生在同 session 的重复调用）。
@@ -381,6 +411,39 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       }
     }
 
+    // ── [U2] 通知账本装配 + 重启恢复（设计 D4：存在性 / 可达性分离）──
+    // bind 先于 service.initSession（notifier.revive 在其内——notify() 经
+    // getBoundNotifyLedger 消费账本）。recoverFromSession 扫 ledger/ack 两列 entry
+    // 差集：未销账号重放投递（已销账零重发，notifyId 幂等）；fork 继承未销账
+    // pending 属可接受语义（D4 归属规则——扫描域 = 单 session 文件，幂等键作用域
+    // 随文件域隔离）。compaction 存活情况归 session_compact handler 的条件降级（P-B4
+    // 探针阶段 5 实测，见 notify-ledger.ts compactionCheck）。
+    try {
+      const ledgerHost: NotifyLedgerHost = {
+        appendLedgerEntry: (customType, data) => {
+          pi.appendEntry(customType, data);
+        },
+        readSessionEntries: () => ctx.sessionManager.getEntries(),
+        isIdle: () => ctx.isIdle(),
+        onAgentSettled: (handler) => {
+          pi.on("agent_settled", handler);
+        },
+        sendDelivery: (message) => {
+          // D5 单通道：唯一发送形态 = sendCustomMessage({triggerTurn:true})，
+          // courier 已在发送前二次复查 isIdle，多通道投递选项已删（D5）。
+          pi.sendMessage(message, { triggerTurn: true });
+        },
+      };
+      // U4：重放观测已内聚到 ledger 分桶日志（recoveryReplays 桶经 extensionLogger
+      // 通道落盘），此处不再重复打日志。
+      bindNotifyLedgerHost(ledgerHost).recoverFromSession();
+    } catch (err) {
+      // 账本装配失败不阻断 session_start（通知退回 notifier 的内核路径）
+      logger.warn("[subagents] notify ledger bind failed", {
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+
     // ── subagents 域：双 Service 装配 ──
     const existingService = getSubagentService();
     const existingModelService = getModelConfigService();
@@ -559,6 +622,41 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     });
   });
 
+  // ════════════════════════════════════════════════════════════
+  //  [U2 P-B4 降级] session_compact：compaction 对 custom entry 保留行为实装未
+  //  验证——检测 ledger/ack entry 被 compaction 清除时按内存态补写（notify-ledger
+  //  compactionCheck；未清除则 no-op）。内存态在 compaction 后仍活着，作为补写源；
+  //  重启后的权威仍是两列 entry 差集（内存不承担销账职责）。
+  // ═══════════════════════════════════════════════════════
+  pi.on("session_compact", (_event: SessionCompactEvent, _ctx: ExtensionContext) => {
+    try {
+      const rewritten = getBoundNotifyLedger()?.compactionCheck() ?? 0;
+      if (rewritten > 0) {
+        logger.warn(`[subagents] notify ledger entries lost to compaction; rewrote ${rewritten} from memory`);
+      }
+    } catch (err) {
+      logger.warn("[subagents] notify ledger compactionCheck failed", {
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+
+  // ════════════════════════════════════════════════════════════
+  //  [U7] before_agent_start：引擎模型段注入（defaultEngine 非 pi 且引擎实现
+  //  listModels 时追加 <available_<engine>_models>——每 turn 重判 config，改配置
+  //  后下一 turn 即生效；fail-safe 任何异常不注入不阻塞 agent loop）
+  // ════════════════════════════════════════════════════════════
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
+    try {
+      const service = getModelConfigService();
+      const append = service === null ? "" : buildEngineModelsPromptAppend(service.getGlobalConfig().defaultEngine);
+      if (append === "" || typeof event.systemPrompt !== "string") return undefined;
+      return { systemPrompt: `${event.systemPrompt}\n\n${append}` };
+    } catch {
+      return undefined;
+    }
+  });
+
   // ════════════════════════════════════════════════════════════
   //  model_select：用户切换 model 时刷新缓存
   // ════════════════════════════════════════════════════════════

package/src/interface/__tests__/subagent-tool-path-guard.test.ts

@@ -0,0 +1,157 @@
+// subagent tool 路径类参数守卫测试（三通道对称审查修复 + MF-13）。
+//
+// 修复背景：subagent tool 的 skillPath 参数此前零校验直传 session-runner 拼
+// `--skill <path>`；cwd 仅 description 声明 "Must be an absolute path" 无运行时
+// 闸。schema pattern（^/）经 pi agent-loop 运行时强校验已是强制（PS-20：
+// agent-loop.js:403-404 → validation.js:247-273），工具层守卫定位 = defense-in-depth
+// + schema 表达力缺口——`..` 穿越语义超出 pattern 能力（^/ 放行 "/a/../b"），
+// 守卫在 executeSubagent start 分支 immediate throw（与 action 枚举守卫同风格）。
+//
+// 本文件锁住：
+//   1. skillPath / cwd 含 `..` 穿越段 → 同步 reject，service.execute 零触达
+//   2. skillPath / cwd 相对路径 → 同步 reject
+//   3. 合法绝对路径放行 → 参数原样透传 service.execute（守卫零误伤对照）
+//
+// harness 复用 sdk-contract.test.ts 的 mock 链（pi-ai/typebox/subagent-service），
+// registerSubagentTool 后捕获 execute 回调直接调用。
+
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("@earendil-works/pi-ai", () => ({
+  StringEnum: (values: string[]) => ({ type: "string", enum: values }),
+}));
+vi.mock("typebox", () => ({
+  Type: {
+    Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
+    Optional: (schema: unknown) => ({ ...(schema as object), optional: true }),
+    String: (opts?: Record<string, unknown>) => ({ type: "string", ...opts }),
+    Boolean: () => ({ type: "boolean" }),
+    Number: (opts?: Record<string, unknown>) => ({ type: "number", ...opts }),
+    Array: (items: unknown) => ({ type: "array", items }),
+    Record: (key: unknown, value: unknown) => ({ type: "object", additionalProperties: value, key }),
+    Unknown: () => ({ type: "unknown" }),
+    Union: (members: unknown[]) => ({ type: "union", members }),
+    Literal: (value: unknown) => ({ type: "literal", value }),
+  },
+}));
+
+// Mock getSubagentService：断言「守卫拒绝时 service.execute 零触达」的承重证据。
+const { mockServiceExecute } = vi.hoisted(() => ({
+  mockServiceExecute: vi.fn(),
+}));
+vi.mock("../../execution/subagent-service.ts", () => ({
+  getSubagentService: () => ({ execute: mockServiceExecute }),
+}));
+
+import { registerSubagentTool } from "../../interface/subagent-tool.ts";
+import { mockExtensionApi } from "../../execution/__tests__/helpers/mock-extension-api.ts";
+
+type ExecuteCb = (...args: unknown[]) => Promise<unknown>;
+
+/** 注册 tool 并捕获 execute 回调（sdk-contract 同款）。 */
+function captureExecute(): ExecuteCb {
+  let captured: ExecuteCb | undefined;
+  const pi = mockExtensionApi({
+    registerTool: (tool: unknown) => {
+      captured = (tool as { execute: ExecuteCb }).execute;
+    },
+  });
+  registerSubagentTool(pi);
+  if (!captured) throw new Error("subagent tool not registered");
+  return captured;
+}
+
+/** 合法 start 入参基线（守卫测试只变动 skillPath/cwd 字段）。 */
+function baseParams(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return { action: "start", task: "guard task", slug: "path-guard", ...over };
+}
+
+/** 合法 execute 返回值 stub（放行路径 adapter 包装用）。 */
+function stubHandle() {
+  return {
+    mode: "background",
+    subagentId: "sa-path-guard",
+    sessionFile: "/tmp/session.jsonl",
+    details: { slug: "path-guard", model: "test/model" },
+  };
+}
+
+describe("subagent tool 路径守卫（skillPath/cwd：绝对路径 + 禁 .. 穿越）", () => {
+  let execute: ExecuteCb;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockServiceExecute.mockResolvedValue(stubHandle());
+    execute = captureExecute();
+  });
+
+  // ── `..` 穿越段拒绝 ──
+
+  it("skillPath 含 .. 穿越段 → immediate reject，service.execute 零触达", async () => {
+    await expect(
+      execute("call-1", baseParams({ skillPath: "../../etc/passwd" }), undefined, undefined, undefined),
+    ).rejects.toThrow(/skillPath must not contain '\.\.' path segments/);
+
+    expect(mockServiceExecute).not.toHaveBeenCalled();
+  });
+
+  it("cwd 含 .. 穿越段 → immediate reject，service.execute 零触达", async () => {
+    await expect(
+      execute("call-2", baseParams({ cwd: "/safe/root/../../unsafe" }), undefined, undefined, undefined),
+    ).rejects.toThrow(/cwd must not contain '\.\.' path segments/);
+
+    expect(mockServiceExecute).not.toHaveBeenCalled();
+  });
+
+  // ── 相对路径拒绝（`~` 缩写不是绝对路径，一并拒）──
+
+  it("skillPath 相对路径 → immediate reject（报错指引展开为绝对路径）", async () => {
+    await expect(
+      execute("call-3", baseParams({ skillPath: ".agents/skills/my-skill" }), undefined, undefined, undefined),
+    ).rejects.toThrow(/skillPath must be an absolute path.*Expand '~' yourself/s);
+
+    expect(mockServiceExecute).not.toHaveBeenCalled();
+  });
+
+  it("cwd 相对路径 → immediate reject", async () => {
+    await expect(
+      execute("call-4", baseParams({ cwd: "relative/dir" }), undefined, undefined, undefined),
+    ).rejects.toThrow(/cwd must be an absolute path/);
+
+    expect(mockServiceExecute).not.toHaveBeenCalled();
+  });
+
+  it("cwd `~` 缩写 → immediate reject（下游 spawn cwd 不展开 ~）", async () => {
+    await expect(
+      execute("call-5", baseParams({ cwd: "~/project" }), undefined, undefined, undefined),
+    ).rejects.toThrow(/cwd must be an absolute path/);
+
+    expect(mockServiceExecute).not.toHaveBeenCalled();
+  });
+
+  // ── 放行对照（守卫零误伤）──
+
+  it("合法绝对路径 skillPath/cwd 放行，参数原样透传 service.execute", async () => {
+    await execute(
+      "call-ok",
+      baseParams({ skillPath: "/work/project/.agents/skills/my-skill", cwd: "/work/project" }),
+      undefined,
+      undefined,
+      undefined,
+    );
+
+    expect(mockServiceExecute).toHaveBeenCalledTimes(1);
+    expect(mockServiceExecute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        skillPath: "/work/project/.agents/skills/my-skill",
+        cwd: "/work/project",
+      }),
+    );
+  });
+
+  it("不传 skillPath/cwd → 守卫不介入（undefined 合法缺省）", async () => {
+    await execute("call-none", baseParams(), undefined, undefined, undefined);
+
+    expect(mockServiceExecute).toHaveBeenCalledTimes(1);
+  });
+});

package/src/interface/__tests__/subagent-tool-prompt.test.ts

@@ -114,6 +114,18 @@ describe("subagent tool description — 行为约束器（非功能说明书）"
     expect(DESCRIPTION).not.toContain('"sa_');
   });
 
+  it("Examples 示例 agent 值必须是绝对路径 .md 形态（显式 ref 硬守卫拒绝裸名）", () => {
+    // 显式 agent ref 走硬守卫：getRequiredAgentConfig → loadByPath(ref, true)，
+    // 裸名（normalizeRef 非绝对路径 → null）同步 throw `Invalid agent ref` +
+    // <available_subagents> 恢复指引（explicit-agent-ref-guard.test.ts 锁定拒绝路径）。
+    // 示例若教裸名（历史漂移："agent":"coder"），弱模型照抄即必败调用——浪费一轮
+    // 并系统性教唆反模式。与 subagentId 格式测试同风格：示例必须与实际契约一致。
+    // ① 零裸名：任何 "agent":"<非/>" 形态都禁止
+    expect(DESCRIPTION).not.toMatch(/"agent":"(?!\/)[^"]*"/);
+    // ② 正例在位且为绝对路径 .md 形态（<available_subagents> 注入的 <location> 形态）
+    expect(DESCRIPTION).toMatch(/"agent":"\/[^"]*\.md"/);
+  });
+
   it("agent 字段 description 不写死枚举，指向 <available_subagents>（通用化防漂移）", () => {
     // 原实现把 9 个内置 agent 名写死在 schema field description（防漏），
     // 但枚举与包内 agents/*.md 存在漂移风险（新增/删除 agent 要手改两处）。

package/src/interface/bg-notify-render.ts

@@ -23,6 +23,9 @@ import type { Component } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
 import { displayAgentName } from "../shared/agent-ref.ts";
+import { deriveOutcome } from "../execution/execution-record.ts";
+import { CLOSED_REASONS } from "../execution/types.ts";
+import type { ClosedReason, ExecutionOutcome } from "../execution/types.ts";
 import {
   firstLine,
   padToVisible,
@@ -55,8 +58,10 @@ interface BgNotifyRecord {
   id: string;
   /** v4 B-1: closed（终态，含 cancelled）或 running（对话模式轮次完成，旧 idle）。 */
   status: "running" | "closed";
-  /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。 */
-  closedReason?: string;
+  /** L2 关闭原因子枚举（内部诊断 + outcome 兑底派生输入；经 toClosedReason 防御性收窄）。 */
+  closedReason?: ClosedReason;
+  /** 终态三态对外语义（U3 C-outcome）。缺失（升级前旧消息重放）时按 deriveOutcome 兑底。 */
+  outcome?: ExecutionOutcome;
   agent: string;
   model?: string;
   result?: string;
@@ -218,12 +223,15 @@ function renderRecordLines(record: BgNotifyRecord, t: ThemeLike): string[] {
   const modelPart = record.model
     ? ` ${t.fg("dim", "·")} ${t.fg("accent", truncLine(record.model, MODEL_MAX_WIDTH))}`
     : "";
-  // v4 B-1: closed 统一终态（含 cancelled）。按 closedReason 派生文案。
-  const reason = record.closedReason ?? "gc";
+  // U3 C-outcome：verb 与正文分流只读 outcome——单一权威派生（升级前旧消息重放等
+  // details 缺 outcome 的存量形态经 deriveOutcome(closedReason, error) 兑底，非同构
+  // 重写）。判定先于 patchFile：failed 分支不展示 patch/result（失败轮也会写
+  // patchFile，历史 bug 存档见 deriveOutcome 注释）。
+  const outcome = record.outcome ?? deriveOutcome(record.closedReason, record.error);
   let verb: string;
-  if (reason === "cancelled") {
+  if (outcome === "cancelled") {
     verb = "cancelled";
-  } else if (reason === "gc" && record.error) {
+  } else if (outcome === "failed") {
     verb = "failed";
   } else {
     verb = "finished";
@@ -233,13 +241,12 @@ function renderRecordLines(record: BgNotifyRecord, t: ThemeLike): string[] {
 
   switch (record.status) {
     case "closed": {
-      // v4 B-1: closed 统一终态（含 cancelled）。cancelled 无正文；失败显示错误；否则结果/patch。
-      const r = record.closedReason ?? "gc";
-      if (r === "cancelled") {
+      // U3 C-outcome：cancelled 无正文；failed 显示错误；否则结果/patch（同上，分流只读 outcome）。
+      if (outcome === "cancelled") {
         return [head];
       }
-      if (r === "gc" && record.error) {
-        return [head, t.fg("dim", truncLine(`Error: ${firstLineSanitized(record.error)}`, BODY_MAX_WIDTH))];
+      if (outcome === "failed") {
+        return [head, t.fg("dim", truncLine(`Error: ${firstLineSanitized(record.error ?? "")}`, BODY_MAX_WIDTH))];
       }
       if (!record.result && !record.patchFile) return [head];
       const lines: string[] = [];
@@ -275,6 +282,19 @@ function extractBatch(details: unknown): BgNotifyRecord[] | undefined {
   return records.length > 0 ? records : undefined;
 }
 
+/**
+ * details.closedReason 防御性收窄：任意字符串 → ClosedReason | undefined。
+ * 旧数据/外部构造的非法值按缺失处理，交由 deriveOutcome 兑底（消费方不崩溃）。
+ */
+function toClosedReason(value: unknown): ClosedReason | undefined {
+  return CLOSED_REASONS.find((reason) => reason === value);
+}
+
+/** details.outcome 防御性收窄：仅接受三态枚举值，其余按缺失处理。 */
+function toOutcome(value: unknown): ExecutionOutcome | undefined {
+  return value === "completed" || value === "failed" || value === "cancelled" ? value : undefined;
+}
+
 /**
  * 从 message.details 防御性提取 BgNotifyRecord。
  * 结构不全（缺 status / agent）返回 undefined。
@@ -297,7 +317,8 @@ function extractBgNotifyRecord(details: unknown): BgNotifyRecord | undefined {
     model: typeof d.model === "string" ? d.model : undefined,
     result: typeof d.result === "string" ? d.result : undefined,
     error: typeof d.error === "string" ? d.error : undefined,
-    closedReason: typeof d.closedReason === "string" ? d.closedReason : undefined,
+    closedReason: toClosedReason(d.closedReason),
+    outcome: toOutcome(d.outcome),
     round: typeof d.round === "number" ? d.round : undefined,
     // [MF#1] 提取 patchFile（worktree background 完成通知携带）。
     patchFile: typeof d.patchFile === "string" ? d.patchFile : undefined,

package/src/interface/helpers.ts

@@ -238,7 +238,7 @@ export function notifyDone(
 
   const content = parts.join("\n");
 
- // deliverAs:"steer" + triggerTurn:true —— workflow 完成作为 steering 消息注入
+ // deliverAs:"steer" + triggerTurn:true —— workflow 完成作为 steering 消息注入（g4-allow: 存量待迁移——结果语义通知，账本化迁移登记 pi-boundary-reliability 附录 B 待办）
  // 并立即唤醒 parent agent 处理结果（与 subagent 的 followUp+triggerTurn 对称）
   const details: WorkflowNotifyDetails = {
     runId,
@@ -275,7 +275,7 @@ export function notifyDone(
       display: true,
       details,
     },
-    { triggerTurn: true, deliverAs: "steer" },
+    { triggerTurn: true, deliverAs: "steer" }, // g4-allow: 存量待迁移——workflow 完成通知属结果语义，迁移切片复用 U2 账本设施（附录 B 待办）
   );
 }
 

package/src/interface/subagent-actions.ts

@@ -17,7 +17,7 @@ import {
 } from "@xyz-agent/extension-protocol";
 
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
-import { computeElapsedSeconds } from "../execution/execution-record.ts";
+import { computeElapsedSeconds, projectOutcome } from "../execution/execution-record.ts";
 import { isResumable } from "../execution/lifecycle-predicates.ts";
 import type { ExecutionRecord } from "../execution/types.ts";
 import type { ModelInfo } from "../execution/model-resolver.ts";
@@ -49,6 +49,9 @@ const MAX_LIST_LIMIT = 100;
 /** background 启动提示文案（spec FR-3 bgResponse.message）。 */
 const BG_MESSAGE = "detached, will notify on completion (auto-injected message, do not poll)";
 
+/** 通知投递契约回显恒值（U1 预置，U2 账本兑现，见 BgResponse.notifyContract）。 */
+const NOTIFY_CONTRACT = "ledger+at-least-once" as const;
+
 /** subagentId（UUID）在 GUI header 的截断显示长度。 */
 const SUBAGENT_ID_PREVIEW = 8;
 
@@ -79,8 +82,13 @@ export interface StartHandlerInput {
   cwd?: string;
   /** 可持续对话模式（true = chatMode，轮次完成进 idle 等续聊）。 */
   conversation?: boolean;
-  /** 空闲超时毫秒数（仅 conversation 模式有意义，覆盖默认 5min）。 */
+  /**
+   * 空闲超时毫秒数（仅 conversation 模式有意义，覆盖默认 5min）。
+   * 显式传 0/负数 = 禁用 idle GC（不挂 timer）；不传走 env/默认优先级。
+   */
   idleTimeoutMs?: number;
+  /** 执行引擎（D4 三层路由第一层：本参数 > agent frontmatter engine > config defaultEngine）。 */
+  engine?: string;
 }
 
 /** start 领域对象（adapter 包成 bgResponse）。 */
@@ -90,6 +98,11 @@ export type StartHandlerResult = {
   sessionFile: string | undefined;
   /** 短标签，来自 record（handle.details.slug）。用于 result 行展示。 */
   slug: string;
+  /**
+   * registry 全等回显（U1）：handle.details.model = record.model = `${provider}/${id}`，
+   * 源头是 resolveModel 裁决放行的条目——通过校验 = 子进程必然按此名执行。
+   */
+  model: string;
   response: BgResponse;
 };
 
@@ -152,9 +165,11 @@ export function mapExternalState(status: ExecutionStatus): ExternalState {
 }
 
 /** SubagentRecord → SubagentListItem（state 四态主字段 + status 调试字段，duration 实时计算）。
- *  [v4 A-6] 新增 parent/resumable/closedReason：parent 从 record.parentRecordId 派生
- *  （配合 A-5 直接父守卫），resumable 从 isResumable 派生（B-1「可续聊」对外表达），
- *  closedReason 透传（SP-4 级联关闭告知替代 before_agent_start 注入）。
+ *  [v4 A-6] 新增 parent/resumable：parent 从 record.parentRecordId 派生（配合 A-5 直接父
+ *  守卫），resumable 从 isResumable 派生（B-1「可续聊」对外表达）。
+ *  [U3 C-outcome] 新增 outcome 一等终态语义（projectOutcome 唯一出口）；closedReason
+ *  退出对外 JSON（保留为 record 内部诊断字段），对外成败判读收口到 outcome，消费方
+ *  零手写推导（三处同构 switch 已收敛删除）。
  *  agent 是 GUI/TUI list 共用的显示名——取 basename 短名（displayAgentName），
  *  完整路径保留在 record.agent（数据层）。 */
 export function recordToListItem(r: SubagentRecord): SubagentListItem {
@@ -171,7 +186,7 @@ export function recordToListItem(r: SubagentRecord): SubagentListItem {
     sessionFile: r.sessionFile,
     parent: r.parentRecordId,
     resumable: isResumable(r),
-    closedReason: r.closedReason,
+    outcome: projectOutcome(r),
   };
 }
 
@@ -219,6 +234,7 @@ export async function startHandler(
     cwd: input.cwd,
     conversation: input.conversation,
     idleTimeoutMs: input.idleTimeoutMs,
+    engine: input.engine,
     ctxModel,
     signal,
     // background detached 运行，完成由 notify 驱动新 turn。
@@ -229,10 +245,13 @@ export async function startHandler(
     subagentId: handle.subagentId,
     sessionFile: handle.sessionFile,
     slug: handle.details.slug,
+    // [U1] registry 全等回显：record.model 由 resolved（裁决放行条目）拼接，原样透出。
+    model: handle.details.model,
     response: {
       status: "running",
       mode: "background",
       message: BG_MESSAGE,
+      notifyContract: NOTIFY_CONTRACT,
     },
   };
 }
@@ -468,7 +487,8 @@ export function adapter(
     const d = input.domain;
     // MF-3（决策 10 细则 4）：LLM content (text) 用 null 瘦身，防诱导 agent 用 read 绕过工具
     // 直接读 session 文件。真实 sessionFile 仅 details 保留（供 GUI/程序化消费）。
-    result = { action, subagentId: d.subagentId, sessionFile: null, slug: d.slug, bgResponse: d.response };
+    // [U1] model 为 registry 全等回显（放行即全等）。
+    result = { action, subagentId: d.subagentId, sessionFile: null, slug: d.slug, model: d.model, bgResponse: d.response };
   } else if (action === "list") {
     result = { action, subagentId: null, sessionFile: null, listResponse: input.domain.response };
   } else if (action === "cancel") {
@@ -488,7 +508,7 @@ export function adapter(
   let detailsBase: SubagentToolResult = result;
   if (action === "start") {
     const d = input.domain;
-    detailsBase = { action: "start", subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, slug: d.slug, bgResponse: d.response };
+    detailsBase = { action: "start", subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, slug: d.slug, model: d.model, bgResponse: d.response };
   }
 
   // GUI 协议：RPC 模式下附加结构化渲染数据（union 各成员已声明 __gui__?，无需强转）
@@ -500,7 +520,7 @@ export function adapter(
   // reminder 作为第二个 text block（独立追加，不污染 details/JSON schema）。
   // 只有 list 触发——start 的 reminder 已在 BG_MESSAGE 里；cancel 无需。
   const reminder = action === "list"
-    ? "\n\nReminder: Subagent completion is auto-notified via injected message (deliverAs: steer). Do NOT poll in a loop — there is no poll action. Use action:'list' only when you concretely need state, then continue working or stop."
+    ? "\n\nReminder: Subagent completion is auto-notified via auto-injected message (turn-triggering on idle). Do NOT poll in a loop — there is no poll action. Use action:'list' only when you concretely need state, then continue working or stop." // g4-allow: 契约文案——reminder 字符串描述自动注入通道（triggerTurn 单通道，U2/D5 无 deliverAs），非实际投递调用
     : "";
 
   return {