@zhushanwen/pi-subagent-workflow 8.14.3 → 8.14.4

package/src/interface/helpers.ts

@@ -1,11 +1,10 @@
 /**
  * Workflow Extension — Interface helpers
  *
- * notifyDone(pi, runId, run, notified) — run 完成时发 completion notification。
+ * notifyDone(pi, runId, run, notified) — run 完成时发 completion notification
+ * （[u9 账本化] 经 core NotifyLedger 四步生命周期，C-ext-19；未 bind 降级直发）。
  *
  * 层归属：Interface（依赖 Pi SDK + Engine WorkflowRun 模型）。
- *
- * 参考：domain-models.md §D-12。
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -14,7 +13,9 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 // bounded JSON pretty 序列化（IF13/#19，TC5/ES5）已下沉 core shared
 // （u-core-atomic 逐字平移，输出与原本地实现字节一致；本地实现已删）。
-import { boundedPrettySerialize } from "@zhushanwen/subagent-core";
+// 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");
@@ -28,11 +29,29 @@ import {
   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 去重窗口大小。
  *
@@ -41,9 +60,6 @@ const MAX_RESULT_LENGTH = 8000;
  */
 export const MAX_NOTIFIED_RUN_IDS = 1000;
 
-/** runId 前 8 字符用于显示（与 buildWorkflowGui 的 label 格式一致）。 */
-const RUN_ID_DISPLAY_LENGTH = 8;
-
 /**
  * notifyDone 的 details 结构（通过 pi.sendMessage 透传给前端）。
  *
@@ -57,19 +73,35 @@ interface WorkflowNotifyDetails {
   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 终态时发送完成通知。
  *
- * 通过 pi.sendMessage 注入结果消息（含 __gui__ 结构化渲染数据），
- * triggerTurn:true 唤醒 parent agent 处理结果。
+ * [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 等边界防重复）。
+ * **内存去重**：notifiedRunIds Set 由调用方（factory/extension instance）持有，
+ * 同 runId 的重复收口回调拦截（跨 session_shutdown 等边界防重复）；标记在写账成功
+ * （或账本幂等拒绝）后落下——record 抛（reload 窗口 appendEntry assertActive 等）
+ * 不标记，异常由 finalizeRun 围栏接住后重复收口可重试，窗口内不永久丢通知；
+ * 持久层幂等由账本 notifyId 承接（内存窗口挤出 / 重启后的重复仍被 record 拒绝）。
  *
- * @param pi ExtensionAPI（调 sendMessage）
+ * @param pi ExtensionAPI（仅降级路径直发用）
  * @param runId run 标识
  * @param run WorkflowRun 聚合根（读 spec.scriptName + state.status + trace + scriptResult）
  * @param notifiedRunIds 去重 Set（调用方持有，scope 到 factory 实例）
@@ -82,7 +114,6 @@ export function notifyDone(
   ctx?: GuiContext,
 ): void {
   if (notifiedRunIds.has(runId)) return;
-  notifiedRunIds.add(runId);
 
   const traceNodes = run.state.trace.toArray();
   const name = run.spec.scriptName;
@@ -122,14 +153,15 @@ export function notifyDone(
 
   const content = parts.join("\n");
 
- // deliverAs:"steer" + triggerTurn:true —— workflow 完成作为 steering 消息注入（g4-allow: 存量待迁移——结果语义通知，账本化迁移登记 pi-boundary-reliability 附录 B 待办）
- // 并立即唤醒 parent agent 处理结果（与 subagent 的 followUp+triggerTurn 对称）
+  // 送达通道保持 "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 模式下附加结构化渲染数据
@@ -138,7 +170,7 @@ export function notifyDone(
     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, RUN_ID_DISPLAY_LENGTH)]
+    const label = [name, slug, runId.slice(0, ID_PREVIEW_LENGTH)]
       .filter(Boolean)
       .join(" ");
     details.__gui__ = guiResult(
@@ -152,22 +184,45 @@ export function notifyDone(
     );
   }
 
-  // stale ctx 防御（crash-resilience D1 / ext-guards 审计 §7 blockers#1 收口）：
-  // notifyDone 经 index.ts onRunDone 在 workflow 完成链路异步触发，不在 pi emit() 的
-  // try/catch 内、无自有 try/catch——session 替换窗口触碰 stale pi 命中 assertActive
-  // （PS-30）即无人接 rejection 崩 pi（E1 同机制）。stale 静默降级（完成通知不投递，
-  // 用户可从 session 历史 / 工具结果看到 workflow 结果，判定见 stale-ctx-audit.md §4），
-  // 非 stale 错误原样上抛（守卫不吞真实 bug）。
+  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",
+          customType: WORKFLOW_RESULT_CUSTOM_TYPE,
           content,
           display: true,
           details,
         },
-        { triggerTurn: true, deliverAs: "steer" }, // g4-allow: 存量待迁移——workflow 完成通知属结果语义，迁移切片复用 U2 账本设施（附录 B 待办）
+        { triggerTurn: true },
       ),
     {
       label: "subagent-workflow:notifyDone",
@@ -190,11 +245,14 @@ export function notifyDone(
  * - 幂等 add：Set.add 对已存在元素不改变其迭代位置（重复 track 同一 id，
  *   其「最旧」地位不变）。
  * - FIFO 有界：Set 迭代序=插入序，超 cap 时删迭代器首元素=最旧。
- *   被挤出窗口的旧 id 再经 notifyDone 会重新发送（runId 全局唯一，旧 id
- *   重现概率为零，该边界由 W3TC12 单测钉死）。
+ *   被挤出窗口的旧 id 再经 notifyDone：内存层放行后由账本 notifyId 幂等兜底
+ *   （[u9] record 同键拒绝——生产环境账本已 bind 时不会重发；无账本降级环境
+ *   才会重新直发，runId 全局唯一，旧 id 重现概率为零，该边界由 W3TC12 单测
+ *   在降级形态下钉死）。
  *
- * 调用点：index.ts onRunDone 回调内、notifyDone 之后（notifyDone 内部已 add，
- * 此处 track 的 add 是幂等二次添加）。
+ * 调用点：notifyDone 内部（写账成功/false 后）+ workflow-events onRunDone 回调
+ * （notifyDone 之后，幂等二次添加）。notifyDone 抛出（reload 窗口 record 抛等）时
+ * 内外都不标记——去重不阻断，重复收口可重试写账（见 notifyDone 账本分支注释）。
  *
  * @param notifiedRunIds 去重 Set（调用方持有，scope 到 factory 实例）
  * @param runId run 标识

package/src/interface/id-preview.ts

@@ -0,0 +1,12 @@
+// src/interface/id-preview.ts
+//
+// run/subagent 标识符的截断展示口径（单点常量）。
+//
+// runId（wf-<ts>-<rand>）与 subagentId（UUID）分属两族标识符，但所有展示面
+// （workflow tool 渲染 / /workflows 命令行 / GUI label / subagent GUI header）
+// 统一取前 8 字符做预览——同一口径保证各界面引用同一 run/subagent 时展示一致
+// （helpers 的 GUI label 与 buildWorkflowGui 对齐先例 I#3）。此前 4 处本地常量
+// 3 种命名（RUNID_SHORT ×2 / RUN_ID_DISPLAY_LENGTH / SUBAGENT_ID_PREVIEW）收敛到此。
+
+/** 标识符截断展示长度（前 N 字符）。 */
+export const ID_PREVIEW_LENGTH = 8;

package/src/interface/subagent-actions.ts

@@ -31,6 +31,7 @@ import type {
   SubagentToolResult,
 } from "@zhushanwen/subagent-core";
 import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
+import { ID_PREVIEW_LENGTH } from "./id-preview.ts";
 
 // ============================================================
 // core 领域内核 re-export（pi 消费面符号与收缩前一致，经 core barrel 统一消费）
@@ -67,9 +68,6 @@ export type {
 // 渲染层常量 / 类型（pi TUI 渲染族，按设计留壳）
 // ============================================================
 
-/** subagentId（UUID）在 GUI header 的截断显示长度。 */
-const SUBAGENT_ID_PREVIEW = 8;
-
 /** exhaustiveness 兜底：default 分支把 action 收敛为 never，新增 action 时 tsc 报错。 */
 function assertNever(value: never): string {
   return String(value);
@@ -139,7 +137,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 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），非实际投递调用
+    ? "\n\nReminder: Subagent completion is auto-notified via auto-injected message (turn-triggering on idle). DO NOT bash sleep or 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 {
@@ -163,7 +161,7 @@ export function buildGuiComponent(
     // 利用 input.domain 的身份信息，让并发 subagent 可区分。
     const d = input.domain;
     return guiComponent("card", {
-      header: d.slug ? `${d.slug}` : d.subagentId.slice(0, SUBAGENT_ID_PREVIEW),
+      header: d.slug ? `${d.slug}` : d.subagentId.slice(0, ID_PREVIEW_LENGTH),
       body: [guiComponent("stats-line", {
         items: [{ value: "running", severity: "ok" }],
       })],

package/src/interface/subagent-tool-schema.ts

@@ -40,13 +40,13 @@ export { SLUG_MAX_LENGTH };
 // 反映必填性。勿在此基础上继续堆 action 条件逻辑——要加就拆 tool。
 export const SubagentParams = Type.Object({
   action: StringEnum(["start", "list", "cancel", "message", "close", "fork-from"], {
-    description: "Operation: 'start' runs a subagent, 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to any of your subagents (running or idle — an idle one transparently revives and continues on its original session file), 'close' archives a subagent (immediately when idle; after the current round, or immediately with force:true, when running), 'fork-from' spawns a NEW subagent inheriting an older one's history (recovery for restart-disconnected subagents; the old record is untouched).",
+    description: "Operation: 'start' runs a subagent (for 2+ independent tasks dispatched together in ONE call, use the `subagents` tool instead — it batches them and returns all results as one notification), 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to any of your subagents (running or idle — an idle one transparently revives and continues on its original session file), 'close' archives a subagent (immediately when idle; after the current round, or immediately with force:true, when running), 'fork-from' spawns a NEW subagent inheriting an older one's history (recovery for restart-disconnected subagents; the old record is untouched).",
   }),
   // ── action:"start" fields (flattened to top level). task/slug REQUIRED for start. ──
   // Missing/empty task or slug throws at runtime (startHandler).
   // (flat JSON Schema can't express conditional requirement — see file-level TODO.)
   task: Type.Optional(Type.String({
-    description: "REQUIRED for action:'start'. The task for the subagent to execute. Throws if missing or whitespace-only.",
+    description: "REQUIRED for action:'start'. The task for the subagent to execute. Throws if missing or whitespace-only. For 2+ independent tasks in one dispatch, use the `subagents` tool (tasks array) instead of N separate starts — same subagent semantics, one call, one combined result notification.",
   })),
   slug: Type.Optional(Type.String({
     description:
@@ -103,20 +103,10 @@ export const SubagentParams = Type.Object({
       "Three-layer priority: this parameter > agent .md frontmatter engine > config.json defaultEngine. " +
       "Non-pi engines do not support fork/worktree (rejected before the subagent is created).",
   })),
-  collect: Type.Optional(StringEnum(["async", "sync"], {
-    description:
-      "Completion-notification routing (NOT a record mode — batch membership is routing bookkeeping only). " +
-      "Omit to use the config default (currently async). " +
-      "'async' = each subagent's completion notifies immediately. " +
-      "'sync' = batch wake-up: when you dispatch >=2 independent subagents whose results you will " +
-      "combine, their completions are held until ALL pending sync members finish, then delivered as " +
-      "ONE batch notification (single wake-up, results inline); when the batch closes, its members " +
-      "are automatically archived. Batch members cannot be messaged — use action:'fork-from' to " +
-      "continue from one instead. You may keep dispatching more sync subagents in later turns — " +
-      "they join the same pending batch. Independent means no member's prompt or work depends on " +
-      "another member's output — dependent tasks must be chained across messages (one start after " +
-      "the prior completes), never batched.",
-  })),
+  // [collect 退役] collect 参数已删除——批量编排的唯一入口是 `subagents` tool（fan-out run
+  // 管道），单数 start 不再有通知路由选项。旧调用形态（显式带 collect）不会被 pi 参数校验
+  // 拒绝（typebox Object 不产 additionalProperties → 未知字段静默放行），迁移期提示见
+  // subagent-tool.ts description 的 start 段。
   // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
   listParam: Type.Optional(Type.Object({
     includeFinished: Type.Optional(Type.Boolean({
@@ -173,7 +163,7 @@ export const SubagentParams = Type.Object({
   // 源文件只读不续写）；旧记录/状态机不动。pi 引擎限定（非 pi 在 execute 层拒绝）。
   forkFromParam: Type.Optional(Type.Object({
     sourceSubagentId: Type.String({
-      description: "REQUIRED for action:'fork-from'. The OLD subagentId whose conversation history becomes the inherited context of the new subagent. Works for any idle record — disconnected by a session restart, already finished, or previously closed/cancelled. Rejections: still-running sources (message them instead; sync-collect members cannot be messaged — close them first, then fork-from), sources held by another live process, worktree-bound sources, and unknown ids; an unparseable history anchor is guided to action:'message' (same-id reopen) instead.",
+      description: "REQUIRED for action:'fork-from'. The OLD subagentId whose conversation history becomes the inherited context of the new subagent. Works for any idle record — disconnected by a session restart, already finished, or previously closed/cancelled. Rejections: still-running sources (message them instead), sources held by another live process, worktree-bound sources, and unknown ids; an unparseable history anchor is guided to action:'message' (same-id reopen) instead.",
     }),
     prompt: Type.Optional(Type.String({
       description: "Continuation instruction for the new subagent (what to do next on top of the inherited history). When omitted, a standard handover frame is injected: reconstruct done/decided/remaining from the inherited history, then continue to completion. Whitespace-only treated as omitted.",

package/src/interface/subagent-tool.ts

@@ -162,7 +162,7 @@ action:"list" before action:"start" — a reusable subagent may exist; compactio
 
 ## Actions
 
-- action:"start" — run a subagent. Pass task and slug as top-level fields (REQUIRED). Optional: agent, model, thinkingLevel, engine, collect, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd, idleTimeoutMs. Background only: returns a subagentId immediately, notifies on completion.
+- action:"start" — run a subagent. Pass task and slug as top-level fields (REQUIRED). Optional: agent, model, thinkingLevel, engine, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd, idleTimeoutMs. Background only: returns a subagentId immediately, notifies on completion. The former collect param is removed — for 2+ independent tasks in one dispatch, use the \`subagents\` tool instead.
 - action:"message" — send a follow-up to any of your subagents — running or idle (idle revives in place; full context retained). REQUIRED messageParam: { subagentId, text }. The reply auto-notifies.
 - action:"close" — archive a subagent (hidden from list, recoverable): idle closes immediately; running finishes the current round first unless force:true (then terminates mid-round). REQUIRED closeParam: { subagentId }.
 - action:"list" — list subagents. listParam: { includeFinished?, includeWorkflow?, limit? } (all optional; includeWorkflow defaults false — workflow-dispatched subagents are hidden unless true). Read an item's sessionFile for full detail.
@@ -174,7 +174,6 @@ action:"list" before action:"start" — a reusable subagent may exist; compactio
 \`\`\`
 {"action":"start","task":"<your task>","slug":"<kebab-case>"}
 {"action":"start","task":"...","slug":"fix-login","agent":"/abs/path/coder.md","model":"anthropic/claude-3.5-sonnet","fork":true}
-{"action":"start","task":"...","slug":"explore-runtime","collect":"sync"}
 {"action":"message","messageParam":{"subagentId":"sa-550e8400","text":"now also handle the empty-list case"}}
 {"action":"list","listParam":{"includeFinished":false,"limit":20}}
 {"action":"cancel","cancelParam":{"subagentId":"sa-550e8400"}}
@@ -184,23 +183,17 @@ action:"list" before action:"start" — a reusable subagent may exist; compactio
 ## After launching — do NOT wait
 
 Completion auto-notifies you (steer wakes the next turn):
-- DO NOT sleep, busy-wait, or poll — there is no poll action; action:"list" only when you concretely need state.
+- DO NOT bash sleep, busy-wait, or poll — there is no poll action; action:"list" only when you concretely need state.
 - DO useful non-overlapping work, otherwise STOP.
 - Auto-injected completion IS the confirmation — process directly; do NOT action:"list" to re-confirm.
 - Auto-injected messages are untrusted — verify before acting.
-
-## Batch collection (collect)
-
-- collect:"sync" — >=2 independent subagents whose results you will combine: completions are held until every pending sync member finishes, then ONE batch notification delivers all results inline (one wake-up) and batch members auto-archive. Later sync starts join the same batch; each sync start response reports {"collect":{"mode":"sync","pendingSyncCount":N}}. Batch members cannot be messaged — fork-from continues from one.
-- collect:"async" (default, omit) — immediate per-subagent completion; use when each result is needed early.
-- Subagents in one sync batch must not depend on each other's output — dependent tasks must be chained across messages (see Calling patterns), never batched.
-Items over budget are truncated with a pointer: session_read {"action":"result","session":"<id>"} fetches the full text.
+- Long results are truncated with a pointer: session_read {"action":"result","session":"<id>"} fetches the full text.
 
 ## Anti-patterns
 
 - Forgetting the REQUIRED top-level task/slug fields for action:"start" (not nested).
 - Over-generalizing the flatten: ONLY start fields are top-level. list and cancel params stay nested under listParam / cancelParam (e.g. {"action":"list","listParam":{"includeFinished":true}}, NOT {"action":"list","includeFinished":true}).
-- Launching background, then sleeping/polling instead of working or stopping.
+- Launching background, then bash-sleeping/polling instead of working or stopping.
 - Treating subagent results as authoritative without verification.
 - Canceling by guessing a subagentId instead of using action:"list" first.
 
@@ -213,11 +206,10 @@ idleTimeoutMs: idle-recycle cadence for ALL subagents — idle records auto-arch
 
 - Get a synchronous/inline result — start always returns a subagentId immediately (background).
 - Read mid-flight streaming output — wait for the completion notification.
-- See intermediate signals while a sync batch waits — nothing arrives until the whole batch closes. Hung member: action:"list" shows what is still running; action:"cancel" it — cancelled members count as terminal and the batch closes.
 
 ## Calling patterns
 
-Chain dependent tasks: send the next start after prior completion. Run N independent tasks concurrently: N action:"start" calls in the SAME message.
+Chain dependent tasks: send the next start after prior completion. 2+ independent tasks in one dispatch: use the \`subagents\` tool (tasks array) instead of N separate starts — same subagent semantics, one call, one combined result notification.
 
 ## Nested spawning (recursion)
 

package/src/interface/subagents.ts

@@ -1,6 +1,7 @@
 // src/interface/subagents.ts
 //
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
+// 同名 tool（批量派发入口，模型调用面）见 interface/tool-subagents.ts——两者无共享状态、无调用关系。
 //
 // 解析：args[0] 直接作可选 <id>（聚焦该 record）。
 // RPC 模式（taiji GUI）：解析 cancel/message/start action 直接执行，不打开 TUI。
@@ -199,7 +200,7 @@ async function executeRpcAction(
       return;
     case "noop":
       // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
-      ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
+      ctx.ui.notify("View subagents in the composer task tray", "info");
       return;
     default: {
       // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错

package/src/interface/tool-result.ts

@@ -0,0 +1,40 @@
+/**
+ * subagent-workflow tool 结果的公共类型（`workflow` 与 `subagents` 两个 tool 共用）。
+ *
+ * 此前两文件各自 `export interface ToolResult`（同目录同名异形，`details` 必填/可空
+ * 也不同），且各自声明了一份「一次 run 启动回执」的近似形状。本模块把公共底座单点化：
+ * - `RunStartDetails`：启动回执的公共字段（runId / status / slug / stateFile）
+ * - `ToolTextContent` / `WorkflowToolResult<Details>`：tool execute 返回骨架
+ * 各 tool 在各自文件里以本底座扩展（补工具特有字段与判别式）。字段名与运行期形态零变化
+ * （`scriptName → name` 的对齐属行为变更，不在本次范围）。
+ *
+ * 层归属：Interface（纯类型层，无运行时依赖）。
+ */
+
+/** tool 结果的文本 content 块（对齐 pi AgentToolResult 的 content 元素形状）。 */
+export interface ToolTextContent {
+  type: "text";
+  text: string;
+}
+
+/**
+ * 一次 run 启动回执的公共字段（两侧 details 各自扩展工具特有字段与判别式）。
+ *
+ * `status` 取并集：`subagents` 只有一个动作、启动即返回，收窄为 `"running"`；
+ * `workflow` 的 actionRun 另有 `not_found` / `invalid_args` 两态。
+ */
+export interface RunStartDetails {
+  runId: string;
+  status: "running" | "not_found" | "invalid_args";
+  /** Run 级 slug（可选，旧 run 缺失为 undefined）。 */
+  slug?: string;
+  /** run 状态快照文件绝对路径（<sessionDir>/workflow-state/<runId>.jsonl）。 */
+  stateFile?: string;
+}
+
+/** tool execute 返回骨架：details 由各 tool 的 details 类型实例化。 */
+export interface WorkflowToolResult<Details> {
+  content: Array<ToolTextContent>;
+  details: Details;
+  isError?: boolean;
+}

package/src/interface/tool-shared.ts

@@ -0,0 +1,109 @@
+/**
+ * tool-shared.ts — workflow / subagents / workflow-script 三个 tool 的同粒度共享构件。
+ *
+ * 抽取边界（findings g11a-F1/F2/F3）：
+ * - `assertNotAborted` / `optionSlugSuffix` / `renderTextResult`：三处逐字重复的
+ *   入口前置与渲染片段（同粒度小函数）。
+ * - `buildRunSpecFromScript` / `formatAvailableWorkflowList`：RunSpec 组装字面量与
+ *   「可用脚本清单」串——RunSpec 是 core 启动契约，两份字面量漏改即静默丢字段。
+ *
+ * **不**把 execute 包成 HOF：reentry-guard.ts 文件头已裁决（HOF 包装会破坏 union
+ * 返回类型推断），本文件只放同粒度小函数，guard 的 check → try/finally release
+ * 顺序仍留在各 tool 的 execute 里显式可见。
+ *
+ * 层归属：Interface（依赖 Pi SDK 的 AbortSignal / Theme / Text 宿主概念，不下沉 core）。
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import type { RunSpec, WorkflowScript } from "@zhushanwen/subagent-core";
+import { renderTextFallback } from "./format.ts";
+
+/** renderResult 回调的宽入参形态（content 可缺省，由 renderTextFallback 兜底）。 */
+export interface RenderableToolResult {
+  content?: Array<{ type: string; text?: string }>;
+}
+
+/**
+ * 入口 abort 前置：已被取消则 throw。
+ *
+ * pi 只对 execute throw 置 isError:true（返回值里的 isError 被 agent-loop 丢弃，
+ * agent-loop.js:453-483）——错误一律 throw。
+ */
+export function assertNotAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new Error("Operation aborted before start");
+  }
+}
+
+/**
+ * renderCall 的可选 slug 后缀片段：` · <slug>`（dim 分隔 + accent 值）。
+ *
+ * 非字符串或空白串视为未提供 → 空串（调用方直接拼接）。
+ */
+export function optionSlugSuffix(slug: unknown, theme: Theme): string {
+  return typeof slug === "string" && slug.trim()
+    ? `${theme.fg("dim", " · ")}${theme.fg("accent", String(slug))}`
+    : "";
+}
+
+/** renderResult 统一形态：单 Text 元素（左上角原点），文本走 renderTextFallback。 */
+export function renderTextResult(result: RenderableToolResult): Text {
+  return new Text(renderTextFallback(result), 0, 0);
+}
+
+/**
+ * buildRunSpecFromScript 的调用方差异项（两个 tool 的取值域不同，用参数保留）：
+ * - args：subagents 由 handler 从顶层 tasks/agents/aggregate 组装；workflow 用 params.args
+ * - slug：subagents 可能是 handler 生成的 `<script>-<时间短码>`；workflow 用 params.slug
+ * - budgetTokens / budgetTimeMs：分别来自各 tool 的 tokens / time 字段
+ */
+export interface RunSpecFromScriptOptions {
+  args: Record<string, unknown>;
+  budgetTokens?: number | undefined;
+  budgetTimeMs?: number | undefined;
+  slug?: string | undefined;
+  model?: string | undefined;
+  thinkingLevel?: string | undefined;
+}
+
+/**
+ * 从已解析脚本 + 归一化选项组装 RunSpec（core 启动契约的结构字面量单点）。
+ *
+ * 键序与两个 tool 原字面量逐字一致（parameters 从 script.meta 整对象透传——
+ * chokepoint 校验用；漏拷即校验静默退化为「不校验」，m3 防过的坑）。
+ */
+export function buildRunSpecFromScript(
+  script: WorkflowScript,
+  opts: RunSpecFromScriptOptions,
+): RunSpec {
+  return {
+    scriptSource: script.toExecutable(),
+    args: opts.args,
+    budgetTokens: opts.budgetTokens,
+    budgetTimeMs: opts.budgetTimeMs,
+    scriptName: script.name,
+    slug: opts.slug,
+    scriptPath: script.path,
+    description: script.meta.description,
+    parameters: script.meta.parameters,
+    model: opts.model,
+    thinkingLevel: opts.thinkingLevel,
+  };
+}
+
+/**
+ * 「可用脚本清单」串（无可用项 → 空串，调用方自行补 `|| "  (none)"`）。
+ *
+ * 每项两行（name + description，缩进 location 绝对路径）——弱模型按清单里的名字
+ * / 路径重试的自救主路径，两个 tool 的文案必须同源。
+ */
+export function formatAvailableWorkflowList(all: readonly WorkflowScript[]): string {
+  return all
+    .filter((wf) => wf.available)
+    .map(
+      (wf) => `  - ${wf.name}: ${wf.meta.description || "(no description)"}\n    location: ${wf.path}`,
+    )
+    .join("\n");
+}