@zhushanwen/pi-subagent-workflow 9.0.1 → 9.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "9.0.1",
+  "version": "9.1.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -58,22 +58,22 @@
     ]
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.16.0",
-    "@zhushanwen/session-delivery": "0.11.0",
+    "@zhushanwen/extension-protocol": "0.17.0",
+    "@zhushanwen/session-delivery": "1.0.0",
     "@zhushanwen/pi-ext-guards": "0.4.2",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-notify-ledger-host": "0.2.0",
-    "@zhushanwen/subagent-core": "0.13.0",
-    "@zhushanwen/zcode-subagent-cli": "0.4.3",
-    "@zhushanwen/pi-subagent-cli": "0.4.5"
+    "@zhushanwen/pi-notify-ledger-host": "0.2.2",
+    "@zhushanwen/subagent-core": "1.1.0",
+    "@zhushanwen/pi-subagent-cli": "0.5.0",
+    "@zhushanwen/zcode-subagent-cli": "0.4.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.8.0",
-    "@zhushanwen/pi-structured-output": "5.1.9"
+    "@zhushanwen/pi-pending-notifications": "0.8.1",
+    "@zhushanwen/pi-structured-output": "6.0.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -87,7 +87,7 @@
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-engine-sdk": "0.7.1"
+    "@zhushanwen/subagent-engine-sdk": "0.8.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/skills/subagent-ext-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-ext-config
-description: "使用或排查 @zhushanwen/pi-subagent-workflow 的引擎路由与同步收集配置时加载。说明 config.json 三环境路径与动态推导方法、字段表（defaultEngine / engineRouting.strict / maxConcurrent / collectSync 三键）、三层路由优先级、生效时机（新 session 生效）、probe 缓存语义、collectSync 预算（perItemChars/totalChars）热读时机、验证步骤与常见错误。触发词：subagent 引擎配置、切换 subagent 引擎、defaultEngine、zcode 派发、subagent 配置在哪、engineFallback、engine_not_found、collectSync、sync collect、collect 配置、subagent-ext-config。"
+description: "使用或排查 @zhushanwen/pi-subagent-workflow 的引擎路由与同步收集配置时加载。说明 config.json 三环境路径与动态推导方法、字段表（defaultEngine / maxConcurrent / collectSync 三键）、三层路由优先级、生效时机（新 session 生效）、probe 缓存语义、collectSync 预算（perItemChars/totalChars）热读时机、验证步骤与常见错误。触发词：subagent 引擎配置、切换 subagent 引擎、defaultEngine、zcode 派发、subagent 配置在哪、engine_not_found、engine_probe_failed、engine_config_unreadable、collectSync、sync collect、collect 配置、subagent-ext-config。"
 ---
 
 # subagent-workflow 引擎路由配置指南
@@ -21,14 +21,13 @@ config.json 位于 pi agent 目录下的 `subagents/config.json`，随环境不
 
 **动态推导（推荐）**：agentDir 由 pi 核心 `getAgentDir()` 决定（读 `PI_CODING_AGENT_DIR`，默认 `~/.pi/agent`）；taiji 通过 `TAIJI_AGENT_DATA_DIR` 隔离数据目录。排查时先查这两个 env 变量组合出实际路径（`<agentDir>/subagents/config.json`），不要假设单一环境——写错环境的配置文件改了也不生效。
 
-文件不存在 / JSON 解析失败 / 字段缺失时全部回默认配置，不报错。旧版 `categories` / `fallback` / `yoloByDefault` 等字段读取时忽略（模型解析已退化为「主 agent model 优先」）。
+文件不存在（ENOENT，合法缺省）/ 字段缺失 → 回默认配置；**文件存在但读不出来（坏 JSON / 权限）** → 派发前显式拒绝 `engine_config_unreadable`（缺省引擎是未知量，不按内置缺省 pi 执行），修复或删除该文件后重试。旧版 `categories` / `fallback` / `yoloByDefault` 等字段读取时忽略（模型解析已退化为「主 agent model 优先」）。
 
 ## 字段表（sanitize 语义）
 
 | 字段 | 类型 | 默认 | 说明 |
 |------|------|------|------|
-| `defaultEngine` | string | 缺省由路由层落 `'pi'` | 全局默认引擎。合法值 `'pi'` / `'zcode'`。坏值（非字符串/空串）**静默忽略**回缺省 pi，不报错——排查「改了 defaultEngine 却还在用 pi」时先检查 JSON 值合法性 |
-| `engineRouting.strict` | boolean | `false` | `true` = 一切 probe 失败直接报错、不做兜底回退。仅认 strict 布尔键，其余键忽略 |
+| `defaultEngine` | string | 缺省由路由层落 `'pi'` | 全局默认引擎。合法值 `'pi'` / `'zcode'`。坏值（非字符串/空串）**静默忽略**回缺省 pi，不报错——排查「改了 defaultEngine 却还在用 pi」时先检查 JSON 值合法性。指向未安装引擎时不回落：派发期报 `engine_not_found` |
 | `maxConcurrent` | number | `6` | subagent 并发池大小。正整数，非正整数/非整数回默认 |
 
 示例（最小可用）：
@@ -37,14 +36,13 @@ config.json 位于 pi agent 目录下的 `subagents/config.json`，随环境不
 {
   "version": 1,
   "defaultEngine": "zcode",
-  "engineRouting": { "strict": false },
   "maxConcurrent": 6
 }
 ```
 
 ## collectSync 节（同步收集）
 
-`collectSync` 控制 subagent 同步收集（`collect:"sync"` 批通知）的默认模式与结果预算。整节缺失 = 不落键，消费方兜底默认（与 defaultEngine/engineRouting 同风格）；逐字段 sanitize——坏字段回该字段默认、好字段透传（部分覆盖合法）；非对象值（字符串/null 等）整节回默认。坏值不炸启动（与 maxConcurrent 同判）。
+`collectSync` 控制 subagent 同步收集（`collect:"sync"` 批通知）的默认模式与结果预算。整节缺失 = 不落键，消费方兜底默认（与 defaultEngine 同风格）；逐字段 sanitize——坏字段回该字段默认、好字段透传（部分覆盖合法）；非对象值（字符串/null 等）整节回默认。坏值不炸启动（与 maxConcurrent 同判）。
 
 | 字段 | 类型 | 默认 | 说明 |
 |------|------|------|------|
@@ -72,13 +70,12 @@ config.json 位于 pi agent 目录下的 `subagents/config.json`，随环境不
 | 2 | agent `.md` frontmatter 的 `engine` 字段 |
 | 3 | config.json 的 `defaultEngine` |
 
-显式指定（层级 1/2）属「守卫命中」——probe 失败**不兜底**、直接报 `engine_probe_failed`；仅全局默认任务才走 fallback 兜底回 pi。
+三层（调用参数 / agent frontmatter / 全局缺省）任一指定了引擎，运行期就按该引擎执行——**不可用即结构化失败，不换目标**：probe 失败一律报 `engine_probe_failed`（含逐项 check 摘要与恢复指引），id 未注册报 `engine_not_found`；要换引擎只能由调用方显式改传 `engine` 参数。三层全缺时落内置缺省 `pi`（免探）。
 
 ## 生效时机与 probe 缓存
 
 - **配置读取**：pi 子进程启动 + 每次 `session_start` 各读一次，session 内不重读。改配置 → 新建 session 生效。
-- **probe 缓存**：引擎探针（zcode CLI 存在性/版本检查）成功或失败均缓存直返，**进程存活期内不重探**。
-- **engineFallback 留痕条件**：兜底回 pi（record 带 `engineFallback` 标记）只在探针**未缓存**时触发。同一 session 内先 probe 成功后 CLI 损坏，不会再触发兜底。要复现/验证 fallback 场景，必须新建 session 重置缓存。
+- **probe 缓存**：引擎探针（zcode CLI 存在性/版本检查）成功或失败均缓存直返，**进程存活期内不重探**——CLI 刚装好 / 刚损坏都要新建 session 重置缓存才会重新探测。
 
 ## 验证步骤
 
@@ -93,8 +90,9 @@ config.json 位于 pi agent 目录下的 `subagents/config.json`，随环境不
 
 | 症状 | 原因与处置 |
 |------|------|
-| `engine_not_found` | engine id 未注册。检查拼写，合法值仅 `pi` / `zcode` |
+| `engine_not_found` | engine id 未注册（含 `defaultEngine` 指向已卸载引擎）。检查拼写，合法值仅 `pi` / `zcode`；不回落其它引擎 |
+| `engine_probe_failed` | 引擎探针失败（CLI 缺失/版本不符）。引擎路由不换目标——修好引擎后重试，或由调用方显式改传 `engine` 参数 |
+| `engine_config_unreadable` | 全局 config.json 存在但读不出来（坏 JSON / 权限）——修复或删除该文件后重试（不按内置缺省 pi 执行） |
 | zcode 任务传 `conversation` / `fork` / `worktree` 被预检拒绝 | 这些是 pi 专属能力，zcode 不支持。改用 `engine: pi` 或不传该参数重试（预检在 record 创建前同步拒绝，可立即换引擎） |
 | 改了 `defaultEngine` 没生效 | 两种可能：① 当前 session 不重读配置——新建 session；② 值非法被静默忽略回 pi——核对 JSON 值 |
-| 期望 fallback 回 pi 却报错 | 显式指定引擎（工具参数/frontmatter）属守卫命中，probe 失败不兜底直接报错；只有走 `defaultEngine` 的任务才兜底 |
 | probe 结果与 CLI 实际状态不符 | 探针进程存活期内缓存——CLI 刚装好/刚损坏，需新建 session 重置缓存 |

package/src/host/__tests__/pi-host.test.ts

@@ -558,7 +558,6 @@ describe("createPiNotifyDomainPorts.createDelivery（透传 session-delivery）"
     const fakePort = {
       supportedPayloads: ["text"] as const,
       isIdle: () => true,
-      hasPendingMessages: () => false,
       send: () => undefined,
     };
     const fakeConfig = { intent: "after-run" as const };

package/src/index.ts

@@ -47,14 +47,14 @@ import { setupEngineAwarenessInjector } from "./injectors/engine-awareness.ts";
 import { setupModelListInjector } from "./injectors/model-list-injector.ts";
 import { setupSubagentListInjector } from "./injectors/subagent-list-injector.ts";
 import { setupWorkflowListInjector } from "./injectors/workflow-list-injector.ts";
-import { renderBgNotifyMessage } from "./interface/bg-notify-render.ts";
-import { registerWorkflowsCommand } from "./interface/commands.ts";
-import { registerSubagentTool } from "./interface/subagent-tool.ts";
+import { renderBgNotifyMessage } from "./interface/gui/bg-notify-render.ts";
+import { registerWorkflowsCommand } from "./interface/command/commands.ts";
+import { registerSubagentTool } from "./interface/tool/subagent-tool.ts";
 // ═══ interface/ 层（tools/commands/tui 合并） ═══
-import { registerSubagentsCommand } from "./interface/subagents.ts";
-import { registerSubagentsTool } from "./interface/tool-subagents.ts";
-import { registerWorkflowTool } from "./interface/tool-workflow.ts";
-import { registerWorkflowScriptTool } from "./interface/tool-workflow-script.ts";
+import { registerSubagentsCommand } from "./interface/command/subagents.ts";
+import { registerSubagentsTool } from "./interface/tool/tool-subagents.ts";
+import { registerWorkflowTool } from "./interface/tool/tool-workflow.ts";
+import { registerWorkflowScriptTool } from "./interface/tool/tool-workflow-script.ts";
 // ═══ workflow 域事件族装配 seam（7 个 pi.on handler + makeDeps/lazyDeps；
 // 与 session-lifecycle.ts 同构，D2 原样搬移 + lazyDeps 样板收敛） ═══
 import { setupWorkflowDomain } from "./workflow-events.ts";

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

@@ -36,7 +36,7 @@ import { createResourceListInjector } from "./resource-list-injector.ts";
 /**
  * pi 版注入引导文案（C5① guide 参数化——core 渲染函数不内嵌平台文案，宿主注入）。
  *
- * 2026-08 C5 重写依据（pi 现参数面，src/interface/subagent-tool-schema.ts）：
+ * 2026-08 C5 重写依据（pi 现参数面，src/interface/tool/subagent-tool-schema.ts）：
  * 旧句「pass systemPrompt alongside the agent name to create a dynamic agent」
  * 指向的 systemPrompt 参数已不在 subagent tool schema——现 agent 参数 = .md 绝对
  * 路径（<location>），缺省落 general-purpose（继承主 agent 模型与项目上下文），

package/src/interface/command/__tests__/commands-open.test.ts

@@ -0,0 +1,278 @@
+/**
+ * /workflows 命令的打开通道契约（与 commands-resume.test.ts 的 resume 通道互补）。
+ *
+ * 覆盖面：
+ *   - getArgumentCompletions：一级 lifecycle 动词（前缀过滤）/ 二级 runId 补全
+ *     （数据源空 → null、getRuns 抛错 → null + warn 留痕）/ 非动词前缀 → null
+ *   - handler：print/json 模式降级提示；runId 精确匹配 / 前缀唯一匹配 / 前缀歧义 /
+ *     未命中；无参 0 runs 提示 / 单 run 直开 / 多 run select（排序 + 取消不打开）
+ *   - openView：ViewActions.abort 接线 + liveRecords 查询域接线（service 在场时）
+ *
+ * mock 策略：WorkflowsView 模块 stub（createWorkflowsView 为 vi.fn——openView 的
+ * 断言面是传参而非真实 TUI）；resume-run 深路径 stub（对齐 commands-resume.test.ts）；
+ * pi-extension-logger stub（catch 冷路径 warn 不落真实日志盘）。
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { setSubagentService, GLOBAL_SLOT_KEYS } from "@zhushanwen/subagent-core";
+import { noteRebuiltSettlement } from "@zhushanwen/subagent-core";
+import type { WorkflowRun } from "@zhushanwen/subagent-core";
+
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+vi.mock("@zhushanwen/subagent-core/orchestration/resume-run.ts", () => ({
+  resumeRun: vi.fn(),
+}));
+vi.mock("../../tui/views/WorkflowsView.ts", () => ({
+  createWorkflowsView: vi.fn(() => Promise.resolve()),
+}));
+
+import { createWorkflowsView } from "../../tui/views/WorkflowsView.ts";
+import { registerWorkflowsCommand } from "../commands.ts";
+import { LIST_LIMIT } from "../../tui/list-shared.ts";
+
+// ── fixture ──────────────────────────────────────────────────
+
+const T0 = 1_700_000_000_000;
+let runSeq = 0;
+
+function makeRun(opts: { status?: "running" | "interrupted" | "done"; startedAt?: number; name?: string; runId?: string } = {}): WorkflowRun {
+  const runId = opts.runId ?? `wf-cmd-${runSeq++}`;
+  const status = opts.status ?? "running";
+  if (status === "done") {
+    noteRebuiltSettlement(runId, { outcome: "done", settledAt: Date.parse("2026-09-27T00:00:00.000Z") });
+  }
+  const meta: Record<string, unknown> = { startedAt: new Date(opts.startedAt ?? T0).toISOString() };
+  if (status === "interrupted") meta.interruptedAt = new Date(T0 + 5000).toISOString();
+  return {
+    runId,
+    spec: { scriptName: opts.name ?? `wf-${runId.slice(-1)}` },
+    meta,
+    state: { status: "running", budget: { usedTokens: 0, usedCost: 0 }, trace: { toArray: () => [] }, errorLogs: [] },
+  } as unknown as WorkflowRun;
+}
+
+interface CompletionsView { // oe-exempt:20260930:test:test double shape for command capture (test infra)
+  getArgumentCompletions(prefix: string): Array<{ label: string; value: string }> | null;
+  handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+}
+
+interface CtxHarness { // oe-exempt:20260930:test:test fixture harness shape (test infra)
+  ctx: ExtensionCommandContext;
+  notifies: Array<{ msg: string; level: string }>;
+  select: ReturnType<typeof vi.fn>;
+}
+
+function captureCommand(getRuns: () => Map<string, WorkflowRun>, deps: Record<string, unknown> = {}): CompletionsView {
+  let captured!: CompletionsView;
+  const api = {
+    registerCommand: (_name: string, def: unknown) => {
+      captured = def as CompletionsView;
+    },
+  };
+  registerWorkflowsCommand(api as never, getRuns, { store: { stateFilePath: (id: string) => `/state/${id}` }, ...deps } as never);
+  return captured;
+}
+
+function makeTuiCtx(): CtxHarness {
+  const notifies: Array<{ msg: string; level: string }> = [];
+  const select = vi.fn(() => Promise.resolve(undefined));
+  const ctx = {
+    mode: "tui",
+    ui: {
+      theme: { fg: (_t: string, text: string) => text, bold: (t: string) => t, bg: (_c: string, t: string) => t, underline: (t: string) => t },
+      notify: (msg: string, level: string) => notifies.push({ msg, level }),
+      select,
+    },
+  };
+  return { ctx: ctx as unknown as ExtensionCommandContext, notifies, select };
+}
+
+/** 重置进程级 SubagentService 单例槽（测试清理，key 与生产 getServiceSlot 一致）。 */
+function resetServiceSlot(): void {
+  const slot = Reflect.get(globalThis, Symbol.for(GLOBAL_SLOT_KEYS.service)) as
+    | { current: unknown }
+    | undefined;
+  if (slot) slot.current = null;
+}
+
+beforeEach(() => {
+  runSeq = 0;
+  vi.mocked(createWorkflowsView).mockClear();
+});
+
+afterEach(() => {
+  resetServiceSlot();
+});
+
+// ── 补全面 ───────────────────────────────────────────────────
+
+describe("/workflows getArgumentCompletions", () => {
+  it("一级：空前缀给 abort/resume 两动词（带尾随空格），前缀过滤生效", () => {
+    const cmd = captureCommand(() => new Map());
+    const all = cmd.getArgumentCompletions("");
+    expect(all).toHaveLength(2);
+    expect(all!.map((o) => o.value)).toEqual(["abort ", "resume "]);
+    expect(cmd.getArgumentCompletions("ab")).toEqual([
+      { label: "abort", value: "abort ", description: "Abort a workflow run" },
+    ]);
+    expect(cmd.getArgumentCompletions("wor")).toEqual([]);
+  });
+
+  it("二级：动词后补全 session runs（runId + 名字/状态描述），按排序输出", () => {
+    const older = makeRun({ startedAt: T0, name: "older" });
+    const newer = makeRun({ startedAt: T0 + 60_000, name: "newer" });
+    const runs = new Map<string, WorkflowRun>([
+      [older.runId, older],
+      [newer.runId, newer],
+    ]);
+    const cmd = captureCommand(() => runs);
+    // 二级触发条件 = parts.length ≥ 2（"abort x"——尾随单空格会被 trim 进一级动词匹配）
+    const items = cmd.getArgumentCompletions("abort x");
+    expect(items).toHaveLength(2);
+    expect(items![0]!.label).toBe(newer.runId); // 新的在前
+    expect(items![0]!.description).toContain("newer");
+    expect(items![0]!.description).toContain("[running]");
+    expect(cmd.getArgumentCompletions("resume x")).toHaveLength(2);
+  });
+
+  it("二级：0 runs → null；getRuns 抛错 → null（补全缺失不致命）", () => {
+    const cmd = captureCommand(() => new Map());
+    expect(cmd.getArgumentCompletions("abort x")).toBeNull();
+    const boom = captureCommand(() => {
+      throw new Error("store unavailable");
+    });
+    expect(boom.getArgumentCompletions("resume x")).toBeNull();
+  });
+
+  it("非动词首词 → null", () => {
+    const cmd = captureCommand(() => new Map());
+    expect(cmd.getArgumentCompletions("view x")).toBeNull();
+  });
+});
+
+// ── handler：模式分流 + 打开通道 ─────────────────────────────
+
+describe("/workflows handler 打开通道（TUI）", () => {
+  it("print 模式 → 交互模式降级提示，不打开面板", async () => {
+    const cmd = captureCommand(() => new Map());
+    const { ctx, notifies } = makeTuiCtx();
+    (ctx as { mode: string }).mode = "print";
+    await cmd.handler("", ctx);
+    expect(notifies).toEqual([{ msg: "/workflows requires interactive mode", level: "error" }]);
+    expect(vi.mocked(createWorkflowsView)).not.toHaveBeenCalled();
+  });
+
+  it("runId 精确匹配 → 打开该 run（theme/stateFilePath 原样透传；service 缺席 → liveRecords undefined）", async () => {
+    const run = makeRun();
+    const cmd = captureCommand(() => new Map([[run.runId, run]]));
+    const { ctx } = makeTuiCtx();
+    await cmd.handler(run.runId, ctx);
+    expect(vi.mocked(createWorkflowsView)).toHaveBeenCalledTimes(1);
+    const args = vi.mocked(createWorkflowsView).mock.calls[0] as unknown as [
+      WorkflowRun, unknown, ExtensionCommandContext, { abort: (id: string) => Promise<void> }, string, undefined,
+    ];
+    expect(args[0]).toBe(run);
+    expect(args[2]).toBe(ctx);
+    expect(args[4]).toBe(`/state/${run.runId}`);
+    expect(args[5]).toBeUndefined();
+  });
+
+  it("runId 前缀唯一匹配 → 打开；前缀歧义/未命中 → error notify", async () => {
+    const a = makeRun({ runId: "wf-alpha-1" });
+    const b = makeRun({ runId: "wf-beta-2" });
+    const cmd = captureCommand(() => new Map([[a.runId, a], [b.runId, b]]));
+    const { ctx, notifies } = makeTuiCtx();
+    await cmd.handler("wf-alp", ctx);
+    expect(vi.mocked(createWorkflowsView)).toHaveBeenCalledTimes(1);
+    expect((vi.mocked(createWorkflowsView).mock.calls[0] as unknown as [WorkflowRun])[0]).toBe(a);
+
+    await cmd.handler("wf-", ctx); // 两 run 同前缀 → 歧义不打开
+    expect(notifies.at(-1)).toMatchObject({ msg: "Workflow 'wf-' not found", level: "error" });
+
+    await cmd.handler("nope", ctx);
+    expect(notifies.at(-1)).toMatchObject({ msg: "Workflow 'nope' not found", level: "error" });
+    expect(vi.mocked(createWorkflowsView)).toHaveBeenCalledTimes(1);
+  });
+
+  it("无参 0 runs → No workflows 提示；单 run 直开", async () => {
+    const cmd = captureCommand(() => new Map());
+    const { ctx, notifies } = makeTuiCtx();
+    await cmd.handler("", ctx);
+    expect(notifies).toEqual([{ msg: "No workflows in current session.", level: "info" }]);
+
+    const run = makeRun();
+    const cmd1 = captureCommand(() => new Map([[run.runId, run]]));
+    await cmd1.handler("", ctx);
+    expect(vi.mocked(createWorkflowsView)).toHaveBeenCalledTimes(1);
+    expect((vi.mocked(createWorkflowsView).mock.calls[0] as unknown as [WorkflowRun])[0]).toBe(run);
+  });
+
+  it("无参多 runs → select 展示排序条目（running 优先、新在前），选中后打开", async () => {
+    const older = makeRun({ startedAt: T0, name: "older" });
+    const newer = makeRun({ startedAt: T0 + 60_000, name: "newer" });
+    const done = makeRun({ status: "done", name: "finished" });
+    const interrupted = makeRun({ status: "interrupted", name: "paused" });
+    const runs = new Map<string, WorkflowRun>([
+      [done.runId, done],
+      [interrupted.runId, interrupted],
+      [older.runId, older],
+      [newer.runId, newer],
+    ]);
+    const cmd = captureCommand(() => runs);
+    const { ctx, notifies, select } = makeTuiCtx();
+    select.mockReturnValue(Promise.resolve(undefined)); // 取消 → 不打开
+    await cmd.handler("", ctx);
+    expect(vi.mocked(createWorkflowsView)).not.toHaveBeenCalled();
+
+    // 排序：running(新) → running(旧) → interrupted → done
+    const entries = select.mock.calls[0][1] as string[];
+    expect(entries).toHaveLength(4);
+    expect(entries[0]).toContain("newer");
+    expect(entries[1]).toContain("older");
+    expect(entries[2]).toContain("paused");
+    expect(entries[2]).toContain("[interrupted]");
+    expect(entries[3]).toContain("finished");
+    expect(entries[3]).toContain("[done]");
+
+    select.mockReturnValue(Promise.resolve(entries[1])); // 选中 older
+    await cmd.handler("", ctx);
+    expect(vi.mocked(createWorkflowsView)).toHaveBeenCalledTimes(1);
+    expect((vi.mocked(createWorkflowsView).mock.calls[0] as unknown as [WorkflowRun])[0]).toBe(older);
+    expect(notifies).toHaveLength(0);
+  });
+
+  it("select 条目不在列表（索引 -1）→ 不打开", async () => {
+    const a = makeRun();
+    const b = makeRun();
+    const cmd = captureCommand(() => new Map([[a.runId, a], [b.runId, b]]));
+    const { ctx, select } = makeTuiCtx();
+    select.mockReturnValue(Promise.resolve("ghost-entry"));
+    await cmd.handler("", ctx);
+    expect(vi.mocked(createWorkflowsView)).not.toHaveBeenCalled();
+  });
+});
+
+// ── openView 接线 ────────────────────────────────────────────
+
+describe("/workflows openView 接线", () => {
+  it("service 在场：liveRecords 绑定 collectRecordsByParentRunId(runId, LIST_LIMIT)", async () => {
+    const collectRecordsByParentRunId = vi.fn(() => []);
+    setSubagentService({
+      queries: { collectRecordsByParentRunId },
+    } as never);
+    const run = makeRun();
+    const cmd = captureCommand(() => new Map([[run.runId, run]]));
+    const { ctx } = makeTuiCtx();
+    await cmd.handler(run.runId, ctx);
+
+    const args = vi.mocked(createWorkflowsView).mock.calls[0] as unknown as [
+      WorkflowRun, unknown, ExtensionCommandContext, { abort: (id: string) => Promise<void> }, string, () => unknown[],
+    ];
+    expect(args[5]).toBeTypeOf("function");
+    expect(args[5]()).toEqual([]);
+    expect(collectRecordsByParentRunId).toHaveBeenCalledWith(run.runId, LIST_LIMIT);
+  });
+});

package/src/interface/{commands.ts → command/commands.ts}

@@ -21,16 +21,17 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import type { LauncherDeps } from "@zhushanwen/subagent-core";
 import { abortRun, getSubagentService, resumeRun } from "@zhushanwen/subagent-core";
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
 import { parseWorkflowRpcCommand, type WorkflowRpcAction } from "./command-actions.ts";
-import { createWorkflowsView, type ViewActions } from "./views/WorkflowsView.ts";
+import { createWorkflowsView, type ViewActions } from "../tui/views/WorkflowsView.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
-import { LIST_LIMIT } from "./list-shared.ts";
-import { ID_PREVIEW_LENGTH } from "./id-preview.ts";
-import { displayStatusOf } from "./tool-workflow.ts";
+import { LIST_LIMIT } from "../tui/list-shared.ts";
+import { ID_PREVIEW_LENGTH } from "../format/id-preview.ts";
+import { displayStatusOf } from "../tool/tool-workflow.ts";
 
 /** status 显示顺序：running 优先（活跃态在前），interrupted 次之（[D2] 暂停态
  *  ——无活体但可续跑，排活体后、终局前），再 startedAt 倒序。
@@ -94,8 +95,15 @@ export function registerWorkflowsCommand(
             value: r.runId,
             description: `${r.spec.scriptName} [${displayStatusOf(r)}]`,
           }));
-        } catch {
-          // 拿不到运行时数据（getRuns 抛错）→ 静默降级，补全失败不影响 command
+        } catch (err) {
+          // runs 补全数据源不可用 → 补全缺失（返回 null，不改变 command 行为），warn 留痕
+          // ——补全静默消失与「当前 session 没有 run」不可区分。
+          // getLogger 惰性调用（catch 是冷路径——测试环境对 pi-extension-logger 的
+          // module-level mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+          getLogger("subagent-workflow").warn(
+            "[commands] /workflows runId completion unavailable — runs data source failed, completion omitted",
+            { reason: toErrorMessage(err) },
+          );
           return null;
         }
       }
@@ -292,7 +300,7 @@ function sortedRuns(runs: Map<string, WorkflowRun>): WorkflowRun[] {
  * 打开 WorkflowsView（三级导航 TUI），注入 lifecycle ViewActions。
  *
  * ViewActions 通过 deps 调 lifecycle（abort），与 view 解耦——
- * view 单测可注入 mock actions（见 views/__tests__/WorkflowsView.test.ts）。
+ * view 单测可注入 mock actions（见 tui/views/__tests__/WorkflowsView.test.ts）。
  *
  * [H2 W3] live 进度数据源（设计 D2 进度源切换）：view 经 store 查询
  * collectRecordsByParentRunId(run.runId)（内存 ∪ 磁盘重建 ∪ manifest，LIST_LIMIT

package/src/interface/{subagents.ts → command/subagents.ts}

@@ -1,7 +1,7 @@
-// src/interface/subagents.ts
+// src/interface/command/subagents.ts
 //
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
-// 同名 tool（批量派发入口，模型调用面）见 interface/tool-subagents.ts——两者无共享状态、无调用关系。
+// 同名 tool（批量派发入口，模型调用面）见 interface/tool/tool-subagents.ts——两者无共享状态、无调用关系。
 //
 // 解析：args[0] 直接作可选 <id>（聚焦该 record）。
 // RPC 模式（taiji GUI）：解析 cancel/message/start action 直接执行，不打开 TUI。
@@ -17,8 +17,8 @@ import { messageHandler, startHandler } from "@zhushanwen/subagent-core";
 import { SUBAGENT_DIRECTIVE_CUSTOM_TYPE } from "@zhushanwen/extension-protocol";
 import { parseSubagentRpcCommand } from "./command-actions.ts";
 import type { SubagentRpcAction } from "./command-actions.ts";
-import { LIST_LIMIT } from "./list-shared.ts";
-import { createSubagentsView } from "./list-view.ts";
+import { LIST_LIMIT } from "../tui/list-shared.ts";
+import { createSubagentsView } from "../tui/list-view.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // subagent-directive customType 经 extension-protocol 单源（与 shared/runtime 消费侧