@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/injectors/__tests__/workflow-list-injector.test.ts

@@ -10,14 +10,14 @@
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { DiscoveredResource } from "../../shared/resource-discovery.ts";
+import type { DiscoveredResource } from "@zhushanwen/subagent-core/shared/resource-discovery.ts";
 // 共享 mock 基建（vi.mock 工厂 / mock pi / mock ctx）：helpers/injector-test-mocks.ts
 import { createDiscoveryModuleMock, createLoggerModuleMock, createMockCtx, createMockPi, type CapturedHandlers } from "./helpers/injector-test-mocks.ts";
 
 // ── 稳定 spy（vi.hoisted 保证 resetModules 后引用不变，见 subagent 测试同款注释） ──
 const spies = vi.hoisted(() => ({ discoverResources: vi.fn(), getCachedFileContent: vi.fn() }));
 
-vi.mock("../../shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
+vi.mock("@zhushanwen/subagent-core/shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
 
 // 工厂必须写成箭头惰性形式（vi.mock 提升后直接传引用会 TDZ，见 helper 文件头注释）
 vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
@@ -293,7 +293,7 @@ describe("discoverAllWorkflows 顺序契约（KV-cache）", () => {
 		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
 
 		const { discoverAllWorkflows } = await import("../workflow-list-injector");
-		const workflows = await discoverAllWorkflows("/ws", "/agent");
+		const workflows = await discoverAllWorkflows("/ws");
 		expect(workflows.map((w) => w.name)).toEqual(["alpha", "chain", "zeta"]);
 	});
 
@@ -314,8 +314,8 @@ describe("discoverAllWorkflows 顺序契约（KV-cache）", () => {
 		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
 
 		const { discoverAllWorkflows, formatWorkflowList } = await import("../workflow-list-injector");
-		const first = await discoverAllWorkflows("/ws", "/agent");
-		const second = await discoverAllWorkflows("/ws", "/agent");
+		const first = await discoverAllWorkflows("/ws");
+		const second = await discoverAllWorkflows("/ws");
 		expect(second).toEqual(first);
 		expect(formatWorkflowList(second)).toBe(formatWorkflowList(first));
 	});

package/src/injectors/engine-awareness.ts

@@ -0,0 +1,123 @@
+// src/injectors/engine-awareness.ts
+//
+// [engine-awareness U3] 引擎感知检测编排。设计权威源：
+// docs/design/subagent-engine-awareness-injection.md §2.3 物理数据流 /
+// §3.3 D1（per-turn poll）、D1b（lastEngine 初始化与静默基线化）、D2（reload 先行）、
+// D3（通知通道）、D5（三态读取语义）。
+//
+// 职责：per-turn（before_agent_start）三态 poll 全局 config → 与 per-session
+// lastEngine diff → 变更时按硬约束顺序编排：提交读取结果到路由缓存（D2，先于一切——
+// 只改注入不改路由会出现「prompt 说引擎 B、实际派发跑引擎 A」，权威信息源说谎）
+// → sendMessage 对话流通知（D3/D4，短文案不含任何模型清单）→ 更新 lastEngine。
+//
+// 本模块是无状态纯编排（依赖注入式，可测）；状态（lastEngine）与宿主能力
+// （readConfig / applyRead / sendMessage）由 index.ts engine handler 装配注入。
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import type { GlobalConfigReadResult } from "@zhushanwen/subagent-core/execution/config.ts";
+import { DEFAULT_ENGINE_ID, normalizeEngineId } from "@zhushanwen/subagent-core/execution/engine/registry.ts";
+
+const logger = getLogger("subagents");
+
+/** 引擎变更通知 customType（D3；renderer/测试按此识别引擎变更消息）。 */
+export const ENGINE_CHANGE_CUSTOM_TYPE = "subagent-engine-changed";
+
+// normalizeEngineId 单一权威源在 registry.ts，此处再导出保持既有导入面（index.ts
+// 与测试经本模块导入）不断裂。
+export { normalizeEngineId };
+
+/**
+ * 引擎变更通知文案（设计 §3.1 英文基准，三行结构逐字骨架；D4：不含任何模型清单，
+ * 清单只活在 system prompt 现值一份）。指路段按目标引擎参数化，与
+ * <current_subagent_engine> 恒在段的分界语义一致：目标 pi → 指向核心段
+ * <available_provider_models>；非 pi → 指向该引擎清单段 <available_<engine>_models>。
+ */
+export function buildEngineChangeNotice(from: string, to: string): string {
+  const modelsLine =
+    to === DEFAULT_ENGINE_ID
+      ? "Use pi-registry ids from <available_provider_models> for explicit models;"
+      : `Use ids from <available_${to}_models> for explicit models;`;
+  return [
+    `Subagent default engine changed: ${from} → ${to} (effective this turn).`,
+    modelsLine,
+    "omit `model` to inherit. The <current_subagent_engine> section reflects the current state.",
+  ].join("\n");
+}
+
+/** 检测编排依赖（注入式）。生产装配在 index.ts engine handler；测试用 stub。 */
+export interface EngineAwarenessDeps {
+  /** 三态读取全局 config（D5；生产 = () => readGlobalConfig(getAgentDir())）。 */
+  readConfig(): GlobalConfigReadResult;
+  /**
+   * D2：将本 turn 三态读取结果提交路由缓存（生产 = ModelConfigService.applyGlobalConfig，
+   * 纯赋值幂等；failed 已由编排层早退，到达此调用的必为 ok/absent）。
+   */
+  applyRead(read: GlobalConfigReadResult): void;
+  /** 对话流通知投递（D3；生产 = pi.sendMessage(message, {})，不设 triggerTurn）。 */
+  sendMessage(message: {
+    customType: string;
+    content: string;
+    display: boolean;
+    details?: unknown;
+  }): void;
+  /** per-session lastEngine 读取（undefined = 未基线化，D1b）。 */
+  getLastEngine(): string | undefined;
+  /** per-session lastEngine 写入（仅合法引擎 id，不写 undefined）。 */
+  setLastEngine(engine: string): void;
+}
+
+/** 单次 per-turn 检测的编排结果（测试断言面 + 诊断留痕消费）。 */
+export type EngineAwarenessOutcome =
+  | { outcome: "changed"; from: string; to: string }
+  | { outcome: "unchanged"; engine: string }
+  | { outcome: "baseline"; engine: string }
+  | { outcome: "read-failed"; reason: string };
+
+/**
+ * 单个 session 的 per-turn 引擎检测编排（§2.3 数据流 ①② 步；③ 渲染归 index.ts）。
+ *
+ * 分派（D5 三态 × D1b 基线）：
+ *   - read failed → 保持 lastEngine 不动、不提交缓存、不通知（防 torn write 瞬间伪通知）；
+ *     read-failure warn 日志由 readGlobalConfig 内部落，此处只返回结果。
+ *   - lastEngine === undefined（session_start 初始化读失败的兜底形态）→ 静默基线化为
+ *     当前目标值：不算变更、不发通知（防「changed: undefined → zcode」首 turn 伪通知）。
+ *   - last === target（absent 归一后同值也在内）→ 无事。
+ *   - last ≠ target（含 ENOENT=合法缺省）→ 提交缓存先行 → 通知 → 记账，三步同 turn。
+ *
+ * 抛错面：不主动 try-catch——readGlobalConfig 三态返回不抛，applyRead/sendMessage 的
+ * 生产实现各自吞错；handler 顶层 catch 兜底（fail-safe 不阻塞 agent loop）。
+ */
+export function runEngineAwarenessTurn(deps: EngineAwarenessDeps): EngineAwarenessOutcome {
+  const read = deps.readConfig();
+  if (read.status === "failed") {
+    return { outcome: "read-failed", reason: read.reason };
+  }
+  const target = normalizeEngineId(read.config.defaultEngine);
+  const last = deps.getLastEngine();
+  if (last === undefined) {
+    // D1b（修订）：基线化前把本 turn 读取结果提交到单例缓存。baseline 形态可能来自
+    // session_start 读取失败（lastEngine 未设置 + Service 缓存回落缺省）而文件此后被
+    // 修好——若只记账不提交，缓存/路由/状态段永停旧值且永不通知（「改 config 不生效」
+    // 以更隐蔽形态复活）。apply 纯赋值——检测值与缓存值构造性同源，重复提交无害。
+    deps.applyRead(read);
+    deps.setLastEngine(target);
+    return { outcome: "baseline", engine: target };
+  }
+  if (last === target) {
+    return { outcome: "unchanged", engine: target };
+  }
+  // D2 顺序硬约束：先提交读取结果到路由缓存（本 turn 路由 + 渲染同源生效）→ 再通知 → 再记账。
+  deps.applyRead(read);
+  deps.sendMessage({
+    customType: ENGINE_CHANGE_CUSTOM_TYPE,
+    content: buildEngineChangeNotice(last, target),
+    display: true,
+    details: { from: last, to: target },
+  });
+  deps.setLastEngine(target);
+  logger.debug(
+    `[engine-awareness] default engine changed: ${last} -> ${target} (route reloaded, notice sent)`,
+  );
+  return { outcome: "changed", from: last, to: target };
+}

package/src/injectors/model-list-injector.ts

@@ -35,7 +35,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import { escapeXml, renderXmlSection } from "../shared/xml-injection.ts";
+import { escapeXml, renderXmlSection } from "@zhushanwen/subagent-core/shared/xml-injection.ts";
 
 const logger = getLogger("injector");
 

package/src/injectors/subagent-list-injector.ts

@@ -28,17 +28,18 @@ import type {
 	SessionShutdownEvent,
 	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
+import { getHostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
+
 import {
 	discoverResources,
 	findWorkspaceRoot,
 	getCachedFileContent,
 	getCachedParsed,
-} from "../shared/resource-discovery.ts";
-import { parseResourceMeta } from "../shared/meta-parser.ts";
-import { escapeXml, renderXmlSection } from "../shared/xml-injection.ts";
+} from "@zhushanwen/subagent-core/shared/resource-discovery.ts";
+import { parseResourceMeta } from "@zhushanwen/subagent-core/shared/meta-parser.ts";
+import { escapeXml, renderXmlSection } from "@zhushanwen/subagent-core/shared/xml-injection.ts";
 
 const logger = getLogger("injector");
 
@@ -112,12 +113,13 @@ export function parseAgentFrontmatter(content: string): AgentEntry | null {
  */
 export async function discoverAllAgents(
 	workspaceRoot: string,
-	agentDir: string,
 ): Promise<AgentEntry[]> {
 	const resources = await discoverResources({
 		kind: "agents",
 		workspaceRoot,
-		agentDir,
+		// 宿主注入根现取（pi 壳 discoveryRoots 每次现取 getAgentDir，实例隔离）；
+		// agentDir 形参已删——其唯一用途就是喂 ScanConfig（u0-data-discovery 偏差 #7）
+		hostRoots: getHostServices().discoveryRoots?.()?.agents ?? [],
 	});
 
 	const agentMap = new Map<string, AgentEntry>();
@@ -214,7 +216,6 @@ export function setupSubagentListInjector(pi: ExtensionAPI): void {
 				setAgentCache(
 					await discoverAllAgents(
 						findWorkspaceRoot(ctx.cwd),
-						getAgentDir(),
 					),
 				);
 			} catch (err) {
@@ -238,7 +239,6 @@ export function setupSubagentListInjector(pi: ExtensionAPI): void {
 					setAgentCache(
 						await discoverAllAgents(
 							findWorkspaceRoot(ctx.cwd),
-							getAgentDir(),
 						),
 					);
 				}

package/src/injectors/workflow-list-injector.ts

@@ -25,16 +25,17 @@ import type {
 	SessionShutdownEvent,
 	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
+import { getHostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
+
 import {
 	discoverResources,
 	findWorkspaceRoot,
 	getCachedParsed,
-} from "../shared/resource-discovery.ts";
-import { parseResourceMeta } from "../shared/meta-parser.ts";
-import { escapeXml, renderXmlSection } from "../shared/xml-injection.ts";
+} from "@zhushanwen/subagent-core/shared/resource-discovery.ts";
+import { parseResourceMeta } from "@zhushanwen/subagent-core/shared/meta-parser.ts";
+import { escapeXml, renderXmlSection } from "@zhushanwen/subagent-core/shared/xml-injection.ts";
 
 const logger = getLogger("injector");
 
@@ -114,12 +115,13 @@ export function parseWorkflowMeta(content: string): WorkflowEntry | null {
  */
 export async function discoverAllWorkflows(
 	workspaceRoot: string,
-	agentDir: string,
 ): Promise<WorkflowEntry[]> {
 	const resources = await discoverResources({
 		kind: "workflows",
 		workspaceRoot,
-		agentDir,
+		// 宿主注入根现取（pi 壳 discoveryRoots 每次现取 getAgentDir，实例隔离）；
+		// agentDir 形参已删——其唯一用途就是喂 ScanConfig（u0-data-discovery 偏差 #7）
+		hostRoots: getHostServices().discoveryRoots?.()?.workflows ?? [],
 		includeTmp: true,
 	});
 
@@ -178,7 +180,6 @@ export function setupWorkflowListInjector(pi: ExtensionAPI): void {
 				setWorkflowCache(
 					await discoverAllWorkflows(
 						findWorkspaceRoot(ctx.cwd),
-						getAgentDir(),
 					),
 				);
 			} catch (err) {
@@ -202,7 +203,6 @@ export function setupWorkflowListInjector(pi: ExtensionAPI): void {
 					setWorkflowCache(
 						await discoverAllWorkflows(
 							findWorkspaceRoot(ctx.cwd),
-							getAgentDir(),
 						),
 					);
 				}

package/src/interface/__tests__/detectors.test.ts

@@ -18,17 +18,17 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { argKeysFromMeta, findFlattenedArgKeys } from "../tool-workflow";
-import { parseResourceMeta } from "../../shared/meta-parser.ts";
+import { parseResourceMeta } from "@zhushanwen/subagent-core/shared/meta-parser.ts";
 
 // 真实参数集（argKeysFromMeta 产物——m6 动态数据源，与 TC2 同源防漂移）
 function rflKeys() {
-  const src = readFileSync(join(__dirname, "../../../workflows/review-fix-loop.js"), "utf-8");
+  const src = readFileSync(join(__dirname, "../../../node_modules/@zhushanwen/subagent-core/workflows/review-fix-loop.js"), "utf-8");
   const meta = parseResourceMeta(src, "workflow");
   if (!meta || meta.kind !== "workflow" || !meta.parameters) throw new Error("rfl meta");
   return argKeysFromMeta(meta.parameters);
 }
 function chainKeys() {
-  const src = readFileSync(join(__dirname, "../../../workflows/chain.js"), "utf-8");
+  const src = readFileSync(join(__dirname, "../../../node_modules/@zhushanwen/subagent-core/workflows/chain.js"), "utf-8");
   const meta = parseResourceMeta(src, "workflow");
   if (!meta || meta.kind !== "workflow" || !meta.parameters) throw new Error("chain meta");
   return argKeysFromMeta(meta.parameters);

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("@zhushanwen/subagent-core/execution/subagent-service.ts", () => ({
+  getSubagentService: () => ({ execute: mockServiceExecute }),
+}));
+
+import { registerSubagentTool } from "../../interface/subagent-tool.ts";
+import { mockExtensionApi } from "@zhushanwen/subagent-core/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/__tests__/tool-workflow-script-generate.test.ts

@@ -11,14 +11,14 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { actionGenerate, type ScriptParams, type TextContent, registerWorkflowScriptTool } from "../tool-workflow-script.ts";
-import { deleteWorkflow, saveWorkflow } from "../../orchestration/workflow-files.ts";
+import { deleteWorkflow, saveWorkflow } from "@zhushanwen/subagent-core/orchestration/workflow-files.ts";
 
 vi.mock("node:fs", () => ({
   mkdirSync: vi.fn(),
   writeFileSync: vi.fn(),
 }));
 
-vi.mock("../../orchestration/workflow-files.ts", () => ({
+vi.mock("@zhushanwen/subagent-core/orchestration/workflow-files.ts", () => ({
   saveWorkflow: vi.fn(),
   deleteWorkflow: vi.fn(),
 }));

package/src/interface/__tests__/tool-workflow-throw-paths.test.ts

@@ -15,7 +15,7 @@
  */
 import { describe, expect, it, vi } from "vitest";
 
-import { SLUG_MAX_LENGTH } from "../../execution/execute-options-mapper.ts";
+import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core/execution/execute-options-mapper.ts";
 import { REENTRY_BUSY_MESSAGE, type ReentryGuardRef } from "../reentry-guard.ts";
 import { registerWorkflowTool } from "../tool-workflow.ts";
 

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

@@ -22,7 +22,10 @@
 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 { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
+import { deriveOutcome } from "@zhushanwen/subagent-core/execution/execution-record.ts";
+import { CLOSED_REASONS } from "@zhushanwen/subagent-core/execution/types.ts";
+import type { ClosedReason, ExecutionOutcome } from "@zhushanwen/subagent-core/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/commands.ts

@@ -21,9 +21,9 @@
 
 import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 
-import type { LauncherDeps } from "../orchestration/launcher.ts";
-import { abortRun } from "../orchestration/lifecycle.ts";
-import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
+import type { LauncherDeps } from "@zhushanwen/subagent-core/orchestration/launcher.ts";
+import { abortRun } from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
 import { parseWorkflowRpcCommand } from "./command-actions.ts";
 import { createWorkflowsView, type ViewActions } from "./views/WorkflowsView.ts";
 

package/src/interface/format.ts

@@ -14,8 +14,8 @@ import os from "node:os";
 
 import { visibleWidth } from "@earendil-works/pi-tui";
 
-import type { AgentEventLogEntry, DisplayItem, ExecutionStatus } from "../execution/types.ts";
-import { DEFAULT_AGENT_NAME } from "../execution/types.ts";
+import type { AgentEventLogEntry, DisplayItem, ExecutionStatus } from "@zhushanwen/subagent-core/execution/types.ts";
+import { DEFAULT_AGENT_NAME } from "@zhushanwen/subagent-core/execution/types.ts";
 
 /**
  * ThemeLike:TUI 语义 token 着色接口(duck-typed,兼容 Pi Theme).

package/src/interface/helpers.ts

@@ -10,7 +10,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
 import {
   guiComponent,
   type GuiContext,
@@ -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 待办）
   );
 }