@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.1

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

@@ -0,0 +1,168 @@
+// src/execution/ui-request-queue.ts
+//
+// W3/W2: 子进程 extension_ui_request 的 FIFO 串行队列 + 转发处理。
+//
+// 从 session-runner.ts 提取（保持文件 < 1000 行）。职责单一：
+//   - createUiRequestQueue：每个子进程一个队列，保证多个 UI 请求（ask_user 等）
+//     FIFO 串行处理，防止并发询问用户导致交错。
+//   - handleUiRequest：从 ExtensionUiRequest 构造 UiRequest → 调主 agent uiRequestHandler
+//     → 按 UiResponse 形状回写 stdin。
+//   - extractMethodFields：method-specific 字段类型安全复制。
+//
+// session-runner.runSpawn 在 stdout pump 中拿到 extension_ui_request 后调 enqueue 入队。
+
+import type { ChildProcess } from "node:child_process";
+
+import type { UiRequest } from "./dialog-queue.ts";
+// 类型再导出：dialog-queue.ts 是 UiRequest/UiResponse/UiRequestHandler 的规范来源，
+// 本模块再导出供测试 import（避免测试直接依赖 dialog-queue 内部实现）。
+export type { UiRequest, UiRequestHandler, UiResponse } from "./dialog-queue.ts";
+import type { SessionRunnerContext } from "./session-runner.ts";
+import type { ExtensionUiRequest } from "./spawn-event-adapter.ts";
+import { respond } from "./stdin-writer.ts";
+import { parseChannel } from "./ui-channels.ts";
+import { notifyMissingHandlerGlobal } from "./ui-request-observability.ts";
+
+/**
+ * 创建 UI 请求队列。返回 enqueue 函数，调用方将 extension_ui_request 入队。
+ *
+ * 多个 extension_ui_request 并发到达时，队列保证 FIFO 串行处理：
+ * 前一个请求的 uiRequestHandler resolve 后，才将下一个请求发给主 agent UI。
+ * 防止并发询问用户导致交错（用户同时看到多个问题）。
+ *
+ * 设计：队列是 runSpawn 生命周期内的闭包状态（非模块级），
+ * 每个子进程实例独立队列，无跨 session 泄漏。
+ *
+ * @param child 子进程（stdin 写入 extension_ui_response）
+ * @param ctx SessionRunnerContext（含 uiRequestHandler 回调）
+ * @returns enqueue 函数：(id, request) => void，将请求入队并触发顺序处理
+ */
+export function createUiRequestQueue(
+  child: ChildProcess,
+  ctx: SessionRunnerContext,
+): (id: string, request: ExtensionUiRequest) => void {
+  // [R3] AbortController 取消 pending handler——子进程退出时队列不再阻塞
+  const abortController = new AbortController();
+  const queue: Array<{ id: string; request: ExtensionUiRequest; signal: AbortSignal }> = [];
+  let processing = false;
+  let closed = false;
+
+  function processNext(): void {
+    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();
+    });
+  }
+
+  // [R3] 子进程退出时 abort 所有 pending handler，队列不再阻塞
+  // [SR-4] 同步清理 L2 队列中该 child 的 pending dialog——child 在 dialog 等 L2 时退出，
+  //   L2 里该项永不 settle → processing 永远 true → 所有其他子进程 dialog 永久阻塞（全局死锁）。
+  //   pid 缺省（spawn 后极短窗口 child.pid 可能为 undefined）时跳过——此时该 child 还未在 L2
+  //   注册过任何 dialog（handleUiRequest 构造 UiRequest 时用同样的 child.pid，pid undefined 时
+  //   不填 _childPid，rejectChildDialogs 也匹配不到），无清理必要。
+  const onClose = (): void => {
+    // #19/#17 幂等守卫：close + error 可能都触发，二次调用会重复 rejectChildDialogs（虽依赖 L2 的 settled 幂等，
+    // 但 close 状态本身需守卫——避免 closed=true 后 queue.length=0 + abort 重复执行，以及重复 reject 导致语义噪声）。
+    if (closed) return;
+    closed = true;
+    abortController.abort();
+    queue.length = 0;
+    if (child.pid !== undefined) {
+      ctx.dialogQueue?.rejectChildDialogs({ pid: child.pid });
+    }
+  };
+  child.on("close", onClose);
+  child.on("error", onClose);
+
+  return function enqueue(id: string, request: ExtensionUiRequest): void {
+    if (closed) return;
+    queue.push({ id, request, signal: abortController.signal });
+    processNext();
+  };
+}
+
+/**
+ * 处理子进程发来的 extension_ui_request（ask_user 及其他 Pi UI method）。
+ *
+ * 流程：从 ExtensionUiRequest 构造 UiRequest（含 channel/channelPayload）
+ *  → 调用主 agent uiRequestHandler → 按 UiResponse 形状回写 stdin。
+ *
+ * handler 未设置时不再静默忽略——console.warn 兜底（FR-9 可观测性），
+ * W3 接入 SubagentService.notifyMissingHandler 的 appendEntry。
+ *
+ * @param child 子进程（stdin 写入响应）
+ * @param id 请求 id（子进程用它关联 response）
+ * @param request ExtensionUiRequest（method 平铺，从 enqueueUiRequest 传入）
+ * @param ctx SessionRunnerContext（含 uiRequestHandler 回调）
+ * @param signal abort signal（子进程退出时触发，取消正在等待的 handler）
+ * @returns Promise（队列等待用：resolve 表示响应已写入 stdin 或已放弃）
+ */
+async function handleUiRequest(
+  child: ChildProcess,
+  id: string,
+  request: ExtensionUiRequest,
+  ctx: SessionRunnerContext,
+  signal?: AbortSignal,
+): Promise<void> {
+  const handler = ctx.uiRequestHandler;
+  if (!handler) {
+    // #9 + #11：handler 缺失时不再静默 return（会让子进程永久挂起等 response）。
+    //   - notifyMissingHandlerGlobal：经 globalThis 桥接到 observability 单例做 per-session 去重告警
+    //     （FR-9 可观测性；未注册时走 fallback warn 不丢日志）
+    //   - respond(cancelled)：让子进程收到明确取消，不再永久挂起。等价于用户主动取消的语义。
+    // 去重 key 用 child.pid（队列内拿不到真实 sessionId；pid 是子进程会话的稳定标识，
+    // 去重粒度正确——同一子进程多次 handler 缺失只告警一次）。
+    notifyMissingHandlerGlobal(child.pid?.toString() ?? id);
+    respond(child, id, { cancelled: true }, signal);
+    return;
+  }
+
+  // 从 ExtensionUiRequest 构造 UiRequest（含 channel/channelPayload）
+  const { channel, channelPayload } = parseChannel(request);
+  // [SR-4] 填入 child.pid 作为内部元数据：L2 队列的 rejectChildDialogs 据此关联 child close
+  //   清理。factory 层 enqueue 时读 req._childPid 传给 opts.child。pid undefined（spawn 后极短
+  //   窗口）时不填——rejectChildDialogs 也匹配不到（onClose 同样用 child.pid 守卫），无副作用。
+  const uiReq: UiRequest = {
+    id,
+    method: request.method,
+    ...(child.pid !== undefined ? { _childPid: child.pid } : {}),
+    ...(channel !== undefined ? { channel } : {}),
+    ...(channelPayload !== undefined ? { channelPayload } : {}),
+    ...extractMethodFields(request),
+  };
+
+  try {
+    const result = await handler(uiReq);
+    // [R3] 子进程已退出，跳过写入
+    if (signal?.aborted) return;
+    respond(child, id, result, signal);
+  } catch (err) {
+    // [R3] 子进程已退出，跳过写入
+    if (signal?.aborted) return;
+    console.error("[subagents] uiRequestHandler threw:", err);
+    respond(child, id, { cancelled: true }, signal);
+  }
+}
+
+/** 从 ExtensionUiRequest 提取 method-specific 字段到 UiRequest（与 Pi rpc-types.ts 1:1）。
+ *  按 method 变体类型安全地复制对应字段；缺失字段不复制（保持 UiRequest 可选）。 */
+function extractMethodFields(req: ExtensionUiRequest): Partial<UiRequest> {
+  const out: Partial<UiRequest> = {};
+  if ("title" in req && typeof req.title === "string") out.title = req.title;
+  if ("options" in req && Array.isArray(req.options)) out.options = req.options;
+  if ("message" in req && typeof req.message === "string") out.message = req.message;
+  if ("placeholder" in req && typeof req.placeholder === "string") out.placeholder = req.placeholder;
+  if ("prefill" in req && typeof req.prefill === "string") out.prefill = req.prefill;
+  if ("notifyType" in req && typeof req.notifyType === "string") out.notifyType = req.notifyType;
+  if ("statusKey" in req && typeof req.statusKey === "string") out.statusKey = req.statusKey;
+  if ("statusText" in req) out.statusText = req.statusText;
+  if ("widgetKey" in req && typeof req.widgetKey === "string") out.widgetKey = req.widgetKey;
+  if ("widgetLines" in req) out.widgetLines = req.widgetLines;
+  if ("widgetPlacement" in req) out.widgetPlacement = req.widgetPlacement;
+  if ("text" in req && typeof req.text === "string") out.text = req.text;
+  if ("timeout" in req && typeof req.timeout === "number") out.timeout = req.timeout;
+  return out;
+}

package/src/index.ts

@@ -17,12 +17,15 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import type { ExtensionAPI, ExtensionContext, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionShutdownEvent, SessionStartEvent } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ModelSelectEvent, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@mariozechner/pi-coding-agent";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 import type { AgentRegistry } from "./execution/agent-registry.ts";
 import { bestEffort } from "./execution/best-effort.ts";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
+import { getOrCreateChannelRegistry } from "./execution/channel-registry-access.ts";
+import { DialogGlobalQueue } from "./execution/dialog-queue.ts";
+import { createUiRequestHandlerForMode } from "./execution/ui-request-handler-factory.ts";
 import {
   getModelConfigService,
   ModelConfigService,
@@ -213,14 +216,35 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       sessionId: ctx.sessionManager.getSessionId(),
       ctxModel: ctx.model ?? undefined,
     });
+
+    // ── W3: handler 注入链路接通 ──
+    // 进程级单例：channel registry + dialog queue 跨 session 复用
+    //（与 SubagentService 单例模式一致，globalThis Symbol 持有避免 jiti 多实例分裂）。
+    const channelRegistry = getOrCreateChannelRegistry();
+    const dialogQueue = getOrCreateDialogQueue();
+    const uiRequestHandler = createUiRequestHandlerForMode(ctx, channelRegistry, dialogQueue);
+    // SR-3: 无论 new 还是 existing（/resume /fork 复用），session_start 都必须注入 handler
+    service.setUiRequestHandler(uiRequestHandler);
+
     service.initSession({
       pi,
       sessionId: ctx.sessionManager.getSessionId(),
       // 注入 ctx.ui.setWidget 作为 streaming sink（只绑方法，不持有整个 ctx）。
       // background subagent 执行期间，text_delta 经 SubagentStream 合并后由此通道转发。
-      streamSink: {
-        setWidget: (key, lines) => ctx.ui.setWidget(key, lines),
-      },
+      // [W1 修复] ctx.mode === 'rpc' 守卫：TUI/json/print 下 streamSink = undefined（无 widget 噪音），
+      // rpc mode（GUI/xyz-agent）下保持原行为（ctx.ui.setWidget → sidecar → chatStore）。
+      // streamSink API 不变（SubagentStream.onDelta 仍可调，只是 TUI 下 stream 不会被创建）。
+      streamSink: ctx.mode === "rpc"
+        ? { setWidget: (key, lines) => ctx.ui.setWidget(key, lines) }
+        : undefined,
+      // [#24] uiRequestHandler 单一注入入口：上方 setUiRequestHandler 已注入（SR-3 语义，
+      // new/existing service 均覆盖）。此处不再重复传 initSession.uiRequestHandler，避免
+      // 同一 handler 双路径注入造成的语义混淆与“哪一个是 source of truth”歧义。
+      // mode 仍需 session 级注入（uiObservability.setMode 依赖它，与 handler 无关）。
+      mode: ctx.mode,
+      // SR-4：注入 L2 dialog 队列——session-runner child close 时调 rejectChildDialogs
+      // 清理该 child 在 L2 的 pending dialog，防全局死锁（C1 修复：清理路径接通）。
+      dialogQueue,
     });
 
     if (!existingService) {
@@ -237,6 +261,18 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       console.warn("[subagents] expired session file cleanup failed:", err);
     }
 
+    // ADR-035 启动恢复：扫描 manifest tmp 残留（崩溃打断的 writeManifest 留下），
+    // 每次 session_start 都调（与上方 maybeCleanupExpiredSessionFiles 一致）。
+    try {
+      const recovered = await service.recoverManifestTmpFiles();
+      if (recovered.recovered > 0 || recovered.deleted > 0) {
+        console.warn(`[subagents] manifest tmp recovery: ${recovered.recovered} promoted, ${recovered.deleted} deleted`);
+      }
+    } catch (err) {
+      void err;
+      console.warn("[subagents] manifest tmp recovery failed:", err);
+    }
+
     try {
       const wtm = new WorktreeManager(agentDir);
       wtm.scan();
@@ -303,7 +339,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   //  model_select：用户切换 model 时刷新缓存
   // ════════════════════════════════════════════════════════════
-  pi.on("model_select", (event: { model: NonNullable<ExtensionContext["model"]> }, ctx: ExtensionContext) => {
+  pi.on("model_select", (event: ModelSelectEvent, ctx: ExtensionContext) => {
     const service = getModelConfigService();
     if (service && typeof service.setCtxModel === "function") {
       service.setCtxModel(event.model);
@@ -319,7 +355,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   //  session_tree：切分支前 pause 所有 running run
   // ════════════════════════════════════════════════════════════
-  pi.on("session_tree", async (_event: Record<string, unknown>, ctx: ExtensionContext) => {
+  pi.on("session_tree", async (_event: SessionTreeEvent, ctx: ExtensionContext) => {
     const sessionId = ctx.sessionManager.getSessionId();
     lsRef.lastSessionId = sessionId;
 
@@ -355,6 +391,20 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       cleanupAllFiles(state.activeTempFiles);
       sessionState.delete(sessionId);
     }
+
+    // M2: 清理 dialog queue 运行时状态（queue/current/processing）。
+    // [#10] 先 rejectAll() settle 所有 pending dialog Promise（防闭包泄漏：未 settle 的
+    // Promise 持有 resolve/reject 闭包及 handler 上下文，session 退出后仍挂在全球队列上），
+    // 再 clear() 重置 queue/current/processing（防异常退出后 processing=true 卡死下次 session）。
+    // rejectAll() 由 dialog-queue.ts 提供（Group B 新增）；若其内部已 reset 状态，此处 clear() 为幂等兜底。
+    // 单 session 假设（M-2，同 lastSessionId）：rejectAll() 清空进程级单例的所有 pending，
+    // 依赖 Pi 单进程单 session 串行保证——不会误清其他 session。多 session 并发的迁移策略
+    // 见 DialogGlobalQueue 类注释（rejectAllForSession）。
+    // channel registry 不清：跨 session 持久是有意设计（ask-user 扩展注册的 channel handler
+    // 在 /new /resume /fork 时不丢失注册）。
+    const dialogQueue = getOrCreateDialogQueue();
+    dialogQueue.rejectAll();
+    dialogQueue.clear();
   });
 
   // ════════════════════════════════════════════════════════════
@@ -465,3 +515,37 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     lazyDeps,
   );
 }
+
+// ============================================================
+// 进程级单例（channel registry + dialog queue）
+// ============================================================
+
+// channel registry 经 channel-registry-access.ts 公开访问（跨扩展 API）。
+// dialog queue 仍为本模块私有——无外部消费者。
+const DIALOG_QUEUE_KEY = Symbol.for("@zhushanwen/pi-subagents.dialogQueue");
+
+/** 获取或创建进程级 dialog queue 单例。
+ *  L2 跨子进程串行队列——所有子进程的 dialog 类请求共享同一队列实例。 */
+function getOrCreateDialogQueue(): DialogGlobalQueue {
+  let queue = Reflect.get(globalThis, DIALOG_QUEUE_KEY) as DialogGlobalQueue | undefined;
+  if (!queue) {
+    queue = new DialogGlobalQueue();
+    Reflect.set(globalThis, DIALOG_QUEUE_KEY, queue);
+  }
+  return queue;
+}
+
+// ============================================================
+// Public cross-extension API（channel handler 注册入口）
+// ============================================================
+//
+// 跨扩展消费者（ask-user 等）通过包根 import 注册 channel handler，
+// 让 subagent 子进程的 UI 请求（ask_user 等）透传到主进程渲染。
+// 重新导出 channel-registry-access 的公开 API——稳定 surface，
+// 内部存储实现演进不影响消费者。
+
+export {
+  getOrCreateChannelRegistry,
+  type UiChannelRegistry,
+  type ChannelHandler,
+} from "./execution/channel-registry-access.ts";

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

@@ -0,0 +1,76 @@
+// Behavioral tests for weak-model parameter-misuse detectors.
+//
+// Complements the source-text prompt-quality tests (subagent-tool-prompt.test.ts /
+// workflow-tool-prompt.test.ts): those lock that the Correct examples / anti-pattern
+// STRINGS exist in source; these lock the actual trigger/no-trigger LOGIC, so a
+// refactor that inverts a condition or swaps keys cannot pass just by keeping the
+// literal string alive.
+//
+// Covers the detectors added in the weak-model-robustness PR:
+//   - subagent hasFlattenedStartFields (startParam envelope missing)
+//   - workflow findFlattenedArgKeys (args sub-fields flattened to top level — P0)
+
+import { describe, expect, it } from "vitest";
+
+import { hasFlattenedStartFields } from "../subagent-tool";
+import { findFlattenedArgKeys } from "../tool-workflow";
+
+describe("hasFlattenedStartFields (subagent startParam flatten detector)", () => {
+  it("triggers when task/slug flattened to top level (the original failure mode)", () => {
+    expect(hasFlattenedStartFields({ action: "start", task: "x", slug: "s" })).toBe(true);
+    expect(hasFlattenedStartFields({ action: "start", task: "x" })).toBe(true);
+    expect(hasFlattenedStartFields({ action: "start", slug: "s" })).toBe(true);
+  });
+
+  it("does NOT trigger when startParam envelope is present (correct nesting)", () => {
+    expect(
+      hasFlattenedStartFields({ action: "start", startParam: { task: "x", slug: "s" } }),
+    ).toBe(false);
+  });
+
+  it("does NOT trigger when neither task nor slug is present", () => {
+    expect(hasFlattenedStartFields({ action: "start" })).toBe(false);
+    expect(hasFlattenedStartFields({ action: "list" })).toBe(false);
+  });
+
+  it("returns false for non-object input", () => {
+    expect(hasFlattenedStartFields(null)).toBe(false);
+    expect(hasFlattenedStartFields(undefined)).toBe(false);
+    expect(hasFlattenedStartFields("start")).toBe(false);
+    expect(hasFlattenedStartFields(42)).toBe(false);
+  });
+});
+
+describe("findFlattenedArgKeys (workflow args flatten detector — P0)", () => {
+  it("triggers when args sub-fields flattened to top level", () => {
+    expect(findFlattenedArgKeys({ action: "run", name: "chain", task: "x" })).toEqual(["task"]);
+    expect(findFlattenedArgKeys({ action: "run", name: "x", items: ["a"] })).toEqual(["items"]);
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "x", task: "t", perspectives: ["p"] }),
+    ).toEqual(["task", "perspectives"]);
+  });
+
+  it("does NOT trigger when fields correctly nested in args", () => {
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "x", args: { task: "x", items: ["a"] } }),
+    ).toEqual([]);
+  });
+
+  it("edge: key present at BOTH top-level and inside args is NOT flagged", () => {
+    // 同时传 args.task 和顶层 task：args 已提供，顶层冗余被忽略，不算平铺。
+    // 这是 reviewer 点名的 untested edge。
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "x", args: { task: "x" }, task: "y" }),
+    ).toEqual([]);
+  });
+
+  it("does NOT trigger when no known arg keys present", () => {
+    expect(findFlattenedArgKeys({ action: "run", name: "x", args: {} })).toEqual([]);
+    expect(findFlattenedArgKeys({ action: "status" })).toEqual([]);
+  });
+
+  it("returns [] for non-object input", () => {
+    expect(findFlattenedArgKeys(null)).toEqual([]);
+    expect(findFlattenedArgKeys(undefined)).toEqual([]);
+  });
+});

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

@@ -9,11 +9,12 @@
 // 删掉或弱化。读源码而非 import，避免 mock 链（subagent-tool.ts 依赖 pi-ai/
 // typebox/pi-tui/ExtensionAPI 等值导入）。
 
-import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+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 SUBAGENT_TOOL_SRC = readFileSync(
   join(__dirname, "../subagent-tool.ts"),
@@ -30,10 +31,12 @@ function extractDescription(src: string): string {
 const DESCRIPTION = extractDescription(SUBAGENT_TOOL_SRC);
 
 describe("subagent tool description — 行为约束器（非功能说明书）", () => {
-  it("词数 ≤ 400（高风险 description 密度上限）", () => {
+  it("词数 ≤ 550（高风险 description 密度上限）", () => {
     // 高风险 tool 的 description 应聚焦约束而非功能铺陈；过长会稀释信号。
+    // 上限从 400 放宽到 550：补了 JSON 调用正例段（start/list/cancel 三 action 完整 JSON），
+    // 正例对弱模型首次调用用对参数的价值 > 节省这点 description 预算。
     const words = DESCRIPTION.trim().split(/\s+/).filter(Boolean).length;
-    expect(words).toBeLessThanOrEqual(400);
+    expect(words).toBeLessThanOrEqual(550);
   });
 
   it("含 'When to delegate' 调用条件段（何时委派 vs 自己做）", () => {
@@ -81,4 +84,24 @@ describe("subagent tool description — 行为约束器（非功能说明书）"
     expect(DESCRIPTION).toMatch(/sequential/);
     expect(DESCRIPTION).toMatch(/SAME message/i);
   });
+
+  it("Examples 段含完整 JSON 正例（含 startParam 嵌套结构）", () => {
+    // 弱模型信任 schema 结构信号 > 文本信号，容易把 task/slug 平铺到顶层。
+    // description 必须有完整 JSON 正例，让模型能直接照抄 startParam 嵌套结构。
+    expect(DESCRIPTION).toContain('{"action":"start","startParam"');
+  });
+
+  it("Anti-patterns 段含参数结构反例（top level 平铺 task/slug）", () => {
+    // 显式说明 task/slug 不能平铺到顶层，必须嵌在 startParam 里。
+    expect(DESCRIPTION).toContain("top level");
+  });
+});
+
+describe("subagent tool runtime handler — 错误文案含纠正正例", () => {
+  // 读源码文本断言 executeSubagent 的平铺检测 throw 含 Correct 正例，
+  // 让弱模型撞错后第二次能直接照抄正确形态。
+  it("subagent-tool.ts 含 runtime 平铺检测 throw + Correct 纠正正例", () => {
+    expect(SUBAGENT_TOOL_SRC).toContain("Correct:");
+    expect(SUBAGENT_TOOL_SRC).toContain("params.action === \"start\" && !params.startParam");
+  });
 });

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

@@ -7,11 +7,12 @@
 // 本测试用源码断言（读 .ts 文件文本）验证提示词内容，避免 import 重 mock 链
 // （tool-workflow.ts 依赖 pi-ai/typebox/pi-tui/lifecycle 等值导入）。
 
-import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+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"),
@@ -43,6 +44,27 @@ describe("U1: workflow tool prompt mentions built-in workflows", () => {
     expect(TOOL_WORKFLOW_SRC).toMatch(/workflow run .+--args/i);
   });
 
+  it("promptGuidelines 含 JSON 调用正例（run/status/lifecycle/retry-node）", () => {
+    // 弱模型信任 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 纠正正例 + 平铺检测", () => {
+    // 读源码文本断言 actionRun/必填校验的错误文案含 Correct 正例，
+    // 让弱模型撞错后第二次能直接照抄正确形态。KNOWN_ARG_KEYS 证明平铺检测存在。
+    expect(TOOL_WORKFLOW_SRC).toContain("Correct:");
+    expect(TOOL_WORKFLOW_SRC).toContain("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);

package/src/interface/format.ts

@@ -176,6 +176,8 @@ export function statusGlyph(status: ExecutionStatus): { icon: string | undefined
       return { icon: "✗", color: "error" };
     case "cancelled":
       return { icon: "■", color: "muted" };
+    case "crashed":
+      return { icon: "✝", color: "error" };
     default:
       // 防御:运行时 status 可能是意外值(SDK 投影异常/未来新增状态),兜底为 running 语义
       return { icon: undefined, color: "accent" };

package/src/interface/subagent-actions.ts

@@ -9,6 +9,12 @@
 // content（JSON 字符串）给 LLM，details（SubagentToolResult）给 renderResult，同源同处生成。
 
 import type { AgentToolResult } from "@mariozechner/pi-coding-agent";
+import {
+  guiComponent,
+  type GuiContext,
+  guiResult,
+  isGuiCapable,
+} from "@xyz-agent/extension-protocol";
 
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { computeElapsedSeconds } from "../execution/execution-record.ts";
@@ -22,12 +28,6 @@ import type {
   SubagentRecord,
   SubagentToolResult,
 } from "../execution/types.ts";
-import {
-  guiComponent,
-  type GuiContext,
-  guiResult,
-  isGuiCapable,
-} from "@xyz-agent/extension-protocol";
 import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
 
 // ============================================================
@@ -40,7 +40,10 @@ const DEFAULT_LIST_LIMIT = 20;
 const MAX_LIST_LIMIT = 100;
 
 /** background 启动提示文案（spec FR-3 bgResponse.message）。 */
-const BG_MESSAGE = "detached, will notify on completion";
+const BG_MESSAGE = "detached, will notify on completion (auto-injected message, do not poll)";
+
+/** subagentId（UUID）在 GUI header 的截断显示长度。 */
+const SUBAGENT_ID_PREVIEW = 8;
 
 // ============================================================
 // 入参 / 出参类型
@@ -49,7 +52,7 @@ const BG_MESSAGE = "detached, will notify on completion";
 /** start 入参（从 tool params.startParam 来，task + slug 必填）。 */
 export interface StartHandlerInput {
   task?: string;
-  /** 短标签（≤20 字符），必填。 */
+  /** 短标签（≤35 字符，kebab-case），必填。 */
   slug?: string;
   agent?: string;
   model?: string;
@@ -141,7 +144,7 @@ export async function startHandler(
   // slug 必填 + 空白校验 + 长度校验（≤ SLUG_MAX_LENGTH 字符）
   const slug = input.slug?.trim();
   if (!slug) throw new Error("startParam.slug is required (and must not be whitespace-only)");
-  if (slug.length > SLUG_MAX_LENGTH) throw new Error(`startParam.slug must be ≤${SLUG_MAX_LENGTH} chars (got ${slug.length})`);
+  if (slug.length > SLUG_MAX_LENGTH) throw new Error(`startParam.slug must be ≤${SLUG_MAX_LENGTH} chars (got ${slug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`);
 
   const handle = await service.execute({
     task,
@@ -267,8 +270,15 @@ export function adapter(
     ? { ...result, __gui__: guiResult(buildGuiComponent(action, input, result)) }
     : result;
 
+  // [W3 修复] list action 追加 reminder text block：LLM 调 list 时提醒不要轮询。
+  // reminder 作为第二个 text block（独立追加，不污染 details/JSON schema）。
+  // 只有 list 触发——start 的 reminder 已在 BG_MESSAGE 里；cancel 无需。
+  const reminder = action === "list"
+    ? "\n\nReminder: Subagent completion is auto-notified via injected message (deliverAs: steer). Do NOT poll in a loop — there is no poll action. Use action:'list' only when you concretely need state, then continue working or stop."
+    : "";
+
   return {
-    content: [{ type: "text", text }],
+    content: [{ type: "text", text }, { type: "text", text: reminder }],
     details,
   };
 }
@@ -284,7 +294,7 @@ export function buildGuiComponent(
     // 利用 input.domain 的身份信息，让并发 subagent 可区分。
     const d = input.domain as StartHandlerResult;
     return guiComponent("card", {
-      header: d.slug ? `${d.slug}` : d.subagentId.slice(0, 8),
+      header: d.slug ? `${d.slug}` : d.subagentId.slice(0, SUBAGENT_ID_PREVIEW),
       body: [guiComponent("stats-line", {
         items: [{ value: "running", severity: "ok" }],
       })],