@zhushanwen/pi-subagent-workflow 8.5.0 → 8.6.0

package/src/execution/subprocess-agent-runner.ts

@@ -31,6 +31,7 @@ import type { AgentOutcome, EngineHandle } from "./engine/types.ts";
 import { mapToExecuteOptions, mergeTimeoutSignal } from "./execute-options-mapper.ts";
 import { getModelConfigService } from "./model-config-service.ts";
 import type { ModelInfo } from "./model-resolver.ts";
+import { modelRefFromVerified } from "../shared/model-ref";
 import { registerSpawnedChildForRecord } from "./session-runner.ts";
 import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
@@ -185,6 +186,19 @@ export class SubprocessAgentRunner implements AgentRunner {
     };
 
     try {
+      // ── [U1 D2] RunContext.modelRef 接入：ctxModel 继承路径的孪生守卫 ──
+      // ctxModel 是运行时已验证的 ModelInfo（豁免 registry 存在性复查），但继承产出的
+      // canonical 串与显式入参走同一个 pi pattern 引擎，孪生守卫同等适用（modelRefFromVerified）。
+      // 守卫在 engine.run 之前同步拒绝：含孪生 registry 下不产生任何 record/spawn，
+      // 失败走下方 catch → errorResult（错误文案含恢复指引）。
+      // RunContext 类型本身定义在 engine/port.ts（跨模块 port，不在本单元领地），
+      // 故接入点为构造 runCtx 前的守卫调用；pi 链路下游 resolveModel 的 ctxModel 分支
+      // 有同一守卫（model-resolver.ts），两处共用同一入口函数。
+      if (this.ctxModel) {
+        const modelService = getModelConfigService();
+        if (modelService) modelRefFromVerified(this.ctxModel, modelService.getModelRegistry());
+      }
+
       // ── D-A9: timeoutMs 合并 signal（超时 abort 带 HOST_TIMEOUT_ABORT_REASON 标记）──
       const mergedSignal = mergeTimeoutSignal(signal, opts.timeoutMs);
 

package/src/execution/types.ts

@@ -61,6 +61,37 @@ export type ExecutionStatus = "running" | "closed";
  */
 export type ClosedReason = 'parent-shutdown' | 'parent-fork' | 'parent-new' | 'user-close' | 'cancelled' | 'gc';
 
+/** ClosedReason 全枚举值（运行时守卫用——防御性解析外部输入时校验成员资格）。 */
+export const CLOSED_REASONS: readonly ClosedReason[] = [
+  'parent-shutdown',
+  'parent-fork',
+  'parent-new',
+  'user-close',
+  'cancelled',
+  'gc',
+];
+
+/**
+ * 终态三态对外语义（U3 C-outcome 一等披露）。
+ *
+ * 由 completeRecord 唯一写入点按 deriveOutcome 一次计算（判定顺序：cancelled 优先
+ * → error 非空 → completed），消费方（project/list/notify 文案/渲染器）只读本字段，
+ * 不再各自手写成败推导 switch（三处同构 switch 已随 U3 收敛删除）。
+ *
+ * [D6 显式取舍] parent-shutdown/parent-fork/parent-new 合成关闭（subagent-service
+ * disposeAllRecords 合成 result 恒写 error:"closed due to ..."）落 "failed"——语义为
+ * 「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏，勿当 bug 改回 cancelled。
+ */
+export type ExecutionOutcome = "completed" | "failed" | "cancelled";
+
+/**
+ * 对外投影的 outcome 联合：含历史 record（outcome 字段诞生前的存量数据）兼容态。
+ * 投影层（projectOutcome 唯一出口）对无 outcome 字段的 closed record 按
+ * deriveOutcome(closedReason, error) 兜底派生；"closed-legacy" 预留给连派生输入都
+ * 不足以判读的存量形态，消费方必须处理该成员（不得因未知值崩溃）。
+ */
+export type ProjectedOutcome = ExecutionOutcome | "closed-legacy";
+
 /**
  * 对外四态（设计决策 10 细则 3）：内部 ExecutionStatus（v4 B-1 两态）收敛为 agent
  * 可理解的状态语义。真实映射只有两条：
@@ -417,6 +448,12 @@ export interface ExecutionRecord {
    *  由 tryTransition(record, "closed", reason) 写入；投影层按需派生对外语义。
    *  向后兼容：旧 record 无此字段，按 gc 处理（通用完成/失败）。 */
   closedReason?: ClosedReason;
+  /**
+   * 终态三态对外语义（U3 C-outcome）。completeRecord 唯一写入点按 deriveOutcome
+   * 一次计算，消费方只读本字段不再自行推导。向后兼容：旧 record / 磁盘重建
+   * record 无此字段，投影层按 projectOutcome 兜底（closed-legacy 语义）。
+   */
+  outcome?: ExecutionOutcome;
   /** 完整执行内容，按 turn 组织。createRecord 初始化为 [空 turn]。 */
   turns: Turn[];
   /** turn 计数（= turns.filter(closed).length，冗余存储供投影直接读）。 */
@@ -520,6 +557,11 @@ export interface ExecutionRecord {
  */
 export interface SubagentToolDetails {
   status: ExecutionStatus;
+  /**
+   * 终态三态对外语义（U3 C-outcome，projectOutcome 唯一出口）。running → undefined；
+   * 历史数据无 outcome 字段时兜底派生（见 ProjectedOutcome）。
+   */
+  outcome?: ProjectedOutcome;
   mode: ExecutionMode;
   agent: string;
   model: string;
@@ -564,6 +606,10 @@ export interface ExecuteOptions {
   schema?: Record<string, unknown>;
   /** D-A6 bridge: workflow schemaEnv 经 ExecuteOptions 透传到 runSpawn childEnv。 */
   schemaEnv?: string;
+  /**
+   * Turn 上限 limiter。显式 0/负 = 显式不限：压过 SPAWN_WATCHDOG_ENV 兑底不挂
+   * watchdog（SP-6 参数 > env，U5）；undefined 未传才由 env 兑底。
+   */
   maxTurns?: number;
   graceTurns?: number;
   /** sync 模式来自 Pi tool 框架；background 模式 hub 忽略，自建 controller。 */
@@ -587,6 +633,7 @@ export interface ExecuteOptions {
   /**
    * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
    * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
+   * 显式传 0/负数 = 禁用 idle GC（不挂 timer；旧实现 0 会落成 setTimeout(0) 立即 kill）。
    */
   idleTimeoutMs?: number;
   /**
@@ -643,10 +690,13 @@ export interface SubagentListItem {
   /** 可冷路径 resume（running 且无活进程句柄）。[v4 A-6] B-1「可续聊」对外表达，
    *  agent 据 list 判断哪些 running subagent 实际可续聊（vs 正在忙）。 */
   resumable?: boolean;
-  /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。[v4 A-6] SP-4 级联关闭告知
-   *  替代——砍 before_agent_start 注入通道后，被级联关闭的 record 经 list
-   *  （includeFinished:true）可查，closedReason 显示 'parent-fork'/'parent-new' 等。 */
-  closedReason?: ClosedReason;
+  /**
+   * 终态三态对外语义（U3 C-outcome 一等披露，projectOutcome 唯一出口）：
+   * completed / failed / cancelled，历史 record 无 outcome 字段时兜底派生，
+   * 不可判读的存量形态为 "closed-legacy"。GUI pane / agent 据此判读成败，
+   * 无需翻 error 字段原文（S5）。
+   */
+  outcome?: ProjectedOutcome;
 }
 
 /** background 启动的内层响应（挂在 SubagentToolResult.bgResponse）。 */
@@ -655,6 +705,19 @@ export interface BgResponse {
   mode: "background";
   /** 启动提示文案（"detached, will notify on completion"）。 */
   message: string;
+  /**
+   * 终态三态语义（U3 C-outcome 对外 JSON 契约完备位）。start 时点 record 尚未终态，
+   * 恒 undefined（JSON.stringify 落键省略）；终态成败语义经 list items[].outcome
+   * 披露。旧字段 status/mode/message 原样保留（向后兼容）。
+   */
+  outcome?: ProjectedOutcome;
+  /**
+   * 通知投递契约回显位（U1 预置，U2 通知账本的契约声明）。恒值
+   * "ledger+at-least-once"：主 agent 在当前 run 结束或有限延迟内收到完成通知，
+   * 送达保证为 at-least-once + notifyId 幂等可识别。字段与填充由 U1 负责，
+   * 值语义由 U2（execution/notify-ledger.ts）兑现。
+   */
+  notifyContract: "ledger+at-least-once";
 }
 
 /** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
@@ -697,7 +760,7 @@ export interface CloseResponse {
  *   - close → closeResponse（subagentId 有值；sessionFile 无意义，可为 null）
  */
 export type SubagentToolResult =
-  | { action: "start"; subagentId: string; sessionFile: string | null; slug: string; bgResponse: BgResponse; __gui__?: GuiRenderResult }
+  | { action: "start"; subagentId: string; sessionFile: string | null; slug: string; /** registry 全等回显（U1）：放行即与 registry 条目全等，"provider/id" 形态。 */ model: string; bgResponse: BgResponse; __gui__?: GuiRenderResult }
   | { action: "list"; subagentId: null; sessionFile: null; listResponse: ListResponse; __gui__?: GuiRenderResult }
   | { action: "cancel"; subagentId: string; sessionFile: null; cancelResponse: CancelResponse; __gui__?: GuiRenderResult }
   | { action: "message"; subagentId: string; sessionFile: null; messageResponse: MessageResponse; __gui__?: GuiRenderResult }

package/src/execution/ui-request-queue.ts

@@ -55,10 +55,20 @@ export function createUiRequestQueue(
     if (processing || queue.length === 0 || closed) return;
     processing = true;
     const { id, request, signal } = queue.shift()!;
-    handleUiRequest(child, id, request, ctx, signal).finally(() => {
-      processing = false;
-      processNext();
-    });
+    // [F2] .catch 在 .finally 之前：handleUiRequest 是 async 函数，任何同步异常（parseChannel
+    // 解析 throw / respond → writeStdinLine 的 EPIPE 同步 throw / catch 分支内 respond 再次
+    // throw）都会变成 rejection。旧链只有 .finally——rejection 穿透后无人接 →
+    // unhandledRejection（Node 15+ 默认 mode=throw）可崩父进程。记 error 后吞掉，
+    // .finally 照常释放 processing 推进队列（单个请求失败不阻塞后续 UI 请求）。
+    handleUiRequest(child, id, request, ctx, signal)
+      .catch((err: unknown) => {
+        const m = err instanceof Error ? err.message : String(err);
+        logger.error(`[subagents] ui request ${id} (${request.method}) failed unexpectedly: ${m}`);
+      })
+      .finally(() => {
+        processing = false;
+        processNext();
+      });
   }
 
   // [R3] 子进程退出时 abort 所有 pending handler，队列不再阻塞

package/src/index.ts

@@ -16,7 +16,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import type { BeforeAgentStartEvent, 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";
 
@@ -39,6 +39,7 @@ import {
   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";
@@ -410,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();
@@ -588,6 +622,25 @@ 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，改配置

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 待办）
   );
 }