dsh-plugin-teamflow 0.1.2 → 0.1.4

package/lib/host.mjs

@@ -4,8 +4,8 @@ import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { parameterSchemaSpecToJsonSchema } from "@deepseek-ai/dsh-tools";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { execFileSync } from "node:child_process";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
 //#region host/constants.ts
 /** 单阶段 token 熔断预算（官方口径总消耗：input+cacheRead+cacheWrite+output 累计）。 */
 const STAGE_TOKEN_BUDGET = 6e4;
@@ -260,6 +260,17 @@ const SAFE_SIGNAL = {
 function normalizeSignal(s) {
 	return s && typeof s === "object" && typeof s.addEventListener === "function" && typeof s.aborted === "boolean" ? s : SAFE_SIGNAL;
 }
+/** 分支 slug 派生（ADR-2026-08-27）：branchName > triageSlug > 需求中的英文标识词 > reqId 数字 > 'feature'。
+* 实锤 feat/feature：lite 显式时 triage 不跑（无 slug）+ 分支检查早于 reqId 生成 → fallback 'feature'。 */
+function deriveBranchSlug(requirement, reqId, triageSlug, branchName) {
+	if (branchName && /^[a-z0-9][a-z0-9-_]*$/i.test(branchName)) return String(branchName).replace(/[^a-z0-9-]/gi, "-").toLowerCase().slice(0, 40);
+	if (triageSlug && /^[a-z0-9-]{3,24}$/i.test(triageSlug)) return triageSlug;
+	const en = String(requirement || "").match(/[a-zA-Z][a-zA-Z0-9-]{2,23}/g);
+	if (en && en.length) return en[0].toLowerCase().slice(0, 40);
+	const num = String(reqId || "").match(/\d+/);
+	if (num) return `r${num[0]}`;
+	return "feature";
+}
 /** 产出物实质校验：非空 + 无拒绝词 + 达到阶段长度下限。 */
 function hasSubstance(phase, text) {
 	if (!text || !text.trim()) return false;
@@ -267,10 +278,11 @@ function hasSubstance(phase, text) {
 	const min = STAGE_MIN_LENGTH[phase] ?? 100;
 	return text.trim().length >= min;
 }
-/** 不可重试的失败原因（上下文耗尽/超长等——重试同一 prompt 大概率复现）。 */
+/** 不可重试的失败原因（上下文耗尽/超长/provider 客户端拒绝等——重试同一 prompt 大概率复现）。
+* 实锤 tf-mtcnejqj：opencode-go 400 invalid_request_error（tool 消息序列非法）被当作可重试 → 烧 1.98M 熔断。 */
 function isUnretryable(reason, outcome) {
 	const r = String(reason || outcome || "");
-	return /context|limit|max-token|token|tool-error/i.test(r);
+	return /context|limit|max-token|token|tool-error|400|invalid_request|INVALID_REQUEST/i.test(r);
 }
 /** 阶段产出 → 精简交接摘要（供审计/展示；产出含显式 <!-- handoff --> 块则优先取块内内容）。 */
 function handoffBrief(text) {
@@ -381,12 +393,13 @@ function extractBlueprint(text) {
 */
 /** 子代理/计量等宿主能力（由 TeamflowService 装配时 setRuntime 注入）。字段为鸭子类型：消费方自行窄化。 */
 const runtime = {};
-function setRuntime(agents, subagents, tokenMeter, workspaceRegistry, agentDefaultModel) {
+function setRuntime(agents, subagents, tokenMeter, workspaceRegistry, agentDefaultModel, llm) {
 	runtime.agents = agents;
 	runtime.subagents = subagents;
 	runtime.tokenMeter = tokenMeter;
 	runtime.workspaceRegistry = workspaceRegistry;
 	runtime.agentDefaultModel = agentDefaultModel;
+	runtime.llm = llm;
 }
 /** 运行期 run 注册表（runId → Journal）。 */
 const runs = /* @__PURE__ */ new Map();
@@ -405,6 +418,32 @@ function providerName() {
 	return names.length > 0 ? names[0] : null;
 }
 /**
+* 探测指定 provider/model 是否支持图像输入（多模态）。
+* 用途：QA/验收的视觉验证条款按能力条件化——不支持视觉的模型禁止「截图看图」（防幻觉/循环），
+* 只走 DOM 计算断言（evaluate 返回文本）；探测失败/未知 → false（安全侧）。
+*/
+async function currentModelSupportsVision(provider, model) {
+	try {
+		const llm = runtime.llm;
+		if (!llm || typeof llm.resolveModelInfo !== "function") return false;
+		const p = provider && provider.trim() || providerName();
+		const m = model && model.trim() || (() => {
+			const adm = runtime.agentDefaultModel;
+			if (adm && typeof adm.currentSelection === "function") try {
+				return adm.currentSelection()?.model;
+			} catch (e) {
+				return;
+			}
+			return adm?.model;
+		})();
+		if (!p || !m) return false;
+		const info = await llm.resolveModelInfo(p, m);
+		return !!info && Array.isArray(info.inputModalities) && info.inputModalities.includes("image");
+	} catch (e) {
+		return false;
+	}
+}
+/**
 * 从发起会话推导工作区作用域。
 *
 * 优先级：
@@ -932,6 +971,17 @@ function verifyReqBugs(journal) {
 	}
 	if (touched) store.persist();
 }
+/** 该需求是否存在未闭环的阻断缺陷（P0/P1/P2 仍 open）——resume 断点定位与 QA 复用判定依赖。
+* 实锤 run tf-mte906e9：QA 修复子代理失败 → run failed，但 QA 阶段本身 done（缺陷已登记），
+* 旧 interruptedPhaseOf 直接定位产品验收 → 带缺陷代码进验收。
+* ⚠️ store key 与 resumeRun/storeFor 解析一致（workspace || product || default），否则查错 store 误判无缺陷。 */
+function hasOpenBlockingBugs(journal) {
+	try {
+		return storeFor(journal.workspace || journal.product || "default").bugs.some((b) => b.reqId === journal.reqId && b.status === "open" && b.severity !== "P3");
+	} catch (e) {
+		return false;
+	}
+}
 /** 默认团队配置文件内容。 */
 const DEFAULT_TEAMS_FILE = {
 	version: 1,
@@ -1030,6 +1080,79 @@ function getActiveStages(team, options) {
 	});
 }
 //#endregion
+//#region host/core/sanity.ts
+/**
+* dsh-plugin-teamflow core — M0 状态核对（sanity check）。
+*
+* 目的（三情况协议）：
+* - 情况一（全新会话）：0 认知 → 核对确认"从零开始"。
+* - 情况二（续会话）：认知大概率过期（多人协作/场外提交/非流水线改动）→ 核对发现预期外变化。
+* - 情况三（新会话处理新需求）：即使共用 state/记忆，仓库也可能被外部改动 → 核对现状。
+*
+* 核心原则：认知资产（索引/记忆/摘要）可复用"减量"，但永不能替代"对代码库当前真实状态的核对"。
+* 本模块在 host 侧直接跑 git（零模型 token、轻量、失败优雅降级为"无法核对"），
+* 产出 externalDiffs 摘要注入到后续所有阶段 prompt。
+*/
+/** 单条 git 检查结果（失败返回 null，调用方降级）。 */
+function gitCmd(cwd, args, timeoutMs = 8e3) {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf8",
+			timeout: timeoutMs,
+			windowsHide: true
+		}).trim();
+	} catch (e) {
+		return null;
+	}
+}
+/**
+* 跑一次状态核对。
+* @param path - 工作区绝对路径（workspaceScopeOf(agent).path）。
+*/
+function runSanityCheck(path) {
+	const defaultOut = {
+		ok: false,
+		inRepo: false,
+		branch: null,
+		dirty: "",
+		hasDirty: false,
+		recentCommits: "",
+		summary: ""
+	};
+	if (!path) return {
+		...defaultOut,
+		summary: "⚠ 无法确定工作区路径，未做状态核对。"
+	};
+	const branch = gitCmd(path, ["branch", "--show-current"]);
+	const status = gitCmd(path, ["status", "--short"]);
+	if (branch === null && status === null) return {
+		...defaultOut,
+		summary: "⚠ 状态核对不可用（非 git 仓库或 git 命令被拒），无法确认代码库真实状态。"
+	};
+	const recent = gitCmd(path, [
+		"log",
+		"--oneline",
+		"-5"
+	]);
+	const dirty = status || "";
+	const dirtyLines = dirty.split("\n").filter(Boolean);
+	const summaryParts = [];
+	summaryParts.push(`分支：${branch && branch !== "HEAD" ? branch : "(detached HEAD / 非分支)"}`);
+	if (dirtyLines.length) summaryParts.push(`未提交改动 ${dirtyLines.length} 处：${dirtyLines.slice(0, 8).join("；")}${dirtyLines.length > 8 ? "…" : ""}`);
+	else summaryParts.push("工作区干净（无未提交改动）");
+	if (recent) summaryParts.push(`近期提交（可能含场外改动）：${recent.split("\n").slice(0, 3).join("；")}`);
+	return {
+		ok: true,
+		inRepo: true,
+		branch: branch && branch !== "HEAD" ? branch : null,
+		dirty,
+		hasDirty: dirtyLines.length > 0,
+		recentCommits: recent || "",
+		summary: `【状态核对】${summaryParts.join("。")}`
+	};
+}
+//#endregion
 //#region host/core/metering.ts
 /**
 * 累计子代理会话中所有 LLM 调用的真实 usage（官方三桶 + 调用数）。
@@ -1083,16 +1206,25 @@ function totalTokensOf(usage) {
 *    的健康节奏工作到第 25 分钟被击落（tf-mt8fbavd dev 尝试一）。
 *
 * 设计原则：【只看进度信号，无任何时间配额】慢吞吐的合法任务永远不该被打断：
-*  A. 复读检测：滑动窗口内同一规范化流式片段出现 ≥ GUARD_REPEAT_LIMIT 次（逐字复读 = 真退化）
-*     → outcome='degenerated'（豁免预算门，允许一次干净重试）。
+*  A. 复读检测：滑动窗口内同一规范化流式片段出现 ≥ GUARD_REPEAT_LIMIT 次，且窗口内零变更进展
+*     （无 edit/write 等写操作）→ 真退化（纯推理打转）→ outcome='degenerated'（豁免预算门，允许一次干净重试）。
+*     ⚠️ 状态判定（实锤 run tf-mte906e9）：大文件 read-edit 循环是正常模式——模型反复 read 同一大文件
+*     （每次 edit 后内容已变，必须重读确认）、输出高度相似的「读后分析」，逐字片段在 400 条窗口内
+*     可累积 ≥12 次——伴随 edit/write 变更调用时只记录观察，不中止（否则大文件修改任务全被误杀）。
 *  B. 挂死检测：连续 GUARD_SILENCE_MS 一个新事件都没有（provider 层挂起/连接静默死亡）
 *     → outcome='stalled'（走正常预算门 → 熔断转人工，不自动重试烧钱）。
 *  C. 空转检测：会话仍在产出事件，但连续 GUARD_NO_TOOL_MS 没有任何工具调用
 *    （纯推理打转/改写式循环；正常 agent 每分钟都在调工具）→ outcome='stalled'。
+*    兜底关系：复读判定放宽后，edit 后陷入死循环的漏网场景由 C（长时间无工具调用）兜住。
 *
 * 中止方式：run.dispose() → run.result 结算。outcome 命名刻意避开 isUnretryable 的
 * /token|context|limit/ 正则；只有 'degenerated' 享受干净重试豁免（runner.withRetry）。
 */
+/** 进展工具（复读状态判定）：变更类写操作 + 脚本执行。
+* 「有进展」= 大文件 read-edit 循环（dev）或只读分析任务的 read+跑脚本循环（QA/验收）均属正常模式；
+* 纯 read 循环（反复整读同一文件却无变更/无脚本执行）= 真退化。实锤 run tf-mte906e9：QA 重跑
+* 只读分析（不 edit）→ 旧判定「零变更进展」误杀，第 2 次 provider error 后 450k 熔断。 */
+const PROGRESS_TOOLS = /^(edit|write|create|apply_patch|patch|remove|delete|rm|mkdir|move|rename|append|bash|pwsh|shell|powershell)$/i;
 /** 与 metering 同款事件访问器（session.events 可能是数组或返回数组的函数）。 */
 function eventsOf(run) {
 	const local = run && run.localAgent;
@@ -1106,6 +1238,38 @@ function eventsOf(run) {
 function normalizeFragment(s) {
 	return String(s || "").toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "");
 }
+/** 观测→执行闭环：向运行中的子代理注入轻提醒（不打断，下一轮 step 可见）。
+* 通道：subagents.start 句柄无 inject——用 DSH 官方 session.append('user/message')（in-process driver 同款用法）。
+* ⚠️ 安全窗口（实锤 tf-mtcnejqj）：绝不能插在 assistant(tool_calls) → tool/result 之间——
+* provider 校验「tool 消息必须响应前序 tool_calls」，插入 user 消息会 400 invalid_request_error。
+* 因此只入队（pendingInjects），在观察到 step/end（该 step 的 tool/result 已写入）后统一 flush。 */
+function injectReminder(run, text) {
+	const queue = run;
+	try {
+		if (!Array.isArray(queue.__teamflowPending)) queue.__teamflowPending = [];
+		queue.__teamflowPending.push(text);
+	} catch (e) {}
+}
+function flushReminders(run) {
+	try {
+		const queue = run.__teamflowPending;
+		if (!queue || queue.length === 0) return;
+		const local = run.localAgent;
+		if (!local || typeof local.session?.append !== "function") return;
+		for (const text of queue.splice(0)) local.session.append("user/message", {
+			id: crypto.randomUUID(),
+			role: "user",
+			content: [{
+				type: "text",
+				text
+			}],
+			source: {
+				kind: "plugin",
+				plugin: "teamflow"
+			}
+		}, { surfaceOp: "append" });
+	} catch (e) {}
+}
 /**
 * 启动单调用护栏轮询，返回取消函数（runAgent finally 必须调用）。
 * 触发时：stage.guardReason/guardOutcome 记录原因 + journal 落日志 + dispose 中止本次尝试。
@@ -1123,7 +1287,9 @@ function startStageGuard(opts) {
 	const warnedReads = /* @__PURE__ */ new Set();
 	const scriptCounts = /* @__PURE__ */ new Map();
 	const warnedScripts = /* @__PURE__ */ new Set();
-	function warnOnce(key, set, message) {
+	let lastMutationAt = 0;
+	let repeatWarned = false;
+	function warnOnce(key, set, message, hint) {
 		if (set.has(key)) return;
 		set.add(key);
 		try {
@@ -1133,6 +1299,7 @@ function startStageGuard(opts) {
 				message: `${label} [token 观测] ${message}`
 			});
 		} catch (e) {}
+		if (hint) injectReminder(run, `[TOKEN GUARD · reminder] ${hint}`);
 	}
 	function fire(reason, outcome) {
 		if (fired) return;
@@ -1155,37 +1322,60 @@ function startStageGuard(opts) {
 		if (fired || journal.cancelled) return;
 		try {
 			const events = eventsOf(run);
-			for (const ev of events.slice(-400)) {
-				const e = ev;
-				if (!e || e.type !== "text-chunks" && e.type !== "reasoning-chunks") continue;
-				const arr = e.data && e.data.texts || e.texts;
-				if (!Array.isArray(arr)) continue;
-				for (const t of arr) {
-					const s = normalizeFragment(String(t));
-					if (s.length < 12) continue;
-					window.push(s);
+			if (events.length > processed) {
+				const newEvents = events.slice(processed);
+				for (const ev of newEvents) {
+					const e = ev;
+					if (!e) continue;
+					let streamText = null;
+					if (e.type === "text-chunks" || e.type === "reasoning-chunks") {
+						const arr = e.data && e.data.texts || e.texts;
+						if (Array.isArray(arr)) streamText = arr.map(String).join("");
+					} else if (e.type === "assistant/chunk") {
+						const chunk = e.data && e.data.chunk || null;
+						if (chunk && (chunk.type === "text-delta" || chunk.type === "reasoning-delta") && typeof chunk.text === "string") streamText = chunk.text;
+					}
+					if (streamText !== null && streamText.length > 0) {
+						const s = normalizeFragment(streamText);
+						if (s.length >= 12) window.push(s);
+						lastGrowthAt = Date.now();
+					}
 				}
-				lastGrowthAt = Date.now();
-			}
-			if (window.length > 400) window.splice(0, window.length - 400);
-			const counts = /* @__PURE__ */ new Map();
-			for (const w of window) counts.set(w, (counts.get(w) || 0) + 1);
-			for (const [, n] of counts) if (n >= 12) {
-				fire(`推理复读（同一片段在近 ${window.length} 条流式片段中出现 ${n} 次）`, "degenerated");
-				return;
+				if (window.length > 400) window.splice(0, window.length - 400);
+				const counts = /* @__PURE__ */ new Map();
+				for (const w of window) counts.set(w, (counts.get(w) || 0) + 1);
+				for (const [, n] of counts) if (n >= 12) {
+					if (lastMutationAt > 0) {
+						if (!repeatWarned) {
+							repeatWarned = true;
+							try {
+								journal.logs.push({
+									t: Date.now(),
+									level: "warn",
+									message: `${label} 复读计数达阈值但检测到变更进展（read-edit 循环属正常模式），不中止；仅零变更进展的纯复读才中止`
+								});
+							} catch (e) {}
+						}
+					} else {
+						fire(`推理复读（同一片段在近 ${window.length} 条流式片段中出现 ${n} 次，且窗口内零变更进展）`, "degenerated");
+						return;
+					}
+				}
+				observeToolCalls(newEvents);
+				if (newEvents.some((ev) => ev?.type === "step/end")) flushReminders(run);
+				processed = events.length;
 			}
 			for (const ev of events.slice(-200)) {
 				const e = ev;
-				if (e && (e.type === "tool-call-chunks" || e.type === "tool/call")) {
+				if (!e) continue;
+				if (e.type === "tool-call-chunks" || e.type === "tool/call") {
 					seenToolCall = true;
 					lastToolSignalAt = Date.now();
+					const d = e.data || e;
+					if (d && typeof d.name === "string" && PROGRESS_TOOLS.test(d.name)) lastMutationAt = Date.now();
 					break;
 				}
 			}
-			if (events.length > processed) {
-				observeToolCalls(events.slice(processed));
-				processed = events.length;
-			}
 			if (events.length !== lastEventCount) {
 				lastEventCount = events.length;
 				lastGrowthAt = Date.now();
@@ -1213,14 +1403,14 @@ function startStageGuard(opts) {
 				const key = m[1].replace(/\\\\/g, "\\").toLowerCase();
 				const n = (readCounts.get(key) || 0) + 1;
 				readCounts.set(key, n);
-				if (n === 3) warnOnce(key, warnedReads, `同一文件重复 read ${n} 次：${m[1].split(/[\\\\/]/).pop()}（TOKEN_HYGIENE 上限 1 次，多余读取在为后续每一步付 cache 重放费）`);
+				if (n === 3) warnOnce(key, warnedReads, `同一文件重复 read ${n} 次：${m[1].split(/[\\\\/]/).pop()}（TOKEN_HYGIENE 上限 1 次，多余读取在为后续每一步付 cache 重放费）`, `你已整读 ${m[1].split(/[\\\\/]/).pop()} 第 3 次（TOKEN_HYGIENE 上限 1 次）。停止整读：需要确认细节时用 grep 定位行号 + 限量片段读取。`);
 			} else if (/bash|pwsh|shell|powershell/i.test(name || "")) {
 				const sm = String(args).match(/(verify-[a-z0-9-]+\.cjs|assembly-check\.cjs|qa-e2e-jsdom\.cjs)/);
 				if (!sm) continue;
 				const key = sm[1];
 				const n = (scriptCounts.get(key) || 0) + 1;
 				scriptCounts.set(key, n);
-				if (n === 3) warnOnce(key, warnedScripts, `验证脚本重复执行 ${n} 次：${key}（批量修复纪律：一次修完所有失败再跑，≤3 轮）`);
+				if (n === 3) warnOnce(key, warnedScripts, `验证脚本重复执行 ${n} 次：${key}（批量修复纪律：一次修完所有失败再跑，≤3 轮）`, `验证脚本 ${key} 已重复执行 3 次。遵守批量修复纪律：一次读完所有失败用例 → 一次全修 → 再跑一次；超出 3 轮请输出诊断摘要并停止。`);
 			}
 		}
 	}
@@ -1453,7 +1643,20 @@ async function withRetry(journal, parent, label, phase, prompt, signal) {
 				stageTokens
 			};
 		}
-		if (!!!(lastStage && lastStage.outcome === "degenerated") && stageTokens >= 6e4) {
+		if (lastStage && lastStage.outcome === "degenerated") {
+			journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: `${label} 进行中护栏中止（退化/推理复读），不再自动重试（污染会话内重试大概率复现且烧钱）；可 teamflow_resume 以全新会话续跑`
+			});
+			journal.humanIntervention = true;
+			return {
+				text: null,
+				attempts,
+				stageTokens
+			};
+		}
+		if (stageTokens >= 6e4) {
 			journal.logs.push({
 				t: Date.now(),
 				level: "error",
@@ -1889,10 +2092,24 @@ ${clip(tech, 12e3)}` : ""}
 3. If spec contradicts reality, explain with evidence in the summary instead of claiming completion or expanding scope on your own.
 4. Actually write/modify code (grep + segmented reads to locate; no repeated whole-file reads), then run relevant build/verification to ensure green.
 5. [Engineering action execution] If task spec or PRD 工程约束 includes git actions (e.g. new branch): **execute the action BEFORE writing code** (e.g. git checkout -b <branch>); if the workspace carries unrelated uncommitted changes, do NOT commit/clean them — state the situation in the summary.
+5b. [Git discipline · hard (ADR-2026-08-27, 统一收口提交)] Work ONLY on the current branch: **never** git checkout main / merge / rebase / delete-branch / commit — main-branch actions and the final commit are performed by the host after acceptance (one commit per run: code + task-folder docs together). Just write/modify files; leave everything uncommitted. If a task asks for "merge back to main" or "commit", treat it as "prepare the delivery" (files ready + summary of what was done), do NOT commit or merge.
 6. [Log discipline] Redirect command output to logs/teamflow/${runId || "<runId>"}/.
 7. Output an implementation summary (≤40 lines): changed files, key implementation points, how verified, leftovers. No big code pastes.
 8. [State] End with a state block (phase="dev"), touched = array of changed files, summary = implementation conclusion.${STATE_BLOCK_INSTRUCTION}`;
-const qaPrompt = (prd, devSummary, root, runId, state) => `You are a senior QA test engineer. The current workspace IS the target project — functionally test this delivery.
+/** 视觉验证能力条款（ADR-2026-08-27，解锁 browser-use 视觉验证）：
+* 按当前模型多模态能力动态生成——vision=true 允许截图看图（人眼类项），精确值仍走 DOM 计算断言；
+* vision=false 禁截图看图（防幻觉/循环，历史禁令动机=模型不识图），只走 DOM 计算断言（evaluate 返回文本）。
+* 两者都要求：浏览器失败降级不重试。 */
+const VISUAL_POLICY = (vision) => vision ? `[Visual verification · enabled (model supports image input)]
+- Real-browser visual verification IS allowed: launch the page (headless browser / browser-use) and verify layout/pixel/overlay/occlusion items by screenshot + reading the image.
+- **Scripted assertions first** (exact values must come from DOM computation, not eyeballing): evaluate offsetWidth/scrollWidth/clientHeight for overflow, getComputedStyle for exact colors/visibility, element sizes & ratios (e.g. 1:2). Assert on those numbers/strings.
+- Screenshot checks are for human-eye items only: overlay occlusion, animation feel, layout reasonableness. Save screenshots under the task folder (docs/teamflow/.../qa/) for acceptance & human review.
+- On browser launch failure: degrade to jsdom/scripted checks + list remaining items in 「人工补测清单」; do NOT retry more than once.` : `[Visual verification · limited (current model has NO image input)]
+- You CANNOT interpret screenshots (no image input) — do NOT take screenshots to "look" at them (waste loop); do NOT guess layout/pixel state from screenshots.
+- Scripted DOM assertions ARE allowed and preferred: launch the page headless and evaluate TEXT values only — overflow (scrollWidth <= clientWidth), exact colors via getComputedStyle, visibility, element sizes/ratios. Assert on those numbers/strings.
+- Visual-judgment items (occlusion, animation feel, layout aesthetics) that cannot be asserted via DOM values: list them in 「人工补测清单」 (acceptance criterion + method + tool), note「环境限制，非交付缺陷」; do NOT guess, do NOT retry.
+- On any browser failure: degrade to jsdom + 「人工补测清单」, do not retry.`;
+const qaPrompt = (prd, devSummary, root, runId, state, vision) => `You are a senior QA test engineer. The current workspace IS the target project — functionally test this delivery.
 ${productCtx(root)}${stateSliceFor(state, "qa")}${TOKEN_HYGIENE(runId)}[PRD (this change & relevant ACs)]
 ${headTailClip(prd, 5e3, 7e3)}
 [DEV RESULT SUMMARY]
@@ -1902,8 +2119,9 @@ ${clip(devSummary, 15e3)}
    - If the injected blueprint JSON ("<!-- blueprint -->") is present, verify the implementation follows it (was the to-be-extracted module extracted? deps/assembly per blueprint? any deviations?).
    - Check for **duplicated implementations** (e.g. multiple security wrappers/storage/adapter utilities drifting), **abstraction not extracted where it should be**, **obviously broken existing structure**.
    - Report architecture findings in the defect table format (severity P1, module =「架构」). This is part of the delivery quality gate, not just functional bugs.
-1. [Environment limits · don't waste effort] The sandbox forbids launching CDP-driven Chrome/Edge: real-browser automation (Playwright/Puppeteer/chromedriver/--remote-debugging-port), audio/pixel/timing/multi-browser/screen-reader checks are ALL impossible — this is a policy refusal, not a broken command; don't try, don't retry with alternative tools. Verification must use sandbox-legal paths: build/assembly checks, unit tests, DOM-level E2E (jsdom or equivalent), static audit, adversarial spot-checks.
-2. Acceptance items that cannot be auto-tested (audio/pixel/real timing/dual resolution/offline multi-browser/screen reader etc.): do NOT fail them — instead list each in the report's「人工补测清单」section (acceptance criteria + method + tool), note「环境限制，非交付缺陷」, for human review.
+1. [Environment limits · dynamic by model capability]${VISUAL_POLICY(!!vision)}
+   - Always-available sandbox-legal paths: build/assembly checks, unit tests, DOM-level E2E (jsdom or equivalent), static audit, adversarial spot-checks.
+2. [人工补测清单] Items that cannot be auto-verified (audio output / real-device: 100dvh dynamic toolbar, safe-area, multi-touch / FPS performance / screen-reader): do NOT fail them — instead list each in the report's「人工补测清单」section (acceptance criteria + method + tool), note「环境限制，非交付缺陷」, for human review.
 3. Read AGENTS.md §4 engineering conventions (verify commands) and the code changes first, then actually run those sandbox-legal verifications.
 4. [Log discipline] Redirect command output to logs/teamflow/${runId || "<runId>"}/ (e.g. qa-out.log); no scatter at project root.
 5. Output the test report (body ≤150 lines, verdict first): scope & environment, cases & results (pass/fail/blocked), conclusion (whether acceptance-ready).
@@ -1929,7 +2147,7 @@ ${tech && String(tech).trim() ? clip(tech, 12e3) : ""}
 3. After fixing, run relevant verification to ensure green (regression floor: existing verify suites pass untouched); redirect output to logs/teamflow/${runId || "<runId>"}/.
 4. Output a fix summary (≤40 lines, Chinese): per defect —「truth judgment + fix」or「false-positive evidence」, changed files, how verified, leftovers. No big code pastes.
 5. [State] End with a state block (phase="dev"), touched = changed files array, summary = fix conclusion.${STATE_BLOCK_INSTRUCTION}`;
-const acceptancePrompt = (prd, qa, devSummary, root, runId, state) => `You are the product manager (acceptance lead). Do a final acceptance of this delivery against the PRD acceptance criteria.
+const acceptancePrompt = (prd, qa, devSummary, root, runId, state, vision) => `You are the product manager (acceptance lead). Do a final acceptance of this delivery against the PRD acceptance criteria.
 ${productCtx(root)}${stateSliceFor(state, "acceptance")}${TOKEN_HYGIENE(runId)}
 ${ONCE_DISCIPLINE}[PRD (revision log + this run's new ACs)]
 ${headTailClip(prd, 4e3, 5e3)}
@@ -1937,6 +2155,7 @@ ${headTailClip(prd, 4e3, 5e3)}
 ${clip(qa, 1e4)}
 [DEV RESULT SUMMARY]
 ${clip(devSummary, 8e3)}
+${vision ? "[Visual re-check] If QA saved screenshots under the task folder, spot-check the human-eye items visually (occlusion / layout reasonableness / animation feel) before concluding; otherwise rely on the QA report + 人工补测清单." : ""}
 [REQUIREMENTS]
 0. [Architecture consistency check · mandatory (M3 quality gate)] Beyond functional ACs, check structural quality:
    - If the injected blueprint JSON ("<!-- blueprint -->") is present: does the implementation follow it (module extracted as planned? assembly order correct? abstraction missing where required?).
@@ -2321,6 +2540,29 @@ function deliverCompletion(journal, parent) {
 			interrupted: "⚠ 中断（可用 teamflow_resume 从断点重跑）"
 		}[journal.status] || journal.status;
 		const stagesLine = stages.length === 0 ? "尚未进入任何阶段" : `${stages.length} 个阶段 · ${done} 完成${failed > 0 ? ` · ${failed} 失败` : ""}${cancelledStages > 0 ? ` · ${cancelledStages} 取消` : ""}`;
+		let mergeHint = "";
+		if (journal.status === "completed" && !journal.error && journal.workspacePath) try {
+			const branch = gitCmd(journal.workspacePath, [
+				"rev-parse",
+				"--abbrev-ref",
+				"HEAD"
+			]);
+			if (branch && branch !== "main") {
+				const ahead = gitCmd(journal.workspacePath, [
+					"rev-list",
+					"--count",
+					"main..HEAD"
+				]);
+				if (ahead && Number(ahead) > 0) {
+					journal.mergeStatus = journal.mergeStatus || "pending";
+					mergeHint = `🧩 合回决策：验收已通过，当前在特性分支 ${branch}（领先 main ${ahead} 个提交）。请**询问用户**是否合回，并按用户选择调用 teamflow_merge：\n   ① host 代为合回 → action="merge"\n   ② 给出命令用户自行合回 → action="command"\n   ③ 暂不合回 → action="keep"\n（选项之外用户自定义输入亦可，如实转述）`;
+				}
+			}
+			if ((journal.options || {}).preAction === "stash") {
+				const stashHint = "🧩 启动前 stash 的改动仍在暂存区：流水线完成后请执行 git stash pop 恢复你的改动";
+				mergeHint = mergeHint ? `${mergeHint}\n${stashHint}` : stashHint;
+			}
+		} catch (e) {}
 		const text = [
 			`【团队研发流水线汇报】runId=${journal.id}`,
 			`状态：${statusLine}${journal.error ? `（${clip(journal.error, 300)}）` : ""}`,
@@ -2334,6 +2576,7 @@ function deliverCompletion(journal, parent) {
 				return typeof m === "string" && m !== "full" && m !== "medium" ? `模式：${MODE_REGISTRY[m] ? MODE_REGISTRY[m].label : m}` : "";
 			})(),
 			`backlog：需求 ${journal.reqId || "—"}（$DSH_HOME/teamflow/ 持久化）`,
+			mergeHint,
 			"用户可打开「🏭 团队工作台」tab 查看阶段泳道、拖拽看板与 token 明细。",
 			"如需继续处理：可认领缺陷（teamflow_claim）、人工流转（teamflow_update）、断点重跑（teamflow_resume）。",
 			"若用户在场请简明转述以上要点；若无人值守仅记录即可，不必长篇回复。"
@@ -2357,79 +2600,6 @@ function deliverCompletion(journal, parent) {
 	}
 }
 //#endregion
-//#region host/core/sanity.ts
-/**
-* dsh-plugin-teamflow core — M0 状态核对（sanity check）。
-*
-* 目的（三情况协议）：
-* - 情况一（全新会话）：0 认知 → 核对确认"从零开始"。
-* - 情况二（续会话）：认知大概率过期（多人协作/场外提交/非流水线改动）→ 核对发现预期外变化。
-* - 情况三（新会话处理新需求）：即使共用 state/记忆，仓库也可能被外部改动 → 核对现状。
-*
-* 核心原则：认知资产（索引/记忆/摘要）可复用"减量"，但永不能替代"对代码库当前真实状态的核对"。
-* 本模块在 host 侧直接跑 git（零模型 token、轻量、失败优雅降级为"无法核对"），
-* 产出 externalDiffs 摘要注入到后续所有阶段 prompt。
-*/
-/** 单条 git 检查结果（失败返回 null，调用方降级）。 */
-function gitCmd(cwd, args, timeoutMs = 8e3) {
-	try {
-		return execFileSync("git", args, {
-			cwd,
-			encoding: "utf8",
-			timeout: timeoutMs,
-			windowsHide: true
-		}).trim();
-	} catch (e) {
-		return null;
-	}
-}
-/**
-* 跑一次状态核对。
-* @param path - 工作区绝对路径（workspaceScopeOf(agent).path）。
-*/
-function runSanityCheck(path) {
-	const defaultOut = {
-		ok: false,
-		inRepo: false,
-		branch: null,
-		dirty: "",
-		hasDirty: false,
-		recentCommits: "",
-		summary: ""
-	};
-	if (!path) return {
-		...defaultOut,
-		summary: "⚠ 无法确定工作区路径，未做状态核对。"
-	};
-	const branch = gitCmd(path, ["branch", "--show-current"]);
-	const status = gitCmd(path, ["status", "--short"]);
-	if (branch === null && status === null) return {
-		...defaultOut,
-		summary: "⚠ 状态核对不可用（非 git 仓库或 git 命令被拒），无法确认代码库真实状态。"
-	};
-	const recent = gitCmd(path, [
-		"log",
-		"--oneline",
-		"-5"
-	]);
-	const dirty = status || "";
-	const dirtyLines = dirty.split("\n").filter(Boolean);
-	const summaryParts = [];
-	summaryParts.push(`分支：${branch && branch !== "HEAD" ? branch : "(detached HEAD / 非分支)"}`);
-	if (dirtyLines.length) summaryParts.push(`未提交改动 ${dirtyLines.length} 处：${dirtyLines.slice(0, 8).join("；")}${dirtyLines.length > 8 ? "…" : ""}`);
-	else summaryParts.push("工作区干净（无未提交改动）");
-	if (recent) summaryParts.push(`近期提交（可能含场外改动）：${recent.split("\n").slice(0, 3).join("；")}`);
-	return {
-		ok: true,
-		inRepo: true,
-		branch: branch && branch !== "HEAD" ? branch : null,
-		dirty,
-		hasDirty: dirtyLines.length > 0,
-		recentCommits: recent || "",
-		summary: `【状态核对】${summaryParts.join("。")}`
-	};
-}
-//#endregion
 //#region host/core/pipeline.ts
 /**
 * dsh-plugin-teamflow core — 流水线编排中枢（阶段执行 / 入口 / 取消 / 断点续跑）。
@@ -2454,14 +2624,38 @@ function buildResumeProducts(journal) {
 	return products;
 }
 /**
-* 断点续跑起点：journal 中第一个未完成阶段（磁盘上 interrupted/running 所在阶段）。
+* 断点续跑起点：第一个「没有任意 done 尝试」的阶段。
+* ⚠️ 按阶段而非尝试判断（实锤 tf-mtcomxpq）：PRD 第 1 次尝试 failed（护栏退化）但第 2 次重试 done——
+* 旧实现取第一个非 done stage → 断点错误回到 PRD，PRD/技术方案被无谓重跑。
 * 全部完成仍被中断（理论极端）→ 从产品验收继续。
 */
 function interruptedPhaseOf(journal) {
-	const stage = (journal.stages || []).find((s) => s.status !== "done");
-	if (stage && PHASE_ORDER.indexOf(stage.phase) !== -1) return stage.phase;
+	if (hasOpenBlockingBugs(journal)) return "QA 测试";
+	for (const phase of PHASE_ORDER) {
+		const phaseStages = (journal.stages || []).filter((s) => s.phase === phase);
+		if (phaseStages.length === 0) continue;
+		if (!phaseStages.some((s) => s.status === "done")) return phase;
+	}
 	return "产品验收";
 }
+/** 开发任务定义（单一来源）：架构蓝图自动拆 > 调用方显式 tasks > 整体开发兜底。
+* resume 补跑与正常执行共用（defByTitle 按 title 匹配失败子卡）。 */
+function buildDevTaskDefs(journal, tasks) {
+	const blueprintTasks = journal.blueprint && Array.isArray(journal.blueprint.tasks) && journal.blueprint.tasks.length ? journal.blueprint.tasks.map((t) => ({
+		title: t.title || "开发任务",
+		files: Array.isArray(t.files) ? t.files : [],
+		spec: t.spec || ""
+	})) : [];
+	return blueprintTasks.length ? blueprintTasks : tasks.length > 0 ? tasks.map((t) => ({
+		title: t.title,
+		spec: t.spec,
+		files: []
+	})) : [{
+		title: "整体开发",
+		spec: "按技术方案/需求实现全部改动",
+		files: []
+	}];
+}
 /**
 * 执行流水线。resume = null 全新运行；resume = { phase, products } 从断点续跑：
 * phase 之前的阶段直接复用 products 产物（跳过执行），从 phase 阶段开始重跑。
@@ -2557,6 +2751,48 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				level: "info",
 				message: `backlog 已建立需求 ${init.reqId}（产品 ${root || "unknown"}，并发 ${maxConcurrency}）`
 			});
+			if (options.branchPolicy !== "keep" && journal.workspacePath) try {
+				const s = runSanityCheck(journal.workspacePath);
+				if (s.ok && s.inRepo && !s.hasDirty) {
+					const branch = `feat/${deriveBranchSlug(requirement, journal.reqId, triageSlug, options.branchName)}`;
+					const exists = gitCmd(journal.workspacePath, [
+						"branch",
+						"--list",
+						branch
+					]);
+					if (exists && exists.trim()) {
+						journal.logs.push({
+							t: Date.now(),
+							level: "warn",
+							message: `分支策略：分支 ${branch} 已存在，沿用现有分支`
+						});
+						gitCmd(journal.workspacePath, ["checkout", branch]);
+						journal.branch = branch;
+					} else {
+						const ok = gitCmd(journal.workspacePath, [
+							"checkout",
+							"-b",
+							branch
+						]);
+						journal.logs.push({
+							t: Date.now(),
+							level: "info",
+							message: ok !== null ? `分支策略：已创建特性分支 ${branch}（从 ${s.branch} 派生）` : `分支策略：自动建分支 ${branch} 失败（git 异常），沿用当前分支`
+						});
+						if (ok !== null) journal.branch = branch;
+					}
+				} else if (s.ok && s.inRepo && s.branch) journal.logs.push({
+					t: Date.now(),
+					level: "warn",
+					message: `分支策略：工作区仍有未提交改动（${s.dirty.split(/\r?\n/).filter((l) => l.trim()).length} 处），跳过建分支，沿用 ${s.branch}——请知悉改动将混入本次开发`
+				});
+			} catch (e) {
+				journal.logs.push({
+					t: Date.now(),
+					level: "warn",
+					message: `分支策略检查失败（降级沿用当前分支）：${String(e && e.message || e)}`
+				});
+			}
 		}
 		persistJournal(journal);
 		if (!journal.runDocs && journal.reqId) {
@@ -2586,6 +2822,49 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				});
 			}
 		}
+		if (!resume && journal.workspacePath && options.preAction === "stash") try {
+			if (gitCmd(journal.workspacePath, [
+				"stash",
+				"push",
+				"-m",
+				`teamflow:${journal.id} pre-pipeline`
+			]) !== null) journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: `分支策略：工作区改动已 stash（teamflow:${journal.id}），流水线完成后 git stash pop 恢复你的改动`
+			});
+			else journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: "分支策略：stash 执行失败（可能无改动），继续"
+			});
+		} catch (e) {
+			journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: `分支策略：stash 异常：${String(e && e.message || e)}`
+			});
+		}
+		else if (!resume && journal.workspacePath && options.preAction === "commit") try {
+			const msg = typeof options.commitMessage === "string" && options.commitMessage.trim() ? options.commitMessage.trim() : `chore(teamflow): 流水线启动前提交现有改动（${journal.id}）`;
+			const add = gitCmd(journal.workspacePath, ["add", "-A"]);
+			const cm = gitCmd(journal.workspacePath, [
+				"commit",
+				"-m",
+				msg
+			]);
+			journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: add !== null && cm !== null ? `分支策略：已提交现有改动（preAction=commit：${msg.slice(0, 60)}）` : "分支策略：commit 执行失败（可能无改动），继续"
+			});
+		} catch (e) {
+			journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: `分支策略：commit 异常：${String(e && e.message || e)}`
+			});
+		}
 		const state = loadState(journal.workspace || "default");
 		state.__runCtx = { ...state.__runCtx || {} };
 		if (journal.runDocs) state.__runCtx.runDocs = journal.runDocs;
@@ -2743,28 +3022,50 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 		let devResults = null;
 		if (resumed("开发")) {
 			devResults = resume.products.dev || [];
-			timeline.dev = devResults;
-			logSkip("开发");
+			const failedSubs = (storeFor(scopeKey).tasks || []).filter((t) => t.reqId === journal.reqId && t.parentId === journal.taskId && (t.status === "failed" || t.failed === true));
+			if (failedSubs.length > 0) {
+				const defs = buildDevTaskDefs(journal, tasks);
+				const defByTitle = new Map(defs.map((d) => [d.title, d]));
+				const rerunDefs = failedSubs.map((s) => {
+					const key = String(s.title || "").replace(/^开发 · /, "");
+					return defByTitle.get(key) || {
+						title: key,
+						spec: s.spec || "按技术方案实现该任务改动",
+						files: []
+					};
+				}).filter(Boolean);
+				const reused = devResults.filter((r) => r && !rerunDefs.some((d) => d.title === r.title));
+				journal.logs.push({
+					t: Date.now(),
+					level: "warn",
+					message: `断点续跑开发：复用 ${reused.length} 个已完成任务，补跑 ${rerunDefs.length} 个失败任务`
+				});
+				const rerun = await runPool(rerunDefs, maxConcurrency, async (task) => {
+					const devR = await withRetry(journal, parent, `开发 · ${task.title}（补跑）`, "开发", devPrompt(task, tech, prd, root, journal.id, state), signal);
+					const ok = !!devR.text;
+					return {
+						title: task.title,
+						failed: !ok,
+						output: devR.text || "开发失败（Agent 未产出结果）"
+					};
+				});
+				for (const t of rerun) {
+					const sub = failedSubs.find((s) => String(s.title || "").replace(/^开发 · /, "") === t.title);
+					if (sub) completeSubtask(journal, sub.id, t.failed, t.output ? snippet(t.output, 1e3) : null, null);
+				}
+				devResults = [...reused, ...rerun];
+				timeline.dev = devResults;
+			} else {
+				timeline.dev = devResults;
+				logSkip("开发");
+			}
 		} else {
 			journal.logs.push({
 				t: Date.now(),
 				level: "phase",
 				message: "进入阶段：开发"
 			});
-			const blueprintTasks = journal.blueprint && Array.isArray(journal.blueprint.tasks) && journal.blueprint.tasks.length ? journal.blueprint.tasks.map((t) => ({
-				title: t.title || "开发任务",
-				files: Array.isArray(t.files) ? t.files : [],
-				spec: t.spec || ""
-			})) : [];
-			const devTaskDefs = blueprintTasks.length ? blueprintTasks : tasks.length > 0 ? tasks.map((t) => ({
-				title: t.title,
-				spec: t.spec,
-				files: []
-			})) : [{
-				title: "整体开发",
-				spec: "按技术方案/需求实现全部改动",
-				files: []
-			}];
+			const devTaskDefs = buildDevTaskDefs(journal, tasks);
 			const mergedDefs = [];
 			for (const t of devTaskDefs) {
 				const hit = t.files && t.files.length ? mergedDefs.find((m) => m.files.some((f) => t.files.includes(f))) : void 0;
@@ -2781,7 +3082,7 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 			journal.logs.push({
 				t: Date.now(),
 				level: "info",
-				message: `开发阶段开始，任务数：${mergedDefs.length}（并发 ${maxConcurrency}${blueprintTasks.length ? "，源自架构蓝图自动拆解" : ""}）`
+				message: `开发阶段开始，任务数：${mergedDefs.length}（并发 ${maxConcurrency}${journal.blueprint && Array.isArray(journal.blueprint.tasks) && journal.blueprint.tasks.length ? "，源自架构蓝图自动拆解" : ""}）`
 			});
 			advanceTask(journal, "running", null, "开发开始（待办 → 开发中）", { by: "dev" });
 			const subCards = mergedDefs.map((dt) => createSubtask(journal, dt.title, dt.spec));
@@ -2825,9 +3126,10 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				}
 				journal.logs.push({
 					t: Date.now(),
-					level: "warn",
-					message: `开发完成，失败任务数：${failedCount}（需人工介入）`
+					level: "error",
+					message: `开发失败任务数：${failedCount}/${devResults.length}（提测门禁拦截）：停止流水线，需人工介入——处理后可 teamflow_resume 从开发阶段补跑失败任务（已完成任务复用）`
 				});
+				throw new Error(`开发失败任务 ${failedCount}/${devResults.length}：提测门禁拦截，不进 QA（已知缺口，QA 检查轮必然重复报告）`);
 			} else {
 				advanceTask(journal, "testable", null, "开发完成待测试（开发中 → 待测试）", { by: "dev" });
 				journal.logs.push({
@@ -2848,7 +3150,7 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				message: "当前档位阶段集不含独立 QA：跳过（单点修复，开发自测兜底）"
 			});
 			qa = "（独立 QA 跳过：当前档位由开发自测兜底）";
-		} else if (resumed("QA 测试")) {
+		} else if (resumed("QA 测试") && !hasOpenBlockingBugs(journal)) {
 			qa = resume.products.qa;
 			timeline.qa = qa;
 			logSkip("QA 测试");
@@ -2872,7 +3174,7 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 			do {
 				round += 1;
 				const isReverify = round > 1;
-				const qaR = await withRetry(journal, parent, isReverify ? `QA 复验 · 第${round - 1}轮修复后` : "QA 测试工程师 · 功能测试", "QA 测试", qaPrompt(prd, qaDevSummary(), root, journal.id, state), signal);
+				const qaR = await withRetry(journal, parent, isReverify ? `QA 复验 · 第${round - 1}轮修复后` : "QA 测试工程师 · 功能测试", "QA 测试", qaPrompt(prd, qaDevSummary(), root, journal.id, state, await currentModelSupportsVision(resolveChildRoute(parent).provider, resolveChildRoute(parent).model)), signal);
 				if (!qaR.text) {
 					advanceTask(journal, "needs-human", null, isReverify ? `QA 复验失败（第 ${round - 1} 轮修复后）` : "QA 失败", { by: "qa" });
 					throw stageFailError(isReverify ? "QA 测试（复验）" : "QA 测试", qaR);
@@ -2952,7 +3254,7 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				const curTask = storeFor(scopeKey).find("task", journal.taskId);
 				if (curTask && curTask.status !== "pending-acceptance" && curTask.status !== "needs-human" && curTask.status !== "rework") advanceTask(journal, "pending-acceptance", null, "进入验收（待验收）", { by: "pm" });
 			}
-			const accR = await withRetry(journal, parent, "产品经理 · 最终验收", "产品验收", acceptancePrompt(prd, qa, JSON.stringify(timeline.dev), root, journal.id, state), signal);
+			const accR = await withRetry(journal, parent, "产品经理 · 最终验收", "产品验收", acceptancePrompt(prd, qa, JSON.stringify(timeline.dev), root, journal.id, state, await currentModelSupportsVision(resolveChildRoute(parent).provider, resolveChildRoute(parent).model)), signal);
 			if (!accR.text) {
 				advanceTask(journal, "needs-human", null, "验收失败", { by: "pm" });
 				throw stageFailError("产品验收", accR);
@@ -3021,6 +3323,35 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 		journal.endedAt = Date.now();
 		inFlight.delete(journal.id);
 		activeProducts.delete(scopeKey);
+		if (journal.workspacePath && journal.status === "completed" && !journal.humanIntervention) try {
+			const reqHead = String(journal.requirement || "").replace(/\s+/g, " ").trim().slice(0, 80);
+			const add = gitCmd(journal.workspacePath, ["add", "-A"]);
+			if ((add === null ? null : gitCmd(journal.workspacePath, [
+				"commit",
+				"-m",
+				`feat: ${reqHead}（runId=${journal.id}${journal.runDocs ? `，任务夹 ${journal.runDocs}` : ""}）`
+			])) !== null) journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: "统一收口提交完成（代码 + 任务夹产物，验收通过后一个 commit）"
+			});
+			else if (add !== null) journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: "统一收口提交：无待提交改动（跳过）"
+			});
+		} catch (e) {
+			journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: `统一收口提交失败（忽略）：${String(e && e.message || e)}`
+			});
+		}
+		else if (journal.workspacePath && journal.runDocs && (journal.status === "failed" || journal.status === "cancelled" || journal.status === "interrupted")) journal.logs.push({
+			t: Date.now(),
+			level: "warn",
+			message: `终态非验收通过：工作区改动与任务夹产物 ${journal.runDocs}/ 保留未提交，供人工处理（resume 修复通过后自动收口提交）`
+		});
 		journal.result = {
 			requirement,
 			options: sanitizeSnapOptions(options),
@@ -3098,7 +3429,11 @@ function startPipeline(agent, requirement, options, signal) {
 			teamId: options.teamId || void 0,
 			tasks: normalizeTasks(options.tasks),
 			productRoot: normalizeRoot(options.productRoot),
-			maxConcurrency: Number.isFinite(options.maxConcurrency) && options.maxConcurrency > 0 ? Math.min(options.maxConcurrency, 8) : null
+			maxConcurrency: Number.isFinite(options.maxConcurrency) && options.maxConcurrency > 0 ? Math.min(options.maxConcurrency, 8) : null,
+			branchPolicy: options.branchPolicy || void 0,
+			branchName: options.branchName || void 0,
+			preAction: options.preAction || void 0,
+			commitMessage: options.commitMessage || void 0
 		},
 		startedAt: null,
 		endedAt: null,
@@ -3201,7 +3536,7 @@ function resumeRun(runId, sessionId) {
 			level: "warn",
 			message: `断点续跑：从「${resumePhase}」继续（已完成阶段复用产物）`
 		});
-		j.stages = (j.stages || []).filter((s) => s.status === "done");
+		j.stages = (j.stages || []).filter((s) => s.status !== "running" && s.status !== "pending");
 		runs.set(id, j);
 		persistJournal(j);
 		executePipeline(j, agent, j.requirement, j.options, void 0, {
@@ -3303,7 +3638,7 @@ function registerTools(ctx) {
 	};
 	T({
 		name: "teamflow_start",
-		description: "Start the team R&D pipeline (background async): runs the stages per team config (PRD→design→tech→dev→QA→acceptance). Specify teamId (matches teams.json) or pick a team via the UI \"+\" button first so messages auto-match. Stage failures auto-retry; beyond threshold → rework/human intervention; per-stage token usage recorded. NOTE: after calling, the implementation work is done by pipeline subagents — the main thread MUST NOT write code or run verifications for it. requirement must be a faithful transcription of the user's words; do not invent file paths / tech claims without code verification (downstream stages build the PRD from it).",
+		description: "Start the team R&D pipeline (background async): runs the stages per team config (PRD→design→tech→dev→QA→acceptance). Specify teamId (matches teams.json) or pick a team via the UI \"+\" button first so messages auto-match. Stage failures auto-retry; beyond threshold → rework/human intervention; per-stage token usage recorded. NOTE: after calling, the implementation work is done by pipeline subagents — the main thread MUST NOT write code or run verifications for it. requirement must be a faithful transcription of the user's words; do not invent file paths / tech claims without code verification (downstream stages build the PRD from it). Branch decision: when the return status is \"needs-decision\", ASK THE USER to pick one of the options (or take their custom input, e.g. a branch name), then RE-CALL this tool passing the CHOSEN OPTION VALUE as branchPolicy (\"new\" = confirmed create branch, \"keep\" = stay), optionally combined with preAction / branchName / commitMessage. Pass branchPolicy=\"keep\" when the user chooses to stay on the current branch.",
 		parameters: {
 			requirement: {
 				type: "string",
@@ -3338,6 +3673,22 @@ function registerTools(ctx) {
 				type: "integer",
 				description: "Dev task concurrency (default 3, max 8)"
 			},
+			branchPolicy: {
+				type: "string",
+				description: "Branch policy: \"auto\" (default, triggers needs-decision when not yet confirmed) — create a feature branch feat/<branchName|slug> from the current HEAD; \"keep\" — stay on current branch; \"new\" — the confirmed value returned by needs-decision options (user already picked \"create branch\"), pass it back as-is to proceed. When auto and a decision is needed (dirty workspace / on main etc.), the tool returns needs-decision for you to ask the user first."
+			},
+			branchName: {
+				type: "string",
+				description: "Custom branch name (used when branchPolicy=auto; defaults to the triage slug; [a-z0-9-_])"
+			},
+			preAction: {
+				type: "string",
+				description: "Pre-start handling of dirty workspace: \"stash\" (stash changes, restore later via git stash pop), \"commit\" (commit existing changes, custom commitMessage), omit = leave as-is (changes mix into this run)"
+			},
+			commitMessage: {
+				type: "string",
+				description: "Custom commit message when preAction=commit"
+			},
 			tasks: {
 				type: "array",
 				description: "Optional splittable dev task list",
@@ -3362,16 +3713,32 @@ function registerTools(ctx) {
 			schema: {
 				type: "object",
 				additionalProperties: false,
-				required: ["runId", "status"],
+				required: ["status"],
 				properties: {
 					runId: { type: "string" },
-					status: { type: "string" }
+					status: { type: "string" },
+					question: { type: "string" },
+					options: { type: "array" },
+					note: { type: "string" }
 				}
 			},
-			render: (args, value) => [{
-				type: "text",
-				text: `团队研发流水线已启动（runId=${value.runId}，${value.status}），正在后台执行。【重要】你现在停手：不要自行读取/修改代码实现该需求，不要重复跑测试验证——实现、QA、汇报由流水线各阶段完成。你只需告知用户流水线已启动，等待流水线完成后的官方完成汇报，再向用户转述结果。可用 teamflow_status 查询进度/阶段 token；backlog 已持久化到 $DSH_HOME/teamflow。`
-			}]
+			render: (args, value) => {
+				if (value && value.status === "needs-decision") {
+					const opts = Array.isArray(value.options) ? value.options.map((o, i) => `${i + 1}. ${o.label}`).join("\n") : "";
+					return [{
+						type: "text",
+						text: `【分支决策】${value.question}\n${opts}\n（也可自定义输入）——请询问用户选择，确认后把所选选项的 value 作为 branchPolicy 重新调用 teamflow_start（如 'new'/'keep'；脏工作区选项可拆为 branchPolicy + preAction 组合），自定义分支名则传 branchName。`
+					}];
+				}
+				if (value && value.status === "needs-confirmation") return [{
+					type: "text",
+					text: `【需求确认】${value.question}\n${value.note || ""}——请按此询问用户后再决定。`
+				}];
+				return [{
+					type: "text",
+					text: `团队研发流水线已启动（runId=${value.runId}，${value.status}），正在后台执行。【重要】你现在停手：不要自行读取/修改代码实现该需求，不要重复跑测试验证——实现、QA、汇报由流水线各阶段完成。你只需告知用户流水线已启动，等待流水线完成后的官方完成汇报，再向用户转述结果。可用 teamflow_status 查询进度/阶段 token；backlog 已持久化到 $DSH_HOME/teamflow。`
+				}];
+			}
 		},
 		async execute(args, exec) {
 			const parent = exec && exec.agent;
@@ -3388,18 +3755,105 @@ function registerTools(ctx) {
 				status: "no-team",
 				message: "请先通过输入框旁的 🏭 按钮选择团队，再发送需求消息。未选团队时不走 teamflow。"
 			};
+			const rawReq = typeof args.requirement === "string" ? args.requirement : "";
+			if (/是不是|要不要|需不需要|是否应该|要不要考虑|建议|我感觉|感觉不出|我们是不是|咱是不是/.test(rawReq)) return {
+				status: "needs-confirmation",
+				question: `这条消息（「${rawReq.slice(0, 60)}」）更像反馈/建议（含疑问句式）而非明确开发需求。请先向用户确认：是否要实现？`,
+				note: "用户确认要实现后，请把明确需求（如「实现 combo/t-spin 触发 Toast 提示」）作为 requirement 重新调用 teamflow_start；若用户只是表达感受/讨论，直接正常回复即可。"
+			};
 			try {
+				const requirement = typeof args.requirement === "string" && args.requirement.trim() ? args.requirement.trim() : "(未提供需求)";
+				const options = {
+					needDesign: !!args.needDesign,
+					needScaffold: !!args.needScaffold,
+					lite: !!args.lite,
+					mode: normalizeMode(args.mode) || void 0,
+					teamId,
+					tasks: normalizeTasks(args.tasks),
+					productRoot: normalizeRoot(args.productRoot),
+					maxConcurrency: args.maxConcurrency,
+					branchPolicy: args.branchPolicy === "keep" ? "keep" : "auto",
+					branchName: typeof args.branchName === "string" && args.branchName.trim() ? args.branchName.trim() : null,
+					preAction: args.preAction === "stash" || args.preAction === "commit" ? args.preAction : null,
+					commitMessage: typeof args.commitMessage === "string" && args.commitMessage.trim() ? args.commitMessage.trim() : null
+				};
+				const branchConfirmed = args.branchPolicy === "new";
+				if (options.branchPolicy === "auto" && !branchConfirmed && !options.branchName && !options.preAction && exec && exec.agent) {
+					const sc = workspaceScopeOf(exec.agent);
+					if (sc.path) try {
+						const s = runSanityCheck(sc.path);
+						if (s.ok && s.inRepo) {
+							const onMain = !!s.branch && s.branch.trim().toLowerCase() === "main";
+							const dirty = s.hasDirty;
+							const dirtyN = s.dirty.split(/\r?\n/).filter((l) => l.trim()).length;
+							let question = "";
+							let optionsList = [];
+							if (onMain && !dirty) {
+								question = `工作区 ${sc.path} 当前在 main 分支（工作区干净）。流水线默认在特性分支上开发，请选择：`;
+								optionsList = [{
+									label: "基于 main 新建分支开发（推荐，分支名取需求 slug，可自定义）",
+									value: "new"
+								}, {
+									label: "直接在 main 上开发",
+									value: "keep"
+								}];
+							} else if (onMain && dirty) {
+								question = `工作区 ${sc.path} 当前在 main 分支，且有 ${dirtyN} 处未提交改动。请选择启动方式：`;
+								optionsList = [
+									{
+										label: `stash 现有改动后新建分支开发（推荐，改动暂存，流水线完成后 git stash pop 恢复）`,
+										value: "stash+auto"
+									},
+									{
+										label: "提交现有改动后新建分支开发（提交信息可自定义）",
+										value: "commit+auto"
+									},
+									{
+										label: "直接在 main 上继续（未提交改动将混入本次开发）",
+										value: "keep"
+									}
+								];
+							} else if (!onMain && !dirty) {
+								question = `工作区 ${sc.path} 当前在特性分支 ${s.branch}（工作区干净）。请选择启动方式：`;
+								optionsList = [{
+									label: "沿用当前分支开发（推荐）",
+									value: "keep"
+								}, {
+									label: "基于当前分支再新建子分支开发",
+									value: "new"
+								}];
+							} else {
+								question = `工作区 ${sc.path} 当前在特性分支 ${s.branch}，且有 ${dirtyN} 处未提交改动。请选择启动方式：`;
+								optionsList = [
+									{
+										label: "stash 现有改动后沿用当前分支开发（推荐，完成后 git stash pop 恢复）",
+										value: "stash+keep"
+									},
+									{
+										label: "直接沿用当前分支（未提交改动混入本次开发）",
+										value: "keep"
+									},
+									{
+										label: "stash 现有改动后新建子分支开发",
+										value: "stash+auto"
+									},
+									{
+										label: "提交现有改动后新建子分支开发",
+										value: "commit+auto"
+									}
+								];
+							}
+							return {
+								status: "needs-decision",
+								question,
+								options: optionsList,
+								note: "选项之外可自定义输入（如指定分支名）。确认选择后，请以 teamflow_start 的 branchPolicy（回传所选选项 value，如 new/keep）与 branchName/preAction/commitMessage 参数重新调用本工具。"
+							};
+						}
+					} catch (e) {}
+				}
 				return {
-					runId: startPipeline(parent, typeof args.requirement === "string" && args.requirement.trim() ? args.requirement.trim() : "(未提供需求)", {
-						needDesign: !!args.needDesign,
-						needScaffold: !!args.needScaffold,
-						lite: !!args.lite,
-						mode: normalizeMode(args.mode) || void 0,
-						teamId,
-						tasks: normalizeTasks(args.tasks),
-						productRoot: normalizeRoot(args.productRoot),
-						maxConcurrency: args.maxConcurrency
-					}, exec && exec.signal),
+					runId: startPipeline(parent, requirement, options, exec && exec.signal),
 					status: "running"
 				};
 			} catch (e) {
@@ -3407,6 +3861,88 @@ function registerTools(ctx) {
 			}
 		}
 	});
+	T({
+		name: "teamflow_merge",
+		description: "Merge the completed run's feature branch back to main — the user-confirmed closing step (ADR-2026-08-27). Valid only after acceptance passed (run status=completed) while on a feature branch ahead of main. **Ask the user first** — the completion report carries the decision invitation (① host merge ② manual command ③ keep). Actions: \"merge\" — host performs git checkout main && git merge --no-ff <branch>; \"command\" — print the manual command for the user to run themselves; \"keep\" — defer, mark run as kept (branch stays).",
+		parameters: {
+			action: {
+				type: "string",
+				required: true,
+				description: "\"merge\" (host performs the merge) / \"command\" (print the manual merge command) / \"keep\" (defer, mark kept)"
+			},
+			runId: {
+				type: "string",
+				description: "Run id (defaults to the latest completed run of this workspace)"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				required: ["status"],
+				properties: {
+					status: { type: "string" },
+					message: { type: "string" },
+					command: { type: "string" }
+				}
+			},
+			render: (args, value) => [{
+				type: "text",
+				text: value.message
+			}]
+		},
+		async execute(args, exec) {
+			const action = args && args.action;
+			if (action !== "merge" && action !== "command" && action !== "keep") throw new Error("action 必须是 merge / command / keep");
+			const sc = workspaceScopeOf(exec && exec.agent);
+			if (!sc.path) throw new Error("当前会话无项目工作区");
+			const key = sc.projectKey;
+			const target = typeof args.runId === "string" && args.runId ? runs.get(args.runId) : [...runs.values()].filter((j) => j.workspace === key && j.status === "completed").sort((a, b) => (b.endedAt || 0) - (a.endedAt || 0))[0];
+			if (!target) throw new Error("未找到已完成流水线（可传 runId 指定）");
+			const branch = gitCmd(sc.path, [
+				"rev-parse",
+				"--abbrev-ref",
+				"HEAD"
+			]);
+			if (!branch || branch === "main") return {
+				status: "noop",
+				message: "当前已在 main 分支，无需合回"
+			};
+			if (action === "command") return {
+				status: "command",
+				command: `git checkout main && git merge --no-ff ${branch}`,
+				message: `请用户在项目目录执行以下命令完成合回（合回后可 git branch -d ${branch} 清理特性分支）：\ngit checkout main && git merge --no-ff ${branch}`
+			};
+			if (action === "keep") {
+				target.mergeStatus = "kept";
+				persistJournal(target);
+				return {
+					status: "kept",
+					message: `已标记暂不合回：特性分支 ${branch} 保留，后续可随时调用 teamflow_merge 合回`
+				};
+			}
+			const co = gitCmd(sc.path, ["checkout", "main"]);
+			const mg = co === null ? null : gitCmd(sc.path, [
+				"merge",
+				"--no-ff",
+				branch
+			]);
+			if (co === null || mg === null) {
+				target.mergeStatus = "failed";
+				persistJournal(target);
+				return {
+					status: "failed",
+					message: `合并失败（工作区可能不干净或有冲突）。请人工处理：先提交/处理当前工作区改动，再执行 git merge --no-ff ${branch}（冲突文件需手动解决）`
+				};
+			}
+			target.mergeStatus = "merged";
+			persistJournal(target);
+			return {
+				status: "merged",
+				message: `✅ 已合回 main（git merge --no-ff ${branch}）。如需清理特性分支：git branch -d ${branch}`
+			};
+		}
+	});
 	T({
 		name: "teamflow_triage",
 		description: "Requirement triage (optional helper): teamflow_start already auto-triages by default — no need to call this manually. Use it only when you want to **pre-evaluate** which pipeline mode a requirement fits, or **force** a mode: a triage analyst Agent thinks one round and returns a suggested mode, nature, UI-need, complexity and rationale.",
@@ -3742,8 +4278,25 @@ function registerTools(ctx) {
 }
 /** 会话级暂停标记：pausedSessions.has(sessionId) → 该会话的 teamflow_start 被拦截。 */
 const pausedSessions = /* @__PURE__ */ new Set();
-/** 会话级当前团队：activeTeams.get(sessionId) → 当前选中的团队 id。 */
+/** 会话级当前团队：activeTeams.get(sessionId) → 当前选中的团队 id。
+* 持久化到 $DSH_HOME/teamflow/active-teams.json——重启后恢复（实锤：重启/刷新后内存清空，
+* UI 显示无团队，但 agent 上下文记忆 teamId 显式传入仍启动流水线，UI 状态与启动通道不一致）。 */
 const activeTeams = /* @__PURE__ */ new Map();
+const ACTIVE_TEAMS_FILE = () => join(teamflowRoot(), "active-teams.json");
+function loadActiveTeams() {
+	try {
+		const raw = readJsonAny(ACTIVE_TEAMS_FILE(), null);
+		if (raw && typeof raw === "object") {
+			for (const [k, v] of Object.entries(raw)) if (typeof k === "string" && typeof v === "string") activeTeams.set(k, v);
+		}
+	} catch (e) {}
+}
+function saveActiveTeams() {
+	try {
+		mkdirSync(teamflowRoot(), { recursive: true });
+		writeJson(ACTIVE_TEAMS_FILE(), Object.fromEntries(activeTeams));
+	} catch (e) {}
+}
 /** 延迟注入队列：选团队时 agent 可能尚未加载，存入 pending，后续时机补发。 */
 const pendingInjections = /* @__PURE__ */ new Map();
 /** 尝试补发延迟注入：agent 可用时注入上下文并清除 pending。 */
@@ -3778,11 +4331,13 @@ var TeamflowService = class extends TypertRemoteService {
 		"subagents",
 		"tokenMeter",
 		"typert",
-		"tools"
+		"tools",
+		"llm"
 	];
 	constructor(ctx) {
 		super(ctx, "teamflow");
-		setRuntime(ctx.get("agents"), ctx.get("subagents"), ctx.get("tokenMeter"), ctx.get("workspaceRegistry"), ctx.get("agentDefaultModel"));
+		setRuntime(ctx.get("agents"), ctx.get("subagents"), ctx.get("tokenMeter"), ctx.get("workspaceRegistry"), ctx.get("agentDefaultModel"), ctx.get("llm"));
+		loadActiveTeams();
 		let interruptedCount = 0;
 		try {
 			for (const { journal, wasInterrupted } of loadJournals()) {
@@ -4083,6 +4638,7 @@ var TeamflowService = class extends TypertRemoteService {
 			error: `团队 ${tid} 不存在`
 		};
 		activeTeams.set(sid, tid);
+		saveActiveTeams();
 		const agent = runtime.agents && runtime.agents.get(sid);
 		const injectPayload = {
 			type: "user",
@@ -4139,6 +4695,7 @@ var TeamflowService = class extends TypertRemoteService {
 			error: "缺少 sessionId"
 		};
 		activeTeams.delete(sid);
+		saveActiveTeams();
 		return { ok: true };
 	}
 	/** 从断点续跑：跳过已完成阶段，从第一个未完成阶段重跑。 */