magic-agent 1.0.46 → 1.0.108

package/internal/team/team_test.go

@@ -0,0 +1,1997 @@
+package team
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+/* 用例的边界：**不碰真引擎**。
+   计划解析、路由、分层并发、事件投影、落盘这些都用假引擎钉住 —— 它们才是团队模式
+   自己的逻辑。真引擎的可用性由 CLI 层的能力探测负责（另有测试），混在一起只会得到
+   一批「本机没装 claude 就红」的假红。 */
+
+// taskDocAnchor 任务书首行锚点，用来在假引擎收到的请求里认出「这是子任务」。
+// 不能只认「任务书」三个字：角色提示词里也会提到任务书。
+const taskDocAnchor = "# 任务书 ·"
+
+// fakeEngine 假引擎：按 prompt 里的关键词回不同的东西。
+type fakeEngine struct {
+	name string
+	// plan 计划阶段返回的正文（第一次调用）。
+	plan string
+	// task 子任务返回的正文（后续调用）。
+	task string
+	// taskSeq 子任务按调用次数依次返回的正文（用完后重复最后一个）。
+	// 用来模拟「第一次没交交接单、重试才补齐」。
+	taskSeq []string
+	// replan 再规划轮（adaptive）返回的正文；为空时回落到 task。
+	replan string
+	// failOn 命中该关键词就报错（模拟子任务失败）。
+	failOn string
+	// sessionID 引擎回报的自己的会话 id（团队模式要把它绑成主会话下的子会话）。
+	sessionID string
+	// writeFiles 每次子任务调用后写进工作目录的文件（模拟真的交出交付物）。
+	writeFiles []string
+	// writeFrom 从第几次子任务调用开始写 writeFiles（0/1 = 每次都写）。
+	// 用来模拟「第一次没交、重试才交」。
+	writeFrom int
+
+	mu    sync.Mutex
+	calls []agent.Request
+	taskN int
+}
+
+func (f *fakeEngine) Name() string             { return f.name }
+func (f *fakeEngine) Detect() (bool, string)   { return true, f.name }
+func (f *fakeEngine) CapabilityFamily() string { return f.name }
+func (f *fakeEngine) Complete(ctx context.Context, req agent.Request) (agent.Response, error) {
+	f.record(req)
+	return agent.Response{Engine: f.name, Text: f.reply(req)}, nil
+}
+
+func (f *fakeEngine) Stream(ctx context.Context, req agent.Request, onEvent func(agent.StreamEvent)) (agent.StreamResult, error) {
+	f.record(req)
+	text := f.reply(req)
+	if f.failOn != "" && strings.Contains(text, f.failOn) {
+		return agent.StreamResult{}, errFake
+	}
+	/* 真引擎的正文事件**不带** session_id（只有 init 行 / turn_end / ask 带），
+	   会话 id 走 OnSessionID 回调 —— 这里照实模拟，才能钉住「执行期每个子事件
+	   都带得上 sub_session_id」这条路径。 */
+	if f.sessionID != "" && req.OnSessionID != nil {
+		req.OnSessionID(f.sessionID)
+	}
+	onEvent(agent.StreamEvent{Kind: agent.KindText, Text: text})
+	return agent.StreamResult{Response: agent.Response{Engine: f.name, Text: text, SessionID: f.sessionID}}, nil
+}
+
+// record 记账，并在子任务调用后按配置落交付物（计划 / 汇总轮没有工作目录，不落）。
+func (f *fakeEngine) record(req agent.Request) {
+	f.mu.Lock()
+	f.calls = append(f.calls, req)
+	n := 0
+	if req.Workspace != "" {
+		f.taskN++
+		n = f.taskN
+	}
+	f.mu.Unlock()
+	if n == 0 || len(f.writeFiles) == 0 || (f.writeFrom > 1 && n < f.writeFrom) {
+		return
+	}
+	if err := os.MkdirAll(req.Workspace, 0o755); err != nil {
+		return
+	}
+	for _, name := range f.writeFiles {
+		_ = os.WriteFile(filepath.Join(req.Workspace, name), []byte("fake"), 0o644)
+	}
+}
+
+func (f *fakeEngine) reply(req agent.Request) string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	// 第一次调用是计划阶段，之后都是子任务 / 汇总。
+	if len(f.calls) <= 1 {
+		return f.plan
+	}
+	// 再规划轮：没有工作目录、系统提示词带 adaptiveMarker。必须先于 taskSeq 判断，
+	// 否则它会按「第 N 个子任务」取到错的内容（多出的调用还会把序列整体错位）。
+	if req.Workspace == "" && strings.Contains(req.SystemPrompt, adaptiveMarker) {
+		if f.replan != "" {
+			return f.replan
+		}
+		return f.plan
+	}
+	if len(f.taskSeq) > 0 {
+		i := len(f.calls) - 2
+		if i >= len(f.taskSeq) {
+			i = len(f.taskSeq) - 1
+		}
+		return f.taskSeq[i]
+	}
+	return f.task
+}
+
+func (f *fakeEngine) requests() []agent.Request {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	out := make([]agent.Request, len(f.calls))
+	copy(out, f.calls)
+	return out
+}
+
+type fakeErr string
+
+func (e fakeErr) Error() string { return string(e) }
+
+const errFake = fakeErr("fake engine failure")
+
+// install 把假引擎临时塞进注册表（Lookup 靠它解析路由）。
+func install(t *testing.T, engines ...agent.Engine) {
+	t.Helper()
+	for _, e := range engines {
+		agent.Register(e)
+	}
+}
+
+func newOpts(t *testing.T, eng agent.Engine, plan string) Options {
+	t.Helper()
+	return Options{
+		Engine:  eng,
+		Prompt:  "做一份带封面的介绍",
+		RunID:   "run-test",
+		BaseDir: t.TempDir(),
+	}
+}
+
+// taskSnapshots 把 KindTasks 事件按到达顺序解析成一份份任务行快照。
+// 快照语义：每份都是全量，取最后一份即当前状态。
+func taskSnapshots(events []agent.StreamEvent) [][]TaskRow {
+	var out [][]TaskRow
+	for _, ev := range events {
+		if ev.Kind != agent.KindTasks {
+			continue
+		}
+		var snap struct {
+			Tasks []TaskRow `json:"tasks"`
+		}
+		if err := json.Unmarshal([]byte(ev.Text), &snap); err != nil {
+			continue
+		}
+		out = append(out, snap.Tasks)
+	}
+	return out
+}
+
+// rowOf 在一份快照里按 id 找一行（找不到返回 nil）。
+func rowOf(rows []TaskRow, id string) *TaskRow {
+	for i := range rows {
+		if rows[i].ID == id {
+			return &rows[i]
+		}
+	}
+	return nil
+}
+
+func TestPlanValidate(t *testing.T) {
+	cases := []struct {
+		name string
+		plan Plan
+		ok   bool
+	}{
+		{"正常", Plan{Goal: "g", Tasks: []Task{{ID: "t1", Kind: KindText, Prompt: "p"}}}, true},
+		{"空任务", Plan{Goal: "g"}, false},
+		{"缺 id", Plan{Tasks: []Task{{Kind: KindText, Prompt: "p"}}}, false},
+		{"id 重复", Plan{Tasks: []Task{
+			{ID: "t1", Kind: KindText, Prompt: "p"},
+			{ID: "t1", Kind: KindText, Prompt: "p"},
+		}}, false},
+		// 认不出的类别降级为 text（NormalizeKind 既有语义），不整份作废。
+		{"类别认不出退 text", Plan{Tasks: []Task{{ID: "t1", Kind: "music", Prompt: "p"}}}, true},
+		{"缺 prompt", Plan{Tasks: []Task{{ID: "t1", Kind: KindText}}}, false},
+		{"依赖不存在", Plan{Tasks: []Task{
+			{ID: "t1", Kind: KindText, Prompt: "p", Deps: []string{"t9"}},
+		}}, false},
+		{"成环", Plan{Tasks: []Task{
+			{ID: "t1", Kind: KindText, Prompt: "p", Deps: []string{"t2"}},
+			{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}},
+		}}, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			err := c.plan.Validate()
+			if c.ok && err != nil {
+				t.Fatalf("应当通过，却报错：%v", err)
+			}
+			if !c.ok && err == nil {
+				t.Fatalf("应当报错，却通过了")
+			}
+		})
+	}
+}
+
+func TestPlanOrderLayers(t *testing.T) {
+	p := Plan{Tasks: []Task{
+		{ID: "t3", Kind: KindText, Prompt: "p", Deps: []string{"t1", "t2"}},
+		{ID: "t2", Kind: KindText, Prompt: "p"},
+		{ID: "t1", Kind: KindText, Prompt: "p"},
+	}}
+	layers, err := p.Order()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(layers) != 2 {
+		t.Fatalf("应当 2 层，得到 %d 层", len(layers))
+	}
+	if len(layers[0]) != 2 {
+		t.Fatalf("第一层应当 2 个任务（t1/t2），得到 %d", len(layers[0]))
+	}
+	// 层内按 id 排，输出稳定。
+	if layers[0][0].ID != "t1" || layers[0][1].ID != "t2" {
+		t.Fatalf("层内顺序应为 t1,t2，得到 %s,%s", layers[0][0].ID, layers[0][1].ID)
+	}
+	if layers[1][0].ID != "t3" {
+		t.Fatalf("第二层应为 t3，得到 %s", layers[1][0].ID)
+	}
+}
+
+func TestParsePlanHandlesFenceAndPrefix(t *testing.T) {
+	// 模型常见的三种包裹：裸 JSON / ```json 围栏 / 前面带一段话。
+	for _, raw := range []string{
+		`{"goal":"g","tasks":[{"id":"t1","kind":"text","prompt":"p"}]}`,
+		"```json\n{\"goal\":\"g\",\"tasks\":[{\"id\":\"t1\",\"kind\":\"text\",\"prompt\":\"p\"}]}\n```",
+		"我打算这么干：\n{\"goal\":\"g\",\"tasks\":[{\"id\":\"t1\",\"kind\":\"text\",\"prompt\":\"p\"}]}\n以上。",
+	} {
+		p, err := parsePlan(raw)
+		if err != nil {
+			t.Fatalf("解析失败（%q）：%v", raw, err)
+		}
+		if len(p.Tasks) != 1 || p.Tasks[0].ID != "t1" {
+			t.Fatalf("解析结果不对：%+v", p)
+		}
+	}
+}
+
+func TestParsePlanNormalizesKind(t *testing.T) {
+	p, err := parsePlan(`{"goal":"g","tasks":[
+	  {"id":"t1","kind":"Text","prompt":"p"},
+	  {"id":"t2","kind":"image generation","prompt":"p"},
+	  {"id":"t3","kind":"视频","prompt":"p"},
+	  {"id":"t4","kind":"2d game","prompt":"p"},
+	  {"id":"t5","kind":"代码改动","prompt":"p"},
+	  {"id":"t6","kind":"认不出来的","prompt":"p"}
+	]}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{KindText, KindImage, KindVideo, KindGame, KindCode, KindText}
+	for i, w := range want {
+		if p.Tasks[i].Kind != w {
+			t.Fatalf("%s 的类别应为 %s，得到 %s", p.Tasks[i].ID, w, p.Tasks[i].Kind)
+		}
+	}
+}
+
+// 代码类任务必须能走到 code（早先 "code" 被归进 text 分支，代码引擎永远接不到活）。
+func TestNormalizeKindAcceptsCode(t *testing.T) {
+	for _, raw := range []string{"code", "Coding", "代码", "编码", "编程", "程序"} {
+		if got := NormalizeKind(raw); got != KindCode {
+			t.Fatalf("%q 应归一为 %s，得到 %q", raw, KindCode, got)
+		}
+	}
+	for _, raw := range []string{"text", "doc", "文案"} {
+		if got := NormalizeKind(raw); got != KindText {
+			t.Fatalf("%q 应归一为 %s，得到 %q", raw, KindText, got)
+		}
+	}
+}
+
+// 计划提示词必须同时表达两件事：code 类存在，且简单代码不拆子任务。
+func TestPlannerPromptGatesCodeKind(t *testing.T) {
+	for _, want := range []string{"code：", "不拆子任务", "简单代码"} {
+		if !strings.Contains(plannerSystemPrompt, want) {
+			t.Fatalf("计划提示词应包含 %q：\n%s", want, plannerSystemPrompt)
+		}
+	}
+	eng := &fakeEngine{name: "main"}
+	hint := routeHint(Options{Engine: eng})
+	if !strings.Contains(hint, "- code（coder）→ ") {
+		t.Fatalf("路由提示应列出 code 类及其角色：\n%s", hint)
+	}
+	if !strings.Contains(hint, "简单代码由主引擎") {
+		t.Fatalf("路由提示应说明简单代码跟随主引擎：\n%s", hint)
+	}
+}
+
+// 拆解粒度只改「最多几个」，其余规则不随档位变（字段契约是解析器依赖的硬要求）。
+func TestPlannerPromptSplit(t *testing.T) {
+	cases := []struct {
+		opts Options
+		want []string
+		deny []string
+	}{
+		{Options{}, []string{"不超过 6 个", "不拆子任务", "简单代码"}, []string{"{{MAX_TASKS}}", "{{CODE_GATE}}"}},
+		{Options{Split: SplitCoarse}, []string{"不超过 3 个"}, nil},
+		{Options{Split: SplitFine}, []string{"不超过 10 个"}, nil},
+		{Options{SplitSimpleCode: true}, []string{"代码也要拆", "纯问答"}, []string{"由主引擎在\n  最终回复里直接给出"}},
+	}
+	for _, c := range cases {
+		got := plannerPrompt(c.opts)
+		for _, want := range c.want {
+			if !strings.Contains(got, want) {
+				t.Fatalf("split=%q splitCode=%v 的提示词应包含 %q：\n%s",
+					c.opts.Split, c.opts.SplitSimpleCode, want, got)
+			}
+		}
+		for _, deny := range c.deny {
+			if strings.Contains(got, deny) {
+				t.Fatalf("split=%q splitCode=%v 的提示词不该包含 %q：\n%s",
+					c.opts.Split, c.opts.SplitSimpleCode, deny, got)
+			}
+		}
+	}
+}
+
+// 角色规则覆盖：写进角色表，替掉内置 Duty；其余角色的描述不受影响。
+func TestRoleHintRuleOverride(t *testing.T) {
+	hint := roleHint(map[string]string{RoleKey("coder"): "只拆多文件、要构建或测试的改动"})
+	if !strings.Contains(hint, "coder [code] —— 只拆多文件、要构建或测试的改动") {
+		t.Fatalf("自定义规则应替掉内置描述：\n%s", hint)
+	}
+	if !strings.Contains(hint, "writer [text] —— 把材料写成结构清晰") {
+		t.Fatalf("没改的角色应保留内置描述：\n%s", hint)
+	}
+}
+
+func TestParseRules(t *testing.T) {
+	rules, err := ParseRules([]string{"role:coder=  只拆  多文件 ", "writer=写文档"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := rules[RoleKey("coder")]; got != "只拆 多文件" {
+		t.Fatalf("coder 规则 = %q（应折叠空白并把裸名归一成 role:coder）", got)
+	}
+	if got := rules[RoleKey("writer")]; got != "写文档" {
+		t.Fatalf("writer 规则 = %q", got)
+	}
+	for _, bad := range []string{"coder", "role:nobody=x", "role:coder="} {
+		if _, err := ParseRules([]string{bad}); err == nil {
+			t.Fatalf("%q 应报错", bad)
+		}
+	}
+	long := make([]rune, RulesMaxLen+1)
+	for i := range long {
+		long[i] = '规'
+	}
+	if _, err := ParseRules([]string{"role:coder=" + string(long)}); err == nil {
+		t.Fatal("超长规则应报错")
+	}
+}
+
+func TestNormalizeSplit(t *testing.T) {
+	for raw, want := range map[string]string{
+		"":         SplitStandard,
+		"  ":       SplitStandard,
+		"STANDARD": SplitStandard,
+		"Coarse":   SplitCoarse,
+		"fine":     SplitFine,
+	} {
+		got, err := NormalizeSplit(raw)
+		if err != nil || got != want {
+			t.Fatalf("NormalizeSplit(%q) = %q, %v；want %q", raw, got, err, want)
+		}
+	}
+	if _, err := NormalizeSplit("tiny"); err == nil {
+		t.Fatal("非法粒度应报错")
+	}
+}
+
+// 简单代码开关也要在路由提示里生效：否则模型只看到「代码也要拆」，上下文里仍留着
+// 「简单代码由主引擎」这条相反的口径。
+func TestRouteHintSplitSimpleCode(t *testing.T) {
+	eng := &fakeEngine{name: "main"}
+	strict := routeHint(Options{Engine: eng})
+	if !strings.Contains(strict, "简单代码由主引擎") {
+		t.Fatalf("默认应保留「简单代码由主引擎」：\n%s", strict)
+	}
+	loose := routeHint(Options{Engine: eng, SplitSimpleCode: true})
+	if strings.Contains(loose, "简单代码由主引擎") {
+		t.Fatalf("开了 simple-code 后不该再写「简单代码由主引擎」：\n%s", loose)
+	}
+	if !strings.Contains(loose, "只要需求里要改代码就拆") {
+		t.Fatalf("开了 simple-code 后应改成「要改代码就拆」：\n%s", loose)
+	}
+}
+
+func TestParsePlanNormalizesRole(t *testing.T) {
+	p, err := parsePlan(`{"goal":"g","tasks":[
+	  {"id":"t1","role":"视觉","prompt":"p"},
+	  {"id":"t2","role":"文字","prompt":"p"},
+	  {"id":"t3","role":"role:Reviewer","kind":"text","prompt":"p"},
+	  {"id":"t4","role":"不存在的","prompt":"p"}
+	]}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// role 是唯一作者字段：认不出 / 漏写都补默认角色 writer，而不是留空。
+	wantRole := []string{"designer", "writer", "reviewer", "writer"}
+	wantKind := []string{KindImage, KindText, KindText, KindText}
+	for i := range wantRole {
+		if p.Tasks[i].Role != wantRole[i] {
+			t.Fatalf("%s 的角色应为 %q，得到 %q", p.Tasks[i].ID, wantRole[i], p.Tasks[i].Role)
+		}
+		// 类别一律由角色派生，模型写的 kind 不参与（t3 的 text 只是巧合一致）。
+		if p.Tasks[i].Kind != wantKind[i] {
+			t.Fatalf("%s 的类别应为 %q，得到 %q", p.Tasks[i].ID, wantKind[i], p.Tasks[i].Kind)
+		}
+	}
+}
+
+// 角色与类别冲突时以角色为准：否则会出现「派给图片引擎却带着代码人设」。
+func TestParsePlanRoleWinsOverKind(t *testing.T) {
+	p, err := parsePlan(`{"goal":"g","tasks":[
+	  {"id":"t1","role":"coder","kind":"image","prompt":"p"},
+	  {"id":"t2","role":"designer","kind":"code","prompt":"p"}
+	]}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Tasks[0].Kind != KindCode || p.Tasks[1].Kind != KindImage {
+		t.Fatalf("冲突时应以角色为准，得到 %s / %s", p.Tasks[0].Kind, p.Tasks[1].Kind)
+	}
+}
+
+// EffectiveKind 的优先级：角色 > 旧 kind 字段 > text。直接构造 Task 的调用方也走这里。
+func TestTaskEffectiveKind(t *testing.T) {
+	if got := (Task{Role: "designer", Kind: KindCode}).EffectiveKind(); got != KindImage {
+		t.Fatalf("角色优先，应为 %s，得到 %s", KindImage, got)
+	}
+	if got := (Task{Kind: KindCode}).EffectiveKind(); got != KindCode {
+		t.Fatalf("没有角色时按旧 kind 回退，应为 %s，得到 %s", KindCode, got)
+	}
+	if got := (Task{}).EffectiveKind(); got != KindText {
+		t.Fatalf("都没有时退 text，得到 %s", got)
+	}
+	// 漏写 role 的旧计划：按 kind 落到该类别的默认角色。
+	got := normalizeTask(Task{ID: "t1", Kind: KindCode, Prompt: "p"})
+	if got.Role != "coder" || got.Kind != KindCode {
+		t.Fatalf("旧计划的 kind 应回退到 coder/code，得到 %q/%q", got.Role, got.Kind)
+	}
+}
+
+func TestTaskDocRendersRole(t *testing.T) {
+	dir := t.TempDir()
+	task := normalizeTask(Task{ID: "t1", Title: "写正文", Prompt: "写 200 字"})
+	plan := Plan{Goal: "g", Tasks: []Task{task}}
+	body := TaskDoc(dir, plan, task, nil)
+	if !strings.Contains(body, "## 你的角色") || !strings.Contains(body, "**writer**") {
+		t.Fatalf("归一化后的任务一定有角色，任务书应渲染角色段：\n%s", body)
+	}
+	if !strings.Contains(body, "结构清晰") {
+		t.Fatalf("角色段应包含职责描述：\n%s", body)
+	}
+	// 未知角色（未经归一化直接构造）不凭空多出一段。
+	body = TaskDoc(dir, Plan{Goal: "g"}, Task{ID: "t2", Title: "x", Prompt: "p"}, nil)
+	if strings.Contains(body, "## 你的角色") {
+		t.Fatalf("未知角色时不该渲染角色段：\n%s", body)
+	}
+}
+
+func TestRolePromptToolsAndPermission(t *testing.T) {
+	opts := Options{SystemPrompt: "主提示词", Tools: agent.ToolsOn, Permission: agent.PermissionAcceptEdits}
+	got := systemPromptFor(opts, Task{Role: "writer"})
+	if !strings.HasPrefix(got, "主提示词") || !strings.Contains(got, "写作者") {
+		t.Fatalf("角色片段应追加在主提示词之后，得到 %q", got)
+	}
+	if got := systemPromptFor(opts, Task{}); got != "主提示词" {
+		t.Fatalf("未设角色时应保持原样，得到 %q", got)
+	}
+	// 内置角色没声明工具 / 权限 → 沿用全局，不凭空收窄。
+	if !toolsFor(opts, Task{Role: "writer"}).IsOn() {
+		t.Fatal("角色没声明工具时应沿用全局")
+	}
+	if permissionFor(opts, Task{Role: "writer"}) != agent.PermissionAcceptEdits {
+		t.Fatal("角色没声明权限时应沿用全局")
+	}
+}
+
+func TestRouteForPrefersRoleOverKind(t *testing.T) {
+	main := &fakeEngine{name: "mainengine"}
+	opts := Options{
+		Engine: main,
+		Model:  "m1",
+		Routes: map[string]Route{
+			KindText:      {Engine: "texteng"},
+			"role:writer": {Engine: "writereng"},
+			"reviewer":    {Engine: "revieweng"}, // 裸角色名也认
+		},
+	}
+	if r := RouteFor(Task{Kind: KindText, Role: "writer"}, opts); r.Engine != "writereng" {
+		t.Fatalf("角色路由应优先于类别路由，得到 %+v", r)
+	}
+	if r := RouteFor(Task{Kind: KindText, Role: "reviewer"}, opts); r.Engine != "revieweng" {
+		t.Fatalf("裸角色名也应命中，得到 %+v", r)
+	}
+	// 没配角色 → 落回类别路由。
+	if r := RouteFor(Task{Kind: KindText, Role: "researcher"}, opts); r.Engine != "texteng" {
+		t.Fatalf("没配角色时应走类别路由，得到 %+v", r)
+	}
+	// 任务写死的仍然最优先。
+	if r := RouteFor(Task{Kind: KindText, Role: "writer", Engine: "x"}, opts); r.Engine != "x" {
+		t.Fatalf("任务写死的引擎应最优先，得到 %+v", r)
+	}
+	// 角色配了引擎但没配模型 → 用角色默认模型（内置角色没配，应为空）。
+	if r := RouteFor(Task{Kind: KindText, Role: "writer"}, Options{Routes: map[string]Route{"role:writer": {Engine: "writereng"}}}); r.Model != "" {
+		t.Fatalf("角色路由没给模型时应为空，得到 %q", r.Model)
+	}
+}
+
+func TestParseRoutesAcceptsRole(t *testing.T) {
+	got, err := ParseRoutes([]string{"role:reviewer=claude/haiku", "role:writer=weng"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r := got["role:reviewer"]; r.Engine != "claude" || r.Model != "haiku" {
+		t.Fatalf("角色路由不对：%+v", r)
+	}
+	if r := got["role:writer"]; r.Engine != "weng" {
+		t.Fatalf("角色路由不对：%+v", r)
+	}
+	if _, err := ParseRoutes([]string{"role:nobody=x"}); err == nil {
+		t.Fatal("未知角色应当报错")
+	}
+}
+
+// 内置角色必须按五类子任务对齐：每一类至少一个默认角色，且角色不引入第六类。
+func TestBuiltinRolesCoverKinds(t *testing.T) {
+	for _, kind := range Kinds {
+		if DefaultRoleForKind(kind) == nil {
+			t.Fatalf("%s 类没有默认角色 —— 角色表应与五类子任务对齐", kind)
+		}
+	}
+	for _, r := range builtinRoles {
+		found := false
+		for _, kind := range Kinds {
+			if r.Kind == kind {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Fatalf("角色 %s 的默认类别 %q 不在五类子任务里", r.Name, r.Kind)
+		}
+	}
+	if r := DefaultRoleForKind(KindVideo); r == nil || r.Name != "director" {
+		t.Fatalf("video 的默认角色应为 director，得到 %+v", r)
+	}
+	if r := DefaultRoleForKind(KindCode); r == nil || r.Name != "coder" {
+		t.Fatalf("code 的默认角色应为 coder，得到 %+v", r)
+	}
+	if hint := roleHint(nil); !strings.Contains(hint, "director [video]") || !strings.Contains(hint, "coder [code]") {
+		t.Fatalf("角色提示词应带上默认类别：\n%s", hint)
+	}
+	// 计划漏写 kind 时，各角色落到自己的类别。
+	for role, kind := range map[string]string{
+		"designer": KindImage, "导演": KindVideo, "builder": KindGame,
+		"coder": KindCode, "开发": KindCode, "engineer": KindCode,
+	} {
+		if got := normalizeTask(Task{Role: role, Prompt: "p"}); got.Kind != kind {
+			t.Fatalf("角色 %s 的默认类别应为 %s，得到 %s", role, kind, got.Kind)
+		}
+	}
+}
+
+// 角色别名不能抢占类别路由键：`--team-route video=…` 必须仍然是 video 类。
+func TestRoleAliasesDoNotShadowKindRoutes(t *testing.T) {
+	for _, kind := range RouteKinds {
+		if got := NormalizeRole(kind); got != "" {
+			t.Fatalf("类别 %q 被角色别名抢成了 %q", kind, got)
+		}
+		got, err := ParseRoutes([]string{kind + "=eng"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, ok := got[kind]; !ok {
+			t.Fatalf("%s 路由键被改写：%+v", kind, got)
+		}
+	}
+	// 影像角色的常用中文写法仍要认。
+	if got := NormalizeRole("导演"); got != "director" {
+		t.Fatalf("「导演」应归一为 director，得到 %q", got)
+	}
+}
+
+func TestParseRoutes(t *testing.T) {
+	got, err := ParseRoutes([]string{"image=llm/hunyuan-image-3.0", "text=claude", "game=codebuddy/x/y"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got[KindImage].Engine != "llm" || got[KindImage].Model != "hunyuan-image-3.0" {
+		t.Fatalf("image 路由不对：%+v", got[KindImage])
+	}
+	if got[KindText].Engine != "claude" || got[KindText].Model != "" {
+		t.Fatalf("text 路由不对：%+v", got[KindText])
+	}
+	// 只按第一个 / 切：模型名里可能还有 /。
+	if got[KindGame].Engine != "codebuddy" || got[KindGame].Model != "x/y" {
+		t.Fatalf("game 路由不对：%+v", got[KindGame])
+	}
+	if _, err := ParseRoutes([]string{"music=x"}); err == nil {
+		t.Fatal("非法类别应当报错")
+	}
+	if _, err := ParseRoutes([]string{"image"}); err == nil {
+		t.Fatal("缺 = 应当报错")
+	}
+}
+
+func TestRouteForPrefersExplicitThenMain(t *testing.T) {
+	main := &fakeEngine{name: "mainengine"}
+	opts := Options{Engine: main, Model: "m1", Routes: map[string]Route{KindImage: {Engine: "imgen"}}}
+	// 任务写死的优先。
+	if r := RouteFor(Task{Kind: KindImage, Engine: "x", Model: "y"}, opts); r.Engine != "x" || r.Model != "y" {
+		t.Fatalf("任务写死的应当优先，得到 %+v", r)
+	}
+	// 其次配置。
+	if r := RouteFor(Task{Kind: KindImage}, opts); r.Engine != "imgen" {
+		t.Fatalf("应当走配置，得到 %+v", r)
+	}
+	// text 没配 → 主引擎。
+	if r := RouteFor(Task{Kind: KindText}, opts); r.Engine != "mainengine" || r.Model != "m1" {
+		t.Fatalf("text 应当回落主引擎，得到 %+v", r)
+	}
+	// video / code 没配 → 同样跟随主引擎（五类一致）。
+	if r := RouteFor(Task{Kind: KindVideo}, opts); r.Engine != "mainengine" || r.Model != "m1" {
+		t.Fatalf("video 没配应当回落主引擎，得到 %+v", r)
+	}
+	if r := RouteFor(Task{Kind: KindCode}, opts); r.Engine != "mainengine" || r.Model != "m1" {
+		t.Fatalf("code 没配应当回落主引擎，得到 %+v", r)
+	}
+	// 主引擎也为空 → 空路由（execute 按失败处理）。
+	if r := RouteFor(Task{Kind: KindGame}, Options{}); r.Engine != "" {
+		t.Fatalf("主引擎为空时应当返回空路由，得到 %+v", r)
+	}
+}
+
+func TestParseRoutesAcceptsPlan(t *testing.T) {
+	// plan 是**阶段**键，不是子任务类别：NormalizeKind 认不出它，所以 ParseRoutes
+	// 必须走自己的归一（含中文写法）。
+	got, err := ParseRoutes([]string{"计划=claude/haiku"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r := got[KindPlan]; r.Engine != "claude" || r.Model != "haiku" {
+		t.Fatalf("plan 路由不对：%+v", r)
+	}
+}
+
+func TestPlanRouteFollowsMainUnlessConfigured(t *testing.T) {
+	main := &fakeEngine{name: "mainengine"}
+	opts := Options{Engine: main, Model: "m1"}
+	if r := PlanRoute(opts); r.Engine != "mainengine" || r.Model != "m1" {
+		t.Fatalf("没配 plan 应当跟随主引擎，得到 %+v", r)
+	}
+	opts.Routes = map[string]Route{KindPlan: {Engine: "plannereng", Model: "pm"}}
+	if r := PlanRoute(opts); r.Engine != "plannereng" || r.Model != "pm" {
+		t.Fatalf("配了 plan 应当照办，得到 %+v", r)
+	}
+}
+
+func TestPlanOnOtherEngineKeepsSessionApart(t *testing.T) {
+	main := &fakeEngine{name: "mainengine", task: "汇总"}
+	planner := &fakeEngine{
+		name: "plannereng",
+		plan: `{"goal":"g","tasks":[{"id":"t1","kind":"text","title":"写","prompt":"写一段"}]}`,
+	}
+	install(t, main, planner)
+	opts := newOpts(t, main, "")
+	opts.SessionID = "main-sid"
+	opts.Routes = map[string]Route{KindPlan: {Engine: "plannereng"}}
+
+	_, sid, err := makePlan(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 跨引擎的 session id 不能交给汇总（那是另一个引擎的上下文）。
+	if sid != "" {
+		t.Fatalf("计划换了引擎时不该返回 session，得到 %q", sid)
+	}
+	reqs := planner.requests()
+	if len(reqs) != 1 || reqs[0].SessionID != "" {
+		t.Fatalf("计划引擎不该拿到主引擎的 session：%+v", reqs)
+	}
+}
+
+func TestRunWritesPlanAndTaskDocs(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fakeplan",
+		plan: `{"goal":"做一份介绍","tasks":[
+		  {"id":"t1","kind":"text","title":"写正文","prompt":"写 200 字","deliverables":["brief.md"]},
+		  {"id":"t2","kind":"text","title":"写摘要","prompt":"写 50 字","deps":["t1"]}
+		]}`,
+		task: "好的",
+		// 交付物必须真的落盘：缺交付物会触发重试（那是另一个用例），这里要钉的是
+		// 「正常一次通过」的文档与事件形状。
+		writeFiles: []string{"brief.md"},
+	}
+	install(t, eng)
+
+	var mu sync.Mutex
+	var events []agent.StreamEvent
+	opts := newOpts(t, eng, "")
+	opts.OnEvent = func(ev agent.StreamEvent) {
+		mu.Lock()
+		events = append(events, ev)
+		mu.Unlock()
+	}
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 计划文档：存在、只读、含关键锚点。
+	st, err := os.Stat(res.PlanPath)
+	if err != nil {
+		t.Fatalf("PLAN.md 没写出来：%v", err)
+	}
+	if mode := st.Mode().Perm(); mode != 0o444 {
+		t.Fatalf("PLAN.md 应当只读（0444），实际 %o", mode)
+	}
+	body, _ := os.ReadFile(res.PlanPath)
+	for _, want := range []string{"## 任务总览", "T1", "T2", "brief.md"} {
+		if !strings.Contains(string(body), want) {
+			t.Fatalf("PLAN.md 缺 %q：\n%s", want, body)
+		}
+	}
+
+	// 任务书：每个任务一份、只读、含工作目录与交付物。
+	for _, id := range []string{"t1", "t2"} {
+		p := TaskDocPath(res.RunDir, id)
+		doc, err := os.ReadFile(p)
+		if err != nil {
+			t.Fatalf("%s 没写出来：%v", id, err)
+		}
+		if !strings.Contains(string(doc), TaskDir(res.RunDir, id)) {
+			t.Fatalf("%s 任务书里没有工作目录：\n%s", id, doc)
+		}
+	}
+	// 子任务工作目录。
+	for _, id := range []string{"t1", "t2"} {
+		if st, err := os.Stat(TaskDir(res.RunDir, id)); err != nil || !st.IsDir() {
+			t.Fatalf("%s 工作目录没建：%v", id, err)
+		}
+	}
+
+	// OUT 落盘。
+	if _, err := os.Stat(OutputPath(res.RunDir, "t1")); err != nil {
+		t.Fatalf("OUT-t1.md 没写：%v", err)
+	}
+
+	/* 最终答复的产物清单由 core 追加（见 reduce.go 的 artsBlock）：短路径 + 列表项，
+	   不再由模型把长绝对路径一行一个地吐出来（那会被 markdown 折成一大段）。 */
+	for _, want := range []string{"**产物**", "- `t1/brief.md` · 写正文", "全部位于：`" + res.RunDir + "`"} {
+		if !strings.Contains(res.Text, want) {
+			t.Fatalf("最终答复缺 %q：\n%s", want, res.Text)
+		}
+	}
+	if strings.Contains(res.Text, filepath.Join(res.RunDir, "t1", "brief.md")) {
+		t.Fatalf("产物清单不该再出现长绝对路径：\n%s", res.Text)
+	}
+
+	/* 事件：主会话里只有**一张任务列表卡**（KindTasks 全量快照）。
+	   计划一确定就把 2 行都登记进去（含等上游的 t2）；开跑 / 收尾各广播一份；
+	   子任务的内部事件**不进主会话**（它们写自己的会话日志）。 */
+	mu.Lock()
+	snaps := taskSnapshots(events)
+	parented, taskCards := 0, 0
+	for _, ev := range events {
+		if ev.Parent != "" {
+			parented++
+		}
+		if ev.Kind == agent.KindToolUse && ev.Name == "Task" {
+			taskCards++
+		}
+	}
+	mu.Unlock()
+	if len(snaps) == 0 {
+		t.Fatal("应当至少广播一份任务列表快照")
+	}
+	if len(snaps[0]) != 2 || rowOf(snaps[0], "t1") == nil || rowOf(snaps[0], "t2") == nil {
+		t.Fatalf("第一份快照就该有 2 行（计划确定即全部登记），得到 %+v", snaps[0])
+	}
+	if r := rowOf(snaps[0], "t2"); r == nil || r.Status != RowPending || len(r.Deps) != 1 || r.Deps[0] != "t1" {
+		t.Fatalf("t2 应当 pending 且带 deps=[t1]，得到 %+v", r)
+	}
+	// 依赖关系在进度上必须成立：t1 还在跑的时候 t2 不能已经开跑。
+	for _, rows := range snaps {
+		t1, t2 := rowOf(rows, "t1"), rowOf(rows, "t2")
+		if t1 == nil || t2 == nil {
+			t.Fatalf("快照必须始终是 2 行全量，得到 %+v", rows)
+		}
+		if t1.Status == RowRunning && t2.Status != RowPending {
+			t.Fatalf("t1 还在跑时 t2 不该是 %s", t2.Status)
+		}
+	}
+	last := snaps[len(snaps)-1]
+	for _, id := range []string{"t1", "t2"} {
+		if r := rowOf(last, id); r == nil || r.Status != TaskDone {
+			t.Fatalf("末份快照里 %s 应当 done，得到 %+v", id, r)
+		}
+	}
+	if parented != 0 || taskCards != 0 {
+		t.Fatalf("子任务事件不该再转发到主会话（parent=%d, tool_use Task=%d）", parented, taskCards)
+	}
+
+	// 子任务**不带会话 id**：这是「不共享上下文」的硬约束。
+	// 只挑真正的子任务调用（提示词是任务书），计划 / 汇总那两轮不算。
+	taskCalls := 0
+	for _, req := range eng.requests() {
+		if len(req.Messages) == 0 || !strings.Contains(req.Messages[0].Content, taskDocAnchor) {
+			continue
+		}
+		taskCalls++
+		if req.SessionID != "" || req.Continue {
+			t.Fatalf("子任务不该接续会话：SessionID=%q Continue=%v", req.SessionID, req.Continue)
+		}
+		if req.Workspace == "" {
+			t.Fatal("子任务必须有独立工作目录")
+		}
+	}
+	if taskCalls != 2 {
+		t.Fatalf("应当派发 2 个子任务，得到 %d", taskCalls)
+	}
+}
+
+func TestRunDegradesWhenPlanUnparseable(t *testing.T) {
+	eng := &fakeEngine{name: "fakebad", plan: "我不会给你 JSON", task: "直接干完了"}
+	install(t, eng)
+
+	opts := newOpts(t, eng, "")
+	var notices []string
+	opts.OnEvent = func(ev agent.StreamEvent) {
+		if ev.Kind == agent.KindNotice {
+			notices = append(notices, ev.Text)
+		}
+	}
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Tasks) != 1 || res.Tasks[0].ID != "t1" {
+		t.Fatalf("应当降级为单任务，得到 %+v", res.Tasks)
+	}
+	join := strings.Join(notices, "\n")
+	if !strings.Contains(join, "降级") {
+		t.Fatalf("降级必须有明说：\n%s", join)
+	}
+}
+
+func TestRunFallsBackToMainEngineForUnroutedKind(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fakeimg",
+		plan: `{"goal":"g","tasks":[{"id":"t1","kind":"image","prompt":"画图"}]}`,
+		task: "ok",
+	}
+	install(t, eng)
+
+	opts := newOpts(t, eng, "")
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Tasks[0].State != TaskDone {
+		t.Fatalf("没配专用引擎的类别应当跟随主引擎跑完，得到 %s（%s）", res.Tasks[0].State, res.Tasks[0].Reason)
+	}
+	if res.Tasks[0].Engine != eng.Name() {
+		t.Fatalf("应当回落主引擎 %s，得到 %q", eng.Name(), res.Tasks[0].Engine)
+	}
+}
+
+func TestRunSkipsDownstreamOfFailedRequired(t *testing.T) {
+	eng := &fakeEngine{
+		name:   "fakefail",
+		plan:   `{"goal":"g","tasks":[{"id":"t1","kind":"text","prompt":"这一步会炸"},{"id":"t2","kind":"text","prompt":"依赖它","deps":["t1"]}]}`,
+		task:   "这一步会炸",
+		failOn: "这一步会炸",
+	}
+	install(t, eng)
+
+	opts := newOpts(t, eng, "")
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Tasks[0].State != TaskFailed {
+		t.Fatalf("t1 应当失败，得到 %s", res.Tasks[0].State)
+	}
+	if res.Tasks[1].State != TaskSkipped {
+		t.Fatalf("t2 应当被跳过（上游必需任务失败），得到 %s", res.Tasks[1].State)
+	}
+	if !strings.Contains(res.Tasks[1].Reason, "上游") {
+		t.Fatalf("跳过原因要说清是上游：%s", res.Tasks[1].Reason)
+	}
+}
+
+func TestRunPlanOnlyDoesNotExecute(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fakeonly",
+		plan: `{"goal":"g","tasks":[{"id":"t1","kind":"text","prompt":"p"}]}`,
+		task: "不该被调用",
+	}
+	install(t, eng)
+
+	opts := newOpts(t, eng, "")
+	opts.PlanOnly = true
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(res.Text, res.PlanPath) {
+		t.Fatalf("plan-only 的输出应当给出计划路径：%s", res.Text)
+	}
+	for _, req := range eng.requests() {
+		if strings.Contains(req.Messages[0].Content, taskDocAnchor) {
+			t.Fatal("plan-only 不该派发子任务")
+		}
+	}
+	if _, err := os.Stat(OutputPath(res.RunDir, "t1")); err == nil {
+		t.Fatal("plan-only 不该产出 OUT 文件")
+	}
+}
+
+func TestTaskDocContainsUpstream(t *testing.T) {
+	dir := t.TempDir()
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Title: "上游"},
+		{ID: "t2", Kind: KindText, Title: "下游", Deps: []string{"t1"}, Prompt: "做事"},
+	}}
+	up := map[string]TaskResult{"t1": {ID: "t1", Title: "上游", State: TaskDone, Text: "上游结论：用蓝色", Arts: []string{"/tmp/a.png"}}}
+	doc := TaskDoc(dir, plan, plan.Tasks[1], up)
+	for _, want := range []string{"上游结论：用蓝色", "/tmp/a.png", "## 任务", "## 交付物"} {
+		if !strings.Contains(doc, want) {
+			t.Fatalf("任务书缺 %q：\n%s", want, doc)
+		}
+	}
+}
+
+func TestTruncateKeepsHeadAndTail(t *testing.T) {
+	s := strings.Repeat("头", 100) + strings.Repeat("中", 100) + strings.Repeat("尾", 100)
+	got := Truncate(s, 30)
+	if !strings.Contains(got, "省略") {
+		t.Fatalf("截断要标注省略量：%s", got)
+	}
+	if !strings.HasPrefix(got, "头") || !strings.HasSuffix(got, "尾") {
+		t.Fatalf("截断应保留首尾：%s", got)
+	}
+}
+
+func TestChooseRunDir(t *testing.T) {
+	opts := Options{RunID: "run-abc"}
+	// 默认空间 → ~/.magic-agent/team/<run_id>
+	home, _ := os.UserHomeDir()
+	got, err := chooseRunDir(opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := filepath.Join(home, ".magic-agent", "team", "run-abc"); got != want {
+		t.Fatalf("默认空间应落 %s，得到 %s", want, got)
+	}
+	// 选了空间 → <ws>/.magic/team/<run_id>
+	opts.Workspace = "/tmp/ws"
+	got, _ = chooseRunDir(opts)
+	if want := filepath.Join("/tmp/ws", ".magic", "team", "run-abc"); got != want {
+		t.Fatalf("空间内应落 %s，得到 %s", want, got)
+	}
+}
+
+func TestArtsAndMissing(t *testing.T) {
+	dir := t.TempDir()
+	png := filepath.Join(dir, "cover.png")
+	if err := os.WriteFile(png, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got := artsFromText("生成了 " + png + " 与 /nope/x.png 还有 dir/rel.md")
+	if len(got) != 1 || got[0] != png {
+		t.Fatalf("应当只认存在且绝对路径的产物，得到 %v", got)
+	}
+	var r TaskResult
+	collectDeliverables(dir, []string{"cover.png", "brief.md"}, &r)
+	if len(r.Missing) != 1 || r.Missing[0] != "brief.md" {
+		t.Fatalf("缺失清单不对：%v", r.Missing)
+	}
+	if len(r.Arts) != 1 || r.Arts[0] != png {
+		t.Fatalf("已存在的交付物应进产物：%v", r.Arts)
+	}
+	// 越界声明按文件名比，不当路径用。
+	var bad TaskResult
+	collectDeliverables(dir, []string{"../../etc/passwd"}, &bad)
+	if len(bad.Missing) != 1 || bad.Missing[0] != "passwd" {
+		t.Fatalf("越界声明应按文件名处理，得到 %v", bad.Missing)
+	}
+}
+
+// 交付物声明允许带子目录（`impl/fizzbuzz.js`）：模型常把文件分目录放，
+// 一律取 basename 会误判「缺少交付物」（2026-10-22 实测团队 6/6 全误判）。
+// 越界写法仍要拦住：路径清洗后才跑出任务目录的（`a/../../etc/passwd`）也按文件名比。
+func TestCollectDeliverablesSubdir(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "impl"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	js := filepath.Join(dir, "impl", "fizzbuzz.js")
+	if err := os.WriteFile(js, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	md := filepath.Join(dir, "README.md")
+	if err := os.WriteFile(md, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var r TaskResult
+	collectDeliverables(dir, []string{"./impl/fizzbuzz.js", "README.md", "impl/nope.js"}, &r)
+	if len(r.Arts) != 2 || r.Arts[0] != js || r.Arts[1] != md {
+		t.Fatalf("子目录交付物应进产物：%v", r.Arts)
+	}
+	if len(r.Missing) != 1 || r.Missing[0] != "impl/nope.js" {
+		t.Fatalf("缺失清单应保留声明里的相对路径：%v", r.Missing)
+	}
+	var esc TaskResult
+	collectDeliverables(dir, []string{"impl/../../../etc/passwd"}, &esc)
+	if len(esc.Arts) != 0 || len(esc.Missing) != 1 || esc.Missing[0] != "passwd" {
+		t.Fatalf("清洗后越界的声明应按文件名比：arts=%v missing=%v", esc.Arts, esc.Missing)
+	}
+}
+
+// 子任务失败/超时也要上报**已经落盘**的交付物 —— 否则汇总会说「什么都没产出」。
+// 回归：2026-10-21 实测 t2 画完 cover.png 后 1 分钟超时，ARTS-t2.json 的 arts 为 null，
+// 汇总正文写「封面没有做出来」。
+func TestRunTaskFailureStillReportsDeliverables(t *testing.T) {
+	eng := &fakeEngine{name: "fake-fail-arts", plan: "画画", task: "画画", failOn: "画画"}
+	install(t, eng)
+	opts := newOpts(t, eng, "")
+	runDir := filepath.Join(opts.BaseDir, "run-1")
+	dir := TaskDir(runDir, "t1")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	png := filepath.Join(dir, "cover.png")
+	if err := os.WriteFile(png, []byte("png"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	task := Task{ID: "t1", Kind: KindImage, Title: "画封面", Prompt: "画画", Deliverables: []string{"cover.png", "brief.md"}}
+	var mu sync.Mutex
+	var events []agent.StreamEvent
+	board := newBoard(func(ev agent.StreamEvent) {
+		mu.Lock()
+		events = append(events, ev)
+		mu.Unlock()
+	})
+	// 真实流程里 Team.Run 已把计划里的任务先行登记（见 board.add）；这里直接调
+	// runTask，所以要自己补上这一行。
+	board.add(task, Route{Engine: eng.Name()})
+	r := runTask(context.Background(), opts, Plan{Goal: "g", Tasks: []Task{task}}, task, runDir, nil, board)
+
+	if r.State != TaskFailed {
+		t.Fatalf("应判失败，得到 %s", r.State)
+	}
+	if len(r.Arts) != 1 || r.Arts[0] != png {
+		t.Fatalf("失败前已落盘的交付物应进产物：%v", r.Arts)
+	}
+	if len(r.Missing) != 1 || r.Missing[0] != "brief.md" {
+		t.Fatalf("缺失清单不对：%v", r.Missing)
+	}
+	raw, err := os.ReadFile(ArtsPath(runDir, "t1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(raw), png) {
+		t.Fatalf("ARTS 应当带上已产出文件：%s", raw)
+	}
+	out, err := os.ReadFile(OutputPath(runDir, "t1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(out), "✓ `cover.png`") || !strings.Contains(string(out), "✗ `brief.md`") {
+		t.Fatalf("OUT 交付物清单不对：\n%s", out)
+	}
+	// 末份快照必须把这一行落定为 failed 并带上原因。
+	mu.Lock()
+	snaps := taskSnapshots(events)
+	mu.Unlock()
+	if len(snaps) == 0 {
+		t.Fatal("应当有任务列表快照")
+	}
+	row := rowOf(snaps[len(snaps)-1], "t1")
+	if row == nil || row.Status != TaskFailed || row.Note == "" {
+		t.Fatalf("末份快照应当是 t1 failed 且带原因，得到 %+v", row)
+	}
+}
+
+/*
+子任务 = 普通会话（2026-10-22 用户定稿）：
+
+	子任务的过程事件原样交给 SubSession，写进它自己的会话日志；主会话里只有一张
+	任务列表卡。这里钉住三条边界：
+
+	  ① 子任务事件全部 Push 给子会话，一条都不进主会话；
+	  ② 主会话只有 KindTasks 快照，快照里带 run_id / session_id（点得进子会话）；
+	  ③ 收尾时 Finish 拿到子会话 id 与 done。
+*/
+type fakeSub struct {
+	runID string
+
+	mu       sync.Mutex
+	pushed   []agent.StreamEvent
+	session  string
+	finished bool
+	state    string
+	reason   string
+	hooked   bool
+}
+
+func (f *fakeSub) RunID() string { return f.runID }
+
+func (f *fakeSub) SetSessionID(id string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.session = id
+}
+
+func (f *fakeSub) Push(ev agent.StreamEvent) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.pushed = append(f.pushed, ev)
+}
+
+func (f *fakeSub) Finish(sessionID, state, reason string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.finished = true
+	if sessionID != "" {
+		f.session = sessionID
+	}
+	f.state, f.reason = state, reason
+}
+
+func (f *fakeSub) Context(parent context.Context) context.Context {
+	f.hooked = true
+	return parent
+}
+
+func TestRunTaskPushesEventsToSubSession(t *testing.T) {
+	eng := &fakeEngine{name: "fake-sub-sess", plan: "", task: "写好了", sessionID: "sess-child-1"}
+	// 这是**直接** runTask（不经过计划阶段）：先记一笔，让 fake 的调用计数越过
+	// 「第一次是计划」那条判断，子任务那次才会返回 task 正文。
+	eng.mu.Lock()
+	eng.calls = append(eng.calls, agent.Request{})
+	eng.mu.Unlock()
+	install(t, eng)
+	opts := newOpts(t, eng, "")
+	runDir := filepath.Join(opts.BaseDir, "run-sub")
+	task := Task{ID: "t1", Kind: KindText, Title: "写正文", Prompt: "写正文"}
+	if err := os.MkdirAll(TaskDir(runDir, task.ID), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	sub := &fakeSub{runID: "run-child-1"}
+	opts.OpenSubSession = func(Task, string, string, string) SubSession { return sub }
+
+	var mu sync.Mutex
+	var events []agent.StreamEvent
+	board := newBoard(func(ev agent.StreamEvent) {
+		mu.Lock()
+		events = append(events, ev)
+		mu.Unlock()
+	})
+	// 真实流程里 Team.Run 已把计划里的任务先行登记（见 board.add）；这里直接调
+	// runTask，所以要自己补上这一行。
+	board.add(task, Route{Engine: eng.Name()})
+	r := runTask(context.Background(), opts, Plan{Goal: "g", Tasks: []Task{task}}, task, runDir, nil, board)
+
+	if r.SessionID != "sess-child-1" {
+		t.Fatalf("TaskResult 应记下子会话 id，得到 %q", r.SessionID)
+	}
+	// ① 正文事件进了子会话自己的日志。
+	sub.mu.Lock()
+	pushed := append([]agent.StreamEvent(nil), sub.pushed...)
+	finished, state, session := sub.finished, sub.state, sub.session
+	sub.mu.Unlock()
+	if len(pushed) == 0 {
+		t.Fatal("子任务事件应当 Push 给子会话")
+	}
+	var gotText bool
+	for _, ev := range pushed {
+		if ev.Kind == agent.KindText && strings.Contains(ev.Text, "写好了") {
+			gotText = true
+		}
+	}
+	if !gotText {
+		t.Fatalf("子会话日志里应当有正文，得到 %+v", pushed)
+	}
+	// ③ 收尾带上子会话 id 与 done。
+	if !finished || state != TaskDone || session != "sess-child-1" {
+		t.Fatalf("Finish 参数不对：finished=%v state=%q session=%q", finished, state, session)
+	}
+	if !sub.hooked {
+		t.Fatal("子任务 ctx 应当挂上子引擎 pid 登记钩子")
+	}
+	// ② 主会话只有任务列表快照，没有子任务事件。
+	mu.Lock()
+	defer mu.Unlock()
+	if len(events) == 0 {
+		t.Fatal("主会话应当有任务列表快照")
+	}
+	for _, ev := range events {
+		if ev.Kind != agent.KindTasks {
+			t.Fatalf("主会话只该有 tasks 快照，得到 %+v", ev)
+		}
+	}
+	row := rowOf(taskSnapshots(events)[len(taskSnapshots(events))-1], "t1")
+	if row == nil || row.RunID != "run-child-1" || row.SessionID != "sess-child-1" || row.Status != TaskDone {
+		t.Fatalf("快照应带子会话 run_id / session_id 且 done，得到 %+v", row)
+	}
+	// 留档：OUT-t1.md 里也有人能读到的「会话：」行。
+	out, err := os.ReadFile(OutputPath(runDir, "t1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(out), "会话：sess-child-1") {
+		t.Fatalf("OUT 应留下子会话 id：\n%s", out)
+	}
+}
+
+func TestFallbackSummaryIsHonest(t *testing.T) {
+	res := []TaskResult{
+		{ID: "t1", Title: "写正文", Kind: KindText, State: TaskDone, Text: "正文在此", Arts: []string{"/tmp/a.png"}},
+		{ID: "t2", Title: "画封面", Kind: KindImage, State: TaskFailed, Reason: "no engine for kind=image"},
+	}
+	plan := Plan{Goal: "g"}
+	got := fallbackSummary(plan, res, "超时")
+	for _, want := range []string{"已完成 1 / 2", "汇总失败：超时", "/tmp/a.png", "no engine for kind=image"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("兜底汇报缺 %q：\n%s", want, got)
+		}
+	}
+}
+
+// 产物清单由 core 确定性生成：短路径 + 运行目录只出现一次（否则手机上就是
+// 「三条长绝对路径被折成一大段」，见 reduce.go 的 artsBlock）。
+func TestArtsBlockUsesRunRelativePaths(t *testing.T) {
+	runDir := filepath.Join("/tmp", "demo", ".magic", "team", "run-1")
+	res := []TaskResult{
+		{ID: "t1", Title: "实现", State: TaskDone, OutputPath: filepath.Join(runDir, "OUT-t1.md"),
+			Arts: []string{filepath.Join(runDir, "t1", "impl", "fizzbuzz.js"), filepath.Join(runDir, "t1", "test", "fizzbuzz.test.js")}},
+		{ID: "t2", Title: "写文档", State: TaskDone,
+			Arts: []string{filepath.Join(runDir, "t2", "docs", "README.md"), "/elsewhere/a.md"}},
+	}
+	got := artsBlock(res)
+	for _, want := range []string{
+		"- `t1/impl/fizzbuzz.js` · 实现\n",
+		"- `t1/test/fizzbuzz.test.js` · 实现\n",
+		"- `t2/docs/README.md` · 写文档\n",
+		"- `/elsewhere/a.md` · 写文档\n", // 运行目录外：原样给绝对路径，不伪造短路径
+		"全部位于：`" + runDir + "`",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("产物清单缺 %q：\n%s", want, got)
+		}
+	}
+	if n := strings.Count(got, runDir); n != 1 {
+		t.Fatalf("运行目录应只出现一次，实际 %d 次：\n%s", n, got)
+	}
+	if strings.Contains(got, runDir+"/t1/impl") {
+		t.Fatalf("列表项不该再出现长绝对路径：\n%s", got)
+	}
+}
+
+func TestReducePromptDoesNotDumpFullText(t *testing.T) {
+	long := strings.Repeat("长", reduceCap*2)
+	res := []TaskResult{{ID: "t1", Title: "t", Kind: KindText, State: TaskDone, Text: long}}
+	got := reducePrompt(Plan{Goal: "g"}, res)
+	if len([]rune(got)) > reduceCap*2 {
+		t.Fatalf("汇总提示词不该灌全文，长度 %d", len([]rune(got)))
+	}
+	if !strings.Contains(got, "省略") {
+		t.Fatal("截断应标注")
+	}
+}
+
+func TestWriteOutputRecordsMissing(t *testing.T) {
+	dir := t.TempDir()
+	r := TaskResult{ID: "t1", Title: "标题", State: TaskDone, Text: "正文", Missing: []string{"b.md"}}
+	writeOutput(dir, r, []string{"a.md", "b.md"})
+	body, err := os.ReadFile(OutputPath(dir, "t1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(body), "✓ `a.md`") || !strings.Contains(string(body), "✗ `b.md`") {
+		t.Fatalf("交付物核对没写进 OUT：\n%s", body)
+	}
+	var arts map[string]any
+	raw, _ := os.ReadFile(ArtsPath(dir, "t1"))
+	if err := json.Unmarshal(raw, &arts); err != nil {
+		t.Fatalf("ARTS 不是合法 JSON：%v", err)
+	}
+	if arts["state"] != TaskDone {
+		t.Fatalf("ARTS 里的状态不对：%v", arts["state"])
+	}
+}
+
+// 执行阶段心跳：只播报「还在跑且很久没动静」的任务，收尾的不再播。
+func TestBoardQuietLinesOnlyAnnouncesSilentRunningTasks(t *testing.T) {
+	b := newBoard(func(agent.StreamEvent) {})
+	t1 := Task{ID: "t1", Kind: KindText, Title: "写介绍"}
+	t2 := Task{ID: "t2", Kind: KindImage, Title: "画封面"}
+	t3 := Task{ID: "t3", Kind: KindText, Title: "汇总图"}
+	for _, task := range []Task{t1, t2, t3} {
+		b.add(task, Route{})
+	}
+	b.start(t1, "e", "")
+	b.start(t2, "e", "")
+	b.finish(t3, TaskResult{ID: "t3", State: TaskDone})
+
+	// t1 刚刚有输出；t3 已收尾；t2 静默超过阈值。
+	b.touch("t1")
+	b.mu.Lock()
+	b.last["t2"] = time.Now().Add(-time.Minute)
+	b.mu.Unlock()
+
+	got := b.quietLines()
+	if len(got) != 1 || !strings.Contains(got[0], "t2") || !strings.Contains(got[0], "画封面") {
+		t.Fatalf("只该播报静默中的 t2，得到 %v", got)
+	}
+	if again := b.quietLines(); len(again) != 0 {
+		t.Fatalf("刚播过的任务不应立刻重复：%v", again)
+	}
+}
+
+// 子任务**内部**的事件只刷新活跃时间，不能把这一行当成收尾 —— 否则任务还在跑也被静音。
+// 回归：2026-10-21 实测 t2 内部读文件后静默十几分钟，一条心跳都没播。
+func TestBoardTouchKeepsRunningRowAlive(t *testing.T) {
+	b := newBoard(func(agent.StreamEvent) {})
+	t2 := Task{ID: "t2", Kind: KindImage, Title: "画封面"}
+	b.add(t2, Route{})
+	b.start(t2, "e", "")
+
+	b.mu.Lock()
+	b.last["t2"] = time.Now().Add(-time.Minute)
+	b.mu.Unlock()
+
+	b.touch("t2")
+	if got := b.quietLines(); len(got) != 0 {
+		t.Fatalf("刚有动静的任务不该被心跳播报：%v", got)
+	}
+	b.mu.Lock()
+	row := b.rows["t2"]
+	b.mu.Unlock()
+	if row == nil || row.Status != RowRunning {
+		t.Fatalf("内部事件不该改变这一行的状态，得到 %+v", row)
+	}
+
+	// 真正的收尾由 finish 落定（之后不再进心跳候选）。
+	b.finish(t2, TaskResult{ID: "t2", State: TaskDone})
+	b.mu.Lock()
+	b.last["t2"] = time.Now().Add(-time.Minute)
+	b.mu.Unlock()
+	if got := b.quietLines(); len(got) != 0 {
+		t.Fatalf("已收尾的任务不该被心跳播报：%v", got)
+	}
+}
+
+/*
+P0 核对闭环：交接单 + 验收命令 + 一次重试 + inputs 开跑前校验。
+
+四条各自的边界：
+  - inputs 只有「由 deps 声明为交付物」的才算硬依赖（否则计划里一处措辞就能断整条链）；
+  - 缺交付物 / 验收命令非零 → 重试一次（执行失败不重试，见 taskMaxAttempts）；
+  - 交接单取正文里最后一个 JSON 对象，解析不出就回落正文截断。
+*/
+
+func TestMissingInputsOnlyCountsHardDeps(t *testing.T) {
+	dir := t.TempDir()
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"brief.md"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"brief.md", "logo.png"}},
+	}}
+	// brief.md 由 deps 声明 → 硬依赖且当前不存在；logo.png 没人认领 → 只是提示。
+	got := MissingInputs(dir, plan, plan.Tasks[1])
+	if len(got) != 1 {
+		t.Fatalf("只该核对硬依赖，得到 %v", got)
+	}
+	if !strings.Contains(got[0], "brief.md") || !strings.Contains(got[0], "t1") {
+		t.Fatalf("缺失原因要能归因到产出者：%s", got[0])
+	}
+	// 文件补齐后放行。
+	if err := os.MkdirAll(TaskDir(dir, "t1"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(TaskDir(dir, "t1"), "brief.md"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got := MissingInputs(dir, plan, plan.Tasks[1]); len(got) != 0 {
+		t.Fatalf("文件已存在就不该报缺：%v", got)
+	}
+}
+
+func TestMissingInputsResolvesSubdirDeliverable(t *testing.T) {
+	dir := t.TempDir()
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"impl/fizzbuzz.js", "./test/fizzbuzz.test.js"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"impl/fizzbuzz.js"}},
+	}}
+	// 上游交付物在子目录里：只比 basename 会去找 t1/fizzbuzz.js，从而误报缺失。
+	specs := ResolveInputs(dir, plan, plan.Tasks[1])
+	if len(specs) != 1 || specs[0].Path != filepath.Join(TaskDir(dir, "t1"), "impl", "fizzbuzz.js") {
+		t.Fatalf("输入应按上游声明的子目录解析，得到 %+v", specs)
+	}
+	if got := MissingInputs(dir, plan, plan.Tasks[1]); len(got) != 1 {
+		t.Fatalf("文件确实不存在时要报缺，得到 %v", got)
+	}
+	p := filepath.Join(TaskDir(dir, "t1"), "impl", "fizzbuzz.js")
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got := MissingInputs(dir, plan, plan.Tasks[1]); len(got) != 0 {
+		t.Fatalf("子目录里的交付物已存在就不该报缺：%v", got)
+	}
+}
+
+func TestMissingInputsKeepsInsideTaskDir(t *testing.T) {
+	dir := t.TempDir()
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"../../etc/passwd"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"passwd"}},
+	}}
+	specs := ResolveInputs(dir, plan, plan.Tasks[1])
+	if len(specs) != 1 || specs[0].Path != filepath.Join(TaskDir(dir, "t1"), "passwd") {
+		t.Fatalf("越界声明应收窄到任务目录内的同名文件，得到 %+v", specs)
+	}
+}
+
+func TestTaskDocExplainsInputs(t *testing.T) {
+	dir := t.TempDir()
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"brief.md"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"brief.md", "mood.png"}},
+	}}
+	doc := TaskDoc(dir, plan, plan.Tasks[1], nil)
+	if !strings.Contains(doc, "## 输入") {
+		t.Fatalf("任务书缺输入区：\n%s", doc)
+	}
+	if !strings.Contains(doc, "由 t1 产出，**必须读到**") {
+		t.Fatalf("硬依赖要说清必须读到：\n%s", doc)
+	}
+	if !strings.Contains(doc, "没写明谁产出它") {
+		t.Fatalf("无来源的输入应当诚实说明：\n%s", doc)
+	}
+}
+
+func TestParseHandoffTakesLastObject(t *testing.T) {
+	text := "先看这段配置 {\"a\":1}\n\n做完了：\n```json\n" +
+		`{"files":["brief.md"],"summary":"写了正文","interface":"brief.md#L1","open":["缺封面"]}` +
+		"\n```\n"
+	h := parseHandoff(text)
+	if h == nil {
+		t.Fatal("应当解析出交接单")
+	}
+	if len(h.Files) != 1 || h.Files[0] != "brief.md" || h.Summary != "写了正文" || len(h.Open) != 1 {
+		t.Fatalf("交接单解析不对：%+v", h)
+	}
+	if parseHandoff("没有 JSON") != nil {
+		t.Fatal("解析不出应当返回 nil")
+	}
+	if parseHandoff(`{"a":1}`) != nil {
+		t.Fatal("全空字段的对象不算交接单")
+	}
+}
+
+func TestTaskDocPrefersHandoffOverBody(t *testing.T) {
+	dir := t.TempDir()
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Title: "上游"},
+		{ID: "t2", Kind: KindText, Title: "下游", Deps: []string{"t1"}, Prompt: "做事"},
+	}}
+	up := map[string]TaskResult{"t1": {
+		ID: "t1", Title: "上游", State: TaskDone,
+		Text:    strings.Repeat("很长很长的正文", 1000),
+		Handoff: &Handoff{Files: []string{"brief.md"}, Summary: "结论：用蓝色", Interface: "brief.md"},
+	}}
+	doc := TaskDoc(dir, plan, plan.Tasks[1], up)
+	if !strings.Contains(doc, "结论：用蓝色") {
+		t.Fatalf("应当渲染交接单：\n%s", doc)
+	}
+	if strings.Contains(doc, strings.Repeat("很长很长的正文", 100)) {
+		t.Fatal("有交接单时不该再灌整段正文")
+	}
+	if !strings.Contains(doc, filepath.Join(TaskDir(dir, "t1"), "brief.md")) {
+		t.Fatalf("交接单里的相对文件名要补成绝对路径：\n%s", doc)
+	}
+}
+
+// 缺交付物 → 重试一次；第二次交齐 → 完成，Attempts=2，提示词里要说明上次为什么没过。
+func TestRunRetriesOnceWhenDeliverableMissing(t *testing.T) {
+	eng := &fakeEngine{
+		name:       "fake-retry",
+		plan:       `{"goal":"g","tasks":[{"id":"t1","kind":"text","title":"写正文","prompt":"写 200 字","deliverables":["brief.md"]}]}`,
+		task:       "好的",
+		writeFiles: []string{"brief.md"},
+		writeFrom:  2, // 第一次不交，重试才交
+	}
+	install(t, eng)
+
+	opts := newOpts(t, eng, "")
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Tasks) != 1 || res.Tasks[0].State != TaskDone {
+		t.Fatalf("重试后应当完成，得到 %+v", res.Tasks)
+	}
+	if res.Tasks[0].Attempts != 2 {
+		t.Fatalf("应当记录 2 次尝试，得到 %d", res.Tasks[0].Attempts)
+	}
+	var prompts []string
+	for _, req := range eng.requests() {
+		if len(req.Messages) > 0 && strings.Contains(req.Messages[0].Content, taskDocAnchor) {
+			prompts = append(prompts, req.Messages[0].Content)
+		}
+	}
+	if len(prompts) != 2 {
+		t.Fatalf("应当跑两次，得到 %d", len(prompts))
+	}
+	if strings.Contains(prompts[0], "上一次尝试未通过") {
+		t.Fatal("首次尝试不该带重试说明")
+	}
+	if !strings.Contains(prompts[1], "上一次尝试未通过") || !strings.Contains(prompts[1], "缺少交付物") {
+		t.Fatalf("重试提示词要说清上次为什么没过：\n%s", prompts[1])
+	}
+	// OUT 留档：尝试次数 + 交付物核对。
+	out, err := os.ReadFile(OutputPath(res.RunDir, "t1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(out), "尝试：2 次") || !strings.Contains(string(out), "✓ `brief.md`") {
+		t.Fatalf("OUT 应记录重试与交付物：\n%s", out)
+	}
+}
+
+// 验收命令非零 → 判失败（重试后仍不过就是最终失败），并在 OUT 留证据。
+func TestRunFailsOnNonZeroCheck(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fake-check",
+		plan: `{"goal":"g","tasks":[{"id":"t1","kind":"text","title":"写正文","prompt":"写 200 字",
+		  "check":["test -s brief.md"]}]}`,
+		task: "我写完了（但没落文件）",
+	}
+	install(t, eng)
+
+	opts := newOpts(t, eng, "")
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	task := res.Tasks[0]
+	if task.State != TaskFailed {
+		t.Fatalf("验收命令非零应当判失败，得到 %s", task.State)
+	}
+	if !strings.Contains(task.Reason, "验收命令未通过") {
+		t.Fatalf("失败原因要指明验收命令：%s", task.Reason)
+	}
+	if task.Attempts != taskMaxAttempts {
+		t.Fatalf("验收不过应当重试到上限，得到 %d", task.Attempts)
+	}
+	out, err := os.ReadFile(OutputPath(res.RunDir, "t1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(out), "## 验收命令") || !strings.Contains(string(out), "✗ `test -s brief.md`") {
+		t.Fatalf("OUT 应留下验收命令结果：\n%s", out)
+	}
+}
+
+// 验收命令通过 → 正常完成（别把「能跑 check」实现成「有 check 就失败」）。
+func TestRunPassesWhenCheckSucceeds(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fake-check-ok",
+		plan: `{"goal":"g","tasks":[{"id":"t1","kind":"text","title":"写正文","prompt":"写 200 字",
+		  "deliverables":["brief.md"],"check":["test -s brief.md"]}]}`,
+		task:       "写好了",
+		writeFiles: []string{"brief.md"},
+	}
+	install(t, eng)
+
+	res, err := Run(context.Background(), newOpts(t, eng, ""))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Tasks[0].State != TaskDone || res.Tasks[0].Attempts != 1 {
+		t.Fatalf("验收通过应当一次完成，得到 %+v", res.Tasks[0])
+	}
+}
+
+// inputs 指向 deps 的交付物但文件不在 → 开跑前直接失败，不白跑一次模型。
+func TestRunTaskFailsFastOnMissingInput(t *testing.T) {
+	eng := &fakeEngine{name: "fake-input", task: "不该被调用"}
+	install(t, eng)
+	opts := newOpts(t, eng, "")
+	runDir := filepath.Join(opts.BaseDir, "run-in")
+
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"brief.md"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"brief.md"}},
+	}}
+	if err := os.MkdirAll(TaskDir(runDir, "t2"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	r := runTask(context.Background(), opts, plan, plan.Tasks[1], runDir, nil, newBoard(func(agent.StreamEvent) {}))
+	if r.State != TaskFailed {
+		t.Fatalf("缺上游输入应当失败，得到 %s", r.State)
+	}
+	if !strings.Contains(r.Reason, "缺少上游输入") || !strings.Contains(r.Reason, "t1") {
+		t.Fatalf("原因要能归因：%s", r.Reason)
+	}
+	if r.Attempts != 0 {
+		t.Fatalf("开跑前就失败，不该记尝试次数，得到 %d", r.Attempts)
+	}
+	if len(eng.requests()) != 0 {
+		t.Fatalf("开跑前核对失败不该调模型，实际调了 %d 次", len(eng.requests()))
+	}
+}
+
+// 交接单要单独落盘一份 JSON（下游 / 外部工具直接读），ARTS 里也带上尝试次数与验收结果。
+func TestWriteOutputPersistsHandoffAndChecks(t *testing.T) {
+	dir := t.TempDir()
+	r := TaskResult{
+		ID: "t1", Title: "标题", State: TaskDone, Attempts: 2,
+		Handoff: &Handoff{Files: []string{"brief.md"}, Summary: "写完了"},
+		Checks:  []CheckResult{{Cmd: "test -s brief.md", Code: 0}},
+	}
+	writeOutput(dir, r, []string{"brief.md"})
+
+	raw, err := os.ReadFile(HandoffPath(dir, "t1"))
+	if err != nil {
+		t.Fatalf("HANDOFF-t1.json 没写：%v", err)
+	}
+	var h Handoff
+	if err := json.Unmarshal(raw, &h); err != nil || h.Summary != "写完了" {
+		t.Fatalf("交接单 JSON 不对：%v %+v", err, h)
+	}
+	out, err := os.ReadFile(OutputPath(dir, "t1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"## 交接单", "## 验收命令", "尝试：2 次"} {
+		if !strings.Contains(string(out), want) {
+			t.Fatalf("OUT 缺 %q：\n%s", want, out)
+		}
+	}
+	var arts map[string]any
+	artsRaw, _ := os.ReadFile(ArtsPath(dir, "t1"))
+	if err := json.Unmarshal(artsRaw, &arts); err != nil {
+		t.Fatal(err)
+	}
+	if arts["attempts"] != float64(2) || arts["checks"] == nil {
+		t.Fatalf("ARTS 应带上 attempts/checks：%s", artsRaw)
+	}
+}
+
+// 计划阶段带结构化输出 schema；子任务不带（否则正文会被 JSON 替换掉）。
+func TestPlanRequestCarriesJSONSchema(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fake-schema",
+		plan: `{"goal":"g","tasks":[{"id":"t1","kind":"text","title":"写","prompt":"写一段"}]}`,
+		task: "写好了",
+	}
+	install(t, eng)
+	if _, err := Run(context.Background(), newOpts(t, eng, "")); err != nil {
+		t.Fatal(err)
+	}
+	reqs := eng.requests()
+	if reqs[0].JSONSchema == nil {
+		t.Fatal("计划请求应当带 JSONSchema")
+	}
+	if got := strings.Join(reqs[0].JSONSchema.Required, ","); got != "goal,tasks" {
+		t.Fatalf("计划 schema 的必填字段应为 goal,tasks，得到 %s", got)
+	}
+	for _, req := range reqs[1:] {
+		if req.JSONSchema != nil {
+			t.Fatalf("子任务 / 汇总请求不该带 JSONSchema（会吞掉正文）：%+v", req.JSONSchema)
+		}
+	}
+}
+
+func TestHandoffRequiredOnlyForHardInputs(t *testing.T) {
+	plan := Plan{Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"brief.md"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"brief.md"}},
+		{ID: "t3", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"mood.png"}},
+	}}
+	if !handoffRequired(plan, "t1") {
+		t.Fatal("交付物被下游当硬输入时应强制交接单")
+	}
+	if handoffRequired(plan, "t2") {
+		t.Fatal("叶子任务不该强制交接单")
+	}
+	// 只写了 deps 没写 inputs（软提示）→ 不强制。
+	soft := Plan{Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"brief.md"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}},
+	}}
+	if handoffRequired(soft, "t1") {
+		t.Fatal("deps 没声明 inputs 时不该强制交接单")
+	}
+}
+
+func TestHandoffProblemsChecksSchema(t *testing.T) {
+	plan := Plan{Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p", Deliverables: []string{"brief.md"}},
+		{ID: "t2", Kind: KindText, Prompt: "p", Deps: []string{"t1"}, Inputs: []string{"brief.md"}},
+	}}
+	// 完全没交接单。
+	if got := handoffProblems(plan, plan.Tasks[0], &TaskResult{}); len(got) == 0 {
+		t.Fatal("缺交接单应当报问题")
+	}
+	// 缺 summary。
+	got := handoffProblems(plan, plan.Tasks[0], &TaskResult{Handoff: &Handoff{Files: []string{"brief.md"}}})
+	if len(got) == 0 || !strings.Contains(got[0], "summary") {
+		t.Fatalf("缺 summary 应当报问题，得到 %v", got)
+	}
+	// 齐了。
+	ok := &TaskResult{Handoff: &Handoff{Files: []string{"brief.md"}, Summary: "完成"}}
+	if got := handoffProblems(plan, plan.Tasks[0], ok); len(got) != 0 {
+		t.Fatalf("交接单齐全时不该报问题，得到 %v", got)
+	}
+}
+
+// 被下游当硬输入的产出者：交接单不全 → 复用一次重试；补齐后通过。
+func TestRunRetriesWhenHandoffIncomplete(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fake-handoff",
+		plan: `{"goal":"g","tasks":[
+		  {"id":"t1","kind":"text","title":"写正文","prompt":"写 200 字","deliverables":["brief.md"]},
+		  {"id":"t2","kind":"text","title":"写摘要","prompt":"写 50 字","deps":["t1"],"inputs":["brief.md"]}]}`,
+		taskSeq: []string{
+			"写好了", // 第一次正文里没有交接单
+			"写好了\n```json\n{\"files\":[\"brief.md\"],\"summary\":\"正文已完成\"}\n```",
+		},
+		writeFiles: []string{"brief.md"},
+	}
+	install(t, eng)
+
+	res, err := Run(context.Background(), newOpts(t, eng, ""))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t1 := res.Tasks[0]
+	if t1.State != TaskDone || t1.Attempts != 2 {
+		t.Fatalf("交接单不全应重试一次后通过，得到 state=%s attempts=%d reason=%s",
+			t1.State, t1.Attempts, t1.Reason)
+	}
+	// 重试提示词里要写清上次为什么没过。
+	reqs := eng.requests()
+	var retry string
+	for _, req := range reqs {
+		if len(req.Messages) > 0 && strings.Contains(req.Messages[0].Content, "上一次尝试未通过") {
+			retry = req.Messages[0].Content
+		}
+	}
+	if !strings.Contains(retry, "交接单") {
+		t.Fatalf("重试提示词应说明交接单问题，得到 %q", retry)
+	}
+	if res.Tasks[1].State != TaskDone {
+		t.Fatalf("下游任务应正常完成，得到 %+v", res.Tasks[1])
+	}
+}
+
+// 再规划的信号只认两类：必需任务失败、已完成任务的交接单 open 项。
+func TestAdaptiveSignals(t *testing.T) {
+	optional := false
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Title: "写正文", Prompt: "p"},
+		{ID: "t2", Kind: KindText, Title: "配图", Prompt: "p", Required: &optional},
+		{ID: "t3", Kind: KindText, Title: "改稿", Prompt: "p"},
+		{ID: "t4", Kind: KindText, Title: "出稿", Prompt: "p"},
+		{ID: "t5", Kind: KindText, Title: "归档", Prompt: "p"},
+	}}
+	results := []TaskResult{
+		{ID: "t1", State: TaskFailed, Reason: "缺交付物"},
+		{ID: "t2", State: TaskFailed, Reason: "可选任务失败"}, // required=false：不补
+		{ID: "t3", State: TaskSkipped, Reason: "上游失败"},  // 级联结果：不补
+		{ID: "t4", State: TaskDone, Handoff: &Handoff{Open: []string{
+			"封面还没配", "标题待定", "字数不足", "第四条不该进提示词",
+		}}},
+		{ID: "t5", State: TaskDone}, // 没有交接单：无信号
+	}
+	got := adaptiveSignals(plan, results)
+	if len(got) != 2 {
+		t.Fatalf("应当只有 2 条信号（失败 t1 + open t4），得到 %d 条：%v", len(got), got)
+	}
+	if !strings.Contains(got[0], "t1") || !strings.Contains(got[0], "缺交付物") {
+		t.Fatalf("失败信号应带上任务与原因，得到 %q", got[0])
+	}
+	if !strings.Contains(got[1], "封面还没配") || strings.Contains(got[1], "第四条") {
+		t.Fatalf("open 项应最多取 %d 条，得到 %q", adaptiveOpenPerTask, got[1])
+	}
+}
+
+// 补充任务的 id 重编号、deps 收窄、无效项过滤。
+func TestNormalizeAdaptiveTasks(t *testing.T) {
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Prompt: "p"},
+		{ID: "a1", Kind: KindText, Prompt: "p"}, // 已占用 → 不能覆盖
+	}}
+	got, dropped := normalizeAdaptiveTasks([]Task{
+		{ID: "x1", Role: "视觉", Prompt: "补封面", Deps: []string{"t1", "x2"}},
+		{ID: "x0", Prompt: "  "}, // 空 prompt：丢弃
+		{ID: "x2", Prompt: "补文案", Deps: []string{"x1"}},
+		{ID: "x3", Prompt: "补一"},
+		{ID: "x4", Prompt: "补二"}, // 超过 adaptiveMaxTasks：丢弃
+	}, plan)
+	if dropped != 0 {
+		t.Fatalf("没有同名补充任务时应返回 0，得到 %d", dropped)
+	}
+
+	if len(got) != adaptiveMaxTasks {
+		t.Fatalf("应当保留 %d 个补充任务，得到 %d 个：%+v", adaptiveMaxTasks, len(got), got)
+	}
+	// a1 已被原计划占用 → 从 a2 开始编号。
+	wantIDs := []string{"a2", "a3", "a4"}
+	for i, want := range wantIDs {
+		if got[i].ID != want {
+			t.Fatalf("第 %d 个补充任务 id 应为 %s，得到 %s", i, want, got[i].ID)
+		}
+	}
+	// 指向原任务的 dep 被丢弃；指向本批的 dep 重映射。
+	if len(got[0].Deps) != 1 || got[0].Deps[0] != "a3" {
+		t.Fatalf("a2 的 deps 应当只剩重映射后的 a3，得到 %v", got[0].Deps)
+	}
+	if len(got[1].Deps) != 1 || got[1].Deps[0] != "a2" {
+		t.Fatalf("a3 的 deps 应当只剩重映射后的 a2，得到 %v", got[1].Deps)
+	}
+	if len(got[2].Deps) != 0 {
+		t.Fatalf("a4 没有依赖，得到 %v", got[2].Deps)
+	}
+	// 归一化同样生效（角色 → 类别）。
+	if got[0].Role != "designer" || got[0].Kind != KindImage {
+		t.Fatalf("补充任务也应过 normalizeTask，得到 role=%q kind=%q", got[0].Role, got[0].Kind)
+	}
+}
+
+// 与原任务同名的补充任务等同重试，应当丢弃：否则任务卡上会多出一行同名任务
+// （2026-10-22 实测 t1/a1、t2/a2、t3/a3 各自并列两行）。
+func TestNormalizeAdaptiveTasksDropsSameTitle(t *testing.T) {
+	plan := Plan{Goal: "g", Tasks: []Task{
+		{ID: "t1", Kind: KindText, Title: "实现fizzbuzz", Prompt: "p"},
+		{ID: "t2", Kind: KindText, Title: "编写测试", Prompt: "p"},
+	}}
+	got, dropped := normalizeAdaptiveTasks([]Task{
+		{ID: "x1", Title: " 实现FizzBuzz ", Prompt: "再做一遍"},
+		{ID: "x2", Title: "补测试断言", Prompt: "补断言"},
+		{ID: "x3", Title: "补测试断言", Prompt: "同名再提一次"},
+	}, plan)
+	if dropped != 2 {
+		t.Fatalf("应当丢弃 2 个同名补充任务，得到 %d", dropped)
+	}
+	if len(got) != 1 || got[0].Title != "补测试断言" || got[0].ID != "a1" {
+		t.Fatalf("只该保留不同名的那一个，得到 %+v", got)
+	}
+}
+
+// 端到端：必需任务失败 → 再规划一轮 → 追加 a1 并执行 → 汇总包含补充任务。
+func TestRunAdaptiveAppendsReplanTasks(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fake-adaptive",
+		plan: `{"goal":"g","tasks":[
+		  {"id":"t1","kind":"text","title":"写正文","prompt":"写正文","check":["test -f never.txt"]}]}`,
+		task: "做完了",
+		replan: `{"goal":"g","tasks":[
+		  {"id":"x1","kind":"text","title":"补正文","prompt":"重新写一版正文","deps":["t1"]}]}`,
+	}
+	install(t, eng)
+
+	opts := newOpts(t, eng, "")
+	opts.Adaptive = true
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Tasks) != 2 {
+		t.Fatalf("应当追加 1 个补充任务，得到 %d 个：%+v", len(res.Tasks), res.Tasks)
+	}
+	if res.Tasks[0].State != TaskFailed {
+		t.Fatalf("t1 的 check 应当失败，得到 %+v", res.Tasks[0])
+	}
+	if res.Tasks[1].ID != "a1" || res.Tasks[1].State != TaskDone {
+		t.Fatalf("补充任务应为 a1 且完成，得到 %+v", res.Tasks[1])
+	}
+
+	var replanReq, extraReq *agent.Request
+	reqs := eng.requests()
+	for i := range reqs {
+		req := &reqs[i]
+		if req.Workspace == "" && strings.Contains(req.SystemPrompt, adaptiveMarker) {
+			replanReq = req
+		}
+		if req.Workspace != "" && len(req.Messages) > 0 &&
+			strings.Contains(req.Messages[0].Content, "重新写一版正文") {
+			extraReq = req
+		}
+	}
+	if replanReq == nil {
+		t.Fatal("没有发出再规划请求")
+	}
+	if replanReq.JSONSchema == nil {
+		t.Fatal("再规划请求应当带计划 schema")
+	}
+	if extraReq == nil {
+		t.Fatal("补充任务没有真正执行")
+	}
+	// 原任务已跑完，指向它的 dep 必须先被丢掉，否则整批校验会失败。
+	if extraReq.Messages[0].Content == "" {
+		t.Fatal("补充任务提示词为空")
+	}
+	planDoc, err := os.ReadFile(PlanPath(res.RunDir))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(planDoc), "a1") {
+		t.Fatalf("PLAN.md 应重写成含补充任务的完整集合：\n%s", planDoc)
+	}
+}
+
+// 没有信号时不该多调一次模型（成功轮次不能被再规划打扰）。
+func TestRunAdaptiveSkipsWhenNoSignal(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fake-adaptive-clean",
+		plan: `{"goal":"g","tasks":[{"id":"t1","kind":"text","title":"写","prompt":"写"}]}`,
+		task: "写好了",
+	}
+	install(t, eng)
+	opts := newOpts(t, eng, "")
+	opts.Adaptive = true
+	if _, err := Run(context.Background(), opts); err != nil {
+		t.Fatal(err)
+	}
+	for _, req := range eng.requests() {
+		if strings.Contains(req.SystemPrompt, adaptiveMarker) {
+			t.Fatal("没有未解决项时不该发再规划请求")
+		}
+	}
+	if len(eng.requests()) != 3 {
+		t.Fatalf("一次计划 + 一次子任务 + 一次汇总 = 3 次调用，得到 %d 次", len(eng.requests()))
+	}
+}
+
+// 再规划输出不可解析时：记一条 notice 收尾，不把整轮变成错误。
+func TestRunAdaptiveIgnoresBadReplan(t *testing.T) {
+	eng := &fakeEngine{
+		name: "fake-adaptive-bad",
+		plan: `{"goal":"g","tasks":[
+		  {"id":"t1","kind":"text","title":"写","prompt":"写","check":["test -f never.txt"]}]}`,
+		task:   "做完了",
+		replan: "我觉得不用补了", // 没有 JSON 对象
+	}
+	install(t, eng)
+	opts := newOpts(t, eng, "")
+	opts.Adaptive = true
+	res, err := Run(context.Background(), opts)
+	if err != nil {
+		t.Fatalf("再规划失败不该让整轮报错：%v", err)
+	}
+	if len(res.Tasks) != 1 {
+		t.Fatalf("再规划失败时应保持原结果，得到 %+v", res.Tasks)
+	}
+	if res.Text == "" {
+		t.Fatal("仍然应当汇总出正文")
+	}
+}