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

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/backend-test-case-coverage-analysis.js

@@ -666,7 +666,9 @@ function scenarioTypes(body) {
 }
 function declaredScripts(body) {
     const automation = sectionBody(body, CASE_SECTION_ALIASES.automation);
-    return orderedUnique([...automation.matchAll(/testcase\/[A-Za-z0-9_./-]*test_[A-Za-z0-9_.-]*\.py/gi)]
+    // Accept both the canonical `.harness/testcase/` root and the legacy
+    // `testcase/` root so Markdown written by older runs still declares.
+    return orderedUnique([...automation.matchAll(/(?:\.harness\/)?testcase\/[A-Za-z0-9_./-]*test_[A-Za-z0-9_.-]*\.py/gi)]
         .map((match) => match[0].replaceAll("\\", "/")));
 }
 function automationLabelBody(body, labels) {

package/dist/workflows/dag/backend-test-layout.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { canonicalTestArtifactRoot } from "./test-artifact-namespace.js";
 /**
  * Backend-test artifact layout (plan A: configurable test asset paths).
  *
@@ -8,13 +9,15 @@ import path from "node:path";
  * writers, gates, analyzers and the executor can never disagree about where
  * backend-test assets live.
  *
- * Default layout keeps the historical frozen contract:
- *   testcase/md/README.md
- *   testcase/md/<stem>.md
- *   testcase/test_<stem>.py
- *   pytest target: testcase/
+ * Default layout (since 2026-09-17) lives under the shared runtime namespace:
+ *   .harness/testcase/md/README.md
+ *   .harness/testcase/md/<stem>.md
+ *   .harness/testcase/test_<stem>.py
+ *   pytest target: .harness/testcase/
  */
-export const BACKEND_TEST_DEFAULT_TEST_ROOT = "testcase";
+export const BACKEND_TEST_DEFAULT_TEST_ROOT = canonicalTestArtifactRoot("backend-test");
+/** Historical pre-2026-09-17 default root, kept for reference/diagnostics. */
+export const BACKEND_TEST_LEGACY_DEFAULT_TEST_ROOT = "testcase";
 export const BACKEND_TEST_DEFAULT_MARKDOWN_REL = "md";
 export const BACKEND_TEST_DEFAULT_SCRIPT_REL = ".";
 /** Repository roots that must never be configured as backend-test test roots. */
@@ -54,6 +57,9 @@ function normalizeRelPosix(value, label) {
     if (segments.some((segment) => segment === ".." || segment === ".")) {
         throw new Error(`backendTest.${label} must not contain "." or ".." segments: ${value}`);
     }
+    if (segments.some((segment) => segment.startsWith("."))) {
+        throw new Error(`backendTest.${label} must not target hidden directories: ${value}`);
+    }
     if (segments.some((segment) => !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(segment))) {
         throw new Error(`backendTest.${label} contains unsafe path segments: ${value}`);
     }
@@ -77,6 +83,10 @@ function normalizeOptionalRel(value, fallback, label) {
     return normalizeRelPosix(value, label);
 }
 function assertTestRootAllowed(testRoot) {
+    // D3: the canonical harness test-artifact root is the ONLY hidden-root
+    // exception. Every other hidden or forbidden top segment stays rejected.
+    if (testRoot === BACKEND_TEST_DEFAULT_TEST_ROOT)
+        return;
     const topSegment = testRoot.split("/")[0];
     if (FORBIDDEN_TEST_ROOT_PREFIXES.some((forbidden) => topSegment === forbidden || topSegment.startsWith(`${forbidden}.`))) {
         throw new Error(`backendTest.testRoot must not target production/governance trees: ${testRoot}`);
@@ -85,6 +95,16 @@ function assertTestRootAllowed(testRoot) {
         throw new Error(`backendTest.testRoot must not target hidden directories: ${testRoot}`);
     }
 }
+function resolveTestRootInput(raw, canonical) {
+    // D3: only the EXACT canonical harness test-artifact root may be a hidden
+    // path. Compare after trimming + stripping trailing slashes so
+    // `.harness/testcase/` matches, but every other hidden spelling falls
+    // through to the fail-closed normalizer below.
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    if (trimmed === canonical)
+        return canonical;
+    return normalizeRelPosix(raw, "testRoot");
+}
 /**
  * Resolve the frozen backend-test artifact layout from task config.
  * Throws on unsafe or ambiguous configuration (fail-closed).
@@ -92,7 +112,7 @@ function assertTestRootAllowed(testRoot) {
 export function resolveBackendTestLayout(config) {
     const testRoot = config?.testRoot === undefined || config?.testRoot === null
         ? BACKEND_TEST_DEFAULT_TEST_ROOT
-        : normalizeRelPosix(config.testRoot, "testRoot");
+        : resolveTestRootInput(config.testRoot, BACKEND_TEST_DEFAULT_TEST_ROOT);
     assertTestRootAllowed(testRoot);
     const markdownRel = config?.markdownRel === undefined || config?.markdownRel === null
         ? BACKEND_TEST_DEFAULT_MARKDOWN_REL

package/dist/workflows/dag/backend-test-markdown-workflow.js

@@ -787,7 +787,9 @@ function extractMappedPytestScripts(testCaseBody) {
     const automation = sectionBody(testCaseBody, CASE_SECTION_ALIASES.automationNotes);
     if (!automation.trim())
         return [];
-    return unique([...automation.matchAll(/`?(testcase\/[A-Za-z0-9_./-]*test_[A-Za-z0-9_.-]*\.py)`?/gi)]
+    // Accept both the canonical `.harness/testcase/` root and the legacy
+    // `testcase/` root so Markdown written by older runs still maps.
+    return unique([...automation.matchAll(/`?((?:\.harness\/)?testcase\/[A-Za-z0-9_./-]*test_[A-Za-z0-9_.-]*\.py)`?/gi)]
         .map((match) => match[1].replaceAll("\\", "/"))
         .filter((value) => !value.includes("..")));
 }

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-case-checklist.js

@@ -142,12 +142,18 @@ function executableListStep(value) {
             return null;
         return normalizeCommand(inlineCode[1]);
     }
-    const prompted = /^[$>]\s*\S/.test(trimmed);
     const normalized = normalizeCommand(trimmed);
     if (isNonExecutableBlockedProse(normalized))
         return null;
-    if (prompted || isCommandLikeExecutable(normalized))
+    // A `$ `/`> ` prompt marker (stripped by normalizeCommand) must NOT turn
+    // Markdown documentation — e.g. a `> 协议说明` blockquote inside 测试步骤 —
+    // into an executable instruction: every line, prompted or not, follows the
+    // same command-like rule. Real commands after the marker (e.g.
+    // `> npx playwright test`) still normalize to command-like executables and
+    // stay gated by the allowlist.
+    if (isCommandLikeExecutable(normalized)) {
         return normalized;
+    }
     return null;
 }
 function hasShellControl(command) {
@@ -330,7 +336,10 @@ export async function validateFrontendCaseChecklist(input) {
         }
         if (expectedPath && casePath.replaceAll("\\", "/") !== expectedPath)
             issues.push({ ruleId: "case-path-mismatch", caseId: id, casePath, detail: `${casePath} must equal ${expectedPath}` });
-        const body = await readFile(absolute, "utf8");
+        // `playwright_cli` (underscore) is the structured tool name; normalize it to
+        // the canonical `playwright-cli` executable spelling before gating so the
+        // same command is accepted regardless of which spelling the case used.
+        const body = (await readFile(absolute, "utf8")).replace(/\bplaywright_cli\b/g, "playwright-cli");
         if (!openRe.test(body))
             issues.push({ ruleId: "open-prefix", caseId: id, casePath, detail: "missing playwright-cli open --browser=chrome <absolute-url>" });
         const match = body.match(/playwright-cli\s+open\s+--browser=chrome\s+(https?:\/\/\S+)/i);

package/dist/workflows/dag/frontend-test-environment-probe.js

@@ -2,8 +2,6 @@ import { spawnSync } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { defaultFrontendTestLayout, frontendTestContextRel, frontendTestProbeRel, } from "./frontend-test-layout.js";
-export const FRONTEND_TEST_CONTEXT_REL = "testcase/frontend/rag/context.md";
-export const FRONTEND_TEST_PROBE_REL = "testcase/frontend/rag/environment-probe.json";
 const CONNECTION_REFUSED_HINT = "被测服务未在 baseUrl 监听（connection refused）。请先启动本地前端（例如 scripts/serve.sh 或项目约定的 npm start），确认可访问后再从 materialize-frontend-test-execution-shell 续跑。";
 export function classifyFrontendBaseUrlProbeFailure(input) {
     if (input.spawnError)

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);
 }