@zhushanwen/pi-subagent-workflow 0.1.0 → 0.2.0

package/agents/context-builder.md

@@ -2,8 +2,6 @@
 name: context-builder
 description: 需求分析与元提示生成
 tools: read
-extensions: false
-category: planning
 ---
 
 You are a context builder. Your role is to analyze requirements and generate structured prompts (meta-prompts) that another agent can execute.
@@ -14,4 +12,4 @@ Do not implement the task yourself. Your job is to produce a meta-prompt that ca
 
 Use absolute file paths only.
 
-**Output:** Produce a structured meta-prompt: objective, requirements (numbered), constraints, success criteria, and relevant file paths. Do not write implementation code — write the prompt that describes the work.
+**Output:** Produce a structured meta-prompt — a task description for another agent to execute. Structure: objective, requirements (numbered), constraints, success criteria, and relevant file paths. Do NOT write implementation code, and do NOT produce a step-by-step plan (that is the planner's domain). Write what needs to be done, not how to do it step by step.

package/agents/oracle.md

@@ -2,8 +2,6 @@
 name: oracle
 description: 高上下文决策一致性守护
 tools: read
-extensions: false
-category: planning
 ---
 
 You are a decision oracle. Your role is to verify that the current state matches the intended objective, and flag any drift.
@@ -12,6 +10,8 @@ Complete the verification fully — check every requirement in the objective aga
 
 Do not implement fixes yourself. Your job is to detect and report drift, not correct it.
 
+Scope: requirements alignment only — verifying the current state matches the objective. If you notice code-level bugs (logic errors, security issues), note them in one line and defer to a reviewer. Do not analyze the bug itself.
+
 Use absolute file paths only.
 
 **Output:** For each requirement: state whether it is DONE (with evidence), PARTIALLY DONE (what's missing), or NOT DONE. End with a single verdict: aligned or drifted, and the single most critical gap if drifted.

package/agents/planner.md

@@ -2,8 +2,6 @@
 name: planner
 description: 实施计划 agent
 tools: read
-extensions: false
-category: planning
 ---
 
 You are a planning agent. Your role is to break down tasks and create implementation plans.
@@ -14,4 +12,4 @@ Do not implement the plan yourself. Your job is to produce the plan, not execute
 
 Use absolute file paths only.
 
-**Output:** Provide a numbered, ordered implementation plan. Each step: what to do, which files it touches (absolute paths), and dependencies on prior steps. Do not write code — describe steps.
+**Output:** Provide a numbered, ordered implementation plan — an execution guide for a worker. Each step: what to do, which files it touches (absolute paths), and dependencies on prior steps. Do NOT write code, and do NOT produce a meta-prompt or requirements analysis (that is the context-builder's domain). Describe ordered steps, not objectives or constraints.

package/agents/researcher.md

@@ -2,8 +2,6 @@
 name: researcher
 description: 网络调研 agent
 tools: read, web_search
-extensions: false
-category: research
 ---
 
 You are a web researcher. Your role is to search, evaluate, and synthesize findings.

package/agents/reviewer.md

@@ -2,8 +2,6 @@
 name: reviewer
 description: 代码审查 agent（diff 分析、问题发现）
 tools: read
-extensions: false
-category: coding
 ---
 
 You are a code reviewer. Your role is to find bugs, logic errors, and security issues.
@@ -12,6 +10,8 @@ Complete the review fully — cover all files you were asked to review. Don't sk
 
 Do not fix issues yourself. Your job is to report them, not implement fixes.
 
+Scope: code-level issues only — bugs, logic errors, security vulnerabilities, performance problems. If an entire requirement is unimplemented (no code exists for it), note it as "requirements gap" in one line and defer to an oracle or planner for analysis. Do not analyze the gap itself.
+
 Use absolute file paths only.
 
 **Output:** For each issue found, report: severity (critical/major/minor), file path + line number, what the problem is, and why it matters. Do not narrate your review process.

package/agents/scout.md

@@ -2,15 +2,25 @@
 name: scout
 description: 快速代码库侦查
 tools: read, bash, grep
-extensions: false
-category: research
 ---
 
 You are a codebase recon agent. Your role is to explore structure and return compressed context.
 
 Complete the recon fully — cover the areas you were asked to explore. Don't stop after listing the top-level directory if the task asks for deeper structure.
 
-You are read-only. Do not modify, create, or delete files. Your bash access is for exploration only (`ls`, `cat`, `grep`, `find`, `wc`). Do not run commands that change state. If you need a command not listed here, say so — do not run unlisted commands.
+You are read-only — inspect, never mutate. Bash commands are restricted below:
+
+NEVER run (state-changing):
+- File writes/deletes: rm, mv, cp, touch, mkdir, chmod, chown
+- Git mutations: git add, git commit, git push, git reset, git checkout, git switch, git rebase, git merge, git stash, git clean
+- Package installs: npm install, npm ci, pnpm install, yarn install, pip install
+- Shell redirection to files: any command with `>` or `>>`
+- Network mutations: curl, wget (downloads create/modify files)
+- Process control: kill, pkill
+
+Free to run (read-only): ls, cat, head, tail, wc, tree, file, stat, grep, find, rg, git log, git diff, git show, git status, git branch (without -D), and pipes combining these.
+
+If unsure whether a command changes state, do NOT run it — report that you need it instead.
 
 Use absolute file paths only.
 

package/agents/worker.md

@@ -1,8 +1,6 @@
 ---
 name: worker
 description: 通用执行 agent（编码、修复、文件操作）
-extensions: true
-category: coding
 ---
 
 You are a coding agent. Your role is to implement, fix, and modify code precisely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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.",
@@ -21,7 +21,7 @@
     "index.ts",
     "agents/",
     "skills/",
-    "examples/",
+    "workflows/",
     "src/index.ts",
     "src/execution/",
     "src/orchestration/",
@@ -39,7 +39,9 @@
       "./agents"
     ]
   },
-  "dependencies": {},
+  "dependencies": {
+    "@xyz-agent/extension-protocol": "^0.2.0"
+  },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-ai": "*",

package/skills/workflow-script-format/SKILL.md

@@ -112,8 +112,8 @@ const final = await pipeline([
 // 对每个 file 依次跑 review → fix
 await pipeline(
   files,                                      // items
-  (file) => agent({ prompt: `Review ${file}`, description: `review-${file}`, schema: {...} }),
-  (review, file) => agent({ prompt: `Fix ${file}: ${JSON.stringify(review)}`, description: `fix-${file}` }),
+  (file) => agent({ prompt: `Review ${file}`, description: 'review', schema: {...} }),
+  (review, file) => agent({ prompt: `Fix ${file}: ${JSON.stringify(review)}`, description: 'fix' }),
 );
 // stage 函数签名：(prevResult, currentItem) => result；第一个 stage 只收 currentItem
 ```
@@ -158,7 +158,7 @@ const results = await parallel(
 );
 ```
 
-> 完整模式模板（chain / parallel / scatter-gather / map-reduce，含 `meta` + `$ARGS` + try-catch 错误处理）见 `extensions/subagent-workflow/examples/`。本段教 API，examples 教模式。
+> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
 
 ### Other globals
 
@@ -224,7 +224,7 @@ while (round < MAX_ROUNDS) {
       },
       required: ['mustFix'],
     },
-    description: `review-${round}`,
+    description: 'review',
   });
 
   // result is already a parsed object thanks to schema
@@ -286,7 +286,7 @@ const review = await agent({
     },
     required: ['findings'],
   },
-  description: `review-${file}`,
+  description: 'review',
 });
 
 const verify = await agent({
@@ -301,7 +301,7 @@ Did the review cover: (1) all functions in the file, (2) at least 3 potential is
     },
     required: ['valid'],
   },
-  description: `verify-review-${file}`,
+  description: 'verify-review',
 });
 
 if (!verify.valid) {

package/src/execution/__tests__/agent-result-mapper.test.ts

@@ -33,6 +33,23 @@ describe("mapToWorkflowAgentResult (D-A10)", () => {
     expect(result.toolCalls).toEqual([]);
   });
 
+  // ── sessionFile 透传（方案 A：让 workflow 继承 subagent 的 session jsonl 路径）──
+
+  it("映射 sessionFile: subagents AgentResult.sessionFile → workflow AgentResult.sessionFile 透传", () => {
+    const r: SubagentsAgentResult = {
+      ...minimalResult,
+      sessionFile: "/abs/path/.pi/agent/subagents/enc/sessions/2026-07-15T10-00-00-000Z_session-123.jsonl",
+    };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.sessionFile).toBe("/abs/path/.pi/agent/subagents/enc/sessions/2026-07-15T10-00-00-000Z_session-123.jsonl");
+  });
+
+  it("映射 sessionFile: 无 sessionFile → workflow AgentResult.sessionFile undefined（窗口期/未回填）", () => {
+    const r: SubagentsAgentResult = { ...minimalResult, sessionFile: undefined };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.sessionFile).toBeUndefined();
+  });
+
   it("映射 parsedOutput 透传（structured-output 契约 BC-8）", () => {
     const parsedData = { score: 0.95, label: "positive" };
     const r: SubagentsAgentResult = { ...minimalResult, parsedOutput: parsedData };
@@ -49,10 +66,15 @@ describe("mapToWorkflowAgentResult (D-A10)", () => {
     expect(result.content).toBe("Hello"); // content 仍保留（可能有部分输出）
   });
 
-  it("映射失败: success=false 但无 error → error=undefined", () => {
+  it("映射失败: success=false 但无 error（abort 路径）→ error 填入 fallback 而非 undefined", () => {
+    // H4: session-runner.ts abort 时 success=false, error=undefined。
+    // 旧代码 error=undefined → executeAgentCall 误判 completed。
+    // 修复后应 synthesize fallback error。
     const r: SubagentsAgentResult = { ...minimalResult, success: false };
     const result = mapToWorkflowAgentResult(r);
-    expect(result.error).toBeUndefined();
+    expect(result.error).toBeDefined();
+    expect(typeof result.error).toBe("string");
+    expect(result.error.length).toBeGreaterThan(0);
   });
 
   it("映射成功: success=true 且 error 存在 → error=undefined（不误填）", () => {

package/src/execution/__tests__/concurrency-pool.test.ts

@@ -214,4 +214,37 @@ describe("DefaultConcurrencyPool", () => {
       expect(negative.maxConcurrent).toBe(1);
     });
   });
+
+  // ============================================================
+  // H2: acquire 支持 AbortSignal — abort 时排队条目 reject
+  // ============================================================
+  describe("H2 abort support for acquire", () => {
+    it("abort signal rejects queued acquire with AbortError", async () => {
+      const pool = new DefaultConcurrencyPool(1);
+      await pool.acquire(0); // 占满
+
+      const controller = new AbortController();
+      const queued = pool.acquire(0, undefined, controller.signal);
+
+      await new Promise((r) => setTimeout(r, 5));
+      expect(pool.active).toBe(1); // 仍在排队
+
+      controller.abort();
+
+      await expect(queued).rejects.toThrow("aborted");
+    });
+
+    it("non-aborted acquire still resolves normally after release", async () => {
+      const pool = new DefaultConcurrencyPool(1);
+      await pool.acquire(0); // 占满
+
+      const controller = new AbortController();
+      const queued = pool.acquire(0, undefined, controller.signal);
+
+      pool.release(); // 释放 → queued 应被 resolve
+      await queued;   // 不应 reject
+      expect(pool.active).toBe(1);
+      pool.release();
+    });
+  });
 });

package/src/execution/__tests__/execute-options-mapper.test.ts

@@ -45,22 +45,39 @@ describe("mapToExecuteOptions (D-A2)", () => {
     expect((result as unknown as { schemaEnv?: string }).schemaEnv).toBeUndefined();
   });
 
-  it("T3.5 model 填底: opts.model 优先", () => {
+  it("T3.5 model: opts.model 优先（显式 override 透传，不与 ctxModel 混合）", () => {
     const opts: AgentCallOpts = { ...baseOpts, model: "explicit-model" };
     const ctxModel: ModelInfo = { id: "ctx-model", provider: "test", input: [] } as ModelInfo;
     const result = mapToExecuteOptions(opts, ctxModel);
     expect(result.model).toBe("explicit-model");
   });
 
-  it("T3.5 model 填底: opts.model 空 → ctxModel (D-008)", () => {
+  it("T3.5 model: opts.model 空 → model undefined（不再从 ctxModel.id 填底）", () => {
     const ctxModel: ModelInfo = { id: "ctx-model", provider: "test", input: [] } as ModelInfo;
     const result = mapToExecuteOptions(baseOpts, ctxModel);
-    expect(result.model).toBe("ctx-model");
+    expect(result.model).toBeUndefined();
+  });
+
+  it("T3.5 ctxModel 透传: opts.model 空时 ctxModel 作为完整 ModelInfo 对象传入 ExecuteOptions.ctxModel", () => {
+    const ctxModel: ModelInfo = { id: "mimo-v2.5-pro", provider: "router-openai", input: [] } as ModelInfo;
+    const result = mapToExecuteOptions(baseOpts, ctxModel);
+    expect(result.ctxModel).toBe(ctxModel);
+    expect(result.ctxModel?.id).toBe("mimo-v2.5-pro");
+    expect(result.ctxModel?.provider).toBe("router-openai");
+  });
+
+  it("T3.5 ctxModel 透传: opts.model 有值时 ctxModel 仍透传（双层可用）", () => {
+    const opts: AgentCallOpts = { ...baseOpts, model: "explicit-model" };
+    const ctxModel: ModelInfo = { id: "ctx-model", provider: "test", input: [] } as ModelInfo;
+    const result = mapToExecuteOptions(opts, ctxModel);
+    expect(result.model).toBe("explicit-model");
+    expect(result.ctxModel).toBe(ctxModel);
   });
 
-  it("T3.5 model 填底: opts.model 空且 ctxModel 空 → model undefined", () => {
+  it("T3.5 ctxModel: 两层均空 → model/ctxModel 都 undefined", () => {
     const result = mapToExecuteOptions(baseOpts);
     expect(result.model).toBeUndefined();
+    expect(result.ctxModel).toBeUndefined();
   });
 
   it("skillPath 透传", () => {
@@ -68,11 +85,26 @@ describe("mapToExecuteOptions (D-A2)", () => {
     expect(result.skillPath).toBe("/path/to/skill.md");
   });
 
-  it("忽略 systemPromptFiles（不映射到 ExecuteOptions）", () => {
-    const opts: AgentCallOpts = { ...baseOpts, systemPromptFiles: ["/tmp/a.txt"] };
+  it("thinkingLevel 透传 (M1)", () => {
+    const opts: AgentCallOpts = { ...baseOpts, thinkingLevel: "high" };
     const result = mapToExecuteOptions(opts);
-    // systemPromptFiles 不应在 ExecuteOptions 中出现
-    expect((result as Record<string, unknown>).appendSystemPrompt).toBeUndefined();
+    expect(result.thinkingLevel).toBe("high");
+  });
+
+  it("thinkingLevel 不传 → thinkingLevel undefined", () => {
+    const result = mapToExecuteOptions(baseOpts);
+    expect(result.thinkingLevel).toBeUndefined();
+  });
+
+  it("systemPromptFiles → appendSystemPrompt 映射 (M2)", () => {
+    const opts: AgentCallOpts = { ...baseOpts, systemPromptFiles: ["/tmp/a.md"] };
+    const result = mapToExecuteOptions(opts);
+    expect(result.appendSystemPrompt).toEqual(["/tmp/a.md"]);
+  });
+
+  it("systemPromptFiles 不传 → appendSystemPrompt undefined", () => {
+    const result = mapToExecuteOptions(baseOpts);
+    expect(result.appendSystemPrompt).toBeUndefined();
   });
 });
 

package/src/execution/__tests__/gui-mode-dispatch.test.ts

@@ -0,0 +1,60 @@
+// src/__tests__/gui-mode-dispatch.test.ts
+//
+// S6: ctx.mode RPC 分发契约测试。
+//
+// 审查发现：sdk-contract.test.ts 只测 ctx.model 透传，未覆盖 ctx.mode === "rpc"
+// 时 __gui__ 被填充、ctx.mode === "tui" 时不填充的 GUI 通道分发。
+//
+// adapter() 是纯函数，ctx.mode === "rpc" → details.__gui__ 被附加，
+// ctx.mode === "tui"/"json"/"print" → details.__gui__ 为 undefined。
+
+import { describe, expect, it } from "vitest";
+
+import type { GuiContext } from "@xyz-agent/extension-protocol";
+
+import { adapter } from "../../interface/subagent-actions.ts";
+import type { AdapterInput } from "../../interface/subagent-actions.ts";
+
+function makeStartInput(): AdapterInput {
+	return {
+		action: "start",
+		domain: {
+			subagentId: "test-id",
+			sessionFile: "/test/session.jsonl",
+			slug: "test-slug",
+			response: { status: "started" },
+		},
+	} as unknown as AdapterInput;
+}
+
+describe("S6: ctx.mode dispatches __gui__ output correctly", () => {
+	it("ctx.mode=rpc → details.__gui__ is populated", () => {
+		const ctx = { mode: "rpc", hasUI: true } as GuiContext;
+		const result = adapter(makeStartInput(), ctx);
+		expect(result.details).toHaveProperty("__gui__");
+		expect(result.details.__gui__).toBeDefined();
+	});
+
+	it("ctx.mode=tui → details.__gui__ is undefined (TUI renders differently)", () => {
+		const ctx = { mode: "tui", hasUI: true } as GuiContext;
+		const result = adapter(makeStartInput(), ctx);
+		expect(result.details.__gui__).toBeUndefined();
+	});
+
+	it("ctx.mode=json → details.__gui__ is undefined (headless)", () => {
+		const ctx = { mode: "json", hasUI: false } as GuiContext;
+		const result = adapter(makeStartInput(), ctx);
+		expect(result.details.__gui__).toBeUndefined();
+	});
+
+	it("ctx.mode=print → details.__gui__ is undefined (headless)", () => {
+		const ctx = { mode: "print", hasUI: false } as GuiContext;
+		const result = adapter(makeStartInput(), ctx);
+		expect(result.details.__gui__).toBeUndefined();
+	});
+
+	it("ctx=undefined → details.__gui__ is undefined (backward compat)", () => {
+		const result = adapter(makeStartInput(), undefined);
+		expect(result.details.__gui__).toBeUndefined();
+	});
+});

package/src/execution/__tests__/sdk-contract.test.ts

@@ -174,13 +174,14 @@ describe("subagent tool contract [MANDATORY]", () => {
       mode: "background",
       subagentId: "bg-test",
       sessionFile: "/test/session.jsonl",
+      details: { slug: "test-slug" },
     });
     const ctxModel = { id: "test-model", name: "Test", provider: "test", reasoning: false };
     const ctx = { model: ctxModel } as object;
 
     await capturedExecute!(
       "call-1",
-      { action: "start", startParam: { task: "test task" } },
+      { action: "start", startParam: { task: "test task", slug: "test-slug" } },
       undefined,
       undefined,
       ctx,
@@ -188,7 +189,7 @@ describe("subagent tool contract [MANDATORY]", () => {
 
     expect(mockServiceExecute).toHaveBeenCalledTimes(1);
     expect(mockServiceExecute).toHaveBeenCalledWith(
-      expect.objectContaining({ ctxModel }),
+      expect.objectContaining({ ctxModel, slug: "test-slug" }),
     );
   });
 
@@ -212,6 +213,7 @@ describe("subagent tool contract [MANDATORY]", () => {
       mode: "background",
       subagentId: "bg-fork-wt",
       sessionFile: "/test/session.jsonl",
+      details: { slug: "iso-work" },
     });
 
     await capturedExecute!(
@@ -220,6 +222,7 @@ describe("subagent tool contract [MANDATORY]", () => {
         action: "start",
         startParam: {
           task: "isolated work",
+          slug: "iso-work",
           fork: true,
           worktree: true,
           cwd: "/x",

package/src/execution/__tests__/session-reconstructor.test.ts

@@ -167,6 +167,26 @@ describe("reconstructFromFile", () => {
       expect(rec!.rootSessionId).toBeUndefined();
     });
 
+    it("读出 identity 里的 slug", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", slug: "extract-urls", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.slug).toBe("extract-urls");
+    });
+
+    it("旧文件 identity 无 slug → 兜底空串（向后兼容）", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.slug).toBe("");
+    });
+
     it("读出 identity 里的 parentRecordId/depth（递归层级）", () => {
       writeJsonl([
         headerLine(),

package/src/execution/__tests__/subagent-service-abort.test.ts

@@ -0,0 +1,60 @@
+// src/__tests__/subagent-service-abort.test.ts
+//
+// S4: subagent-service abort 终态一致性测试。
+//
+// 审查发现：排队中被 abort（pool.acquire reject）走 finalizeFailed（status=failed），
+// 而已运行中被 abort 走 cancelled。同一用户 abort 因时机不同产生两种终态。
+//
+// 修复后：pool reject 的 error 带 name="AbortError"，runAndFinalize catch 判断
+// signal?.aborted 走 cancelled 路径。
+//
+// 本文件覆盖两层：
+//   1. pool 层：acquire reject 的 error.name 是 "AbortError"（S1 前半）
+//   2. pool 层：pre-aborted signal 也带 AbortError name（S1 另一处）
+
+import { describe, expect, it } from "vitest";
+
+import { DefaultConcurrencyPool } from "../concurrency-pool.ts";
+
+describe("S1: ConcurrencyPool abort reject produces AbortError name", () => {
+	it("queued acquire aborted via signal rejects with error.name=AbortError", async () => {
+		const pool = new DefaultConcurrencyPool(1);
+		await pool.acquire(0); // 占满
+
+		const controller = new AbortController();
+		const queued = pool.acquire(0, undefined, controller.signal);
+
+		await new Promise((r) => setTimeout(r, 5));
+		expect(pool.active).toBe(1); // 仍在排队
+
+		controller.abort();
+
+		try {
+			await queued;
+			expect.unreachable("should have rejected");
+		} catch (err) {
+			expect(err).toBeInstanceOf(Error);
+			expect((err as Error).name).toBe("AbortError");
+			expect((err as Error).message).toContain("abort");
+		}
+		pool.release();
+	});
+
+	it("pre-aborted signal rejects immediately with error.name=AbortError", async () => {
+		const pool = new DefaultConcurrencyPool(1);
+		await pool.acquire(0); // 占满
+
+		const controller = new AbortController();
+		controller.abort(); // 先 abort 再 acquire
+
+		try {
+			await pool.acquire(0, undefined, controller.signal);
+			expect.unreachable("should have rejected");
+		} catch (err) {
+			expect(err).toBeInstanceOf(Error);
+			expect((err as Error).name).toBe("AbortError");
+			expect((err as Error).message).toContain("abort");
+		}
+		pool.release();
+	});
+});

package/src/execution/__tests__/subprocess-agent-runner.test.ts

@@ -15,9 +15,9 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
-import type { SubprocessAgentRunnerDeps } from "../subprocess-agent-runner.ts";
 import type { AgentCallOpts, AgentResult } from "../../orchestration/models/types.ts";
+import type { SubprocessAgentRunnerDeps } from "../subprocess-agent-runner.ts";
+import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
 
 // ── 测试辅助 ──
 
@@ -42,6 +42,7 @@ function createMockService(impl?: typeof vi.fn) {
       opts: Record<string, unknown>,
       signal?: AbortSignal,
       onEvent?: (e: Record<string, unknown>) => void,
+      stream?: unknown,
     ) => Promise<AgentResult>;
   };
 }
@@ -175,7 +176,37 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
       const opts = { ...makeBaseOpts(), model: undefined };
       await sar.run(opts, new AbortController().signal);
 
-      expect(capturedOpts!.model).toBe("ctx-model");
+      // 修复后：opts.model 不再从 ctxModel.id 填底，ctxModel 作为完整对象透传
+      expect(capturedOpts!.model).toBeUndefined();
+      expect(capturedOpts!.ctxModel).toBe(ctxModel);
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // H1: SAR ctxModel 刷新（model_select 后不再 stale）
+  // ────────────────────────────────────────────────
+  describe("H1 ctxModel refresh via updateCtxModel", () => {
+    it("updateCtxModel 后 run() 传入新的 ctxModel 而非旧值", async () => {
+      let capturedOpts: Record<string, unknown> | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
+          capturedOpts = opts;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const oldModel = { id: "old-model", provider: "test", input: [] };
+      const newModel = { id: "new-model", provider: "test", input: [] };
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService, ctxModel: oldModel };
+      const sar = new SubprocessAgentRunner(deps);
+
+      // 模拟 model_select：刷新 ctxModel
+      sar.updateCtxModel(newModel);
+
+      const opts = { ...makeBaseOpts(), model: undefined };
+      await sar.run(opts, new AbortController().signal);
+
+      expect(capturedOpts!.ctxModel).toBe(newModel);
+      expect(capturedOpts!.ctxModel).not.toBe(oldModel);
     });
   });
 
@@ -386,4 +417,42 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
       expect(result.error).toBe("raw string error");
     });
   });
+
+  // ────────────────────────────────────────────────
+  // U1: stream 透传给 executeAndAwait
+  // ────────────────────────────────────────────────
+  describe("U1 stream 透传", () => {
+    it("SAR.run 传 stream → executeAndAwait 第 4 参收到同一 stream 对象", async () => {
+      let capturedStream: unknown;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((_opts, _sig, _onEvt, stream) => {
+          capturedStream = stream;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const fakeStream = { onDelta: vi.fn(), dispose: vi.fn() };
+      await sar.run(makeBaseOpts(), new AbortController().signal, undefined, fakeStream as never);
+
+      expect(capturedStream).toBe(fakeStream);
+    });
+
+    it("SAR.run 不传 stream → executeAndAwait 第 4 参为 undefined", async () => {
+      let capturedStream: unknown = "sentinel";
+      const mockService = createMockService(
+        vi.fn().mockImplementation((_opts, _sig, _onEvt, stream) => {
+          capturedStream = stream;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      await sar.run(makeBaseOpts(), new AbortController().signal);
+
+      expect(capturedStream).toBeUndefined();
+    });
+  });
 });