@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.4

package/dist/executors/shell-executor.js

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { writeDagNodeJsonArtifact, writeDagNodeTextArtifact, } from "../infrastructure/harness/artifact-store.js";
+import { writeDagNodeJsonArtifact, writeDagNodeTextArtifact, writeDagRunJsonArtifact, } from "../infrastructure/harness/artifact-store.js";
 import { captureWorkspaceCheckpoint } from "../workflows/dag/workspace-checkpoint.js";
 import { truncateOutput } from "../shared/output-truncation.js";
 import { processTreeSpawnOptions, terminateProcessTree, } from "./process-tree.js";
@@ -14,15 +15,25 @@ import { buildRequirementCoverageGateShellCommand, expandShellPreset, buildVerdi
 import { materializeBackendTestAnalysisContract } from "../workflows/dag/backend-test-analysis-contract.js";
 import { extractBackendTestContractEnvelope } from "../workflows/dag/backend-test-contract-envelope.js";
 import { materializeFrontendImplementationContract } from "../workflows/dag/frontend-implementation-contract.js";
+import { assertFrontendSourceBindingFresh, buildContractFromCommittedFacts, deterministicSha256, frontendImplementationContractSchema, serializeDeterministicJson, sha256Hex, writeFrontendImplementationContractArtifact, } from "../workflows/dag/frontend-implementation-contract.js";
 import { materializeFrontendTestResult, validateFrontendCaseEvidence, } from "../workflows/dag/frontend-test-result-contract.js";
+import { copyFrontendTestStandardScenarios } from "../workflows/dag/frontend-test-standard-scenarios.js";
+import { probeFrontendTestEnvironment } from "../workflows/dag/frontend-test-environment-probe.js";
 import { renderFrontendTestL5Report } from "../workflows/dag/frontend-test-l5-report.js";
 import { validateFrontendCaseChecklist } from "../workflows/dag/frontend-test-case-checklist.js";
 import { materializeFrontendTestCaseManifest } from "../workflows/dag/frontend-test-case-manifest.js";
 import { renderFrontendTestHtmlReport } from "../workflows/dag/frontend-test-html-report.js";
 import { formatFrontendVerificationTraceStdout, runFrontendVerificationTraceGate, } from "../workflows/dag/frontend-verification-trace.js";
-import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "../workflows/dag/frontend-worktree-diff.js";
-import { formatFrontendFailureAssessStdout, formatFrontendRepairContractStdout, runFrontendFailureAssessGate, runFrontendRepairContractGate, } from "../workflows/dag/frontend-repair.js";
-import { formatFrontendPrewriteGateStdout, runFrontendPrewriteGate, } from "../workflows/dag/frontend-prewrite-gate.js";
+import { captureFrontendWorktreeBaseline, formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "../workflows/dag/frontend-worktree-diff.js";
+import { readTypedEventStoreFromJsonl } from "../workflows/dag/frontend-typed-event-store.js";
+import { classifyFrontendFailure, } from "../workflows/dag/frontend-repair.js";
+import { FRONTEND_CONTRACT_MAX_BYTES, formatFrontendPrewriteGateStdout, runFrontendPrewriteGate, } from "../workflows/dag/frontend-prewrite-gate.js";
+import { evaluateFrontendDesignPolicy, } from "../workflows/dag/frontend-design-policy.js";
+import { deriveFrontendWriterAdmissionShell, FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT, frontendWriterAdmissionResultV1Schema, } from "../workflows/dag/frontend-writer-admission.js";
+import { deriveFrontendIntegrationFacts, buildFrontendTestHandoff, frontendCloseoutFactsSchema, renderFrontendCloseout, } from "../workflows/dag/frontend-closeout.js";
+import { buildFrontendHumanDecisionEnvelope, evaluateHighAdmissionReceipt, routeVerificationConfig, } from "../workflows/dag/frontend-human-decision.js";
+import { classifyFailureOwner, classifyIssueCategoryRestartPhase, classifyRestartPhase, } from "../workflows/dag/frontend-recovery-capsule.js";
+import { pathMatchesPattern } from "../shared/git-progress.js";
 import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from "../workflows/dag/frontend-review-context.js";
 import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } from "../workflows/dag/frontend-lint-baseline.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
@@ -121,6 +132,39 @@ function shouldReuseSuccessfulShellCommands(shell) {
 const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
 const SUMMARY_STDOUT_MAX = 4_000;
 const SUMMARY_STDERR_MAX = 2_000;
+const TEST_TIMEOUT_CLASSIFY_MAX_CHARS = 8_000;
+const TEST_TIMEOUT_MARKERS = [
+    /Test timed out in \d+ms/i,
+    /Timeout of \d+ms exceeded/i,
+];
+const DETERMINISTIC_NON_TIMEOUT_FAILURE_MARKERS = [
+    /AssertionError/i,
+    /expected:?\s/i,
+    /received:?\s/i,
+    /Snapshot /i,
+    /toMatchSnapshot/i,
+    /SyntaxError/i,
+    /TS\d{4}/,
+    /error TS/i,
+    /eslint/i,
+    /compile error/i,
+    /Failed to compile/i,
+];
+function isIdentifiedTestCommand(command) {
+    return /(?:^|[\s"'`])(?:npx\s+)?vitest(?:\s|$)|(?:^|[\s"'`])npm(?:\.cmd)?\s+test(?:\s|$)|(?:^|[\s"'`])pnpm(?:\.cmd)?\s+test(?:\s|$)|(?:^|[\s"'`])yarn(?:\.cmd)?\s+test(?:\s|$)/i.test(command);
+}
+function classifyShellCommandFailure(input) {
+    if (input.processCategory !== "nonzero-exit")
+        return input.processCategory;
+    if (!isIdentifiedTestCommand(input.command))
+        return "nonzero-exit";
+    const sample = `${input.stdout}\n${input.stderr}`.slice(0, TEST_TIMEOUT_CLASSIFY_MAX_CHARS);
+    const hasTimeoutMarker = TEST_TIMEOUT_MARKERS.some((marker) => marker.test(sample));
+    if (!hasTimeoutMarker)
+        return "nonzero-exit";
+    const mixedDeterministicFailure = DETERMINISTIC_NON_TIMEOUT_FAILURE_MARKERS.some((marker) => marker.test(sample));
+    return mixedDeterministicFailure ? "nonzero-exit" : "test-timeout";
+}
 const NODE_STDOUT_MAX = 12_000;
 const NODE_STDERR_MAX = 8_000;
 const MAX_BUFFERED_OUTPUT_BYTES = 64 * 1024;
@@ -327,16 +371,21 @@ export async function executeShellCommand(input) {
             });
         });
         child.on("close", (code) => {
-            let failureCategory = "nonzero-exit";
+            let processCategory = "nonzero-exit";
             if (timedOut) {
-                failureCategory = "timeout";
+                processCategory = "timeout";
             }
             else if (code === 0) {
-                failureCategory = "success";
+                processCategory = "success";
             }
             finish({
                 exitCode: code,
-                failureCategory,
+                failureCategory: classifyShellCommandFailure({
+                    command: input.command,
+                    processCategory,
+                    stdout: formatBoundedOutput(stdout),
+                    stderr: formatBoundedOutput(stderr),
+                }),
                 ok: code === 0 && !timedOut,
             });
         });
@@ -1740,6 +1789,45 @@ async function executePipelineCommands(input, meta, overrideCommands) {
     }
     return results;
 }
+/** A+B (AC-008): derive unresolved verification entrypoints from committed plan
+ * facts. A verification target is unresolved when its commandLabel does not
+ * match any frozen command label from the verify shell evidence bundle.
+ * Returns `{ ref, digest }` entries; a missing/unreadable plan ledger fails
+ * closed to [] so the router restarts the contract instead of inventing refs. */
+async function deriveUnresolvedVerificationEntrypointRefs(runDir, frozenCommandLabels) {
+    try {
+        const { restorePlanPatchFromCommittedFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
+        const records = await readTypedEventStoreFromJsonl(path.join(runDir, "frontend-plan-pi", "plan-typed-facts.jsonl"));
+        const patch = restorePlanPatchFromCommittedFacts(records);
+        const targets = patch
+            ?.verificationTargets;
+        if (!Array.isArray(targets))
+            return [];
+        const frozen = new Set(frozenCommandLabels
+            .map((label) => label.trim().toLowerCase())
+            .filter(Boolean));
+        const refs = [];
+        for (const item of targets) {
+            const target = item;
+            const commandLabel = typeof target.commandLabel === "string" ? target.commandLabel : "";
+            if (commandLabel &&
+                frozen.has(commandLabel.trim().toLowerCase())) {
+                continue;
+            }
+            const file = typeof target.file === "string" ? target.file : "";
+            const symbol = typeof target.symbol === "string" ? target.symbol : "";
+            const id = typeof target.id === "string" ? target.id : "";
+            const ref = file || symbol || id;
+            if (!ref)
+                continue;
+            refs.push({ ref, digest: sha256Hex(ref) });
+        }
+        return refs;
+    }
+    catch {
+        return [];
+    }
+}
 async function executeFrontendVerificationBundle(input, meta) {
     const started = Date.now();
     const shell = input.task.shell;
@@ -1894,75 +1982,809 @@ async function executeFrontendVerificationBundle(input, meta) {
     catch (error) {
         traceError = error instanceof Error ? error : new Error(String(error));
     }
-    if (bundle.mode === "repair") {
-        if (firstFailure || lintSyntheticFailure || traceError) {
+    const verifyFailed = firstFailure !== undefined || lintSyntheticFailure !== undefined || traceError !== undefined;
+    if (verifyFailed) {
+        // M8: verify failure is TERMINAL. There is no same-run repair branch and
+        // no frontend-repair-assessment.json; we only materialize failure
+        // ownership facts (frontend-repair classification + recovery capsule
+        // ownership) for the operation controller / recovery run.
+        const failedNodeId = input.task.id;
+        const failureCategory = firstFailure?.failureCategory ??
+            lintSyntheticFailure?.failureCategory ??
+            (traceError ? "invalid-output" : undefined) ??
+            "invalid-output";
+        const failureClass = classifyFrontendFailure({
+            nodeId: failedNodeId,
+            failureCategory,
+            stdout: firstFailure?.stdout,
+            stderr: firstFailure?.stderr ?? traceError?.message,
+        });
+        // A verify failure means the writer's candidate failed verification, so
+        // the recovery ownership maps to the implement phase (frontend-recovery
+        // capsule classification, fail-closed to implement-pi).
+        const classifiedOwner = classifyFailureOwner({
+            failureSource: "frontend-verify-shell",
+            nodeId: failedNodeId,
+            rawFailureCategory: failureCategory,
+        });
+        const failureOwner = classifiedOwner === "unknown" ? "implement-pi" : classifiedOwner;
+        const restartPhase = classifyRestartPhase(failureOwner);
+        // A+B (AC-008): verification-config routing. Produce structured
+        // unresolved entrypoint refs from committed plan facts and the frozen
+        // command labels; a non-empty unresolved set routes to
+        // verification-config-decision and materializes the frozen
+        // verification-config envelope. An empty/untyped signal fails closed to
+        // contract-restart. The decision is recorded so the recovery controller
+        // never re-classifies the same signal twice.
+        let verificationConfigRoute;
+        if (failureOwner === "verification-config") {
+            const frozenCommandLabels = [
+                ...(bundle.staticEvidence.commandLabels ?? []),
+                ...(bundle.behaviorEvidence.commandLabels ?? []),
+                ...(bundle.mockEvidence?.commandLabels ?? []),
+            ];
+            const unresolvedEntrypointRefs = await deriveUnresolvedVerificationEntrypointRefs(meta.runDir, frozenCommandLabels);
+            verificationConfigRoute = routeVerificationConfig({
+                unresolvedEntrypointRefs: unresolvedEntrypointRefs.map((ref) => ref.ref),
+            });
+            const allowlistedResolvers = [
+                ...new Set(frozenCommandLabels
+                    .map((label) => label.trim())
+                    .filter(Boolean)),
+            ].sort();
+            if (verificationConfigRoute.decision ===
+                "verification-config-decision" &&
+                unresolvedEntrypointRefs.length > 0 &&
+                allowlistedResolvers.length > 0) {
+                const envelope = buildFrontendHumanDecisionEnvelope({
+                    operationId: input.task.id,
+                    runId: meta.runId,
+                    operationRevision: 1,
+                    targetDigest: sha256Hex(frozenCommandLabels.slice().sort().join("\n")),
+                    staleOnTargetDigestChange: true,
+                    kind: "verification-config",
+                    resumeAction: "select-verification-config",
+                    payload: {
+                        unresolvedEntrypointRefs,
+                        allowlistedResolvers,
+                    },
+                });
+                await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-verification-config-envelope.json", envelope);
+            }
+        }
+        const verifyFailure = {
+            schemaVersion: 1,
+            schemaId: "frontend-verify-failure-v1",
+            nodeId: failedNodeId,
+            failureCategory,
+            failureClass,
+            failureOwner,
+            restartPhase,
+            ...(verificationConfigRoute
+                ? { verificationConfigRoute }
+                : {}),
+            commandResults,
+            failedAt: new Date().toISOString(),
+        };
+        await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-verify-failure.json", verifyFailure);
+        return {
+            ok: false,
+            stdout: summarizeCommandResults(results).stdout,
+            stderr: firstFailure?.stderr ||
+                lintSyntheticFailure?.stderr ||
+                traceError?.message ||
+                "frontend verification failed",
+            failureCategory,
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+    // A+B (AC-008): when lint is `require-clean` but the assessment proves
+    // baseline-debt, materialize the frozen `baseline-debt-acceptance` envelope
+    // whose only positive resume is `accept-baseline-debt`. Evidence stays
+    // `baseline-debt` and is never rewritten to `passed`.
+    if (lintAssessment?.status === "baseline-debt") {
+        const baselineEvidenceRefs = (lintAssessment.rawEvidenceRefs ?? [])
+            .filter((ref) => ref?.path && ref?.sha256)
+            .map((ref) => ({ ref: ref.path, digest: ref.sha256 }));
+        if (baselineEvidenceRefs.length > 0) {
+            const envelope = buildFrontendHumanDecisionEnvelope({
+                operationId: input.task.id,
+                runId: meta.runId,
+                operationRevision: 1,
+                targetDigest: lintAssessment.commandIdentity.sha256,
+                staleOnTargetDigestChange: true,
+                kind: "baseline-debt-acceptance",
+                resumeAction: "accept-baseline-debt",
+                payload: {
+                    baselineEvidenceRefs,
+                    candidateDigest: lintAssessment.commandIdentity.sha256,
+                    commandDigest: lintAssessment.commandIdentity.sha256,
+                    resultingPolicy: "allow-non-regression",
+                },
+            });
+            await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-baseline-debt-acceptance-envelope.json", envelope);
+        }
+    }
+    return {
+        ok: true,
+        stdout: lintAssessment?.status === "baseline-debt"
+            ? "Frontend verification bundle: pass with lint baseline-debt"
+            : "Frontend verification bundle: pass",
+        stderr: "",
+        failureCategory: "success",
+        durationMs: Date.now() - started,
+        ...{ commandResults },
+    };
+}
+/* ------------------------------------------------------------------ *
+ * M8 deterministic frontend shell nodes: design policy, writer       *
+ * admission, closeout. These replace the prewrite-gate authorization  *
+ * path and the Pi closeout node.                                      *
+ * ------------------------------------------------------------------ */
+async function readRunDirJson(runDir, relativePath) {
+    return JSON.parse(await readFile(path.join(runDir, relativePath), "utf8"));
+}
+/** Committed typed review terminal kinds from the review node's typed event
+ * store (AC-003: typed terminal tools are the only authoritative verdict). */
+async function collectReviewTerminalKinds(runDir, reviewNodeId) {
+    try {
+        const records = await readTypedEventStoreFromJsonl(path.join(runDir, reviewNodeId, "review-typed-facts.jsonl"));
+        return records
+            .filter((record) => record.phase === "committed")
+            .map((record) => {
+            const kind = record.fact.kind;
+            return typeof kind === "string" ? kind : "";
+        })
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/** Committed typed design terminal kinds from the design review node's typed
+ * event store (M8: the committed approve_design / request_design_changes fact
+ * is the only authoritative verdict; the legacy first-line VERDICT text is
+ * never read for writer admission). Fail-closed on a missing/unreadable store. */
+async function collectDesignTerminalKinds(runDir, designNodeId) {
+    try {
+        const records = await readTypedEventStoreFromJsonl(path.join(runDir, designNodeId, "design-typed-facts.jsonl"));
+        return records
+            .filter((record) => record.phase === "committed")
+            .map((record) => {
+            const kind = record.fact.kind;
+            return typeof kind === "string" ? kind : "";
+        })
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/** A+B (AC-009): deterministic §4.10 restart phase for a committed
+ * `request_review_changes` fact. The typed issueCategory is mapped through the
+ * frozen classifier; `unknown` (or an unreadable store) fails closed to
+ * `undefined` so the runtime never trusts an untyped category. */
+async function collectReviewRestartPhase(runDir, reviewNodeId) {
+    try {
+        const records = await readTypedEventStoreFromJsonl(path.join(runDir, reviewNodeId, "review-typed-facts.jsonl"));
+        const request = records.find((record) => record.phase === "committed" &&
+            record.fact.kind === "request_review_changes");
+        const issueCategory = request?.fact
+            ?.issueCategory;
+        return typeof issueCategory === "string"
+            ? (classifyIssueCategoryRestartPhase(issueCategory) ?? undefined)
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A+B (AC-009): deterministic §4.10 restart phase for a committed
+ * `request_design_changes` fact. Mirrors the review collector. */
+async function collectDesignRestartPhase(runDir, designNodeId) {
+    try {
+        const records = await readTypedEventStoreFromJsonl(path.join(runDir, designNodeId, "design-typed-facts.jsonl"));
+        const request = records.find((record) => record.phase === "committed" &&
+            record.fact.kind === "request_design_changes");
+        const issueCategory = request?.fact
+            ?.issueCategory;
+        return typeof issueCategory === "string"
+            ? (classifyIssueCategoryRestartPhase(issueCategory) ?? undefined)
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the deterministic runtime skeleton for the frontend plan patch from
+ * the DAG spec. The plan task carries it via `structuredContractOutput.skeleton`
+ * (the only schema-recognized persistent channel); absence is a fail-closed
+ * generation/configuration defect, never a reason to fall back to text.
+ */
+function resolveFrontendContractSkeleton(spec, planNodeId) {
+    const planTask = spec.tasks.find((task) => task.id === planNodeId);
+    const skeleton = planTask?.structuredContractOutput?.skeleton;
+    if (!skeleton || Object.keys(skeleton).length === 0) {
+        throw new Error(`frontend design policy blocked: missing runtime contract skeleton for ${planNodeId}`);
+    }
+    return skeleton;
+}
+async function collectFrontendSourceFreshness(input) {
+    const entries = [];
+    for (const source of input.sourceBinding?.sources ?? []) {
+        entries.push({ path: source.path, sha256: source.sha256, fresh: true });
+    }
+    for (const evidencePath of input.contract.designEvidence.paths) {
+        if (entries.some((entry) => entry.path === evidencePath))
+            continue;
+        try {
+            const bytes = await readFile(path.join(input.workspaceRoot, evidencePath));
+            entries.push({
+                path: evidencePath,
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+                fresh: true,
+            });
+        }
+        catch {
+            entries.push({
+                path: evidencePath,
+                sha256: "0".repeat(64),
+                fresh: false,
+            });
+        }
+    }
+    return entries;
+}
+/** R3/R4 openspec invariants: frozen candidates must exist and content
+ * snapshots must not have drifted. Citation is enforced upstream by the
+ * prewrite gate read-event evidence and ledger specReference conformance. */
+async function checkFrontendOpenspecFacts(input) {
+    const frozenCandidatePaths = input.config.openspecCandidatePaths ?? [];
+    const candidateRoot = input.workspaceRoot;
+    const missingCandidates = [];
+    for (const candidate of frozenCandidatePaths) {
+        try {
+            await stat(path.join(candidateRoot, candidate));
+        }
+        catch {
+            missingCandidates.push(candidate);
+        }
+    }
+    if (missingCandidates.length > 0) {
+        throw new Error(`frontend design policy blocked: openspec candidate paths frozen at generation time no longer exist on disk: ${missingCandidates.join(", ")}`);
+    }
+    const snapshots = input.config.openspecCandidateSnapshots;
+    if (snapshots && snapshots.length > 0) {
+        for (const snapshot of snapshots) {
+            try {
+                const bytes = await readFile(path.join(candidateRoot, snapshot.path));
+                const actual = createHash("sha256").update(bytes).digest("hex");
+                if (actual !== snapshot.sha256) {
+                    throw new Error(`frontend design policy blocked: openspec candidate content hash drifted: ${snapshot.path}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.startsWith("frontend design policy blocked")) {
+                    throw error;
+                }
+                throw new Error(`frontend design policy blocked: openspec candidate unreadable: ${snapshot.path}`);
+            }
+        }
+    }
+}
+async function executeFrontendDesignPolicy(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const config = shell.frontendDesignPolicy;
+    try {
+        // 1. Materialize the canonical contract from committed typed facts. After
+        // M9a the plan node's assistantText is a pure Markdown narrative; the
+        // compile authority is the committed plan ledger ⊕ runtime skeleton.
+        // Fail closed on missing committed facts — never fall back to text.
+        const { readCommittedOriginFacts, checkCommittedOriginFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
+        // A+B (AC-001/003): fail-closed committed contract/scout typed facts.
+        // Missing/uncommitted facts block here; never fall back to text parsing.
+        const committedContractFacts = await readCommittedOriginFacts(meta.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl");
+        const contractCheck = checkCommittedOriginFacts({
+            records: committedContractFacts,
+            origin: "contract",
+        });
+        if (!contractCheck.ok) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend design policy blocked: ${contractCheck.reason}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        const committedScoutFacts = await readCommittedOriginFacts(meta.runDir, "frontend-scout-pi", "scout-typed-facts.jsonl");
+        const scoutCheck = checkCommittedOriginFacts({
+            records: committedScoutFacts,
+            origin: "scout",
+        });
+        if (!scoutCheck.ok) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend design policy blocked: ${scoutCheck.reason}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        const skeleton = resolveFrontendContractSkeleton(meta.spec, config.planFromNodeId);
+        const assembled = await buildContractFromCommittedFacts({
+            runDir: meta.runDir,
+            planNodeId: config.planFromNodeId,
+            contractNodeId: "frontend-contract-pi",
+            sourceBinding: meta.spec.sourceBinding,
+            skeleton,
+        });
+        if (!assembled.ok) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend design policy blocked: ${assembled.reason}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        const contract = assembled.canonical;
+        const contractSizeBytes = Buffer.byteLength(serializeDeterministicJson(contract), "utf8");
+        if (contractSizeBytes > FRONTEND_CONTRACT_MAX_BYTES) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend design policy blocked: canonical contract serialization is ${contractSizeBytes} bytes, exceeding the ${FRONTEND_CONTRACT_MAX_BYTES}-byte limit`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        // 2. Requirement id retention (R11): search the canonical contract
+        // serialization instead of the plan node narrative.
+        const contractText = serializeDeterministicJson(contract);
+        const missingIds = config.requiredRequirementIds.filter((id) => !contractText.includes(id));
+        if (missingIds.length > 0) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend design policy blocked: missing requirement ids: ${missingIds.join(", ")}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        // 3. Mock strategy allowed + frozen command binding (R1).
+        const mockStrategy = contract.mockApi.strategy;
+        if (!config.allowedMockStrategies.includes(mockStrategy)) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend contract mock strategy "${mockStrategy}" is incompatible with the generated allowed strategies [${config.allowedMockStrategies.join(", ")}]`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        if (mockStrategy !== "not-needed" && config.mockCommandLabels.length === 0) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend design policy blocked: contract selected Mock strategy ${mockStrategy} but the DAG has no authorized Mock verification commands`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        // 4. writeSet containment.
+        if (config.implementationWriteSet) {
+            const writeSet = new Set(config.implementationWriteSet);
+            const uncoveredTargets = contract.targets.files.filter((target) => ![...writeSet].some((pattern) => pathMatchesPattern(target, pattern) || target === pattern));
+            if (uncoveredTargets.length > 0) {
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: `frontend design policy blocked: contract target is outside implementation writeSet: ${uncoveredTargets.join(", ")}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const uncoveredVTs = contract.verificationTargets
+                .filter((vt) => vt.type !== "static")
+                .filter((vt) => ![...writeSet].some((pattern) => pathMatchesPattern(vt.file, pattern) || vt.file === pattern));
+            if (uncoveredVTs.length > 0) {
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: `frontend design policy blocked: verification target is outside implementation writeSet: ${uncoveredVTs.map((vt) => vt.file).join(", ")}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        // 5. Source freshness (R4) + freshness entries.
+        if (config.requireSourceFreshness) {
+            if (!meta.spec.sourceBinding) {
+                throw new Error("frontend design policy requires sourceBinding for freshness check");
+            }
+            await assertFrontendSourceBindingFresh({
+                workspaceRoot: input.cwd,
+                binding: meta.spec.sourceBinding,
+            });
+        }
+        const sourceFreshness = await collectFrontendSourceFreshness({
+            workspaceRoot: input.cwd,
+            sourceBinding: meta.spec.sourceBinding,
+            contract,
+        });
+        // 6. Openspec invariants (R3): frozen candidates exist and snapshots have
+        // not drifted. Citation is superseded by prewrite-gate read evidence.
+        await checkFrontendOpenspecFacts({
+            workspaceRoot: input.cwd,
+            config,
+        });
+        // 7. Deterministic design policy (M8 D2: designApproval is optional here;
+        // the design verdict is enforced by the writer-admission shell).
+        const policyResult = evaluateFrontendDesignPolicy({
+            contract,
+            allowedMockStrategies: config.allowedMockStrategies,
+            sourceFreshness,
+            componentSpecCandidatePaths: config.openspecCandidatePaths ??
+                config.componentSpecCandidatePaths ??
+                [],
+            allowedDependencies: config.allowedDependencies,
+            writeSetPatterns: config.implementationWriteSet ?? [],
+        });
+        // 8. Write canonical contract + policy result.
+        await writeFrontendImplementationContractArtifact({
+            runDir: meta.runDir,
+            outputDir: config.outputDir,
+            artifactName: config.artifactName,
+            canonical: contract,
+        });
+        await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-design-policy-result.json", policyResult);
+        if (policyResult.classification === "blocked") {
             return {
                 ok: false,
-                stdout: summarizeCommandResults(results).stdout,
-                stderr: firstFailure?.stderr ||
-                    lintSyntheticFailure?.stderr ||
-                    traceError?.message ||
-                    "frontend reverify failed",
-                failureCategory: firstFailure?.failureCategory ??
-                    lintSyntheticFailure?.failureCategory ??
-                    "invalid-output",
+                stdout: "",
+                stderr: `frontend design policy blocked: ${policyResult.findings.map((finding) => `${finding.code}: ${finding.message}`).join("; ")}`,
+                failureCategory: "invalid-output",
                 durationMs: Date.now() - started,
-                ...{ commandResults },
             };
         }
         return {
             ok: true,
-            stdout: lintAssessment?.status === "baseline-debt"
-                ? "Frontend reverify bundle: pass with lint baseline-debt"
-                : "Frontend reverify bundle: pass",
+            stdout: `Frontend design policy: approved findings=0\nContract: ${path.posix.join(config.outputDir, config.artifactName)}`,
             stderr: "",
             failureCategory: "success",
             durationMs: Date.now() - started,
-            ...{ commandResults },
         };
     }
-    const failureFacts = [];
-    if (firstFailure || lintSyntheticFailure) {
-        const failureStdout = firstFailure
-            ? [firstFailure.command, firstFailure.stdout].filter(Boolean).join("\n")
-            : "";
-        failureFacts.push({
-            nodeId: input.task.id,
-            record: {
-                status: "FINISHED",
-                failureCategory: firstFailure?.failureCategory ??
-                    lintSyntheticFailure?.failureCategory,
-                // Keep classification scoped to the failed command. Aggregate
-                // successful output may contain unrelated writeSet-like JSON.
-                stdout: failureStdout,
-                stderr: firstFailure?.stderr ?? lintSyntheticFailure?.stderr,
-                commandResults,
-            },
-        });
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
     }
-    if (traceError) {
-        failureFacts.push({
-            nodeId: "frontend-verification-trace-shell",
-            record: {
-                status: "FINISHED",
-                failureCategory: "invalid-output",
-                stderr: traceError.message,
-            },
+}
+async function executeFrontendWriterAdmission(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const config = shell.frontendWriterAdmission;
+    try {
+        // 1. Design verdict pass is a hard admission condition (M8 D2). In small
+        // topology the design review node is absent and the check is vacuous.
+        // The verdict is read from the committed typed design terminal fact, not
+        // from the legacy first-line VERDICT text protocol (AC-003/AC-004).
+        let verdictPass = true;
+        let designRestartPhase;
+        if (config.designReviewFromNodeId) {
+            const designKinds = await collectDesignTerminalKinds(meta.runDir, config.designReviewFromNodeId);
+            verdictPass =
+                designKinds.length === 1 && designKinds[0] === "approve_design";
+            // A+B (AC-009): request_design_changes issueCategory maps to the
+            // deterministic §4.10 restart phase; unknown fails closed to undefined.
+            designRestartPhase = verdictPass
+                ? undefined
+                : await collectDesignRestartPhase(meta.runDir, config.designReviewFromNodeId);
+        }
+        // 2. Read the canonical contract + design-policy result.
+        const contractRaw = await readRunDirJson(meta.runDir, "contracts/frontend-implementation-contract.json");
+        const contract = frontendImplementationContractSchema.parse(contractRaw);
+        const policyRaw = (await readRunDirJson(meta.runDir, "contracts/frontend-design-policy-result.json"));
+        if (policyRaw.schemaId !== "frontend-design-policy-v1") {
+            throw new Error("frontend writer admission: design policy result artifact invalid");
+        }
+        const designPolicyResult = {
+            schemaId: "frontend-design-policy-v1",
+            classification: policyRaw.classification === "approved" ? "approved" : "blocked",
+            findings: policyRaw.findings ?? [],
+            digest: "",
+        };
+        // 3. Freeze the pre-writer worktree baseline (cumulative diff baseline).
+        await captureFrontendWorktreeBaseline({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
         });
+        const baselineRaw = (await readRunDirJson(meta.runDir, "contracts/frontend-worktree-baseline.json"));
+        const baseline = (baselineRaw.files ?? [])
+            .map((file) => ({
+            path: file,
+            sha256: baselineRaw.hashes?.[file] ?? null,
+        }))
+            .filter((entry) => entry.sha256 !== null);
+        // 4. Writer-preceding lint baseline (R5) when lint is configured.
+        let lintResults = [];
+        if ((config.lintCommands?.length ?? 0) > 0) {
+            for (const command of config.lintCommands) {
+                const commandNumber = lintResults.length + 1;
+                const result = await executeShellCommand({
+                    command,
+                    cwd: input.cwd,
+                    timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+                    envAllowlist: shell.envAllowlist,
+                    dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+                    reportActivity: input.reportActivity,
+                    outputArtifacts: {
+                        stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
+                        stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+                    },
+                });
+                lintResults.push(result);
+            }
+            await materializeFrontendLintBaseline({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+                commands: config.lintCommands,
+                results: lintResults,
+                worktreeChanged: false,
+            });
+        }
+        // 5. Derive admission (writeSet + digests + findings). Glob entries in
+        // the contract targets (e.g. `src/**` inherited from the skeleton) are
+        // expanded against the concrete workspace files so the derived writeSet
+        // contains only real paths the writer can touch.
+        const workspaceFiles = await collectWorkspaceFiles(input.cwd);
+        const admission = deriveFrontendWriterAdmissionShell({
+            contract,
+            designPolicyResult,
+            baseline,
+            frozenCommandLabels: config.frozenCommandLabels,
+            allowedMockStrategies: config.allowedMockStrategies,
+            workspaceFiles,
+        });
+        // 6. Design verdict enforcement: request-revision is a blocked admission.
+        const failureSource = policyRaw.classification === "blocked"
+            ? "frontend-design-policy-shell"
+            : "frontend-writer-admission-shell";
+        const findings = verdictPass
+            ? admission.findings
+            : [
+                ...admission.findings,
+                {
+                    code: "design-approval-request-revision",
+                    message: designRestartPhase !== undefined
+                        ? `design review typed terminal verdict is not approve_design (restartPhase=${designRestartPhase})`
+                        : "design review typed terminal verdict is not approve_design",
+                },
+            ];
+        const classification = findings.length === 0 && admission.classification === "accepted"
+            ? admission.classification
+            : findings.length === 0 &&
+                admission.classification === "requires-human-approval"
+                ? "requires-human-approval"
+                : "blocked";
+        const result = frontendWriterAdmissionResultV1Schema.parse({
+            schemaVersion: 1,
+            schemaId: "frontend-writer-admission-shell-v1",
+            classification,
+            writeSet: admission.writeSet,
+            writeSetDigest: admission.writeSetDigest,
+            baselineDigest: admission.baselineDigest,
+            admissionDigest: admission.admissionDigest,
+            ...(admission.baselineDebtPolicy !== undefined
+                ? { baselineDebtPolicy: admission.baselineDebtPolicy }
+                : {}),
+            findings,
+            failureSource,
+        });
+        await writeDagRunJsonArtifact(meta.runDir, FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT, result);
+        // A+B (AC-007): High topology materializes a `high-admission-receipt-v1`
+        // catalog whose candidate digest must match the admission digest before
+        // the gate can transition from `requires-human-approval` to `accepted`.
+        // Any digest drift resolves to `stale` (never silently accepted).
+        if (classification === "requires-human-approval") {
+            const receipt = evaluateHighAdmissionReceipt({
+                candidateDigest: result.admissionDigest,
+                admissionDigest: result.admissionDigest,
+            });
+            await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-high-admission-receipt.json", receipt);
+            if (receipt.status !== "accepted") {
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: `frontend writer admission stale: high-admission receipt candidate digest drifted from admission digest`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        if (classification === "blocked") {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend writer admission ${classification}: ${findings.map((finding) => `${finding.code}: ${finding.message}`).join("; ")}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        return {
+            ok: true,
+            stdout: `Frontend writer admission: ${classification} writeSet=${result.writeSet.length} writeSetDigest=${result.writeSetDigest}`,
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
     }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
+    }
+}
+async function executeFrontendContractImport(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const config = shell.frontendContractImport;
     try {
-        const assessment = await runFrontendFailureAssessGate({
-            runDir: meta.runDir,
-            failureFacts,
+        const binding = meta.spec.sourceBinding;
+        if (!binding) {
+            throw new Error("frontend contract-import requires a DAG sourceBinding to re-validate freshness");
+        }
+        if (config.requireSourceFreshness) {
+            await assertFrontendSourceBindingFresh({
+                workspaceRoot: input.cwd,
+                binding,
+            });
+        }
+        const digest = createHash("sha256")
+            .update(JSON.stringify({
+            taskId: binding.taskId,
+            sources: binding.sources,
+            artifactName: config.artifactName,
+        }))
+            .digest("hex");
+        const facts = {
+            schemaVersion: 1,
+            schemaId: "frontend-contract-import-v1",
+            artifactName: config.artifactName,
+            sourceBindingTaskId: binding.taskId,
+            sourceCount: binding.sources.length,
+            fresh: true,
+            digest,
+        };
+        return {
+            ok: true,
+            stdout: JSON.stringify(facts, null, 2),
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
+    }
+}
+async function executeFrontendCloseout(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const config = shell.frontendCloseout;
+    try {
+        const context = (await readRunDirJson(meta.runDir, "contracts/frontend-review-context.json"));
+        const contract = frontendImplementationContractSchema.parse(context.contract);
+        const trace = context.verificationTrace;
+        const verificationTargets = (trace?.targets ?? []).map((target) => ({
+            status: target.status === "ok" ? "ok" : "failed",
+        }));
+        const mockEvidenceBound = contract.mockApi.strategy !== "not-needed" &&
+            typeof trace?.mockCommandNodeId === "string" &&
+            trace.mockCommandNodeId.length > 0 &&
+            Array.isArray(trace?.mockCommandLabels) &&
+            trace.mockCommandLabels.length > 0 &&
+            Array.isArray(trace?.mockCommandTexts) &&
+            trace.mockCommandTexts.length === trace.mockCommandLabels.length;
+        const integrationFacts = deriveFrontendIntegrationFacts({
+            mockStrategy: contract.mockApi.strategy,
+            realApiEvidence: { present: false, passed: false },
+            mockEvidenceBound,
+            verificationTargets,
         });
-        await runFrontendRepairContractGate({ runDir: meta.runDir });
+        // Typed review terminal (AC-003) from the committed typed event store.
+        const typedKinds = await collectReviewTerminalKinds(meta.runDir, config.reviewFromNodeId);
+        const typedVerdict = typedKinds.length === 1 &&
+            (typedKinds[0] === "approve_review" || typedKinds[0] === "request_review_changes")
+            ? typedKinds[0]
+            : null;
+        // A+B (AC-009): request_review_changes issueCategory maps to the
+        // deterministic §4.10 restart phase. Recorded as a run-owned audit
+        // artifact so the frozen closeout schema is never widened; `unknown`
+        // fails closed to no restart phase.
+        const reviewRestartPhase = typedVerdict === "request_review_changes"
+            ? await collectReviewRestartPhase(meta.runDir, config.reviewFromNodeId)
+            : undefined;
+        if (reviewRestartPhase !== undefined) {
+            await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-review-restart-phase.json", {
+                schemaVersion: 1,
+                nodeId: config.reviewFromNodeId,
+                restartPhase: reviewRestartPhase,
+            });
+        }
+        const facts = frontendCloseoutFactsSchema.parse({
+            schemaVersion: 1,
+            schemaId: "frontend-closeout-facts-v1",
+            coverageMatrix: verificationTargets.map((target, index) => ({
+                verificationTargetId: trace?.targets?.[index]?.id ?? `vt-${index}`,
+                status: target.status === "ok" ? "passed" : "failed",
+            })),
+            lintStatus: "unavailable",
+            integrationFacts,
+            reviewApproval: {
+                typedVerdict,
+                legacyVerdict: null,
+                match: true,
+            },
+            cumulativeDiff: {
+                cumulativeDigest: (typeof context.verificationTrace === "object" &&
+                    context.verificationTrace !== null &&
+                    "schemaId" in context.verificationTrace
+                    ? deterministicSha256({ verificationTrace: context.verificationTrace })
+                    : deterministicSha256({})),
+                empty: false,
+            },
+            notRun: { browser: "not-run", visual: "not-run" },
+            pendingRealIntegration: integrationFacts !== "real-api",
+        });
+        const rendered = renderFrontendCloseout(facts);
+        await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-closeout-facts.json", facts);
+        // A+B (AC-010): materialize the deterministic frontend-test handoff.
+        // browser/visual/runtime-a11y are always `not-run` and the handoff is
+        // always `deferred-to-frontend-test`, so it never blocks implementation
+        // and can never be rewritten into a passed result.
+        const handoffTaskId = meta.spec.sourceBinding?.taskId ?? input.task.id;
+        const sourceDigest = meta.spec.sourceBinding
+            ? createHash("sha256")
+                .update(JSON.stringify({
+                taskId: meta.spec.sourceBinding.taskId,
+                sources: meta.spec.sourceBinding.sources,
+            }))
+                .digest("hex")
+            : deterministicSha256({});
+        const handoff = buildFrontendTestHandoff({
+            taskId: handoffTaskId,
+            sourceDigest,
+            candidateHash: facts.cumulativeDiff.cumulativeDigest,
+        });
+        await writeDagRunJsonArtifact(meta.runDir, "contracts/frontend-test-handoff.json", handoff);
+        await writeDagNodeTextArtifact(meta.runDir, input.task.id, "frontend-closeout.md", rendered);
         return {
             ok: true,
-            stdout: formatFrontendFailureAssessStdout(assessment),
+            stdout: `Frontend closeout rendered\n${rendered.split("\n").slice(0, 8).join("\n")}`,
             stderr: "",
             failureCategory: "success",
             durationMs: Date.now() - started,
-            ...{ commandResults },
         };
     }
     catch (error) {
@@ -1972,7 +2794,6 @@ async function executeFrontendVerificationBundle(input, meta) {
             stderr: error instanceof Error ? error.message : String(error),
             failureCategory: "invalid-output",
             durationMs: Date.now() - started,
-            ...{ commandResults },
         };
     }
 }
@@ -2061,6 +2882,52 @@ async function executeFrontendTestHtmlReport(input, meta) {
         };
     }
 }
+async function executeFrontendTestStandardScenarios(input) {
+    const started = Date.now();
+    try {
+        const result = await copyFrontendTestStandardScenarios({
+            workspaceRoot: input.cwd,
+        });
+        return {
+            ok: true,
+            stdout: JSON.stringify(result),
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
+    }
+}
+async function executeFrontendTestEnvironmentProbe(input) {
+    const started = Date.now();
+    const result = await probeFrontendTestEnvironment({
+        workspaceRoot: input.cwd,
+    });
+    if (result.ok) {
+        return {
+            ok: true,
+            stdout: result.stdout,
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    return {
+        ok: false,
+        stdout: "",
+        stderr: result.stderr,
+        failureCategory: "nonzero-exit",
+        durationMs: Date.now() - started,
+    };
+}
 async function executeFrontendTestEvidenceValidation(input) {
     const started = Date.now();
     try {
@@ -2238,69 +3105,76 @@ async function executeFrontendTestReports(input, meta) {
         };
     }
 }
-async function executeFrontendLintBaseline(input, meta) {
-    const started = Date.now();
-    const shell = input.task.shell;
-    const baseline = shell.frontendLintBaseline;
-    const cwd = resolveShellCwd(input.cwd, shell.cwd);
-    let beforeStatus;
-    try {
-        beforeStatus = await readGitStatusPorcelain(input.cwd);
-    }
-    catch {
-        beforeStatus = undefined;
+async function writeShellPresetProcessReceipt(input) {
+    await writeDagNodeJsonArtifact(input.runDir, input.nodeId, "process-receipt.json", {
+        schemaVersion: 1,
+        kind: "shell-preset",
+        preset: input.preset,
+        ok: input.ok,
+        durationMs: input.durationMs,
+        steps: input.steps,
+    });
+}
+async function ensureShellPresetProcessReceipt(input) {
+    const receiptPath = path.join(input.runDir, input.nodeId, "process-receipt.json");
+    if (existsSync(receiptPath))
+        return;
+    if (existsSync(path.join(input.runDir, input.nodeId, "shell-command-receipt.json"))) {
+        return;
     }
-    const results = [];
-    for (const command of baseline.lintCommands) {
-        const commandNumber = results.length + 1;
-        results.push(await executeShellCommand({
-            command,
-            cwd,
-            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
-            envAllowlist: shell.envAllowlist,
-            dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
-            outputArtifacts: {
-                stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
-                stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+    const detail = input.result.ok ? input.result.stdout : input.result.stderr;
+    await writeShellPresetProcessReceipt({
+        runDir: input.runDir,
+        nodeId: input.nodeId,
+        preset: input.preset,
+        ok: input.result.ok,
+        durationMs: input.result.durationMs,
+        steps: [
+            {
+                id: "run",
+                label: input.preset,
+                ok: input.result.ok,
+                detail: detail?.slice(0, 8 * 1024),
+                durationMs: input.result.durationMs,
             },
-        }));
-    }
-    let afterStatus;
-    try {
-        afterStatus = await readGitStatusPorcelain(input.cwd);
-    }
-    catch {
-        afterStatus = undefined;
-    }
-    try {
-        const materialized = await materializeFrontendLintBaseline({
-            runDir: meta.runDir,
-            workspaceRoot: input.cwd,
-            commands: baseline.lintCommands,
-            results,
-            worktreeChanged: beforeStatus === undefined ||
-                afterStatus === undefined ||
-                beforeStatus !== afterStatus,
-        });
-        return {
-            ok: true,
-            stdout: `Frontend lint baseline: ${materialized.artifact.status}\nArtifact: ${materialized.ref.path}\nDiagnostics: ${materialized.artifact.diagnostics.length}`,
-            stderr: materialized.artifact.reason ?? "",
-            failureCategory: "success",
-            durationMs: Date.now() - started,
-        };
-    }
-    catch (error) {
-        return {
-            ok: false,
-            stdout: "",
-            stderr: error instanceof Error ? error.message : String(error),
-            failureCategory: "invalid-output",
-            durationMs: Date.now() - started,
-        };
-    }
+        ],
+    });
 }
-export async function executeDagShellNode(input, meta) {
+function namedShellHandler(shell) {
+    if (!shell)
+        return null;
+    const record = shell;
+    for (const key of [
+        "finalWriteSetApprovalGate",
+        "frontendTestStandardScenarios",
+        "frontendTestEnvironmentProbe",
+        "frontendBrowserToolPreflight",
+        "frontendPrewriteGate",
+        "frontendLintBaseline",
+        "frontendVerificationBundle",
+        "frontendReviewContext",
+        "frontendTestCaseChecklist",
+        "frontendTestCaseManifest",
+        "frontendTestEvidenceValidation",
+        "frontendTestResultFinalize",
+        "frontendTestL5Report",
+        "frontendTestHtmlReport",
+        "frontendTestReports",
+        "backendTestPipeline",
+        "jsonArtifactGate",
+        "projectGovernanceGate",
+        "requirementCoverageGate",
+        "verdictGate",
+        "verifyEvidence",
+        "repairArtifactGate",
+        "jacocoCoverage",
+    ]) {
+        if (record[key] != null)
+            return key;
+    }
+    return null;
+}
+async function executeDagShellNodeInner(input, meta) {
     const shell = input.task.shell;
     if (shell?.finalWriteSetApprovalGate) {
         const started = Date.now();
@@ -2339,30 +3213,89 @@ export async function executeDagShellNode(input, meta) {
             };
         }
     }
+    if (shell?.frontendTestStandardScenarios) {
+        return executeFrontendTestStandardScenarios(input);
+    }
+    if (shell?.frontendTestEnvironmentProbe) {
+        return executeFrontendTestEnvironmentProbe(input);
+    }
     if (shell?.frontendBrowserToolPreflight) {
         const started = Date.now();
+        const steps = [];
+        const finish = async (result) => {
+            await writeShellPresetProcessReceipt({
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                preset: "frontendBrowserToolPreflight",
+                ok: result.ok,
+                durationMs: result.durationMs,
+                steps: steps.length > 0
+                    ? steps
+                    : [
+                        {
+                            id: "run",
+                            label: "浏览器工具能力探测",
+                            ok: result.ok,
+                            detail: result.ok ? result.stdout : result.stderr,
+                            durationMs: result.durationMs,
+                        },
+                    ],
+            });
+            return result;
+        };
         try {
             if (resolvePiBackend() === "cli-only") {
+                steps.push({
+                    id: "pi-backend",
+                    label: "Pi SDK 后端可用",
+                    ok: false,
+                    detail: "CODE_AGENT_PI_BACKEND=cli-only",
+                });
                 throw new Error("browser-command-capability-unavailable: CODE_AGENT_PI_BACKEND=cli-only rejects SDK-only playwright_cli");
             }
+            steps.push({
+                id: "pi-backend",
+                label: "Pi SDK 后端可用",
+                ok: true,
+            });
             const sdkCapability = await checkPiSdkCustomToolCapability(input.cwd);
             if (!sdkCapability.ok) {
+                steps.push({
+                    id: "sdk-custom-tool",
+                    label: "Pi SDK custom-tool 能力",
+                    ok: false,
+                    detail: sdkCapability.detail,
+                });
                 throw new Error(`browser-command-capability-unavailable: ${sdkCapability.detail}`);
             }
+            steps.push({
+                id: "sdk-custom-tool",
+                label: "Pi SDK custom-tool 能力",
+                ok: true,
+            });
             const toolProbe = await createPlaywrightCliTool({
                 repoRoot: input.cwd,
                 runDir: meta.runDir,
                 nodeId: input.task.id,
                 caseId: "frontend-browser-preflight",
                 evidenceDir: "testcase/frontend/evidence/frontend-browser-preflight",
-                // Capability-only registration probe. The tested URL is selected later by
-                // retrieve-frontend-test-context-pi and validated by the environment shell.
                 baseUrl: "http://localhost:5173/",
                 inputRoot: "testcase/frontend/fixtures",
             });
             if (toolProbe.name !== "playwright_cli") {
+                steps.push({
+                    id: "structured-tool",
+                    label: "注册 playwright_cli",
+                    ok: false,
+                    detail: toolProbe.name,
+                });
                 throw new Error("browser-command-capability-unavailable: structured playwright_cli tool registration failed");
             }
+            steps.push({
+                id: "structured-tool",
+                label: "注册 playwright_cli",
+                ok: true,
+            });
             const launcher = resolvePlaywrightCliLauncher(input.cwd);
             const result = await defaultPlaywrightCliCommandRunner({
                 executable: launcher.executable,
@@ -2375,8 +3308,19 @@ export async function executeDagShellNode(input, meta) {
             if (result.exitCode !== 0 ||
                 result.timedOut ||
                 !["open", "close", "find", "snapshot", "click"].every((command) => new RegExp(`\\b${command}\\b`, "i").test(help))) {
+                steps.push({
+                    id: "playwright-cli-help",
+                    label: "playwright-cli --help 合同",
+                    ok: false,
+                    detail: help.slice(0, 8 * 1024),
+                });
                 throw new Error("playwright-cli-contract-incompatible");
             }
+            steps.push({
+                id: "playwright-cli-help",
+                label: "playwright-cli --help 合同",
+                ok: true,
+            });
             const capability = {
                 schemaVersion: 1,
                 status: "ready",
@@ -2387,24 +3331,36 @@ export async function executeDagShellNode(input, meta) {
                 targetUrlAuthority: "retrieve-context-and-environment-probe",
             };
             await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "frontend-browser-capability.json", capability);
-            return {
+            steps.push({
+                id: "capability-artifact",
+                label: "写出 frontend-browser-capability.json",
+                ok: true,
+                detail: JSON.stringify(capability, null, 2),
+            });
+            return await finish({
                 ok: true,
                 stdout: JSON.stringify(capability),
                 stderr: "",
                 failureCategory: "success",
                 durationMs: Date.now() - started,
-            };
+            });
         }
         catch (error) {
-            return {
+            return await finish({
                 ok: false,
                 stdout: "",
                 stderr: `playwright-cli-unavailable: ${error instanceof Error ? error.message : String(error)}`,
                 failureCategory: "tool-policy",
                 durationMs: Date.now() - started,
-            };
+            });
         }
     }
+    if (shell?.frontendDesignPolicy) {
+        return executeFrontendDesignPolicy(input, meta);
+    }
+    if (shell?.frontendWriterAdmission) {
+        return executeFrontendWriterAdmission(input, meta);
+    }
     if (shell?.frontendPrewriteGate) {
         const started = Date.now();
         try {
@@ -2433,9 +3389,6 @@ export async function executeDagShellNode(input, meta) {
             };
         }
     }
-    if (shell?.frontendLintBaseline) {
-        return executeFrontendLintBaseline(input, meta);
-    }
     if (shell?.frontendVerificationBundle) {
         return executeFrontendVerificationBundle(input, meta);
     }
@@ -2465,6 +3418,12 @@ export async function executeDagShellNode(input, meta) {
             };
         }
     }
+    if (shell?.frontendContractImport) {
+        return executeFrontendContractImport(input, meta);
+    }
+    if (shell?.frontendCloseout) {
+        return executeFrontendCloseout(input, meta);
+    }
     if (shell?.frontendTestCaseChecklist) {
         return executeFrontendTestCaseChecklist(input, meta);
     }
@@ -2686,53 +3645,23 @@ export async function executeDagShellNode(input, meta) {
     }
     if (shell?.commands?.length === 1 &&
         shell.commands[0] === "frontend-failure-assess-gate") {
-        const started = Date.now();
-        try {
-            const result = await runFrontendFailureAssessGate({
-                runDir: meta.runDir,
-            });
-            return {
-                ok: true,
-                stdout: formatFrontendFailureAssessStdout(result),
-                stderr: "",
-                failureCategory: "success",
-                durationMs: Date.now() - started,
-            };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                stdout: "",
-                stderr: error instanceof Error ? error.message : String(error),
-                failureCategory: "invalid-output",
-                durationMs: Date.now() - started,
-            };
-        }
+        return {
+            ok: false,
+            stdout: "",
+            stderr: "frontend-failure-assess-gate legacy command removed in M8: verify failure is terminal and materializes failure ownership facts in the verification bundle itself",
+            failureCategory: "invalid-output",
+            durationMs: 0,
+        };
     }
     if (shell?.commands?.length === 1 &&
         shell.commands[0] === "frontend-repair-contract-gate") {
-        const started = Date.now();
-        try {
-            const result = await runFrontendRepairContractGate({
-                runDir: meta.runDir,
-            });
-            return {
-                ok: true,
-                stdout: formatFrontendRepairContractStdout(result.assessment),
-                stderr: "",
-                failureCategory: "success",
-                durationMs: Date.now() - started,
-            };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                stdout: "",
-                stderr: error instanceof Error ? error.message : String(error),
-                failureCategory: "invalid-output",
-                durationMs: Date.now() - started,
-            };
-        }
+        return {
+            ok: false,
+            stdout: "",
+            stderr: "frontend-repair-contract-gate legacy command removed in M8: no same-run repair branch exists in the new topology",
+            failureCategory: "invalid-output",
+            durationMs: 0,
+        };
     }
     if (shell?.projectGovernanceGate) {
         const started = Date.now();
@@ -2824,6 +3753,7 @@ export async function executeDagShellNode(input, meta) {
     const cwd = resolveShellCwd(input.cwd, shell.cwd);
     const timeoutMs = shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
     const failFast = shell.failFast !== false;
+    const attemptNumber = input.attempt ?? 1;
     const results = [];
     const executedCommandKeys = new Set();
     let beforeStatus;
@@ -2919,8 +3849,8 @@ export async function executeDagShellNode(input, meta) {
             dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
             reportActivity: input.reportActivity,
             outputArtifacts: {
-                stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
-                stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+                stdoutPath: path.join(meta.runDir, input.task.id, `attempt-${attemptNumber}`, "commands", `${commandNumber}.stdout.txt`),
+                stderrPath: path.join(meta.runDir, input.task.id, `attempt-${attemptNumber}`, "commands", `${commandNumber}.stderr.txt`),
             },
         });
         results.push(result);
@@ -2979,6 +3909,7 @@ export async function executeDagShellNode(input, meta) {
         schemaVersion: 1,
         runId: meta.runId,
         nodeId: input.task.id,
+        attempt: attemptNumber,
         workspaceFingerprint: workspaceFingerprint ?? null,
         failFast,
         commands: results.map((result) => ({
@@ -2997,6 +3928,7 @@ export async function executeDagShellNode(input, meta) {
             subchecks: parseCheckRepoSubcheckDurations(result),
         })),
     };
+    await writeDagNodeJsonArtifact(meta.runDir, input.task.id, path.posix.join(`attempt-${attemptNumber}`, "shell-command-receipt.json"), receipt);
     await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "shell-command-receipt.json", receipt);
     const summaryMarkdown = buildShellResultSummaryMarkdown({
         nodeId: input.task.id,
@@ -3048,8 +3980,57 @@ export async function executeDagShellNode(input, meta) {
         stdout: `${recordPrefix}${reuseNote}${aggregate.stdout}`,
         stderr: stderrParts.filter(Boolean).join("\n\n"),
         failureCategory,
+        ...(firstFailure?.failureCategory
+            ? { rawFailureCategory: firstFailure.failureCategory }
+            : {}),
         durationMs: Date.now() - started,
         // extra field consumed by node-execution if supported; also embedded in stdout marker
         ...{ commandResults },
     };
 }
+/**
+ * Enumerate the workspace's concrete file paths for glob writeSet expansion.
+ *
+ * Uses `git ls-files -co --exclude-standard` (tracked + untracked, excluding
+ * gitignored) so the expanded writeSet reflects real files the writer can
+ * touch. Falls back to [] when the workspace is not a git repository or git
+ * fails — in that case glob entries fail closed as non-concrete paths.
+ */
+async function collectWorkspaceFiles(workspaceRoot) {
+    try {
+        const files = await new Promise((resolve, reject) => {
+            const child = spawn("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: workspaceRoot, stdio: ["ignore", "pipe", "ignore"] });
+            const chunks = [];
+            child.stdout.on("data", (chunk) => chunks.push(chunk));
+            child.on("error", reject);
+            child.on("close", (code) => {
+                if (code === 0) {
+                    resolve(Buffer.concat(chunks)
+                        .toString("utf8")
+                        .split("\0")
+                        .filter(Boolean));
+                }
+                else {
+                    reject(new Error(`git ls-files exited ${String(code)}`));
+                }
+            });
+        });
+        return files.map((file) => file.replace(/\\/g, "/")).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function executeDagShellNode(input, meta) {
+    const handler = namedShellHandler(input.task.shell);
+    const result = await executeDagShellNodeInner(input, meta);
+    if (handler) {
+        await ensureShellPresetProcessReceipt({
+            runDir: meta.runDir,
+            nodeId: input.task.id,
+            preset: handler,
+            result,
+        });
+    }
+    return result;
+}