@zhushanwen/pi-subagent-workflow 8.14.7 → 9.0.1

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

@@ -1,215 +0,0 @@
-/**
- * W4b：workflow tool 错误路径 throw 语义（代表路径）。
- *
- * pi 只对 execute throw 置 isError:true——返回值里的 isError 被 agent-loop 丢弃
- * （agent-loop.js:453-483），故错误路径必须 throw。本文件抽 4 个代表路径
- * （W4b 验收交付物 3）：
- * - not_found（abort 目标 runId 不存在）
- * - reentry-busy（guard 占用，throw 前未 acquire）
- * - 平铺检测（args 子字段平铺到顶层，LLM 常见错误）
- * - slug 护栏（schema maxLength 之后的运行时第二道）
- * generate 校验族（第 5 代表路径）见 tool-workflow-script-generate.test.ts。
- *
- * 经 registerWorkflowTool 注册层测（capture tool + 最小 deps stub），
- * 与 W4 save/delete 测试同范式。框架：vitest。
- */
-import { describe, expect, it, vi } from "vitest";
-
-import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core";
-import { REENTRY_BUSY_MESSAGE, type ReentryGuardRef } from "../reentry-guard.ts";
-import { registerWorkflowTool } from "../tool-workflow.ts";
-
-// ── capture helper ──
-
-interface CapturedTool {
-  name: string;
-  execute: (
-    toolCallId: string,
-    params: Record<string, unknown>,
-    signal: AbortSignal | undefined,
-    onUpdate: unknown,
-    ctx: unknown,
-  ) => Promise<unknown>;
-}
-
-function captureTool(deps: unknown, reentryRef: ReentryGuardRef): CapturedTool {
-  const tools: CapturedTool[] = [];
-  const pi = { registerTool: (t: unknown) => tools.push(t as CapturedTool) };
-  registerWorkflowTool(pi as never, deps as never, reentryRef);
-  if (!tools[0] || tools[0].name !== "workflow") {
-    throw new Error("registerWorkflowTool did not register the workflow tool");
-  }
-  return tools[0];
-}
-
-/** 最小 LauncherDeps stub：被测路径只触 registry / runs（C5③ 起 actionRun 先查
- *  registry.get 再 registry.getPath——两查都须在 stub 面）。 */
-function makeDeps(overrides: Record<string, unknown> = {}): Record<string, unknown> {
-  return {
-    runs: new Map(),
-    registry: {
-      get: vi.fn().mockResolvedValue(undefined),
-      getPath: vi.fn().mockResolvedValue(undefined),
-      loadAll: vi.fn().mockResolvedValue([]),
-    },
-    ...overrides,
-  };
-}
-
-/** 平铺检测 / slug 护栏路径的 registry script stub（meta.parameters 驱动已知键集）。 */
-function makeScript(parameters?: object): Record<string, unknown> {
-  return {
-    name: "demo-wf",
-    path: "/abs/demo-wf.js",
-    available: true,
-    sourceCode: "// demo",
-    meta: { description: "demo workflow", parameters },
-    toExecutable: () => "// demo",
-  };
-}
-
-// ── 代表路径 ──
-
-describe("W4b: workflow tool 错误路径 throw 语义", () => {
-  it("not_found：abort 目标 runId 不存在 → throw（pi catch 后置 isError:true）", async () => {
-    const tool = captureTool(makeDeps(), { isProcessing: false });
-    await expect(
-      tool.execute("id", { action: "abort", runId: "no-such-run" }, undefined, undefined, {}),
-    ).rejects.toThrow(
-      "Workflow 'no-such-run' not found. Use action:status to list active runs and their runIds.",
-    );
-  });
-
-  it("W4c not_found：run 目标路径不可读（getPath 返回 available:false stub 而非 undefined）→ throw，不假启动", async () => {
-    // config-loader.toCachedMeta 对不存在/不可读文件返回 available:false 的空壳实体
-    // （非 undefined）——旧判定仅 !script 绕过 not_found，空 sourceCode 的 run 假启动
-    // （W4b verifier 探针实测复现）。registry 层真行为见 config-loader.ts:143-151。
-    const deps = makeDeps({
-      registry: {
-        get: vi.fn().mockResolvedValue(undefined),
-        getPath: vi.fn().mockResolvedValue({
-          name: "ghost-wf",
-          path: "/tmp/no-such-workflow.js",
-          available: false,
-          sourceCode: "",
-          meta: { description: "", parameters: undefined },
-          toExecutable: () => "",
-        }),
-        loadAll: vi.fn().mockResolvedValue([]),
-      },
-    });
-    const tool = captureTool(deps, { isProcessing: false });
-    await expect(
-      tool.execute("id", { action: "run", name: "/tmp/no-such-workflow.js" }, undefined, undefined, {}),
-    ).rejects.toThrow("Workflow '/tmp/no-such-workflow.js' not found.");
-    // 未假启动：runs 注册表不出现该 run
-    expect(deps.runs).toBeInstanceOf(Map);
-    expect((deps.runs as Map<string, unknown>).size).toBe(0);
-  });
-
-  it("reentry-busy：guard 占用 → throw REENTRY_BUSY_MESSAGE，且 guard 状态不被污染", async () => {
-    const guard: ReentryGuardRef = { isProcessing: true };
-    const tool = captureTool(makeDeps(), guard);
-    await expect(
-      tool.execute("id", { action: "status" }, undefined, undefined, {}),
-    ).rejects.toThrow(REENTRY_BUSY_MESSAGE);
-    // throw 发生在 acquire 之前——占用方语义保持，不产生双重 release
-    expect(guard.isProcessing).toBe(true);
-  });
-
-  it("平铺检测：args 子字段提到顶层 → throw 'Detected ... at top level'（含 Correct 正例）", async () => {
-    const deps = makeDeps({
-      registry: {
-        get: vi.fn().mockResolvedValue(undefined),
-        getPath: vi.fn().mockResolvedValue(
-          makeScript({
-            type: "object",
-            properties: { task: { type: "string" }, items: { type: "array" } },
-            required: ["task"],
-          }),
-        ),
-      },
-    });
-    const tool = captureTool(deps, { isProcessing: false });
-    await expect(
-      tool.execute(
-        "id",
-        { action: "run", name: "/abs/demo-wf.js", task: "do work" },
-        undefined,
-        undefined,
-        {},
-      ),
-    ).rejects.toThrow(
-      /Detected task at top level — they belong inside 'args'\. Correct: \{"action":"run","name":"\/abs\/demo-wf\.js","args":\{"task": "<value>"\}\}/,
-    );
-  });
-
-  it("slug 护栏：slug 超 SLUG_MAX_LENGTH → throw 'slug exceeds ...'（运行时第二道）", async () => {
-    const deps = makeDeps({
-      registry: {
-        get: vi.fn().mockResolvedValue(undefined),
-        getPath: vi.fn().mockResolvedValue(
-          makeScript({
-            type: "object",
-            properties: { task: { type: "string" } },
-            required: ["task"],
-          }),
-        ),
-      },
-    });
-    const tool = captureTool(deps, { isProcessing: false });
-    const longSlug = "a".repeat(SLUG_MAX_LENGTH + 1);
-    await expect(
-      tool.execute(
-        "id",
-        { action: "run", name: "/abs/demo-wf.js", slug: longSlug, args: {} },
-        undefined,
-        undefined,
-        {},
-      ),
-    ).rejects.toThrow(
-      `slug exceeds ${SLUG_MAX_LENGTH} chars (got ${longSlug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`,
-    );
-  });
-
-  it("OR-1 入口校验：time 超 setTimeout 上限 → throw 含上限 2147483647 与实际值，run 未启动", async () => {
-    const deps = makeDeps({
-      registry: {
-        get: vi.fn().mockResolvedValue(undefined),
-        getPath: vi.fn().mockResolvedValue(
-          makeScript({
-            type: "object",
-            properties: { task: { type: "string" } },
-            required: ["task"],
-          }),
-        ),
-      },
-    });
-    const tool = captureTool(deps, { isProcessing: false });
-    // LLM 对「跑久一点」完全可能生成 1e12——超 2^31-1 的典型形态（schema Type.Number
-    // 直通无上界，用户入口 fail-fast 不依赖 lifecycle 内层 assertSafeTimerDelay）
-    await expect(
-      tool.execute(
-        "id",
-        { action: "run", name: "/abs/demo-wf.js", args: { task: "do work" }, time: 1_000_000_000_000 },
-        undefined,
-        undefined,
-        {},
-      ),
-    ).rejects.toThrow(
-      "time budget 1000000000000 ms exceeds the maximum of 2147483647 ms (~24.8 days). Retry with a smaller \"time\", or omit it for unlimited.",
-    );
-    // fail-fast 于 runWorkflow 之前：runs 无条目（abortRun not found 语义保持）
-    expect((deps.runs as Map<string, unknown>).size).toBe(0);
-  });
-
-  it("throw 后 reentry guard 经 finally 正常释放（成功路径回归）", async () => {
-    // abort not_found throw 穿透 execute try/finally：guard 必须复位，否则后续命令全部 busy
-    const guard: ReentryGuardRef = { isProcessing: false };
-    const tool = captureTool(makeDeps(), guard);
-    await expect(
-      tool.execute("id", { action: "abort", runId: "no-such-run" }, undefined, undefined, {}),
-    ).rejects.toThrow(/not found/);
-    expect(guard.isProcessing).toBe(false);
-  });
-});

package/src/interface/__tests__/workflow-state-file-exposure.test.ts

@@ -1,38 +0,0 @@
-// src/interface/__tests__/workflow-state-file-exposure.test.ts
-//
-// W2: WorkflowToolDetails 携带 stateFile + toRunSummary 填充逻辑
-//
-// 防的 bug：workflow run 自身的状态文件路径（<sessionDir>/workflow-state/<runId>.jsonl）
-// 从未暴露到 tool details——overlay/GUI 拿不到，无法定位 run 状态文件做后续查看。
-// 本测试验证 toRunSummary 和 actionRun 的 details 包含 stateFile 字段。
-//
-// 使用源码断言（读 .ts 文件文本）避免 import 重 mock 链——与 workflow-tool-prompt.test.ts 同模式。
-
-import { describe, expect, it } from "vitest";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const TOOL_WORKFLOW_SRC = readFileSync(
-  join(__dirname, "../tool-workflow.ts"),
-  "utf-8",
-);
-
-describe("W2: workflow tool details 暴露 stateFile", () => {
-  it("RunSummary 类型声明含 stateFile 可选字段", () => {
-    // RunSummary 必须声明 stateFile，否则 toRunSummary 返回的对象类型不含此字段
-    expect(TOOL_WORKFLOW_SRC).toMatch(/stateFile\?\s*:\s*string/);
-  });
-
-  it("toRunSummary 调用 deps.store.stateFilePath 填充 stateFile", () => {
-    // toRunSummary 必须从 store.stateFilePath(runId) 取值——这是数据来源
-    expect(TOOL_WORKFLOW_SRC).toMatch(/stateFilePath/);
-  });
-
-  it("run action 的 details 含 stateFile 字段", () => {
-    // actionRun 返回的 details 必须携带 stateFile（run 启动时即暴露路径）
-    // 验证 actionRun 函数体中构造 details 时引用了 stateFilePath
-    expect(TOOL_WORKFLOW_SRC).toMatch(/action.*run[\s\S]*stateFilePath|stateFilePath[\s\S]*action.*run/i);
-  });
-});

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

@@ -1,129 +0,0 @@
-// U1: workflow tool 提示词包含内置 workflow 清单 + 交叉引用。
-//
-// agent（LLM）决策时唯一能看到的 tool 元信息就是 description + promptGuidelines。
-// 若这些文本里不提及内置 workflow（chain/parallel/scatter-gather/map-reduce），
-// LLM 无法知道有现成的编排工具可用，会倾向自己 generate 脚本或瞎猜 name。
-//
-// 本测试用源码断言（读 .ts 文件文本）验证提示词内容，避免 import 重 mock 链
-// （tool-workflow.ts 依赖 pi-ai/typebox/pi-tui/lifecycle 等值导入）。
-
-import { readFileSync } from "node:fs";
-import { dirname,join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { describe, expect, it } from "vitest";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const TOOL_WORKFLOW_SRC = readFileSync(
-  join(__dirname, "../tool-workflow.ts"),
-  "utf-8",
-);
-const TOOL_WORKFLOW_SCRIPT_SRC = readFileSync(
-  join(__dirname, "../tool-workflow-script.ts"),
-  "utf-8",
-);
-
-/** 截取 promptGuidelines 数组文本——防 KNOWN_ARG_KEYS 等注释/代码中的裸词污染断言。
- * 数到数组闭合（跳过字符串字面量内的括号，exec-review F9：'],' 序列静默截断）。 */
-function promptGuidelinesText(src: string): string {
-  const start = src.indexOf("promptGuidelines: [");
-  let depth = 0;
-  let inStr = false;
-  for (let i = start; i < src.length; i++) {
-    const ch = src[i];
-    if (inStr) {
-      if (ch === "\\") { i++; continue; }
-      if (ch === '"') inStr = false;
-      continue;
-    }
-    if (ch === '"') inStr = true;
-    else if (ch === "[") depth++;
-    else if (ch === "]") {
-      depth--;
-      if (depth === 0) return src.slice(start, i + 1);
-    }
-  }
-  return src.slice(start);
-}
-
-describe("U1: workflow tool prompt mentions built-in workflows", () => {
-  it("TC4a: promptGuidelines 不含具体内置 args 枚举（m4 瘦身——参数知识在 read location）", () => {
-    // m4：BUILT-IN 枚举删除，发现职责转移给 <available_workflows> 注入段 + read location。
-    // 截取 promptGuidelines 段断言（"batch1..batchN" 等在 KNOWN_ARG_KEYS 注释中出现）。
-    const guidelines = promptGuidelinesText(TOOL_WORKFLOW_SRC);
-    expect(guidelines).not.toContain("chain (sequential");
-    expect(guidelines).not.toContain("args: task");
-    expect(guidelines).not.toContain("batch1..batchN");
-    expect(guidelines).not.toContain("chain/parallel/scatter-gather/map-reduce");
-  });
-
-  it("TC4b: promptGuidelines 引导 read location 获取参数细节（info 已砍，ADR-0003 D5）", () => {
-    const guidelines = promptGuidelinesText(TOOL_WORKFLOW_SRC);
-    expect(guidelines).toContain("read the <location>");
-    expect(guidelines).toContain("script file");
-    // info action 已砍，引导语不再含 workflow info
-    expect(guidelines).not.toContain("workflow info");
-  });
-
-  it("tool-workflow.ts promptGuidelines 含 workflow-script list 交叉引用", () => {
-    // LLM 需要知道"先 list 再 run"的发现路径——两个 tool 之间必须有交叉引用。
-    // 文本可能跨字符串拼接行，分别断言两个关键词都存在。
-    expect(TOOL_WORKFLOW_SRC).toContain("workflow-script");
-    expect(TOOL_WORKFLOW_SRC).toMatch(/action.*list/i);
-  });
-
-  it("tool-workflow.ts promptGuidelines 含 run action 的正例", () => {
-    // 给出 run 调用的 JSON 示例，LLM 才知道参数格式（action/name/args 嵌套）。
-    expect(TOOL_WORKFLOW_SRC).toContain('{"action":"run","name":"');
-  });
-
-  it("promptGuidelines 含 JSON 调用正例（run/status/lifecycle）", () => {
-    // 弱模型信任 schema 结构信号 > 文本信号，容易把 args 子字段平铺到顶层。
-    // promptGuidelines 必须有完整 JSON 调用正例，让模型能直接照抄 {"action":"run",...} 嵌套结构。
-    expect(TOOL_WORKFLOW_SRC).toContain('{"action":"run"');
-    expect(TOOL_WORKFLOW_SRC).toContain("Call shapes (JSON)");
-  });
-
-  it("promptGuidelines 含参数结构反例（args 平铺到顶层）", () => {
-    // 显式说明 args 子字段不能平铺到顶层，必须嵌在 args 里。
-    expect(TOOL_WORKFLOW_SRC).toContain("args");
-    expect(TOOL_WORKFLOW_SRC).toContain("Anti-patterns");
-    expect(TOOL_WORKFLOW_SRC).toContain("top level");
-  });
-
-  it("runtime handler 错误文案含 Correct 纠正正例 + 平铺检测（m6：动态参数集）", () => {
-    // 读源码文本断言 actionRun/必填校验的错误文案含 Correct 正例，
-    // 让弱模型撞错后第二次能直接照抄正确形态。m6 后平铺检测数据源为动态
-    // argKeysFromMeta（schema 即 SSOT）——断言新机制存在（KNOWN_ARG_KEYS 已删）。
-    expect(TOOL_WORKFLOW_SRC).toContain("Correct:");
-    expect(TOOL_WORKFLOW_SRC).toContain("findFlattenedArgKeys");
-    expect(TOOL_WORKFLOW_SRC).toContain("argKeysFromMeta");
-    expect(TOOL_WORKFLOW_SRC).not.toMatch(/const\s+KNOWN_ARG_KEYS/);
-  });
-
-  it("tool-workflow-script.ts list action 的 promptGuidelines 含 workflow run 交叉引用", () => {
-    // 反向交叉引用：list 的指引里要提到用 workflow tool 的 run action 启动脚本。
-    expect(TOOL_WORKFLOW_SCRIPT_SRC).toMatch(/workflow.*tool.*run|run.*workflow.*tool/i);
-  });
-
-  it("tool-workflow.ts promptGuidelines 强化 anti-generate（直接 run，不要 generate）", () => {
-    // session 证据：弱模型看到 workflow list 后倾向 workflow-script generate 而非直接 run。
-    // 提示词必须显式禁止对内置编排使用 generate。
-    expect(TOOL_WORKFLOW_SRC).toContain("NEVER use workflow-script action:generate");
-  });
-
-  it("tool-workflow-script.ts promptGuidelines 强化 anti-generate（CRITICAL ANTI-PATTERN）", () => {
-    expect(TOOL_WORKFLOW_SCRIPT_SRC).toContain("CRITICAL ANTI-PATTERN");
-    expect(TOOL_WORKFLOW_SCRIPT_SRC).toContain("NEVER generate");
-  });
-
-  it("promptGuidelines + parameter description 标注 budget 默认不限制（B/C：除非用户要求否则别设）", () => {
-    // budget 是 run 级参数，运行时 maxTokens===undefined → 不限制（budget.ts isExceeded 守卫）。
-    // 但 call shape 示例展示了 tokens/time 字段，LLM 会误以为每次都该填。
-    // promptGuidelines 必须明确 "Do NOT set ... unless user explicitly requests",
-    // parameter description 同步标 "omit = unlimited"，双重约束压过示例的反引导。
-    const guidelines = promptGuidelinesText(TOOL_WORKFLOW_SRC);
-    expect(guidelines).toContain("Do NOT set tokens/time unless the user explicitly requests");
-    expect(TOOL_WORKFLOW_SRC).toContain("omit = unlimited (default)");
-  });
-});

package/src/interface/helpers.ts

@@ -1,272 +0,0 @@
-/**
- * Workflow Extension — Interface helpers
- *
- * notifyDone(pi, runId, run, notified) — run 完成时发 completion notification
- * （[u9 账本化] 经 core NotifyLedger 四步生命周期，C-ext-19；未 bind 降级直发）。
- *
- * 层归属：Interface（依赖 Pi SDK + Engine WorkflowRun 模型）。
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-// bounded JSON pretty 序列化（IF13/#19，TC5/ES5）已下沉 core shared
-// （u-core-atomic 逐字平移，输出与原本地实现字节一致；本地实现已删）。
-// getBoundNotifyLedger：core 通知账本消费入口（bindNotifyLedgerHost 在
-// session-lifecycle.ts session_start 装配；未 bind 时降级直发，见 notifyDone 注释）。
-import { boundedPrettySerialize, getBoundNotifyLedger } from "@zhushanwen/subagent-core";
-
-// 模块级 logger（与 session-lifecycle.ts / index.ts 同 component 名）
-const logger = getLogger("subagents");
-
-import type { WorkflowRun } from "@zhushanwen/subagent-core";
-import {
-  guiComponent,
-  type GuiContext,
-  type GuiRenderResult,
-  guiResult,
-  isGuiCapable,
-} from "@zhushanwen/extension-protocol";
-import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
-import { ID_PREVIEW_LENGTH } from "./id-preview.ts";
-
-// ── 常量 ─────────────────────────────────────────────────────
-
-const MAX_RESULT_LENGTH = 8000;
-
-/**
- * notifyDone 账本幂等键前缀（u9 账本化，对齐 C-ext-19）。键形态
- * `wf-done:<runId>`——一个 run 的收口通知只投递一次（写账 → courier 边沿投递 →
- * 回执销账 → 断连/重启经账本重放，幂等键去重不双投递）。前缀惯例承接 collect
- * 时代 `sync-batch:` 的「通道语义前缀 + 天然唯一标识」形态；导出供测试构造
- * 回执 entry 与账本断言复用同键。
- */
-export const WORKFLOW_DONE_NOTIFY_ID_PREFIX = "wf-done:";
-
-/**
- * workflow 收口通知的送达 customType。保持与账本化前一致：runtime
- * event-interpreter 按该类型识别 run 完成并驱动 W18 workflow-record 失效信号
- * （session.workflows 增量广播），taiji 完成通知 display 覆写 SSOT
- * （COMPLETE_NOTIFY_CUSTOM_TYPES）亦按它收录——不可复用 subagent-bg-notify 通道。
- */
-const WORKFLOW_RESULT_CUSTOM_TYPE = "workflow-result";
-
-/**
- * notifiedRunIds 去重窗口大小。
- *
- * 最近该数量的已通知 runId 可去重，更旧挤出后不再去重——runId 全局唯一
- * （wf-<Date.now>-<rand>），旧 id 重现概率为零，语义无损。
- */
-export const MAX_NOTIFIED_RUN_IDS = 1000;
-
-/**
- * notifyDone 的 details 结构（通过 pi.sendMessage 透传给前端）。
- *
- * 抽取为显式接口替代裸 Record<string, unknown>，明确 __gui__ 契约。
- * 模块私有（原 export 已删）：无跨文件消费者，测试经 notifyDone 公共入口
- * 观察并内联类型。
- */
-interface WorkflowNotifyDetails {
-  runId: string;
-  name: string;
-  status: string;
-  reason: string | undefined;
-  traceLength: number;
-  /**
-   * [u9] 账本幂等键（`wf-done:<runId>`）——回执匹配键（ledger checkReceipts 扫
-   * 送达 custom_message entry 的 details.notifyId 判定销账）。携带在 details 不进
-   * 文案（G4 字节锁定不受影响）。
-   */
-  notifyId: string;
-  __gui__?: GuiRenderResult;
-}
-
-/**
- * workflow 到达 done 终态时发送完成通知。
- *
- * [u9 账本化] 结果语义通知接 core NotifyLedger 四步生命周期（C-ext-19：持久账本 +
- * notifyId 幂等，替代裸 steer fire-once——relay 瞬断不再丢通知）：
- *   ① 写账：ledger.record(`wf-done:<runId>`) 落盘（幂等键去重，同 run 跨重启
- *      不双投递）→ ② courier 边沿投递（settled 边沿 + isIdle 二次复查 + 120s
- *      看门狗，送达 customType 保持 "workflow-result"）→ ③ 回执销账 → ④ 断连/
- *      重启经 recoverFromSession at-least-once 重放（机制见 notify-ledger.ts）。
- * 账本未装配时（旧宿主 / 无 ledger 测试）降级为 fire-once 直发（at-most-once，
- * 对齐 notifier 内核降级路径；triggerTurn 单通道，deliverAs 已删——u9 偏差裁决，
- * D7 账本化配套）。
- *
- * **内存去重**：notifiedRunIds Set 由调用方（factory/extension instance）持有，
- * 同 runId 的重复收口回调拦截（跨 session_shutdown 等边界防重复）；标记在写账成功
- * （或账本幂等拒绝）后落下——record 抛（reload 窗口 appendEntry assertActive 等）
- * 不标记，异常由 finalizeRun 围栏接住后重复收口可重试，窗口内不永久丢通知；
- * 持久层幂等由账本 notifyId 承接（内存窗口挤出 / 重启后的重复仍被 record 拒绝）。
- *
- * @param pi ExtensionAPI（仅降级路径直发用）
- * @param runId run 标识
- * @param run WorkflowRun 聚合根（读 spec.scriptName + state.status + trace + scriptResult）
- * @param notifiedRunIds 去重 Set（调用方持有，scope 到 factory 实例）
- */
-export function notifyDone(
-  pi: ExtensionAPI,
-  runId: string,
-  run: WorkflowRun,
-  notifiedRunIds: Set<string>,
-  ctx?: GuiContext,
-): void {
-  if (notifiedRunIds.has(runId)) return;
-
-  const traceNodes = run.state.trace.toArray();
-  const name = run.spec.scriptName;
-  const status = `${run.state.status}${run.state.reason ? ` (${run.state.reason})` : ""}`;
-
- // 构建消息内容
-  const parts: string[] = [];
-  parts.push(`Workflow '${name}' done: ${status}`);
-
- // 终止性原因（非正常完成）追加防偷懒收尾指令——budget/time 耗尽或 abort 不是任务完成，
- // 模型可能把 "done" 当成功汇报（F3 偷懒完成）。收尾三步骤与 turn-limiter WRAP_UP_MESSAGE 对齐。
-  const TERMINAL_REASONS = new Set(["budget_limited", "time_limited", "aborted", "failed", "circular"]);
-  if (run.state.reason && TERMINAL_REASONS.has(run.state.reason)) {
-    parts.push("");
-    parts.push(
-      "This is NOT task completion. Summarize what was DONE and VERIFIED, list what remains " +
-      "NOT DONE, and give the user the single most important next step.",
-    );
-  }
-
-  if (run.state.scriptResult !== undefined && run.state.scriptResult !== null) {
-    // M10: scriptResult 来自 worker 脚本返回值（用户可控），可能含循环引用导致 JSON.stringify 抛 TypeError
-    // IF13(#19)：bounded 序列化（只生成会被保留的前缀；BigInt/循环引用整体回退
-    // String(x) 与旧实现整串 catch 同款）——≤8000 与旧全量 pretty 逐字节一致，
-    // >8000 与 .slice(0,8000)+标记 逐字节一致（等价测试锚定）
-    const truncated = boundedPrettySerialize(run.state.scriptResult, MAX_RESULT_LENGTH);
-    parts.push("");
-    parts.push("--- Script Result ---");
-    parts.push(truncated);
-  }
-
-  parts.push("");
-  parts.push("--- Agent Trace ---");
-  for (const node of traceNodes) {
-    parts.push(`[${node.stepIndex}] ${node.agent}: ${node.status}`);
-  }
-
-  const content = parts.join("\n");
-
-  // 送达通道保持 "workflow-result"（runtime W18 失效信号 + taiji display 覆写 SSOT
-  // 按该类型识别；迁移不改变消息类型与文案字节，只改变投递可靠性机制）
-  const details: WorkflowNotifyDetails = {
-    runId,
-    name,
-    status: run.state.status,
-    reason: run.state.reason,
-    traceLength: traceNodes.length,
-    notifyId: `${WORKFLOW_DONE_NOTIFY_ID_PREFIX}${runId}`,
-  };
-
-  // GUI 协议：RPC 模式下附加结构化渲染数据
-  if (ctx && isGuiCapable(ctx)) {
-    const reason = run.state.reason;
-    const statusStr = `${run.state.status}${reason ? ` (${reason})` : ""}`;
-    // label 对齐 buildWorkflowGui 的格式：name + slug + runId 前 8 字符（I#3）
-    const slug = run.spec.slug;
-    const label = [name, slug, runId.slice(0, ID_PREVIEW_LENGTH)]
-      .filter(Boolean)
-      .join(" ");
-    details.__gui__ = guiResult(
-      guiComponent("list-tree", {
-        items: [{
-          label,
-          status: mapRunStatus(statusStr),
-          icon: mapRunIcon(statusStr),
-        }],
-      }),
-    );
-  }
-
-  const ledger = getBoundNotifyLedger();
-  if (ledger) {
-    // [u9 账本化] ledger 在 → ①写账（record false = 同幂等键已在账/已销账——内存
-    // 去重窗口挤出或重启恢复后的重复收口，跳过投递）→ ②attemptDeliver（courier
-    // 边沿 + isIdle 二次复查，③销账 ④重放在 ledger 内；送达通道经
-    // deliveryCustomType 保持 "workflow-result"）。
-    // 内存去重标记在写账**成功后**才落下：record 抛（reload 窗口 appendEntry 命中
-    // assertActive 等）时不标记——异常由 finalizeRun 围栏接住（不崩），账面 entry 未写，
-    // 后续重复收口回调（adoption 快照重发等）可重试写账；提前标记会把「窗口内丢失」
-    // 变成永久丢失（去重阻断 + 账本无 entry 不可重放）。stale ctx 防御由装配层
-    // sendDelivery 内置（session-lifecycle.ts bindLedgerHostAndRecover），此处无需
-    // 重复包裹。
-    if (!ledger.record(details.notifyId, content, details, { deliveryCustomType: WORKFLOW_RESULT_CUSTOM_TYPE })) {
-      trackNotifiedRunId(notifiedRunIds, runId);
-      return;
-    }
-    trackNotifiedRunId(notifiedRunIds, runId);
-    ledger.attemptDeliver();
-    return;
-  }
-
-  // 降级：ledger 未装配（旧宿主 / 无账本测试）→ fire-once 直发（at-most-once）。
-  // triggerTurn 单通道（deliverAs 已删——u9 偏差裁决，D7 账本化配套：busy 场景的
-  // 投递时机治理本就由账本路径承担，降级路径不再依赖 pi 内存队列的 steer 形态）；stale ctx 防御
-  // （crash-resilience D1 / ext-guards 审计 §7 blockers#1 收口）：session 替换窗口
-  // 触碰 stale pi 命中 assertActive（PS-30）即无人接 rejection 崩 pi（E1 同机制）。
-  // stale 静默降级（完成通知不投递，用户可从 session 历史 / 工具结果看到 workflow
-  // 结果，判定见 stale-ctx-audit.md §4），非 stale 错误原样上抛（守卫不吞真实 bug）。
-  trackNotifiedRunId(notifiedRunIds, runId);
-  guardStaleCtx(
-    () =>
-      pi.sendMessage(
-        {
-          customType: WORKFLOW_RESULT_CUSTOM_TYPE,
-          content,
-          display: true,
-          details,
-        },
-        { triggerTurn: true },
-      ),
-    {
-      label: "subagent-workflow:notifyDone",
-      onStale: (error) =>
-        logger.warn("workflow completion notice delivery skipped (stale ctx)", {
-          runId,
-          error: toErrorMessage(error),
-        }),
-    },
-  );
-}
-
-/**
- * 把 runId 纳入 notifiedRunIds 去重窗口，超 cap 时删最旧（契约 W3C2）。
- *
- * 职责拆分：**去重判定**留在 notifyDone 的 has 读（本体零改动），
- * 本函数只持**有界化**职责——返回 void，不引入双重去重判定语义。
- *
- * 语义：
- * - 幂等 add：Set.add 对已存在元素不改变其迭代位置（重复 track 同一 id，
- *   其「最旧」地位不变）。
- * - FIFO 有界：Set 迭代序=插入序，超 cap 时删迭代器首元素=最旧。
- *   被挤出窗口的旧 id 再经 notifyDone：内存层放行后由账本 notifyId 幂等兜底
- *   （[u9] record 同键拒绝——生产环境账本已 bind 时不会重发；无账本降级环境
- *   才会重新直发，runId 全局唯一，旧 id 重现概率为零，该边界由 W3TC12 单测
- *   在降级形态下钉死）。
- *
- * 调用点：notifyDone 内部（写账成功/false 后）+ workflow-events onRunDone 回调
- * （notifyDone 之后，幂等二次添加）。notifyDone 抛出（reload 窗口 record 抛等）时
- * 内外都不标记——去重不阻断，重复收口可重试写账（见 notifyDone 账本分支注释）。
- *
- * @param notifiedRunIds 去重 Set（调用方持有，scope 到 factory 实例）
- * @param runId run 标识
- * @param cap 窗口大小（默认 MAX_NOTIFIED_RUN_IDS）
- */
-export function trackNotifiedRunId(
-  notifiedRunIds: Set<string>,
-  runId: string,
-  cap: number = MAX_NOTIFIED_RUN_IDS,
-): void {
-  notifiedRunIds.add(runId);
-  while (notifiedRunIds.size > cap) {
-    const oldest = notifiedRunIds.values().next().value;
-    if (oldest === undefined) break;
-    notifiedRunIds.delete(oldest);
-  }
-}