@zhushanwen/pi-subagent-workflow 8.14.7 → 9.0.1

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

@@ -12,18 +12,18 @@
  * - 三 handler 自管缓存生命周期（不耦合 index.ts session 逻辑）：
  *   session_start（含 reload）发现+覆盖缓存（刷新节奏对齐 pi skill，fail-safe 异常
  *   不阻断、缓存保持 null）；before_agent_start 读缓存渲染注入、miss（session_start
- *   未触发/缓存被清）则 fallback 重新发现+赋值，空列表/空注入不返回 systemPrompt，
- *   任何异常被吞掉（记日志）不阻断 agent turn；session_shutdown 清缓存。
+ *   未触发/缓存被清）则 fallback 重新发现+赋值，空发现渲染空态段（D4-2：(none
+ *   discovered; roots: ...)，不再整段消失；invalids 随段具名呈现——D4-3 损坏文件
+ *   不静默），任何异常被吞掉（记日志）不阻断 agent turn；session_shutdown 清缓存。
  *   pi 支持 async handler，同一 event 多 handler 链式（前者返回的 systemPrompt 作
  *   后者输入）。
  *
  * 两实例的真差异经 config 参数化承载：kind（发现种类 + discoveryRoots 宿主槽位）/
  * parse（单文件内容 → entry；workflow 侧 description 截断内聚于其 parse）/ format
  * （entries → XML 注入段；guide 文案差异内聚于各自 format）/ includeTmp（workflow 侧
- * 覆盖 .pi/workflows/.tmp/ generate 产物）/ onParseNull（agent 侧「有 frontmatter 但
- * 解析失败」warn 判据）/ logTag（错误日志前缀，保持既有可检索性）；assemble（agent
- * 侧真差异：装配循环覆写——U11 下沉 core discoverAgents 后工厂不重复装配语义，
- * parse/onParseNull 不参与）。
+ * 覆盖 .pi/workflows/.tmp/ generate 产物）/ logTag（错误日志前缀，保持既有可检索性）；
+ * assemble（agent 侧真差异：装配循环覆写——U11 下沉 core discoverAgents 后工厂不重复
+ * 装配语义，parse 不参与）。
  *
  * model-list-injector 不参与本工厂：数据源是 ModelRegistry 内存快照（真差异，无文件
  * 发现与缓存生命周期），见该文件头注释。
@@ -37,15 +37,19 @@ import type {
 	SessionShutdownEvent,
 	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
+
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import { getHostServices } from "@zhushanwen/subagent-core";
 
 import {
+	conventionRootDirs,
 	discoverResources,
 	findWorkspaceRoot,
+	formatEmptyResourceList,
 	getCachedParsed,
 	sortByCodepoint,
+	type InvalidResource,
 } from "@zhushanwen/subagent-core";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
@@ -57,6 +61,13 @@ export interface ResourceListEntry {
 	path: string;
 }
 
+/** discover 产物（P5 D4-3）：entries = 可用条目；invalids = 损坏文件具名上报
+ *  （三处静默点收敛：available=false 占位 / meta 解析失败 / 文件读失败）。 */
+export interface ResourceDiscoveryResult<TEntry extends ResourceListEntry> {
+	entries: TEntry[];
+	invalids: InvalidResource[];
+}
+
 /** 工厂参数（真差异承载面，见文件头）。 */
 export interface ResourceListInjectorConfig<TEntry extends ResourceListEntry> {
 	/** 发现种类（discoverResources kind + discoveryRoots 宿主槽位）。 */
@@ -67,23 +78,26 @@ export interface ResourceListInjectorConfig<TEntry extends ResourceListEntry> {
 	 * 装配循环覆写：提供时工厂 discover 整体委托它（发现→解析→去重→排序 +
 	 * warn/error 口径全归被委托方），工厂不再跑内置装配循环。agent 侧真差异：
 	 * U11（sink 设计）装配算法单源 core discoverAgents（第三宿主免复刻 G3/S5），
-	 * 壳侧收缩为「宿主注入根现取 + 委托」。此时 parse/onParseNull 不参与工厂装配。
+	 * 壳侧收缩为「宿主注入根现取 + 委托」。此时 parse 不参与工厂装配，
+	 * invalids 恒空（core discoverAgents 无 invalid 产出面）。
 	 */
 	assemble?: (workspaceRoot: string) => Promise<TEntry[]>;
-	/** 单文件内容 → entry；null = 跳过该文件（无有效 frontmatter/meta）。assemble 覆写时不需要。 */
+	/** 单文件内容 → entry；null = 损坏文件（invalid 具名上报，D4-3）。assemble 覆写时不需要。 */
 	parse?(content: string): TEntry | null;
-	/** entry 列表 → 注入段；空列表返回空串（不注入）。 */
-	format(entries: TEntry[]): string;
+	/**
+	 * entry 列表 → 注入段；返回空串 = 空发现（工厂接管渲染 D4-2 空态段，invalids
+	 * 随空态段具名呈现）。第二参 = invalid 具名上报（P5 D4-3），段内渲染点由
+	 * 实例的 format 决定（workflow 实例透传 core formatWorkflowList 的 invalids 选项）。
+	 */
+	format(entries: TEntry[], invalids: readonly InvalidResource[]): string;
 	/** workflow 侧真差异：包含 .pi/workflows/.tmp/（workflow-script generate 产物）。 */
 	includeTmp?: boolean;
-	/** parse 返 null 的旁路处理（agent 侧真差异：仅「有 frontmatter 但解析失败」warn）。 */
-	onParseNull?(filePath: string): void;
 }
 
 /** 工厂产物：setup 注册三 handler；discover 为发现函数（薄模块再导出）。 */
 export interface ResourceListInjector<TEntry extends ResourceListEntry> {
 	setup(pi: ExtensionAPI): void;
-	discover(workspaceRoot: string): Promise<TEntry[]>;
+	discover(workspaceRoot: string): Promise<ResourceDiscoveryResult<TEntry>>;
 }
 
 /** 码点序排序契约见 core sortByCodepoint（KV-cache 契约：禁 localeCompare——宿主 locale 差异会破坏跨环境字节一致）。 */
@@ -93,36 +107,81 @@ function singularKind(kind: "agents" | "workflows"): string {
 	return kind === "agents" ? "agent" : "workflow";
 }
 
+/**
+ * 空态注入（D4-2）渲染的发现根清单：宿主注入根（discoveryRoots 槽，现取——
+ * 实例隔离语义同 discover）+ core 约定根推导（conventionRootDirs 单源，含
+ * includeTmp 的 .tmp 根）——本函数只做纯投影，不持有任何 join 字面。
+ * TAIJI_EXTENSION_PATHS 刻意不列——taiji 内部 dev-link 通道，非 agent 自救面。
+ * 清单是给 agent 的提示信息：顺序无优先级契约，保序去重由渲染函数保证
+ * （同 turn 重建字节稳定，KV-cache 契约）。
+ */
+function discoveryRootDirs(
+	workspaceRoot: string,
+	kind: "agents" | "workflows",
+	includeTmp: boolean,
+): string[] {
+	const hostRoots = getHostServices().discoveryRoots?.()?.[kind] ?? [];
+	const roots = hostRoots.map((root) => root.dir);
+	roots.push(...conventionRootDirs({ kind, workspaceRoot, includeTmp }));
+	return roots;
+}
+
 export function createResourceListInjector<TEntry extends ResourceListEntry>(
 	config: ResourceListInjectorConfig<TEntry>,
 ): ResourceListInjector<TEntry> {
-	let entriesCache: TEntry[] | null = null;
+	let discoveryCache: ResourceDiscoveryResult<TEntry> | null = null;
 	let injectionCache: string | null = null;
 
-	/** 缓存唯一写点：数据与渲染缓存同步更新（null 清空两者）。 */
-	function setCache(entries: TEntry[] | null): void {
-		entriesCache = entries;
-		injectionCache = entries !== null ? config.format(entries) : null;
+	/**
+	 * 缓存唯一写点：数据与渲染缓存同步更新（null 清空两者，此时 workspaceRoot
+	 * 不消费）。空发现（format 返回空串——core formatXxxList 空列表的判据契约）
+	 * 不再让注入段整段消失，改渲染空态段（D4-2）：agent 可区分「功能关闭」与
+	 * 「确实没有」，roots 清单供自救；invalids 随空态段具名呈现（D4-3——条目为零
+	 * 与存在损坏文件两个事实同段）。非空路径 format 输出原样缓存（invalids 缺省
+	 * 逐字节零变更）。
+	 */
+	function setCache(
+		result: ResourceDiscoveryResult<TEntry> | null,
+		workspaceRoot: string,
+	): void {
+		discoveryCache = result;
+		if (result === null) {
+			injectionCache = null;
+			return;
+		}
+		const rendered = config.format(result.entries, result.invalids);
+		injectionCache = rendered !== ""
+			? rendered
+			: formatEmptyResourceList(
+					config.kind,
+					discoveryRootDirs(workspaceRoot, config.kind, config.includeTmp === true),
+					result.invalids,
+				);
 	}
 
 	/**
 	 * 用统一资源发现（ADR-031）发现所有可用条目。永不抛错——发现本身 fail-safe，
-	 * 单个文件读失败仅记日志。
+	 * 单个文件读失败仅记日志（并 invalid 具名上报，不静默）。
 	 *
-	 * assemble 覆写时整体委托（agent 侧：core discoverAgents 单源装配，U11）；
-	 * 否则跑内置装配循环——
+	 * assemble 覆写时整体委托（agent 侧：core discoverAgents 单源装配，U11；
+	 * invalids 恒空）；否则跑内置装配循环——
 	 * discoverResources 返回按文件名 stem 去重、优先级合并后的 DiscoveredResource[]
 	 * （project > user > builtin，返回顺序低→高优先级——Map 后写覆盖依赖此序，不可在
 	 * 发现层重排）。此处逐个 parse 提取条目（经 getCachedParsed mtime 级缓存），再按
 	 * name 去重（高优先级靠后，Map.set 后者覆盖前者，故最终保留最高优先级同名条目）。
 	 *
+	 * invalid 收集（P5 D4-3，三处原静默点）：available=false 占位（manifest 声明
+	 * 路径缺失，reason 由发现层具名）/ parse null（文件在场但 meta 无效或缺失）/
+	 * 读失败（reason = 错误消息，日志照记）。损坏文件从此在注入段具名可见，
+	 * 不再静默跳过。
+	 *
 	 * 输出按 name 码点序排序（KV-cache 契约）：注入段进每 turn system prompt，顺序必须
 	 * 与文件系统枚举序（readdir 无契约）解耦——目录内容不变时，session_start / fallback /
 	 * resume 任意重建的渲染结果逐字节一致；仅条目增减时文本才变化。
 	 */
-	async function discover(workspaceRoot: string): Promise<TEntry[]> {
+	async function discover(workspaceRoot: string): Promise<ResourceDiscoveryResult<TEntry>> {
 		if (config.assemble) {
-			return config.assemble(workspaceRoot);
+			return { entries: await config.assemble(workspaceRoot), invalids: [] };
 		}
 		if (!config.parse) {
 			throw new Error(
@@ -139,24 +198,32 @@ export function createResourceListInjector<TEntry extends ResourceListEntry>(
 		});
 
 		const map = new Map<string, TEntry>();
+		const invalids: InvalidResource[] = [];
 		for (const resource of resources) {
-			if (!resource.available) continue;
+			if (!resource.available) {
+				invalids.push({
+					path: resource.path,
+					reason: resource.reason ?? "unavailable",
+				});
+				continue;
+			}
 			try {
 				const entry = getCachedParsed(resource.path, config.parse);
 				if (entry) {
 					map.set(entry.name, { ...entry, path: resource.path });
 				} else {
-					config.onParseNull?.(resource.path);
+					invalids.push({ path: resource.path, reason: "no valid resource metadata" });
 				}
 			} catch (err) {
-				// 单个文件读失败不阻断整条清单注入
+				// 单个文件读失败不阻断整条清单注入；具名上报（D4-3）+ 日志照记
+				invalids.push({ path: resource.path, reason: toErrorMessage(err) });
 				logger.error(
 					`${config.logTag} skip unreadable ${singularKind(config.kind)} file ${resource.path}`,
 					{ reason: toErrorMessage(err) },
 				);
 			}
 		}
-		return sortByCodepoint([...map.values()], (entry) => entry.name);
+		return { entries: sortByCodepoint([...map.values()], (entry) => entry.name), invalids };
 	}
 
 	function setup(pi: ExtensionAPI): void {
@@ -164,7 +231,8 @@ export function createResourceListInjector<TEntry extends ResourceListEntry>(
 			"session_start",
 			async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
 				try {
-					setCache(await discover(findWorkspaceRoot(ctx.cwd)));
+					const workspaceRoot = findWorkspaceRoot(ctx.cwd);
+					setCache(await discover(workspaceRoot), workspaceRoot);
 				} catch (err) {
 					// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
 					logger.error(`${config.logTag} session_start discover failed`, {
@@ -182,10 +250,12 @@ export function createResourceListInjector<TEntry extends ResourceListEntry>(
 			): Promise<BeforeAgentStartEventResult | void> => {
 				try {
 					// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
-					if (entriesCache === null) {
-						setCache(await discover(findWorkspaceRoot(ctx.cwd)));
+					if (discoveryCache === null) {
+						const workspaceRoot = findWorkspaceRoot(ctx.cwd);
+						setCache(await discover(workspaceRoot), workspaceRoot);
 					}
-					// injectionCache 与 entriesCache 不变量同步（setCache 保证），直接复用
+					// injectionCache 与 discoveryCache 不变量同步（setCache 保证），直接复用；
+					// 空串仅出现在「空发现且 roots 清单为空」的退化态（约定根恒在，实际不可达）
 					const injection = injectionCache;
 					if (!injection) return;
 					return { systemPrompt: event.systemPrompt + injection };
@@ -200,7 +270,8 @@ export function createResourceListInjector<TEntry extends ResourceListEntry>(
 		pi.on(
 			"session_shutdown",
 			(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
-				setCache(null);
+				// 清缓存：null 分支不消费 workspaceRoot（空态渲染仅在发现路径发生）
+				setCache(null, "");
 			},
 		);
 	}

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

@@ -29,7 +29,6 @@ import {
 	discoverAgents,
 	formatAgentList,
 	getHostServices,
-	parseResourceMeta,
 } from "@zhushanwen/subagent-core";
 
 import { createResourceListInjector } from "./resource-list-injector.ts";
@@ -46,38 +45,18 @@ import { createResourceListInjector } from "./resource-list-injector.ts";
 export const SUBAGENT_LIST_GUIDE =
 	"The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agents from this list — pass the <location> path (absolute .md path) as the agent param. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.";
 
-/**
- * 解析 markdown 文件的 YAML frontmatter（name + description）。
- *
- * m2 收敛：删本地单行 key:value parser，改调 shared/meta-parser.ts parseResourceMeta
- * （IF1 统一 parser，支持 block scalar）。无有效 frontmatter 或缺 name/description 返 null。
- * 投影 {name, description} 注入用（examples 注入留 m5）。
- *
- * U11 后装配循环（含本函数的装配内消费）单源 core discoverAgents；保留导出作为
- * 严格注入投影语义锚（parseResourceMeta 消费面）。
- */
-export function parseAgentFrontmatter(content: string): AgentEntry | null {
-	const meta = parseResourceMeta(content, "agent");
-	if (!meta || meta.kind !== "agent") return null;
-	return {
-		name: meta.name,
-		description: meta.description,
-		when: meta.when,
-		examples: meta.examples,
-		path: "", // 装配时由 core discoverAgents 从 DiscoveredResource.path 填充
-	};
-}
-
 /**
  * agent 清单实例：缓存生命周期 / 三 handler 经工厂骨架；装配循环经 assemble 覆写
- * 委托 core discoverAgents（U11 单源，parse/onParseNull 不参与工厂装配——warn 口径
+ * 委托 core discoverAgents（U11 单源，parse 不参与工厂装配——warn 口径
  * 内聚 core：仅「有 frontmatter 但严格校验未通过」才 warn，README 等无 frontmatter
  * 的 .md 静默跳过）。
  */
 const injector = createResourceListInjector<AgentEntry>({
 	kind: "agents",
 	logTag: "[subagent-list-injector]",
-	format: (agents) => formatAgentList(agents, { guide: SUBAGENT_LIST_GUIDE }),
+	// agents 段无 invalid 产出面（assemble 路径 invalids 恒空），第二参忽略——
+	// 签名对齐工厂 config.format（P5 D4-3 invalid 上报仅 workflow 域接线）。
+	format: (agents, _invalids) => formatAgentList(agents, { guide: SUBAGENT_LIST_GUIDE }),
 	assemble: (workspaceRoot) =>
 		discoverAgents(
 			workspaceRoot,
@@ -85,8 +64,5 @@ const injector = createResourceListInjector<AgentEntry>({
 		),
 });
 
-/** 发现所有可用 agent（装配骨架见工厂；装配算法单源 core discoverAgents，U11）。 */
-export const discoverAllAgents = injector.discover;
-
 /** 注册 session 生命周期 handler，注入 `<available_subagents>` 段（三 handler 语义见工厂）。 */
 export const setupSubagentListInjector = injector.setup;

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

@@ -25,6 +25,7 @@ import {
 	formatWorkflowList,
 	parseResourceMeta,
 	summarizeDescription,
+	type InvalidResource,
 	type WorkflowEntry,
 } from "@zhushanwen/subagent-core";
 
@@ -61,12 +62,15 @@ const injector = createResourceListInjector<WorkflowEntry>({
 	kind: "workflows",
 	logTag: "[workflow-list-injector]",
 	parse: parseWorkflowMeta,
-	format: (workflows) => formatWorkflowList(workflows, { guide: WORKFLOW_LIST_GUIDE }),
+	// invalids 透传 core 渲染（P5 D4-3 具名上报：条目段内 invalid 行；条目为零时
+	// 随工厂空态段呈现）。空数组不渲染（core 侧零字节变更）。
+	format: (workflows, invalids: readonly InvalidResource[]) =>
+		formatWorkflowList(workflows, {
+			guide: WORKFLOW_LIST_GUIDE,
+			...(invalids.length > 0 ? { invalids } : {}),
+		}),
 	includeTmp: true,
 });
 
-/** 用统一资源发现发现所有可用 workflow（includeTmp 覆盖 generate 产物；骨架与排序契约见工厂）。 */
-export const discoverAllWorkflows = injector.discover;
-
 /** 注册 session 生命周期 handler，注入 `<available_workflows>` 段（与 subagent 注入 handler 链式）。 */
 export const setupWorkflowListInjector = injector.setup;

package/src/interface/__tests__/capture-tool.ts

@@ -0,0 +1,56 @@
+/**
+ * 注册层黑盒测试共享捕获 helper：fake pi 收集 registerTool 入参，断言恰好注册
+ * 一个 tool（可锁定期望名）并返回首个。此前 7 个测试文件各自内联同构拷贝
+ * （fake pi + tools 数组 + name 断言 + CapturedTool 类型），收敛至此单点；
+ * 差异面（注册函数、pi 之后的实参、deps 形状）留在调用方闭包。
+ */
+
+/** 注册层捕获到的 tool 定义最小形态（各文件按需用泛型传窄 view 类型）。 */
+export interface CapturedTool {
+  name: string;
+  execute: (
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<unknown>;
+}
+
+/** workflow-script tool 的窄 view（list/lint 测试共用的 execute 返回形态）。 */
+export interface ScriptResultToolView extends CapturedTool { // oe-exempt:20260929:framework:测试 fixture 契约类型（mock 桩/断言视图）——dev-0.10.5 已验收代码 merge 带入
+  execute: (
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<{
+    content: Array<{ type: string; text: string }>;
+    details: unknown;
+    isError?: boolean;
+  }>;
+}
+
+/**
+ * 注册并捕获 tool 定义。泛型 T 供需要窄 execute 返回类型的调用方传 view
+ * 类型（方法参数双变 + 返回协变，窄形态天然 extends CapturedTool，零 cast）。
+ *
+ * @param register 拿 fake pi 执行注册（调用方闭包内传齐注册函数与其余实参）
+ * @param expectedName 期望的 tool 名（缺省不锁定——仅断言恰好注册一个）
+ */
+export function captureTool<T extends CapturedTool = CapturedTool>(
+  register: (pi: { registerTool: (tool: unknown) => void }) => void,
+  expectedName?: string,
+): T {
+  const tools: unknown[] = [];
+  register({ registerTool: (tool) => tools.push(tool) });
+  const first = tools[0] as T | undefined;
+  if (first === undefined || tools.length !== 1) {
+    throw new Error(`expected exactly one registered tool, got ${tools.length}`);
+  }
+  if (expectedName !== undefined && first.name !== expectedName) {
+    throw new Error(`expected registered tool '${expectedName}', got '${String(first.name)}'`);
+  }
+  return first;
+}

package/src/interface/__tests__/commands-resume.test.ts

@@ -0,0 +1,103 @@
+/**
+ * /workflows 命令的 resume 通道契约（workflow-run-resume-revision U3）。
+ *
+ * 覆盖面（TUI 模式）：/workflows resume <runId> → 执行断点续跑后 notify，不打开
+ * 面板；缺 runId → Usage 提示；resumeRun 拒绝 → warning notify 透出恢复指引文案。
+ *
+ * RPC 模式（taiji GUI）的 resume verb 接线未随 U3 落地：解析词表在
+ * command-actions.ts（领地外，resume verb 现仍解析为 lifecycle-removed），其
+ * dispatch 断言由 src/__tests__/rpc-command-handling.test.ts 原样锁定——词表
+ * 适配归编排层（见 commands.ts handleRpcMode 注释）。workflow tool 通道
+ * （action:"resume"，含 D14 args 校验）由 tool-workflow-resume.test.ts 覆盖。
+ *
+ * mock 策略：resume-run 深路径 stub（对齐 tool-workflow-resume.test.ts）；命令
+ * 注册层经 fake api 捕获 handler 后以 fake ctx 直接调用。
+ */
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+// 被 mock 的模块——import 路径与被测源文件的等值实例（对齐 tool-workflow-resume.test.ts）
+import { resumeRun } from "@zhushanwen/subagent-core/orchestration/resume-run.ts";
+
+import { registerWorkflowsCommand } from "../commands.ts";
+
+vi.mock("@zhushanwen/subagent-core/orchestration/resume-run.ts", () => ({
+  resumeRun: vi.fn(),
+}));
+
+// ── fixture ──────────────────────────────────────────────────
+
+interface CapturedCommand { // oe-exempt:20260929:test:test double shape for command capture (test infra)
+  name: string;
+  description: string;
+  handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+}
+
+/** 注册层捕获（对齐 capture-tool 形态：fake api 收集 registerCommand 入参）。 */
+function captureCommand(): CapturedCommand {
+  const commands: CapturedCommand[] = [];
+  const api = {
+    registerCommand: (name: string, def: Omit<CapturedCommand, "name">) => {
+      commands.push({ name, ...def });
+    },
+  };
+  registerWorkflowsCommand(
+    api as never,
+    () => new Map(),
+    { runs: new Map(), store: { stateFilePath: () => "/state/x" } } as never,
+  );
+  expect(commands).toHaveLength(1);
+  expect(commands[0]!.name).toBe("workflows");
+  return commands[0]!;
+}
+
+/** fake ctx：notify 收集 + mode 注入（TUI 分支的 theme/select 不触 resume 用例）。 */
+function makeCtx(mode: "rpc" | "tui"): { ctx: ExtensionCommandContext; notifies: Array<{ msg: string; level: string }> } {
+  const notifies: Array<{ msg: string; level: string }> = [];
+  const ctx = {
+    mode,
+    ui: {
+      notify: (msg: string, level: string) => notifies.push({ msg, level }),
+      theme: {},
+      select: vi.fn(),
+    },
+  };
+  return { ctx: ctx as never, notifies };
+}
+
+beforeEach(() => {
+  vi.mocked(resumeRun).mockReset();
+  vi.mocked(resumeRun).mockResolvedValue("wf-x");
+});
+
+// ── TUI 模式 ─────────────────────────────────────────────────
+
+describe("/workflows TUI resume", () => {
+  it("resume <runId> → resumeRun 接线 + notify（不打开面板）", async () => {
+    const cmd = captureCommand();
+    const { ctx, notifies } = makeCtx("tui");
+    await cmd.handler("resume wf-x", ctx);
+    expect(vi.mocked(resumeRun)).toHaveBeenCalledWith("wf-x", expect.anything());
+    expect(notifies).toHaveLength(1);
+    expect(notifies[0]!.msg).toContain("resuming");
+    expect(notifies[0]!.level).toBe("info");
+  });
+
+  it("resume 缺 runId → Usage warning", async () => {
+    const cmd = captureCommand();
+    const { ctx, notifies } = makeCtx("tui");
+    await cmd.handler("resume", ctx);
+    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
+    expect(notifies[0]).toMatchObject({ msg: "Usage: /workflows resume <runId>", level: "warning" });
+  });
+
+  it("resumeRun 拒绝 → warning notify（TUI 同款透出）", async () => {
+    vi.mocked(resumeRun).mockRejectedValue(new Error("Resume rejected: lock held"));
+    const cmd = captureCommand();
+    const { ctx, notifies } = makeCtx("tui");
+    await cmd.handler("resume wf-x", ctx);
+    expect(notifies[0]!.msg).toContain("Failed to resume workflow wf-x: Resume rejected: lock held");
+    expect(notifies[0]!.level).toBe("warning");
+  });
+});