@zhushanwen/pi-subagent-workflow 0.1.0 → 0.2.0

package/src/interface/subagents.ts

@@ -3,26 +3,66 @@
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
 //
 // 解析：args[0] 直接作可选 <id>（聚焦该 record）。
+// RPC 模式（xyz-agent GUI）：解析 cancel action 直接执行，不打开 TUI。
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 
 import { getSubagentService } from "../execution/subagent-service.ts";
+import { parseSubagentRpcCommand } from "./command-actions.ts";
 import { createSubagentsView } from "./list-view.ts";
 
 /** 注册 /subagents 命令（= list overlay）。 */
 export function registerSubagentsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("subagents", {
-    description: "Subagents: /subagents [<id>]",
+    description: "Subagents: /subagents [<id>] | /subagents cancel <id>",
     handler: async (argsStr: string, ctx: ExtensionCommandContext) => {
-      if (!ctx.hasUI) {
-        ctx.ui.notify("/subagents requires an interactive UI", "error");
-        return;
-      }
       const service = getSubagentService();
       if (!service) {
         ctx.ui.notify("subagents execution runtime not ready (session not started)", "error");
         return;
       }
+
+      // ── RPC 模式（xyz-agent GUI）：解析 action 直接执行，不打开 TUI ──
+      // hasUI 在 TUI 和 RPC 都为 true，不能用于区分；用 ctx.mode === "rpc" 判定 GUI 通道。
+      if (ctx.mode === "rpc") {
+        const parsed = parseSubagentRpcCommand(argsStr);
+        switch (parsed.action) {
+          case "cancel": {
+            try {
+              const ok = service.cancel(parsed.recordId);
+              ctx.ui.notify(
+                ok ? `Cancelled subagent ${parsed.recordId}` : `Subagent ${parsed.recordId} not found or already finished`,
+                ok ? "info" : "warning",
+              );
+            } catch (err) {
+              // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
+              const msg = err instanceof Error ? err.message : String(err);
+              ctx.ui.notify(`Failed to cancel subagent ${parsed.recordId}: ${msg}`, "warning");
+            }
+            return;
+          }
+          case "cancel-missing-id":
+            ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
+            return;
+          case "noop":
+            // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+            ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
+            return;
+          default: {
+            // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
+            const _exhaustive: never = parsed;
+            throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
+          }
+        }
+      }
+
+      // ── print/json 模式（headless）：不可交互 ──
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/subagents requires interactive mode", "error");
+        return;
+      }
+
+      // ── TUI 模式：打开 list overlay（原逻辑不变）──
       const args = argsStr.trim().split(/\s+/).filter(Boolean);
       await createSubagentsView(service, ctx.ui.theme, ctx, args[0]);
     },

package/src/interface/tool-render.ts

@@ -98,7 +98,14 @@ export function renderSubagentCall(
     ? (args as { startParam?: unknown }).startParam
     : undefined;
   const agent = extractAgentName(startParam);
-  const parts = [`${t.fg("toolTitle", t.bold("subagent "))}${t.fg("accent", agent)}`];
+  // slug：从 startParam 提取（必填字段），非空时在 agent 后用 · 分隔展示。
+  const slug = typeof startParam === "object" && startParam !== null && "slug" in startParam
+    ? (startParam as { slug?: unknown }).slug
+    : undefined;
+  const slugStr = typeof slug === "string" ? slug.trim() : "";
+  const parts = slugStr
+    ? [`${t.fg("toolTitle", t.bold("subagent "))}${t.fg("accent", agent)}${t.fg("dim", " · ")}${t.fg("accent", slugStr)}`]
+    : [`${t.fg("toolTitle", t.bold("subagent "))}${t.fg("accent", agent)}`];
 
   // model + thinking——完整 provider/model（accent 色），thinking 保持 dim。
   // 不去 provider 前缀——provider 是模型来源的关键信息，感知「用错模型」需要完整路径。
@@ -210,8 +217,9 @@ function buildCompactLines(d: SubagentToolResult, theme: ThemeLike): string[] {
   }
   // ── start 分支：background ──
   if ("bgResponse" in d) {
+    const slugPart = d.slug ? `${theme.fg("dim", " · ")}${theme.fg("accent", d.slug)}` : "";
     return [truncLine(
-      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}`
+      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}${slugPart}`
       + ` ${theme.fg("dim", "· running detached · will notify on completion")}`,
       width,
     )];
@@ -238,8 +246,9 @@ function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
   const lines: string[] = [];
   // bg 占位 expanded 与 compact 同（一次性 block 无细节可展开）
   if ("bgResponse" in d) {
+    const slugPart = d.slug ? `${theme.fg("dim", " · ")}${theme.fg("accent", d.slug)}` : "";
     lines.push(truncLine(
-      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}`,
+      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}${slugPart}`,
       width,
     ));
     return lines;
@@ -302,7 +311,7 @@ function firstLineSanitized(text?: string): string {
 // list 渲染 helper（action:"list" 分支）
 // ============================================================
 
-/** list compact：标题行 + 每行一个 item 摘要（glyph + agent + mode + status + duration）。 */
+/** list compact：标题行 + 每行一个 item 摘要（glyph + agent + slug + mode + status + duration）。 */
 function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number): string[] {
   if (resp.items.length === 0) {
     return [truncLine(theme.fg("dim", `No subagents (running: ${resp.running})`), width)];
@@ -314,7 +323,9 @@ function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number):
     const glyph = statusGlyph(it.status);
     const icon = glyph.icon ?? "●";
     const mode = "bg";
-    const line = `${theme.fg(glyph.color, icon)} ${theme.fg("accent", it.agent)}`
+    // slug 非空时在 agent 后展示（· 分隔），空串时省略。
+    const slugPart = it.slug ? `${theme.fg("dim", " · ")}${theme.fg("accent", it.slug)}` : "";
+    const line = `${theme.fg(glyph.color, icon)} ${theme.fg("accent", it.agent)}${slugPart}`
       + ` ${theme.fg("dim", `· ${mode} · ${it.status} · ${formatElapsedSeconds(it.duration)}`)}`;
     lines.push(truncLine(`${STREAM_PREFIX}${line}`, width));
   }

package/src/interface/tool-workflow-script.ts

@@ -23,9 +23,17 @@ import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-cod
 import { Text } from "@mariozechner/pi-tui";
 import { type Static, Type } from "typebox";
 
+import {
+  guiComponent,
+  type GuiContext,
+  type GuiRenderResult,
+  guiResult,
+  isGuiCapable,
+} from "@xyz-agent/extension-protocol";
 import type { WorkflowScriptRegistry } from "../orchestration/models/workflow-script-registry.ts";
 import { lintScript } from "../orchestration/script-lint.ts";
 import { deleteWorkflow, saveWorkflow } from "../orchestration/workflow-files.ts";
+import { toGuiCtx } from "./gui-mappers.ts";
 import { renderTextFallback } from "./views/format.ts";
 
 // ── Parameter schema ─────────────────────────────────────────
@@ -60,11 +68,11 @@ type ScriptParams = Static<typeof WorkflowScriptParams>;
  * can distinguish error shape from success.
  */
 export type WorkflowScriptToolDetails =
-  | { action: "generate"; path: string; name: string; status: "ready" }
-  | { action: "lint"; name: string; valid: boolean; findingCount: number }
-  | { action: "list"; count: number }
-  | { action: "save"; name: string; ok: boolean }
-  | { action: "delete"; name: string; ok: boolean };
+  | { action: "generate"; path: string; name: string; status: "ready"; __gui__?: GuiRenderResult }
+  | { action: "lint"; name: string; valid: boolean; findingCount: number; __gui__?: GuiRenderResult }
+  | { action: "list"; count: number; __gui__?: GuiRenderResult }
+  | { action: "save"; name: string; ok: boolean; __gui__?: GuiRenderResult }
+  | { action: "delete"; name: string; ok: boolean; __gui__?: GuiRenderResult };
 
 /** Result returned by the `workflow-script` tool's execute. */
 export interface TextContent {
@@ -73,6 +81,71 @@ export interface TextContent {
   isError?: boolean;
 }
 
+// ── GUI 协议 helpers ───────────────────────────────────────
+
+/**
+ * 为 details 附加 __gui__（RPC 模式下）。
+ *
+ * 所有 5 个 action 都映射到 stats-line（单行统计，无复杂结构）：
+ *   - generate: 显示生成的脚本名
+ *   - lint: passed / N findings
+ *   - list: 脚本数量
+ *   - save/delete: ok/warn
+ */
+function withScriptGui(
+  result: TextContent,
+  ctx?: GuiContext,
+): TextContent {
+  if (!ctx || !isGuiCapable(ctx) || !result.details) return result;
+  const details = result.details;
+  // union 各成员已声明 __gui__?，spread + 补字段类型安全，无需强转
+  return {
+    ...result,
+    details: { ...details, __gui__: guiResult(buildScriptGui(details)) },
+  };
+}
+
+/** 按 WorkflowScriptToolDetails 构造 stats-line GuiComponent。 */
+export function buildScriptGui(details: WorkflowScriptToolDetails) {
+  switch (details.action) {
+    case "generate":
+      return guiComponent("stats-line", {
+        items: [{ label: "generated", value: details.name, severity: "ok" }],
+      });
+    case "lint":
+      return guiComponent("stats-line", {
+        items: [
+          {
+            label: "lint",
+            value: details.valid ? "passed" : `${details.findingCount} findings`,
+            severity: details.valid ? "ok" : "warn",
+          },
+        ],
+      });
+    case "list":
+      return guiComponent("stats-line", {
+        items: [{ label: "scripts", value: String(details.count), severity: "ok" }],
+      });
+    case "save":
+    case "delete":
+      return guiComponent("stats-line", {
+        items: [
+          {
+            label: details.action,
+            value: details.name,
+            severity: details.ok ? "ok" : "warn",
+          },
+        ],
+      });
+    default:
+      // 防御性兜底：action 是有限联合类型，理论不可达。
+      // 若未来新增 action 忘了更新此 switch，返回中性 stats-line 而非 undefined。
+      return guiComponent("stats-line", {
+        items: [{ label: "action", value: String((details as { action: string }).action), severity: "warn" }],
+      });
+  }
+}
+
 // ── Tool registration ────────────────────────────────────────
 
 /**
@@ -92,14 +165,22 @@ export function registerWorkflowScriptTool(
     label: "Workflow Script",
     description:
       "Manage workflow scripts: generate (AI creates tmp script), lint (static check), " +
-      "save (tmp→permanent), delete, list. Replaces workflow-generate + workflow-lint tools.",
+      "save (tmp→permanent), delete, list. Before generating a new script, use action:list " +
+      "to check if a built-in workflow (chain/parallel/scatter-gather/map-reduce) already " +
+      "covers the use case. Replaces workflow-generate + workflow-lint tools.",
     promptSnippet: "Generate, lint, save, delete, or list workflow scripts",
     promptGuidelines: [
       "generate: AI writes a tmp workflow script to .pi/workflows/.tmp/. Script can be run immediately via the workflow tool.",
       "lint: Statically check a script for common API misuse (outputSchema, result.output, file state).",
       "save: Promote a tmp script to permanent (.pi/workflows/).",
       "delete: Remove a script (blocked if a run is active).",
-      "list: Show all available workflow scripts with source tags.",
+      "list: Show all available workflow scripts with source tags. " +
+      "Use this to discover built-in workflows (chain/parallel/scatter-gather/map-reduce) " +
+      "and user-generated scripts before starting a run. After listing, start a script via " +
+      "the workflow tool with action:run and the script name.",
+      "ANTI-PATTERN: Do NOT generate a new script for chain/parallel/scatter-gather/map-reduce " +
+      "orchestration — these are built-in. Call action:list first. Generate only when no built-in " +
+      "matches the use case.",
     ],
     parameters: WorkflowScriptParams,
 
@@ -108,22 +189,31 @@ export function registerWorkflowScriptTool(
       params: ScriptParams,
       signal: AbortSignal | undefined,
       _onUpdate: unknown,
-      _ctx: ExtensionContext,
+      ctx: ExtensionContext,
     ): Promise<TextContent> {
+      let result: TextContent;
       switch (params.action) {
         case "generate":
-          return actionGenerate(params, signal);
+          result = actionGenerate(params, signal);
+          break;
         case "lint":
-          return actionLint(params, registry);
+          result = await actionLint(params, registry);
+          break;
         case "save":
-          return actionSave(params);
+          result = await actionSave(params);
+          break;
         case "delete":
-          return actionDelete(params, registry, isRunning);
+          result = actionDelete(params, registry, isRunning);
+          break;
         case "list":
-          return await actionList(registry);
+          result = await actionList(registry);
+          break;
         default:
-          return textResult(`Unknown action: ${String(params.action)}`, true);
+          result = textResult(`Unknown action: ${String(params.action)}`, true);
+          break;
       }
+      // GUI 协议：RPC 模式下附加 __gui__ 到 details
+      return withScriptGui(result, toGuiCtx(ctx));
     },
 
     renderCall(args: ScriptParams, theme: Theme, _context?: unknown) {
@@ -228,7 +318,15 @@ async function actionLint(
   }
   const source = await loadScriptSource(name, registry);
   if (!source) {
-    return textResult(`Workflow '${name}' not found or not available.`, true);
+    const all = await registry.loadAll();
+    const available = all.filter((wf) => wf.available);
+    const suggestions = available
+      .map((wf) => `  - ${wf.name}: ${wf.meta.description || "(no description)"}`)
+      .join("\n");
+    return textResult(
+      `Workflow '${name}' not found or not available.\nAvailable:\n${suggestions || "  (none)"}`,
+      true,
+    );
   }
 
   const result = lintScript(source);

package/src/interface/tool-workflow.ts

@@ -26,14 +26,17 @@ import { type Static, Type } from "typebox";
 
 import type { LauncherDeps } from "../orchestration/launcher.ts";
 import { abortRun, pauseRun, resumeRun, runWorkflow } from "../orchestration/lifecycle.ts";
+import type { RunStore } from "../orchestration/models/ports.ts";
 import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
 import { retryNode, skipNode } from "../orchestration/node-ops.ts";
 import {
   guiComponent,
   type GuiContext,
+  type GuiRenderResult,
   guiResult,
   isGuiCapable,
-} from "./gui-adapter.ts";
+} from "@xyz-agent/extension-protocol";
+import { mapRunIcon, mapRunStatus, toGuiCtx } from "./gui-mappers.ts";
 import {
   acquireReentryGuard,
   REENTRY_BUSY_MESSAGE,
@@ -69,6 +72,14 @@ const WorkflowParams = Type.Object({
   name: Type.Optional(
     Type.String({ description: "Workflow name (run action)" }),
   ),
+  slug: Type.Optional(
+    Type.String({
+      description:
+        "Short label (max 20 chars) for this run, shown in the TUI to distinguish concurrent runs. " +
+        "If omitted, defaults to the script name.",
+      maxLength: 20,
+    }),
+  ),
   runId: Type.Optional(
     Type.String({ description: "Workflow run ID (pause/resume/abort/retry-node/skip-node)" }),
   ),
@@ -99,11 +110,15 @@ const RUNID_SHORT = 8;
 interface RunSummary {
   runId: string;
   name: string;
+  /** Run 级 slug（可选，旧 run 缺失为 undefined）。 */
+  slug?: string;
   status: string;
   reason?: string;
   startedAt?: string;
   completedAt?: string;
   error?: string;
+  /** Run 状态快照文件绝对路径（<sessionDir>/workflow-state/<runId>.jsonl）。 */
+  stateFile?: string;
 }
 
 // ── Tool result types ──
@@ -112,14 +127,14 @@ interface RunSummary {
  * Discriminated union of `workflow` tool `details` payloads.
  *
  * Discriminant: `action`. Each action's details shape is explicitly typed so
- * downstream consumers (GUI task-list renderer, structured-output) can narrow
+ * downstream consumers (GUI list-tree renderer, structured-output) can narrow
  * without unsafe casts.
  */
 export type WorkflowToolDetails =
-  | { action: "run"; runId: string; status: "running" | "not_found"; name: string }
-  | { action: "status"; runs: RunSummary[] }
-  | { action: "pause" | "resume" | "abort"; runId: string; status: string; reason?: string }
-  | { action: "retry-node" | "skip-node"; runId: string; callId: number };
+  | { action: "run"; runId: string; status: "running" | "not_found"; name: string; slug?: string; stateFile?: string; __gui__?: GuiRenderResult }
+  | { action: "status"; runs: RunSummary[]; __gui__?: GuiRenderResult }
+  | { action: "pause" | "resume" | "abort"; runId: string; status: string; reason?: string; __gui__?: GuiRenderResult }
+  | { action: "retry-node" | "skip-node"; runId: string; callId: number; __gui__?: GuiRenderResult };
 
 /** Result returned by the `workflow` tool's execute. */
 export interface ToolResult {
@@ -130,42 +145,57 @@ export interface ToolResult {
 
 // ── GUI 协议 helpers ───────────────────────────────────────
 
-/** 为 details 附加 __gui__（RPC 模式下）。 */
-function withGui<T extends WorkflowToolDetails | undefined>(
-  details: T,
+/** 为 details 附加 __gui__（RPC 模式下）。union 各成员已声明 __gui__?，无需强转。 */
+function withGui(
+  details: WorkflowToolDetails | undefined,
   ctx?: GuiContext,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = details ? { ...details } : {};
-  if (ctx && isGuiCapable(ctx) && details) {
-    out.__gui__ = guiResult(buildWorkflowGui(details));
+): WorkflowToolDetails | undefined {
+  if (!details) return undefined;
+  if (ctx && isGuiCapable(ctx)) {
+    return { ...details, __gui__: guiResult(buildWorkflowGui(details)) };
   }
-  return out;
+  return details;
 }
 
 /** 按 WorkflowToolDetails 构造对应的 GuiComponent。 */
-function buildWorkflowGui(details: WorkflowToolDetails) {
+export function buildWorkflowGui(details: WorkflowToolDetails) {
   if (details.action === "run") {
-    return guiComponent("workflow-runs", {
-      runs: [{ runId: details.runId, name: details.name, status: details.status }],
+    // not_found 是脚本未找到的逻辑错误（isError:true），不能走通用 mapper 的 done/check 成功映射。
+    // 短路为 danger severity 的 stats-line，与 isError 文案一致。
+    if (details.status === "not_found") {
+      return guiComponent("stats-line", {
+        items: [{ label: "run", value: "not found", severity: "danger" as const }],
+      });
+    }
+    const statusStr = details.status;
+    return guiComponent("list-tree", {
+      items: [{
+        label: [details.name, details.slug, details.runId.slice(0, 8)].filter(Boolean).join(" "),
+        status: mapRunStatus(statusStr),
+        icon: mapRunIcon(statusStr),
+      }],
     });
   }
   if (details.action === "status") {
-    return guiComponent("workflow-runs", {
-      runs: details.runs.map((r) => ({
-        runId: r.runId,
-        name: r.name,
-        status: r.status,
-        reason: r.reason,
-        error: r.error,
-      })),
+    return guiComponent("list-tree", {
+      items: details.runs.map((r) => {
+        const statusStr = r.reason ? `${r.status} (${r.reason})` : r.status;
+        return {
+          label: [r.name, r.slug, r.runId.slice(0, 8)].filter(Boolean).join(" "),
+          status: mapRunStatus(statusStr),
+          icon: mapRunIcon(statusStr),
+        };
+      }),
     });
   }
   // pause/resume/abort/retry-node/skip-node
+  // abort 是破坏性终止、pause 是挂起（非成功完成），用 warn 区分；resume/retry/skip 保留 ok
+  const severity = details.action === "abort" || details.action === "pause" ? "warn" as const : "ok" as const;
   return guiComponent("stats-line", {
     items: [{
       label: details.action,
       value: details.runId.slice(0, 8),
-      severity: "ok" as const,
+      severity,
     }],
   });
 }
@@ -200,6 +230,15 @@ export function registerWorkflowTool(
     promptSnippet: "Run, pause, resume, abort, or check workflow status",
     promptGuidelines: [
       "PRIORITY: When user says 'workflow', 'run workflow', try run action FIRST.",
+      "BUILT-IN workflows (ready to use, no script generation needed): " +
+      "chain (analyze→transform→synthesize sequential; args: task), " +
+      "parallel (multi-perspective analysis; args: target, optional perspectives), " +
+      "scatter-gather (split→parallel process→merge; args: task), " +
+      "map-reduce (parallel map→reduce; args: items/itemsJson + operation). " +
+      "Example: workflow run chain --args task=\"<description>\".",
+      "DISCOVERY: If unsure what workflows exist, call the workflow-script tool with " +
+      "action:list first — it returns all available scripts (built-in + user-generated) " +
+      "with source tags and descriptions. Then use this tool's run action to start one.",
       "run: discover by name/description, then start in background (no user confirmation needed).",
       "Do NOT poll status after starting — results appear automatically via notifyDone.",
       "retry-node/skip-node: for specific failed agent calls (requires runId + callId). " +
@@ -260,7 +299,7 @@ export function registerWorkflowTool(
         // GUI 协议：RPC 模式下附加 __gui__ 到 details
         return {
           ...result,
-          details: withGui(result.details, _ctx as GuiContext) as unknown as WorkflowToolDetails,
+          details: withGui(result.details, toGuiCtx(_ctx)),
         };
       } finally {
         releaseReentryGuard(reentryRef);
@@ -270,11 +309,16 @@ export function registerWorkflowTool(
     renderCall(args: Record<string, unknown>, theme: Theme, _context?: unknown) {
       const action = String(args.action ?? "");
       const name = args.name ? ` ${String(args.name)}` : "";
+      // run action 可选 slug：在 name 后追加 · slug（accent 色）
+      const slug = typeof args.slug === "string" && args.slug.trim()
+        ? `${theme.fg("dim", " · ")}${theme.fg("accent", String(args.slug))}`
+        : "";
       const runId = args.runId ? ` ${String(args.runId).slice(0, RUNID_SHORT)}` : "";
       return new Text(
         theme.fg("toolTitle", theme.bold("workflow ")) +
           theme.fg("muted", action) +
           theme.fg("accent", name) +
+          slug +
           theme.fg("dim", runId),
         0,
         0,
@@ -330,6 +374,7 @@ async function actionRun(
       budgetTokens: tokens,
       budgetTimeMs: time,
       scriptName: script.name,
+      slug: params.slug,
       scriptPath: script.path,
       description: script.meta.description,
     },
@@ -341,10 +386,12 @@ async function actionRun(
     content: [
       {
         type: "text",
-        text: `Started workflow '${script.name}' (${runId}). Running in background — do NOT poll status.`,
+        text: params.slug
+          ? `Started workflow '${script.name}' · ${params.slug} (${runId}). Running in background — do NOT poll status.`
+          : `Started workflow '${script.name}' (${runId}). Running in background — do NOT poll status.`,
       },
     ],
-    details: { action: "run", runId, status: "running", name: script.name },
+    details: { action: "run", runId, status: "running", name: script.name, slug: params.slug, stateFile: deps.store.stateFilePath(runId) },
   };
 }
 
@@ -358,7 +405,7 @@ function actionStatus(deps: LauncherDeps): ToolResult {
       details: { action: "status", runs: [] },
     };
   }
-  const summaries = runs.map(toRunSummary);
+  const summaries = runs.map((r) => toRunSummary(r, deps.store));
   const lines = summaries.map((s) => {
     const duration = s.startedAt ? ` (${formatElapsed(s.startedAt)})` : "";
     const reasonSuffix = s.reason && s.reason !== "completed" ? ` [${s.reason}]` : "";
@@ -383,7 +430,10 @@ async function actionLifecycle(
   }
   const run = deps.runs.get(runId);
   if (!run) {
-    return textResult(`Workflow '${runId}' not found`, true);
+    return textResult(
+      `Workflow '${runId}' not found. Use action:status to list active runs and their runIds.`,
+      true,
+    );
   }
   try {
     const oldStatus = run.state.status;
@@ -421,7 +471,10 @@ async function actionRetryNode(params: WorkflowToolParams, deps: LauncherDeps):
   }
   const run = deps.runs.get(runId);
   if (!run) {
-    return textResult(`Workflow '${runId}' not found`, true);
+    return textResult(
+      `Workflow '${runId}' not found. Use action:status to list active runs and their runIds.`,
+      true,
+    );
   }
   try {
     await retryNode(run, callId, deps);
@@ -445,7 +498,10 @@ async function actionSkipNode(params: WorkflowToolParams, deps: LauncherDeps): P
   }
   const run = deps.runs.get(runId);
   if (!run) {
-    return textResult(`Workflow '${runId}' not found`, true);
+    return textResult(
+      `Workflow '${runId}' not found. Use action:status to list active runs and their runIds.`,
+      true,
+    );
   }
   try {
     await skipNode(run, callId, deps);
@@ -464,15 +520,17 @@ async function actionSkipNode(params: WorkflowToolParams, deps: LauncherDeps): P
 // ── helpers ──────────────────────────────────────────────────
 
 /** WorkflowRun → 摘要（status action 用）。 */
-function toRunSummary(run: WorkflowRun): RunSummary {
+function toRunSummary(run: WorkflowRun, store: RunStore): RunSummary {
   return {
     runId: run.runId,
     name: run.spec.scriptName,
+    slug: run.spec.slug,
     status: run.state.status,
     reason: run.state.reason,
     startedAt: run.meta.startedAt,
     completedAt: run.meta.completedAt,
     error: run.state.error,
+    stateFile: store.stateFilePath(run.runId),
   };
 }
 

package/src/interface/views/WorkflowsView.ts

@@ -188,6 +188,7 @@ export function createWorkflowsView(
   theme: ThemeLike,
   ctx: ExtensionContext,
   actions: ViewActions,
+  runStateFile?: string,
 ): Promise<void> {
   return ctx.ui.custom<void>((_tui: unknown, _t: unknown, _kb: unknown, done: (result: void) => void) => {
     const state = createInitialState();
@@ -467,7 +468,7 @@ export function createWorkflowsView(
  // 缺陷 #1 修复：每次 render 从 run.state.trace 实时读（toArray 返回内部数组引用，
  // 后续 trace.append 会反映到 view），不再用 factory 时的冻结快照。
         const liveGroups = buildPhaseGroups([...run.state.trace.toArray()]);
-        const raw = renderLayout(run, state, liveGroups, theme, width, height);
+        const raw = renderLayout(run, state, liveGroups, theme, width, height, runStateFile);
  // Pad to terminal height so the overlay fills the screen (matches main 行为）
         const lines = raw.length < height
           ? [...raw, ...Array.from({ length: height - raw.length }, () => "")]
@@ -517,12 +518,13 @@ function renderLayout(
   theme: ThemeLike,
   screenWidth: number,
   screenHeight: number,
+  runStateFile?: string,
 ): string[] {
   const lines: string[] = [];
   const contentWidth = screenWidth - BOX_BORDER_CHARS;
   const mainWidth = contentWidth - SIDEBAR_WIDTH - 1; // -1 for the │ divider
 
-  renderHeader(lines, run, theme, contentWidth);
+  renderHeader(lines, run, theme, contentWidth, runStateFile);
 
   const phase = phaseGroups[state.phaseIdx] ?? phaseGroups[0];
   const agents = phase?.nodes ?? [];
@@ -564,12 +566,13 @@ function renderLayout(
   return lines;
 }
 
-/** Header：╭─╮ + name(bold) + 右侧 status/agents/elapsed/budget。 */
+/** Header：╭─╮ + name(bold) + 右侧 status/agents/elapsed/budget + 可选 state 路径行。 */
 function renderHeader(
   lines: string[],
   run: WorkflowRun,
   theme: ThemeLike,
   contentWidth: number,
+  runStateFile?: string,
 ): void {
   const traceArr = run.state.trace.toArray();
   const completed = traceArr.filter((n) => n.status === "completed").length;
@@ -579,7 +582,9 @@ function renderHeader(
   const budget = run.state.budget;
   const budgetStr = `${Math.round(budget.usedTokens / BUDGET_TOKENS_DIVISOR)}k/${budget.maxTokens ? `${Math.round(budget.maxTokens / BUDGET_TOKENS_DIVISOR)}k` : "∞"} tok · $${budget.usedCost.toFixed(BUDGET_COST_DECIMALS)}`;
 
-  const nameLine = theme.bold(run.spec.scriptName);
+  const nameLine = run.spec.slug
+    ? `${theme.bold(run.spec.scriptName)}${theme.fg("dim", " · ")}${theme.fg("accent", run.spec.slug)}`
+    : theme.bold(run.spec.scriptName);
   const rightPart = theme.fg("muted", `${headerRight} · ${budgetStr}`);
 
   lines.push(plainBorder(theme, "╭", "╮", contentWidth));
@@ -596,6 +601,10 @@ function renderHeader(
   } else {
     lines.push(walled(theme, rightPart, contentWidth));
   }
+  // run 状态快照文件路径（可选——无 store 注入时不渲染）
+  if (runStateFile) {
+    lines.push(walled(theme, theme.fg("dim", `state: ${runStateFile}`.slice(0, contentWidth)), contentWidth));
+  }
   lines.push(plainBorder(theme, "├", "┤", contentWidth));
 }