@tea-agent/loop-agent 0.44.0-next.11 → 0.44.0-next.12

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ### 新增
 
+- 前端 DAG 的行为验证不再只认 Vitest：测试框架改为可插拔适配层，首批支持 Vitest、Jest 与 Playwright Test。三类项目都能用**真实报告**证明契约绑定的测试文件确实执行且通过，`npm`/`pnpm`/`yarn` 的常用测试入口走同一套识别逻辑，直接命令与 `package.json` 脚本不会再得出不同结论。
+- 未适配的测试框架（Cypress、`node --test`、Mocha、自定义脚本等）现在明确报「缺少适配能力」，并附上具体命令与原因；此前这类命令会被判为不支持，错误信息还暗示你「必须改用 Vitest」，把工具的能力缺口显示成了用户配置错误。
+- 行为验证保留「测试确实执行过」的校验：零测试、全部跳过、报告缺失、报告过期、契约绑定文件未执行都判失败，不会退回只看退出码（全部跳过的运行退出码是 0）。
+
 - main 上的 npm `next` 预发布改为跑默认测试（fast + integration），不再在每次发布时重复跑约 6 分钟的 I/O-heavy 池；完整三池仍由 PR、正式 release 线、本地推送前检查与发布前钩子承担。同时把该预发布任务的 I/O 并发从 1 调到 2，并把 npm 包可见性确认的等待窗口从约 3 分钟拉长到约 10 分钟，避免包已发出却因仓库异步处理未完成而被判失败。
 
 - 修复 main 分支的 next 发布链在类型检查阶段内存溢出失败的问题：完整源码与测试的类型图已超过 Node 默认约 2 GiB 堆上限，类型检查进程因此中止（exit 134），导致 `next` 发布无法完成。此前该上限只在部分验证入口生效，其余入口直接运行类型检查就会因默认堆不足而失败；现把上限固化到类型检查命令本身，各验证入口与本地开发统一生效，不再依赖各入口自行声明。
@@ -137,6 +141,7 @@
 
 ### 改进
 
+- DAG 运行时内部按职责拆开：模型配置、领域工具、分段会话、模板族、终态判定与检查点各自独立维护，测试也按行为分成可单独调度的文件。命令、任务流程与用户可见结果不变。本机默认测试并行下整池耗时未证实变快。
 - Operator Chat 输入框下方的会话统计对齐 DSH：长串静态文字收敛为两个可点击摘要，可分别查看模型/工具用时、TTFT、TPS 与 Token 分项；详情卡互斥并支持外部点击或 Escape 关闭，窄屏打开时不会推动输入框或消息流。
 - Operator Chat 长会话新增完整轮次轨道与按需历史定位，可从任意用户消息精确新建会话；历史图片刷新后仍可预览，仓库文件链接可直接定位到行，最终回答显示单轮 token/耗时，并支持可持久化的紧凑/完整阅读模式。图片文件与消息记录分离保存，删除、分叉和失败回滚会同步清理，附件读取重新校验类型与引用。
 - 本地分支合并默认只执行与影响面匹配的定向测试、类型检查、构建和治理检查；完整测试推迟到 push 或完整交付前，并通过 receipt、`verify:tree` 或 pre-push 在最终 tree 上只执行一次。发布与推送门禁仍包含 I/O-heavy 测试。
@@ -149,6 +154,12 @@
 
 ### 修复
 
+- 前端 DAG 的验证失败不再把配置问题算到业务代码头上：报告缺失或过期、报告协议错误、命令或脚本哈希漂移、框架未适配都归为验证配置问题，不再触发一轮无意义的实现重写；测试断言失败仍归实现问题。
+- 已经自带 `--reporter`/`--outputFile` 的测试命令或脚本不会被悄悄覆盖；无法安全注入报告参数时在生成阶段直接报错，要求改用可注入的入口。
+- 修复 Playwright 项目在 Review 阶段被误判失败的问题：审查重读报告时没有带上协议，仍按 Vitest 解析，导致 Playwright 报告因缺少 `testResults` 报错，即使执行与 trace 已经通过。report 引用现在记录协议，review 按同一协议解析并校验一致性。
+- 修复 Playwright 报告路径按 `testDir` 解析错误的问题：报告中的文件路径相对 Playwright 自身的 `config.rootDir`，此前按进程 cwd 解析，配了 `testDir: "./tests"` 的项目会得到 `orders.spec.js` 而非 `tests/orders.spec.js`，契约目标永远无法匹配。
+- 修复新建 Jest/Playwright 项目被误报“绑定漂移”的问题：`deferred` 观测的协议只是占位值，此前无条件参与比较，writer 一补上合法测试脚本就触发 `FRONTEND_TEST_BINDING_DRIFT`；现在只有已解析出 adapter 的观测才比较协议，真实脚本改动仍会被拦截。
+
 - 修复 macOS/Linux 开发路径在 Windows 暴露的三类兼容问题：前端组合验证夹具不再依赖 POSIX 单引号；无 `.gitmodules` 的仓库不再把 Git 空结果误判为启动失败；定时任务用 Git 规范化内容生成稳定树指纹，CRLF checkout 不再造成虚假 evidence drift。托管任务路径与嵌套 submodule 测试也统一使用跨平台路径语义。
 - 切换会话后，旧会话尚未确认的输入不会再出现在新会话中。
 - 修复 Windows 上 Pi 节点在没有提交改动时误报“文件在打开期间被替换”的问题，同时保留原有文件安全检查。

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.0-next.11",
-  "gitSha": "332db6a894b640eef5c495e3a3ba92b383fcf259",
-  "builtAt": "2026-09-17T05:51:06.283Z"
+  "version": "0.44.0-next.12",
+  "gitSha": "91181001a8cbed75a00a8a6d8e76ae5fab889b36",
+  "builtAt": "2026-09-17T10:04:11.141Z"
 }

package/dist/executors/shell-executor.js

@@ -1,7 +1,7 @@
 import { collectExistingFrontendVerificationPaths } from "../workflows/dag/frontend-implementation-contract.js";
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { inspectFrontendTestCommand, compareFrontendTestObservation, parseFrontendTestExecutionReport } from "../workflows/dag/frontend-test-execution-evidence.js";
+import { FRONTEND_TEST_OBSERVATION_FAILURES, inspectFrontendTestCommand, compareFrontendTestObservation, parseFrontendTestExecutionReport } from "../workflows/dag/frontend-test-execution-evidence.js";
 import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -135,6 +135,13 @@ function shouldReuseSuccessfulShellCommands(shell) {
     return shell.verifyEvidence?.phase === "intermediate" || shell.verifyEvidence?.phase === "final";
 }
 const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
+/**
+ * Tolerance for filesystem mtime granularity when rejecting a test report as
+ * stale. Reports are written by the command we just ran, so the only legitimate
+ * skew is coarse mtime resolution (1s on some filesystems) — not a real clock
+ * difference.
+ */
+const REPORT_FRESHNESS_SKEW_MS = 2_000;
 const SUMMARY_STDOUT_MAX = 4_000;
 const SUMMARY_STDERR_MAX = 2_000;
 const TEST_TIMEOUT_CLASSIFY_MAX_CHARS = 8_000;
@@ -312,7 +319,10 @@ export async function executeShellCommand(input) {
             : undefined;
         const child = spawn(resolveBashExecutable(), ["-c", input.command], {
             cwd: input.cwd,
-            env: buildShellProcessEnv(input.envAllowlist, injectedEnv),
+            env: buildShellProcessEnv(input.envAllowlist, {
+                ...injectedEnv,
+                ...input.extraEnv,
+            }),
             ...processTreeSpawnOptions(),
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -2140,16 +2150,20 @@ async function executeFrontendVerificationBundle(input, meta) {
             let result = cached ? reuseCommandResult(cached, command) : undefined;
             if (!result) {
                 const commandNumber = results.length + 1;
-                const reportPath = path.join(meta.runDir, input.task.id, "commands", `${commandNumber}-${randomUUID()}.vitest.json`);
                 const observedTest = testPreflight.inspected.get(command);
-                const observedCommand = observedTest?.withReporter?.(reportPath);
-                if (observedCommand)
+                // Name the report after the resolved protocol so an operator can
+                // tell at a glance which runner produced it.
+                const reportScheme = observedTest?.observation.scheme ?? "vitest-json-v1";
+                const reportPath = path.join(meta.runDir, input.task.id, "commands", `${commandNumber}-${randomUUID()}.${reportScheme}.json`);
+                const observedInvocation = observedTest?.withReporter?.(reportPath);
+                if (observedInvocation)
                     await mkdir(path.dirname(reportPath), { recursive: true });
                 result = await executeShellCommand({
-                    command: observedCommand ?? command,
+                    command: observedInvocation?.command ?? command,
                     cwd,
                     timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
                     envAllowlist: shell.envAllowlist,
+                    extraEnv: observedInvocation?.env,
                     dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
                     reportActivity: input.reportActivity,
                     outputArtifacts: {
@@ -2158,21 +2172,35 @@ async function executeFrontendVerificationBundle(input, meta) {
                     },
                 });
                 let reportError;
-                if (observedCommand && result.ok) {
+                if (observedInvocation && result.ok) {
                     try {
-                        // Vitest reports physical paths (e.g. /private/var on macOS).
+                        // Runners report physical paths (e.g. /private/var on macOS).
                         // Match those in workspace coordinates even when shell.cwd is
                         // a subdirectory or the caller used a directory alias.
+                        const reportStat = await stat(reportPath);
+                        // A stale report from an earlier run would otherwise let a
+                        // command that wrote nothing at all look verified.
+                        if (reportStat.mtimeMs < started - REPORT_FRESHNESS_SKEW_MS) {
+                            throw new Error(`stale test execution report (${FRONTEND_TEST_OBSERVATION_FAILURES.reportProtocol}): report predates this command`);
+                        }
                         const rawReport = await readFile(reportPath, "utf8");
                         const reportSha256 = createHash("sha256").update(rawReport).digest("hex");
-                        commandExecutionEvidence.set(key, parseFrontendTestExecutionReport(JSON.parse(rawReport), await realpath(observedTest?.effectiveCwd ?? cwd), await realpath(input.cwd)));
+                        const parsedExecutions = parseFrontendTestExecutionReport(JSON.parse(rawReport), await realpath(observedTest?.effectiveCwd ?? cwd), await realpath(input.cwd), observedTest.observation.scheme);
+                        // Zero tests is not evidence: the runner may have matched no
+                        // file at all. The trace gate also rejects a target file with
+                        // no matching record, but failing here keeps the report itself
+                        // from being recorded as a successful observation.
+                        if (parsedExecutions.length === 0) {
+                            throw new Error(`test execution report contains no test cases (${FRONTEND_TEST_OBSERVATION_FAILURES.reportProtocol})`);
+                        }
+                        commandExecutionEvidence.set(key, parsedExecutions);
                         const actual = commandExecutionEvidence.get(key);
                         for (let offset = 0; offset < actual.length; offset += 24) {
                             const relative = `${input.task.id}/commands/${commandNumber}-execution-${offset / 24}.json`;
-                            const excerpt = { schemaVersion: 1, commandSha256: observedTest.observation.commandSha256, cwd: observedTest.observation.cwd, reportSha256, offset, total: actual.length, behaviorCoverage: "unconfirmed", tests: actual.slice(offset, offset + 24).map(test => ({ file: test.file, status: test.status, title: test.title.slice(0, 500), ...(test.title.length > 500 ? { titleTruncated: true } : {}) })) };
+                            const excerpt = { schemaVersion: 1, scheme: observedTest.observation.scheme, commandSha256: observedTest.observation.commandSha256, cwd: observedTest.observation.cwd, reportSha256, offset, total: actual.length, behaviorCoverage: "unconfirmed", tests: actual.slice(offset, offset + 24).map(test => ({ file: test.file, status: test.status, title: test.title.slice(0, 500), ...(test.title.length > 500 ? { titleTruncated: true } : {}) })) };
                             await writeDagRunJsonArtifact(meta.runDir, relative, excerpt);
                             const bytes = await readFile(path.join(meta.runDir, relative));
-                            testExecutionEvidence.push({ path: relative, sha256: createHash("sha256").update(bytes).digest("hex"), reportPath: path.relative(meta.runDir, reportPath).replace(/\\/g, "/"), reportSha256 });
+                            testExecutionEvidence.push({ path: relative, sha256: createHash("sha256").update(bytes).digest("hex"), reportPath: path.relative(meta.runDir, reportPath).replace(/\\/g, "/"), reportSha256, scheme: observedTest.observation.scheme });
                         }
                     }
                     catch (error) {

package/dist/worker/console/routes.js

@@ -38,6 +38,11 @@ function contentTypeFor(pathname) {
         return "text/css; charset=utf-8";
     if (lower.endsWith(".json"))
         return "application/json; charset=utf-8";
+    // A web app manifest must carry this exact type: browsers ignore the
+    // document (and therefore offer no install entry) when it arrives as
+    // application/octet-stream.
+    if (lower.endsWith(".webmanifest"))
+        return "application/manifest+json";
     if (lower.endsWith(".svg"))
         return "image/svg+xml";
     if (lower.endsWith(".png"))

package/dist/worker/console/static/app-icon.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
+  <title>Loop Agent App Icon</title>
+  <style>
+    .loop-ink { stroke: #26251e; }
+    @media (prefers-color-scheme: dark) {
+      .loop-ink { stroke: #f7f7f4; }
+    }
+  </style>
+  <defs>
+    <mask id="square-handoff" maskUnits="userSpaceOnUse" x="0" y="6" width="64" height="52">
+      <rect x="0" y="6" width="64" height="52" fill="#ffffff" />
+      <path
+        d="m31.15 32.28 2.83 3.11"
+        fill="none"
+        stroke="#000000"
+        stroke-linecap="round"
+        stroke-width="6.23"
+      />
+    </mask>
+  </defs>
+  <g transform="translate(4.8485 13.899) scale(0.56566)">
+    <path
+      class="loop-ink"
+      d="M12 32c0-16 16-20 28-6l17 18c11 11 27 5 27-12S68 9 57 20L39 39C28 51 12 48 12 32Z"
+      fill="none"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      stroke-width="11"
+      mask="url(#square-handoff)"
+    />
+  </g>
+  <path
+    d="m31.15 32.28 2.83 3.11"
+    fill="none"
+    stroke="#f54e00"
+    stroke-linecap="round"
+    stroke-width="5.37"
+  />
+</svg>

package/dist/worker/console/static/index.html

@@ -3,7 +3,10 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#f4f2ee" />
+    <link rel="manifest" href="/manifest.webmanifest" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/app-icon.svg" />
     <link rel="preconnect" href="https://cdn.jsdelivr.net" />
     <link
       rel="stylesheet"

package/dist/worker/console/static/manifest.webmanifest

@@ -0,0 +1,19 @@
+{
+  "id": "/",
+  "name": "Loop Operator Console",
+  "short_name": "Loop Console",
+  "description": "Loop Agent 操作台：任务、Agent DAG 运行与交付证据的只读观察与受控操作界面",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "background_color": "#f4f2ee",
+  "theme_color": "#f4f2ee",
+  "icons": [
+    {
+      "src": "/app-icon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any"
+    }
+  ]
+}

package/dist/worker/observe/static/console-theme.js

@@ -7,10 +7,46 @@ export const CONSOLE_THEMES = Object.freeze([
 
 const STORAGE_KEY = "loop-console.theme.v1";
 
+/**
+ * Titlebar colour per theme, matching each palette's --canvas. An installed PWA
+ * paints the OS window frame with the theme-color meta value, so it must track
+ * the active theme: a fixed brand colour leaves an orange titlebar above the
+ * dark midnight palette. Values mirror console-theme.css --canvas.
+ */
+const TITLEBAR_COLOR = Object.freeze({
+	default: "#f4f2ee",
+	midnight: "#1c222a",
+	daylight: "#eef0f2",
+});
+
 function normalizeTheme(value) {
 	return CONSOLE_THEMES.some((theme) => theme.id === value) ? value : "default";
 }
 
+/**
+ * Project the theme onto the document's theme-color meta tag. Browsers read
+ * this tag live (the manifest theme_color only applies at install time), and
+ * an installed window repaints its frame when it changes.
+ *
+ * Strictly best-effort: the titlebar is cosmetic, so a missing or partial DOM
+ * (SSR, a test stub, an exotic embedder) must never break theme switching.
+ */
+function syncTitlebarColor(theme) {
+	try {
+		const head = document?.head;
+		if (!head || typeof document.createElement !== "function") return;
+		let meta = document.querySelector?.('meta[name="theme-color"]');
+		if (!meta) {
+			meta = document.createElement("meta");
+			meta.setAttribute("name", "theme-color");
+			head.appendChild(meta);
+		}
+		meta.setAttribute("content", TITLEBAR_COLOR[theme] ?? TITLEBAR_COLOR.default);
+	} catch {
+		// The palette switch above already succeeded; the titlebar is optional.
+	}
+}
+
 export function applyStoredConsoleTheme() {
 	let value;
 	try {
@@ -20,6 +56,7 @@ export function applyStoredConsoleTheme() {
 	}
 	const theme = normalizeTheme(value);
 	document.documentElement.dataset.consoleTheme = theme;
+	syncTitlebarColor(theme);
 	return theme;
 }
 
@@ -27,6 +64,7 @@ export function setConsoleTheme(value) {
 	const theme = normalizeTheme(value);
 	// Apply before persistence: a storage failure must not disable the picker.
 	document.documentElement.dataset.consoleTheme = theme;
+	syncTitlebarColor(theme);
 	try {
 		window.localStorage.setItem(STORAGE_KEY, theme);
 	} catch {

package/dist/workflows/dag/frontend-repair.js

@@ -1,5 +1,19 @@
 import { z } from "zod";
 import { FRONTEND_NO_VERIFICATION_MARKER_TEXT, } from "./frontend-verification-trace.js";
+import { FRONTEND_TEST_OBSERVATION_FAILURES } from "./frontend-test-execution-evidence.js";
+/**
+ * Substrings that prove a behavior-verification failure came from the
+ * verification configuration rather than the candidate's code. Kept next to the
+ * taxonomy so a new failure code is routed deliberately instead of falling
+ * through to the string-blob heuristics below.
+ */
+const FRONTEND_TEST_VERIFICATION_CONFIG_MARKERS = [
+    FRONTEND_TEST_OBSERVATION_FAILURES.bindingDrift,
+    FRONTEND_TEST_OBSERVATION_FAILURES.reportProtocol,
+    FRONTEND_TEST_OBSERVATION_FAILURES.capabilityGap,
+    "FRONTEND_TEST_OBSERVATION_INVALID",
+    "frontend test execution report unavailable",
+];
 export const frontendRepairFailureClassSchema = z.enum([
     "typecheck",
     "build",
@@ -73,6 +87,16 @@ export function classifyFrontendFailure(input) {
     if (input.failureCategory === "write-guard") {
         return "path";
     }
+    // Verification-config faults must never be mistaken for product defects.
+    // A missing/unreadable report, a stale report, an unsupported runner or a
+    // drifted command binding are all tooling/contract problems: rewriting the
+    // candidate's business code cannot fix them and burns a repair round. These
+    // are detected structurally, before any blob heuristic can see a runner name
+    // (the `unit-test` rule matches the literal word "jest") and misroute the
+    // failure to the implementation owner.
+    if (FRONTEND_TEST_VERIFICATION_CONFIG_MARKERS.some((marker) => `${input.stderr ?? ""}\n${input.stdout ?? ""}`.includes(marker))) {
+        return "contract";
+    }
     if (`${input.stderr ?? ""}\n${input.stdout ?? ""}`.includes(FRONTEND_NO_VERIFICATION_MARKER_TEXT)) {
         // Verification unavailability is a generation-time contract gap: no
         // authorized verification command exists. Bounded repair cannot fix it;

package/dist/workflows/dag/frontend-review-scopes.js

@@ -1,4 +1,5 @@
 import { parseFrontendTestExecutionReport } from "./frontend-test-execution-evidence.js";
+import { isFrontendTestReportScheme } from "./frontend-test-framework-adapters.js";
 import { readFileBoundarySafe } from "../../shared/path-safety.js";
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, realpath, lstat } from "node:fs/promises";
@@ -109,12 +110,16 @@ export async function loadFrontendReviewScopes(runDir, phase, targetBytes, works
         const reportCoverage = new Map();
         const reportedTests = [];
         for (const ref of payload.verificationTrace?.testExecutionEvidence ?? []) {
-            if (!isArtifactReference(ref) || typeof ref.reportPath !== "string" || !/^[a-f0-9]{64}$/.test(ref.reportSha256))
+            if (!isArtifactReference(ref) || typeof ref.reportPath !== "string" || !/^[a-f0-9]{64}$/.test(ref.reportSha256) || !isFrontendTestReportScheme(ref.scheme))
                 throw invalidScope("invalid test execution reference");
             const excerpt = await read(ref.path, ref.sha256);
             const data = JSON.parse(excerpt.text);
             if (data.reportSha256 !== ref.reportSha256)
                 throw invalidScope("test execution report binding mismatch");
+            // The excerpt records the protocol that produced it. A mismatch means the
+            // trace and its report disagree, so refuse rather than guess an adapter.
+            if (data.scheme !== ref.scheme)
+                throw invalidScope("test execution report protocol binding mismatch");
             const coverage = reportCoverage.get(ref.reportPath) ?? { count: 0, total: data.total };
             if (!Number.isInteger(data.total) || data.total < 1 || data.total !== coverage.total || data.offset !== coverage.count || !Array.isArray(data.tests) || !data.tests.length || data.tests.length > 24)
                 throw invalidScope("test report excerpt coverage invalid");
@@ -128,7 +133,10 @@ export async function loadFrontendReviewScopes(runDir, phase, targetBytes, works
                 const cwdPath = await realpath(path.resolve(workspaceRoot, data.cwd));
                 if (cwdPath !== rootPath && !cwdPath.startsWith(rootPath + path.sep))
                     throw invalidScope("test report cwd escaped workspace");
-                const actual = parseFrontendTestExecutionReport(JSON.parse(report.text), cwdPath, rootPath);
+                // Parse with the protocol the runner actually used. Defaulting to
+                // Vitest here failed every Playwright/Jest report at review time even
+                // though execution and trace had accepted it.
+                const actual = parseFrontendTestExecutionReport(JSON.parse(report.text), cwdPath, rootPath, ref.scheme);
                 const expected = actual.slice(data.offset, data.offset + 24).map(test => ({ file: test.file, status: test.status, title: test.title.slice(0, 500), ...(test.title.length > 500 ? { titleTruncated: true } : {}) }));
                 if (data.total !== actual.length || !expected.length || sha256OfCanonicalJson(expected) !== sha256OfCanonicalJson(data.tests))
                     throw invalidScope("test report excerpt differs from actual runner report");

package/dist/workflows/dag/frontend-test-execution-evidence.js

@@ -3,14 +3,32 @@ import { createHash } from "node:crypto";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { readFile, realpath } from "node:fs/promises";
 import { z } from "zod";
+import { FRONTEND_TEST_ADAPTERS, detectUnadaptedRunner, frontendTestReportSchemeSchema, resolveFrontendTestAdapter, resolveRunnerArgv, } from "./frontend-test-framework-adapters.js";
+/** Scheme → adapter lookup, built once from the adapter registry. */
+const FRONTEND_TEST_ADAPTERS_BY_SCHEME = Object.fromEntries(FRONTEND_TEST_ADAPTERS.map((adapter) => [adapter.scheme, adapter]));
+/**
+ * Failure taxonomy for behavior verification. Kept separate from the writer's
+ * `failureCategory` so a broken report protocol never reads as broken product
+ * code and trigger a pointless implementation rewrite.
+ */
+export const FRONTEND_TEST_OBSERVATION_FAILURES = {
+    /** The frozen command drift from what the contract bound. */
+    bindingDrift: "FRONTEND_TEST_BINDING_DRIFT",
+    /** The runner produced no readable report, or the report was stale. */
+    reportProtocol: "FRONTEND_TEST_REPORT_PROTOCOL",
+    /** The runner itself is not adapted (Cypress, `node --test`, …). */
+    capabilityGap: "FRONTEND_TEST_CAPABILITY_GAP",
+};
 export const frontendTestObservationSchema = z.object({
-    scheme: z.literal("vitest-json-v1"),
+    scheme: frontendTestReportSchemeSchema,
     commandId: z.string().optional(),
     status: z.enum(["supported", "deferred", "unsupported"]),
     commandSha256: z.string().regex(/^[a-f0-9]{64}$/),
     cwd: z.string(),
     packageScript: z.object({ file: z.string(), name: z.string(), sha256: z.string().nullable() }).optional(),
     reason: z.string().optional(),
+    /** Set when `status: "unsupported"` because no adapter exists yet. */
+    capabilityGap: z.string().optional(),
 }).strict();
 const hash = (text) => createHash("sha256").update(text).digest("hex");
 const quote = (text) => `'${text.replace(/'/g, `'"'"'`)}'`;
@@ -124,20 +142,68 @@ function literalCommand(command, cwd, depth = 0) {
     }
     return { argv, cwd, append: suffix => command.trimEnd() + suffix };
 }
-function directVitest(argv) {
-    const args = [...argv];
-    if (["npx"].includes(args[0] ?? ""))
-        args.shift();
-    else if (["pnpm", "yarn"].includes(args[0] ?? "") && args[1] === "exec")
-        args.splice(0, 2);
-    return args[0] === "vitest" && args[1] === "run";
-}
 function hasReporter(argv) { return argv.some(arg => /^--(?:reporter|outputFile)(?:[.=]|$)/.test(arg)); }
-/** Shared read-only capability resolver, used at generation, admission and
- * immediately before execution. It never executes or rewrites an npm script. */
+/** Locate the `npm|pnpm|yarn` script invocation in a literal argv. */
+function scriptInvocation(argv) {
+    const manager = argv[0];
+    if (manager !== "npm" && manager !== "pnpm" && manager !== "yarn")
+        return undefined;
+    // `exec`/`dlx`/`create` run a binary rather than a package script, so they
+    // are not script invocations — `yarn exec vitest run` must resolve as a
+    // direct runner command, not as a script literally named "exec".
+    const subcommands = new Set(["exec", "dlx", "create", "init", "add", "install", "why", "config"]);
+    // npm test | npm run <name> | pnpm test | pnpm run <name> | yarn <name>
+    let name;
+    let rest = [];
+    if (argv[1] === "test") {
+        name = "test";
+        rest = argv.slice(2);
+    }
+    else if (argv[1] === "run") {
+        name = argv[2];
+        rest = argv.slice(3);
+    }
+    else if (manager === "yarn" && argv[1] && !argv[1].startsWith("-") && !subcommands.has(argv[1])) {
+        name = argv[1];
+        rest = argv.slice(2);
+    }
+    if (!name || !/^[\w:-]+$/.test(name))
+        return undefined;
+    if (rest.length && rest[0] !== "--")
+        throw Error("package manager script arguments require --");
+    return { name, rest };
+}
+/**
+ * Build the report invocation for an adapter.
+ *
+ * When the adapter names a `reportPathEnv`, the path travels in the environment
+ * and the suffix only selects the reporter — appending the path to the command
+ * would hand it to the runner as a positional argument (Playwright treats a
+ * stray argument as a test-name filter and then finds no tests at all).
+ *
+ * Otherwise the path is joined to the suffix: a suffix ending in `=` (Vitest's
+ * `--outputFile=`) binds it directly, and any other suffix names a flag
+ * (`--outputFile`, `--json`) that takes the path as the next argument.
+ */
+function reportInvocation(adapter, append, suffix, reportPath) {
+    if (adapter.reportPathEnv) {
+        return {
+            command: append(suffix),
+            env: { [adapter.reportPathEnv]: reportPath },
+        };
+    }
+    const joiner = suffix.endsWith("=") ? "" : " ";
+    return { command: append(`${suffix}${joiner}${quote(reportPath)}`) };
+}
+/**
+ * Shared read-only capability resolver, used at generation, admission and
+ * immediately before execution. It never executes or rewrites an npm script.
+ */
 export async function inspectFrontendTestCommand(input) {
     const root = path.resolve(input.workspaceRoot ?? input.cwd);
     let cwd = path.resolve(input.cwd);
+    // `scheme` is unknowable until an adapter resolves; the placeholder is only
+    // ever surfaced on the unsupported path, where no report is produced.
     const base = { scheme: "vitest-json-v1", status: "unsupported", commandSha256: hash(input.command), cwd: path.relative(root, cwd).replace(/\\/g, "/") || "." };
     try {
         const parsed = literalCommand(input.command, cwd);
@@ -154,79 +220,109 @@ export async function inspectFrontendTestCommand(input) {
             throw Error("test cwd resolves outside the workspace");
         if (hasReporter(parsed.argv))
             throw Error("frozen command already owns reporter/outputFile flags");
-        let separator = "";
-        if (!directVitest(parsed.argv)) {
-            const argv = parsed.argv;
-            const name = argv[0] === "npm" ? argv[1] === "test" ? "test" : argv[1] === "run" ? argv[2] : undefined : undefined;
-            if (!name || !/^[\w:-]+$/.test(name))
-                throw Error("no supported test reporter adapter for this command");
-            const rest = argv.slice(argv[1] === "test" ? 2 : 3);
-            if (rest.length && rest[0] !== "--")
-                throw Error("npm script arguments require --");
-            const file = path.relative(root, path.join(cwd, "package.json")).replace(/\\/g, "/");
-            let manifest = {};
-            try {
-                manifest = JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
-            }
-            catch (error) {
-                if (error.code !== "ENOENT")
-                    throw Error("package.json is unreadable or invalid");
-            }
-            const script = manifest?.scripts?.[name];
-            base.packageScript = { file, name, sha256: typeof script === "string" ? hash(JSON.stringify({ script, pre: manifest.scripts?.[`pre${name}`] ?? null, post: manifest.scripts?.[`post${name}`] ?? null })) : null };
-            if (script === undefined) {
-                const authorized = input.allowedPaths?.some(pattern => pathMatchesPattern(file, pattern)) && !input.forbiddenPaths?.some(pattern => pathMatchesPattern(file, pattern));
-                if (!authorized)
-                    throw Error(`missing npm script ${name}; ${file} is not an authorized delivery`);
-                return { observation: { ...base, status: "deferred", reason: `Awaiting authorized ${file} script ${name} with vitest-json-v1 capability` }, effectiveCwd: cwd };
-            }
-            if (typeof script !== "string")
-                throw Error("npm script must be a string");
-            const scriptWords = words(script);
-            if (scriptWords.some(word => word.operator) || !directVitest(scriptWords.map(w => w.value)) || hasReporter(scriptWords.map(w => w.value)))
-                throw Error("npm script has no supported Vitest JSON reporter capability");
-            separator = rest.length ? "" : " --";
+        const runner = resolveRunnerArgv(parsed.argv);
+        const invocation = scriptInvocation(parsed.argv);
+        if (!invocation) {
+            const adapter = resolveFrontendTestAdapter({ argv: parsed.argv, runner });
+            if (!adapter)
+                throw capabilityGapError(runner);
+            const suffix = adapter.reportSuffix({ argv: parsed.argv, runner });
+            if (suffix === undefined)
+                throw Error(`${adapter.runner} project configuration owns report output; declare an explicit regression command instead of overriding it`);
+            return { observation: { ...base, scheme: adapter.scheme, status: "supported" }, effectiveCwd: cwd,
+                withReporter: reportPath => reportInvocation(adapter, inner => parsed.append(` ${inner}`), suffix, reportPath) };
+        }
+        const file = path.relative(root, path.join(cwd, "package.json")).replace(/\\/g, "/");
+        let manifest = {};
+        try {
+            manifest = JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
         }
-        return { observation: { ...base, status: "supported" }, effectiveCwd: cwd,
-            withReporter: reportPath => parsed.append(`${separator} --reporter=json --outputFile=${quote(reportPath)}`) };
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw Error("package.json is unreadable or invalid");
+        }
+        const script = manifest?.scripts?.[invocation.name];
+        base.packageScript = { file, name: invocation.name, sha256: typeof script === "string" ? hash(JSON.stringify({ script, pre: manifest.scripts?.[`pre${invocation.name}`] ?? null, post: manifest.scripts?.[`post${invocation.name}`] ?? null })) : null };
+        if (script === undefined) {
+            const authorized = input.allowedPaths?.some(pattern => pathMatchesPattern(file, pattern)) && !input.forbiddenPaths?.some(pattern => pathMatchesPattern(file, pattern));
+            if (!authorized)
+                throw Error(`missing npm script ${invocation.name}; ${file} is not an authorized delivery`);
+            return { observation: { ...base, status: "deferred", reason: `Awaiting authorized ${file} script ${invocation.name} with a supported test report capability` }, effectiveCwd: cwd };
+        }
+        if (typeof script !== "string")
+            throw Error("npm script must be a string");
+        const scriptWords = words(script);
+        if (scriptWords.some(word => word.operator))
+            throw Error("npm script must be a single literal command");
+        const scriptArgv = scriptWords.map(w => w.value);
+        if (hasReporter(scriptArgv))
+            throw Error("npm script already owns reporter/outputFile flags");
+        const scriptRunner = resolveRunnerArgv(scriptArgv);
+        const adapter = resolveFrontendTestAdapter({ argv: parsed.argv, runner: scriptRunner, scriptName: invocation.name, scriptArgv });
+        if (!adapter)
+            throw capabilityGapError(scriptRunner);
+        const suffix = adapter.reportSuffix({ argv: scriptArgv, runner: scriptRunner });
+        if (suffix === undefined)
+            throw Error(`${adapter.runner} project configuration owns report output; declare an explicit regression command instead of overriding it`);
+        // `npm test -- --json` forwards the flags to the script; a bare script
+        // uses the same `--` separator so npm never eats the report flags.
+        // Space-prefixed because `append` concatenates onto the trimmed
+        // command; a bare script needs `--` so npm forwards the report flags.
+        const separator = invocation.rest.length ? "" : " -- ";
+        return { observation: { ...base, scheme: adapter.scheme, status: "supported" }, effectiveCwd: cwd,
+            withReporter: reportPath => reportInvocation(adapter, inner => parsed.append(invocation.rest.length ? ` ${inner}` : `${separator}${inner}`), suffix, reportPath) };
     }
     catch (error) {
-        return { observation: { ...base, status: "unsupported", reason: error instanceof Error ? error.message : String(error) }, effectiveCwd: cwd };
+        const gap = error.capabilityGap;
+        return { observation: { ...base, status: "unsupported", reason: error instanceof Error ? error.message : String(error), ...(gap ? { capabilityGap: gap } : {}) }, effectiveCwd: cwd };
     }
 }
+/**
+ * An unadapted runner is a capability gap in this tool, not a user mistake: the
+ * message must never suggest switching frameworks.
+ */
+function capabilityGapError(runner) {
+    const known = detectUnadaptedRunner(runner);
+    const binary = known ?? (runner[0] ?? "unknown");
+    const error = new Error(`${FRONTEND_TEST_OBSERVATION_FAILURES.capabilityGap}: no test report adapter for ${binary}; ` +
+        `frontend behavior verification currently adapts vitest, jest and playwright test, ` +
+        `so this command cannot produce execution evidence`);
+    error.capabilityGap = binary;
+    return error;
+}
 export function compareFrontendTestObservation(frozen, observed, phase, writeSet = []) {
     if (frozen.status === "unsupported")
         return frozen.reason ?? "unsupported test observation scheme";
     if (observed.status === "unsupported")
         return observed.reason ?? "unsupported test observation scheme";
-    if (frozen.scheme !== observed.scheme || frozen.commandSha256 !== observed.commandSha256 || frozen.cwd !== observed.cwd || frozen.packageScript?.file !== observed.packageScript?.file || frozen.packageScript?.name !== observed.packageScript?.name)
-        return "frozen test command/cwd/script binding changed";
+    // A `deferred` observation has no resolved adapter, so its `scheme` is the
+    // placeholder rather than a binding. Comparing it would reject every new
+    // Jest/Playwright project the moment the writer adds the very script the
+    // contract asked for. The scheme only becomes a binding once the frozen
+    // observation is `supported`; script identity is still checked below.
+    const schemeBound = frozen.status !== "deferred";
+    if ((schemeBound && frozen.scheme !== observed.scheme) || frozen.commandSha256 !== observed.commandSha256 || frozen.cwd !== observed.cwd || frozen.packageScript?.file !== observed.packageScript?.file || frozen.packageScript?.name !== observed.packageScript?.name)
+        return `${FRONTEND_TEST_OBSERVATION_FAILURES.bindingDrift}: frozen test command/cwd/script binding changed`;
     if (frozen.status === "supported" && (observed.status !== "supported" || frozen.packageScript?.sha256 !== observed.packageScript?.sha256))
-        return "frozen npm test script changed";
+        return `${FRONTEND_TEST_OBSERVATION_FAILURES.bindingDrift}: frozen npm test script changed`;
     if (frozen.status === "deferred" && phase === "admission" && (!frozen.packageScript || !writeSet.includes(frozen.packageScript.file)))
         return "future test script is outside the admitted concrete writeSet";
     if (phase === "execution" && observed.status !== "supported")
         return "future test reporter capability is still unavailable";
     return undefined;
 }
-/** Observe supported frozen Vitest commands without changing their selection. */
+/** Observe supported frozen commands without changing their selection. */
 export async function withFrontendTestReporter(input) {
-    return (await inspectFrontendTestCommand(input)).withReporter?.(input.reportPath);
+    return (await inspectFrontendTestCommand(input)).withReporter?.(input.reportPath)?.command;
 }
-const resultSchema = z.object({
-    testResults: z.array(z.object({
-        name: z.string().min(1),
-        assertionResults: z.array(z.object({
-            title: z.string(), fullName: z.string().optional(),
-            ancestorTitles: z.array(z.string()).optional(), status: z.string(),
-        })),
-    })),
-});
-/** Resolve runner paths against its cwd, then use the contract workspace coordinates. */
-export function parseFrontendTestExecutionReport(raw, cwd, workspaceRoot = cwd) {
-    return resultSchema.parse(raw).testResults.flatMap((suite) => suite.assertionResults.map((test) => ({
-        file: path.relative(workspaceRoot, path.resolve(cwd, suite.name)).replace(/\\/g, "/"),
-        title: test.fullName ?? [...(test.ancestorTitles ?? []), test.title].join(" "),
-        status: test.status,
-    })));
+/**
+ * Parse a runner report into uniform execution records using the adapter for
+ * `scheme`. A malformed report throws; callers classify that as a report
+ * protocol failure, never as a product defect.
+ */
+export function parseFrontendTestExecutionReport(raw, cwd, workspaceRoot = cwd, scheme = "vitest-json-v1") {
+    const adapter = FRONTEND_TEST_ADAPTERS_BY_SCHEME[scheme];
+    if (!adapter)
+        throw Error(`no test report adapter for scheme ${scheme}`);
+    return adapter.parse(raw, cwd, workspaceRoot);
 }

package/dist/workflows/dag/frontend-test-framework-adapters.js

@@ -0,0 +1,309 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+/**
+ * Framework adapters decouple the frontend behavior-verification contract from
+ * any single test runner.
+ *
+ * The contract, writer admission and execution all need three things from a
+ * frozen verify command:
+ *   1. whether the runner can emit a machine-readable execution report at all
+ *      (capability), so an unsupported runner fails closed *before* implement;
+ *   2. how to ask that runner for a report without clobbering the project's
+ *      own reporter configuration;
+ *   3. how to read that report back as uniform file/title/status triples.
+ *
+ * Historically all three were hardcoded to Vitest (`vitest-json-v1`), while the
+ * command classifier was already framework-agnostic. Jest and Playwright
+ * commands were therefore classified into the behavior lane correctly and then
+ * rejected as "unsupported", surfacing a capability gap to the user as if they
+ * had misconfigured their project. Adapters make the two sources of truth agree.
+ */
+/** Report protocols a frozen behavior command may be observed through. */
+export const frontendTestReportSchemeSchema = z.enum([
+    "vitest-json-v1",
+    "jest-json-v1",
+    "playwright-json-v1",
+]);
+/** Runtime guard for a persisted scheme, e.g. read back from a trace artifact. */
+export const isFrontendTestReportScheme = (value) => typeof value === "string" &&
+    frontendTestReportSchemeSchema.options.includes(value);
+const asRecord = (value) => typeof value === "object" && value !== null
+    ? value
+    : undefined;
+/**
+ * Resolve a runner-relative path into contract workspace coordinates.
+ *
+ * A runner may report an absolute path (`config.rootDir` is absolute in a
+ * Playwright report) or one relative to its own root. Either way the result is
+ * expressed against `workspaceRoot`, which is resolved physically first: a
+ * workspace reached through a symlink (macOS `/var` -> `/private/var`, i.e. the
+ * default `os.tmpdir()`) is never a lexical prefix of the runner's canonical
+ * path, so comparing raw strings would yield a `../..` escape instead of a
+ * contract-relative file.
+ */
+const toWorkspacePath = (raw, cwd, workspaceRoot) => {
+    const absolute = path.resolve(cwd, raw);
+    const physical = (target) => {
+        try {
+            return realpathSync(target);
+        }
+        catch {
+            return target;
+        }
+    };
+    const root = physical(path.resolve(workspaceRoot));
+    // The path may itself sit under the unresolved root; re-anchor it physically
+    // by resolving its root-relative tail against the physical root.
+    const anchored = absolute.startsWith(path.resolve(workspaceRoot) + path.sep)
+        ? path.join(root, path.relative(path.resolve(workspaceRoot), absolute))
+        : absolute;
+    return path.relative(root, physical(anchored)).replace(/\\/g, "/");
+};
+/**
+ * Strip package-manager indirection so `npx vitest run`, `pnpm exec vitest
+ * run`, `yarn exec vitest run` and a bare `vitest run` all reduce to the same
+ * runner invocation. Returns the remaining words.
+ */
+export function resolveRunnerArgv(argv) {
+    const words = [...argv];
+    // Skip leading env assignments (`CI=1 vitest run`).
+    while (words.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) {
+        words.shift();
+    }
+    const head = words[0];
+    if (head === "npx" || head === "pnpx" || head === "bunx") {
+        words.shift();
+        // `npx --no-install vitest run` / `npx -y vitest run`
+        while (words[0]?.startsWith("-"))
+            words.shift();
+        return words;
+    }
+    if ((head === "pnpm" || head === "yarn" || head === "npm") && words[1] === "exec") {
+        words.splice(0, 2);
+        while (words[0]?.startsWith("-"))
+            words.shift();
+        return words;
+    }
+    return words;
+}
+/** Runner binaries each adapter claims, keyed by adapter scheme. */
+const VITEST_BINARIES = new Set(["vitest"]);
+const JEST_BINARIES = new Set(["jest"]);
+const PLAYWRIGHT_BINARIES = new Set(["playwright"]);
+const basenameOf = (value) => value.split(/[\\/]/).pop() ?? "";
+/** True when `runner` invokes `binary` directly (allowing an explicit path). */
+const invokesBinary = (runner, binaries) => binaries.has(basenameOf(runner[0] ?? ""));
+const vitestAdapter = {
+    scheme: "vitest-json-v1",
+    runner: "vitest",
+    matches: ({ runner }) => invokesBinary(runner, VITEST_BINARIES),
+    // Vitest's json reporter writes to stdout unless an output file is given,
+    // and the executor reads the report from disk, so both flags are required.
+    reportSuffix: () => `--reporter=json --outputFile=`,
+    parse: (raw, cwd, workspaceRoot) => {
+        const schema = z.object({
+            testResults: z.array(z.object({
+                name: z.string().min(1),
+                assertionResults: z.array(z.object({
+                    title: z.string(),
+                    fullName: z.string().optional(),
+                    ancestorTitles: z.array(z.string()).optional(),
+                    status: z.string(),
+                })),
+            })),
+        });
+        return schema
+            .parse(raw)
+            .testResults.flatMap((suite) => suite.assertionResults.map((test) => ({
+            file: toWorkspacePath(suite.name, cwd, workspaceRoot),
+            title: test.fullName ??
+                [...(test.ancestorTitles ?? []), test.title].join(" "),
+            status: test.status,
+        })));
+    },
+};
+const jestAdapter = {
+    scheme: "jest-json-v1",
+    runner: "jest",
+    matches: ({ runner }) => invokesBinary(runner, JEST_BINARIES),
+    reportSuffix: () => `--json --outputFile`,
+    parse: (raw, cwd, workspaceRoot) => {
+        // Jest's `--json` shape: testResults[] carry a per-file `name` plus
+        // assertionResults[] that mirror Vitest's field names.
+        const schema = z.object({
+            testResults: z.array(z.object({
+                name: z.string().min(1),
+                assertionResults: z.array(z.object({
+                    title: z.string(),
+                    fullName: z.string().optional(),
+                    ancestorTitles: z.array(z.string()).optional(),
+                    status: z.string(),
+                })),
+            })),
+        });
+        return schema
+            .parse(raw)
+            .testResults.flatMap((suite) => suite.assertionResults.map((test) => ({
+            file: toWorkspacePath(suite.name, cwd, workspaceRoot),
+            title: test.fullName ??
+                [...(test.ancestorTitles ?? []), test.title].join(" "),
+            status: test.status,
+        })));
+    },
+};
+/**
+ * Playwright's JSON reporter emits a nested `suites` tree whose leaf `specs`
+ * carry `tests[].results[].status`. File paths live on the enclosing `file`
+ * field of each suite node, so the tree is walked while tracking it.
+ */
+const playwrightAdapter = {
+    scheme: "playwright-json-v1",
+    runner: "playwright",
+    matches: ({ runner }) => {
+        if (!invokesBinary(runner, PLAYWRIGHT_BINARIES))
+            return false;
+        // `playwright test` runs tests; `playwright install`/`codegen` do not.
+        return runner[1] === "test" || runner[1] === undefined;
+    },
+    reportSuffix: () => `--reporter=json`,
+    // Playwright ignores an output filename on the CLI (`--output` is its
+    // artifacts directory); its JSON reporter goes to stdout unless this
+    // variable names a file.
+    reportPathEnv: "PLAYWRIGHT_JSON_OUTPUT_NAME",
+    parse: (raw, cwd, workspaceRoot) => {
+        const suiteSchema = z.lazy(() => z.object({
+            file: z.string().optional(),
+            title: z.string().optional(),
+            specs: z
+                .array(z.object({
+                title: z.string(),
+                ok: z.boolean(),
+                tests: z.array(z.object({
+                    status: z.string().optional(),
+                    results: z
+                        .array(z.object({
+                        status: z.string(),
+                    }))
+                        .optional(),
+                })),
+            }))
+                .optional(),
+            suites: z.array(suiteSchema).optional(),
+        }));
+        const root = z
+            .object({
+            suites: z.array(suiteSchema).optional(),
+            // Playwright reports each suite's `file` relative to the resolved
+            // `testDir` (`config.rootDir`), not to the process cwd. A project
+            // with `testDir: "./tests"` reports `orders.spec.js` for
+            // `tests/orders.spec.js`, so resolving against cwd would produce a
+            // path that can never match a contract target.
+            config: z
+                .object({ rootDir: z.string().optional() })
+                .optional(),
+        })
+            .parse(raw);
+        // Prefer the runner's own reported root; fall back to cwd only when the
+        // report omitted it (older report shapes).
+        const reportedRoot = root.config?.rootDir;
+        const baseCwd = typeof reportedRoot === "string" && reportedRoot.length > 0
+            ? reportedRoot
+            : cwd;
+        const out = [];
+        const walk = (node, inheritedFile) => {
+            const record = asRecord(node);
+            if (!record)
+                return;
+            const file = typeof record.file === "string" ? record.file : inheritedFile;
+            for (const spec of record.specs ?? []) {
+                const specRecord = asRecord(spec);
+                if (!specRecord)
+                    continue;
+                const title = String(specRecord.title ?? "");
+                const tests = specRecord.tests ?? [];
+                // A spec with several projects/retries yields several tests; the
+                // spec only passes when every attempt passed.
+                const statuses = tests.flatMap((test) => {
+                    const testRecord = asRecord(test);
+                    const results = testRecord?.results ?? [];
+                    const attempts = results
+                        .map((result) => asRecord(result)?.status)
+                        .filter((value) => typeof value === "string");
+                    return attempts.length > 0
+                        ? attempts
+                        : [String(testRecord?.status ?? "unknown")];
+                });
+                const status = statuses.every((value) => value === "passed")
+                    ? "passed"
+                    : statuses.includes("passed")
+                        ? "failed"
+                        : (statuses[0] ?? "unknown");
+                out.push({
+                    file: toWorkspacePath(file ?? "", baseCwd, workspaceRoot),
+                    title,
+                    status,
+                });
+            }
+            for (const child of record.suites ?? []) {
+                walk(child, file);
+            }
+        };
+        for (const suite of root.suites ?? [])
+            walk(suite, undefined);
+        return out;
+    },
+};
+export const FRONTEND_TEST_ADAPTERS = [
+    vitestAdapter,
+    jestAdapter,
+    playwrightAdapter,
+];
+/**
+ * Runners the container classifier recognizes as behavior verification but
+ * that have no adapter yet. Naming them lets the capability gap read as
+ * "framework not adapted yet" instead of a user configuration error.
+ */
+const KNOWN_UNADAPTED_RUNNERS = new Set([
+    "mocha",
+    "ava",
+    "tap",
+    "cypress",
+    "testcafe",
+    "nightwatch",
+    "wdio",
+    "webdriverio",
+]);
+/** Resolve the adapter for a command, or `undefined` when none matches. */
+export function resolveFrontendTestAdapter(context) {
+    // A package script owns the detail: `npm test` must resolve through the
+    // script body, not the wrapper, or `npm test` and `vitest run` would
+    // disagree about capability.
+    if (context.scriptArgv) {
+        const scriptRunner = resolveRunnerArgv(context.scriptArgv);
+        const fromScript = FRONTEND_TEST_ADAPTERS.find((adapter) => adapter.matches({ ...context, runner: scriptRunner }));
+        if (fromScript)
+            return fromScript;
+    }
+    return FRONTEND_TEST_ADAPTERS.find((adapter) => adapter.matches(context));
+}
+/**
+ * Detect a recognized-but-unadapted runner so callers can report a capability
+ * gap. Returns the runner name when the command is a test runner we know of
+ * but cannot observe.
+ */
+export function detectUnadaptedRunner(runner) {
+    const binary = basenameOf(runner[0] ?? "").replace(/\.(?:js|cjs|mjs|cmd|exe)$/u, "");
+    if (KNOWN_UNADAPTED_RUNNERS.has(binary))
+        return binary;
+    // `node --test`, `node --test-only`, plus `deno test`/`bun test`.
+    if (binary === "node" && runner.includes("--test"))
+        return "node --test";
+    if (binary === "deno" && runner[1] === "test")
+        return "deno test";
+    if (binary === "bun" && runner[1] === "test")
+        return "bun test";
+    return undefined;
+}
+/** Empty `file` means the runner reported a spec outside the workspace. */
+export const isOutsideWorkspacePath = (file) => file === ".." || file.startsWith("../") || path.isAbsolute(file);

package/docs/architecture/dag-execution.md

@@ -9,7 +9,7 @@
 ```text
 src/commands/dag-run-task.ts  runDagRunTask
   → src/application/dag/generate-task-dag.ts  generateTaskDagUseCase
-      └─ src/workflows/dag/init-hybrid.ts  initHybridDagFromTask     （生成 DagSpec）
+      └─ src/workflows/dag/init-hybrid.ts  initHybridDagFromTask     （生成 DagSpec；模板族在 hybrid/templates/，输入准备在 hybrid/types.ts + hybrid/sources.ts）
       └─ src/application/dag/validate-dag.ts  validateDagUseCase      （候选 + 最终校验）
       └─ assertSafeForExecution                               （执行前安全检查）
       └─ src/application/dag/run-dag.ts  runDagUseCase              （执行）
@@ -43,7 +43,7 @@ src/commands/dag-validate.ts  runDagValidate
 
 ### 专用 taskKind 与模板选择（架构摘要）
 
-- `initHybridDagFromTask` 按 `task.json.taskKind`（及前端需求自动分类）选择专用拓扑：`frontend-implementation`、`frontend-test`、`backend-test`、`knowledge-sync`、`knowledge-graph-bootstrap` 等；默认 `standard` 走 governance profile 通用实现链。
+- `initHybridDagFromTask` 按 `task.json.taskKind`（及前端需求自动分类）选择专用拓扑：`frontend-implementation`、`frontend-test`、`backend-test`、`knowledge-sync`、`knowledge-graph-bootstrap` 等；默认 `standard` 走 governance profile 通用实现链。入口只做分发与治理装饰，六个模板 builder 在 `src/workflows/dag/hybrid/templates/`。
 - **backend-test（0.17.x）**：Markdown-first 固定短链（环境硬门 → Markdown 用例/Review → 单次 pytest + HTML → 报告与 L-5）；不在本页展开节点清单，见 `docs/runtime/backend-test-workflow.md` 与 completed markdown-first plan。
 - 专用模板不是新的 governance profile：风险等级仍由 profile 规则判断；写边界仍受 `allowedPaths` / `forbiddenPaths` / `writeSet` 约束。
 
@@ -73,7 +73,7 @@ src/commands/dag-validate.ts  runDagValidate
 - schema：`src/workflows/dag/types.ts`
   `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；DagNodeExecutor 默认 `"pi"`（`executor: dagNodeExecutorSchema.default("pi")`）。
 - `executor: "cursor"` 在 schema refine 阶段抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`（Pi-only = ADR 0001）。
-- Pi handler 先 `requireModel(input)` 校验已解析 model，再委托 `executeDagPiNode`（`src/executors/dag-pi-executor.ts`）。
+- Pi handler 先 `requireModel(input)` 校验已解析 model，再委托 `executeDagPiNode`（`src/executors/dag-pi-executor.ts`；领域工具、plan ledger、分段会话在 `src/executors/dag-pi/`）。
 - shell handler = `executeDagShellNode`（`src/executors/shell-executor.ts`）；static handler = `executeDagStaticNode`（`src/executors/dag-static-executor.ts`）。
 
 Executor 不得依赖 commands 或 CLI formatting；Cursor 不在受治理路径（`runtime-boundaries.md` §Executors）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.44.0-next.11",
+  "version": "0.44.0-next.12",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",