@tea-agent/loop-agent 0.24.11-beta.0 → 0.25.0

package/dist/executors/shell-executor.js

@@ -1,14 +1,15 @@
 import { spawn } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { writeDagNodeTextArtifact } from "../infrastructure/harness/artifact-store.js";
 import { truncateOutput } from "../shared/output-truncation.js";
+import { processTreeSpawnOptions, terminateProcessTree } from "./process-tree.js";
 import { buildRequirementCoverageGateShellCommand, expandShellPreset, buildVerdictGateShellCommand, } from "./shell-presets.js";
 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 { materializeFrontendTestResult, } from "../workflows/dag/frontend-test-result-contract.js";
+import { materializeFrontendTestResult, validateFrontendCaseEvidence, } from "../workflows/dag/frontend-test-result-contract.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";
@@ -17,14 +18,16 @@ import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from
 import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } from "../workflows/dag/frontend-lint-baseline.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
-import { materializeBackendTestResultFromRunDir, parsePytestHtmlReport } from "../workflows/dag/backend-test-result-contract.js";
-import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, hasBlockingBackendMarkdownSafetyFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport } from "../workflows/dag/backend-test-result-contract.js";
+import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, hasBlockingBackendMarkdownSafetyFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { computeL5ReportMetrics } from "../workflows/dag/l5-report-metrics.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
 import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { buildShellProcessEnv } from "./shell-verification.js";
 import { readRunState } from "../workflows/dag/run-store.js";
 import { readProjectGovernanceContext } from "../workflows/dag/project-governance-context.js";
+import { assertMavenPlanFresh, MavenPlanStaleError, } from "../verification/maven/index.js";
 const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
 const SUMMARY_STDOUT_MAX = 4_000;
 const SUMMARY_STDERR_MAX = 2_000;
@@ -46,6 +49,54 @@ function resolveBashExecutable() {
         envCandidate ??
         "bash");
 }
+/** POSIX-style runDir for bash `${HARNESS_DAG_RUN_DIR}` expansions on Windows. */
+function normalizeHarnessDagRunDir(runDir) {
+    return runDir.replaceAll(path.sep, "/");
+}
+const BACKEND_TEST_EXECUTE_DIAGNOSTICS_REL = "reports/backend-test-execute-diagnostics.md";
+/**
+ * Write diagnostics *before* any bash spawn so Windows STATUS_DLL_INIT_FAILED
+ * (0xC0000142) / empty-shell-output failures still leave an auditable file.
+ * Shell steps append under `## shell-steps`; they must not overwrite this head.
+ */
+async function writeBackendTestExecuteDiagnosticsPreSpawn(input) {
+    const harnessDagRunDir = normalizeHarnessDagRunDir(input.runDir);
+    if (!harnessDagRunDir.trim()) {
+        throw new Error("HARNESS_DAG_RUN_DIR would be empty; refusing backend-test execute (would write under /reports)");
+    }
+    const reportsDir = path.join(input.runDir, "reports");
+    await mkdir(reportsDir, { recursive: true });
+    const diagnosticsPath = path.join(reportsDir, "backend-test-execute-diagnostics.md");
+    const lines = [
+        "# Backend Test Execute Diagnostics",
+        "",
+        "## pre-spawn",
+        "",
+        `- phase: pre-spawn`,
+        `- startedAt: ${new Date().toISOString()}`,
+        `- cwd: ${input.cwd}`,
+        `- runId: ${input.runId}`,
+        `- runDir: ${input.runDir}`,
+        `- HARNESS_DAG_RUN_DIR: ${harnessDagRunDir}`,
+        `- bashExecutable: ${resolveBashExecutable()}`,
+        `- platform: ${process.platform}`,
+        `- mappedScriptCount: ${input.mappedScripts.length}`,
+        "- mappedScripts:",
+        ...(input.mappedScripts.length > 0
+            ? input.mappedScripts.map((script) => `  - ${script}`)
+            : ["  - <none>"]),
+        `- commandPlanCount: ${input.commandPlan.length}`,
+        "- commandPlan:",
+        ...input.commandPlan.map((label, index) => `  - ${index + 1}. ${label}`),
+        "",
+        "## shell-steps",
+        "",
+        "_Shell commands append below. If this section stays empty, bash never ran successfully._",
+        "",
+    ];
+    await writeFile(diagnosticsPath, `${lines.join("\n")}\n`, "utf8");
+    return { diagnosticsPath, harnessDagRunDir };
+}
 function isWithinRoot(root, candidate) {
     const relative = path.relative(root, candidate);
     return (relative === "" ||
@@ -114,6 +165,7 @@ export async function executeShellCommand(input) {
         const child = spawn(resolveBashExecutable(), ["-c", input.command], {
             cwd: input.cwd,
             env: buildShellProcessEnv(input.envAllowlist, injectedEnv),
+            ...processTreeSpawnOptions(),
             stdio: ["ignore", "pipe", "pipe"],
         });
         let stdout = createBoundedOutput();
@@ -187,10 +239,10 @@ export async function executeShellCommand(input) {
         if (input.timeoutMs > 0) {
             timeoutHandle = setTimeout(() => {
                 timedOut = true;
-                child.kill("SIGTERM");
+                terminateProcessTree(child, "SIGTERM");
                 sigkillHandle = setTimeout(() => {
                     if (child.exitCode === null) {
-                        child.kill("SIGKILL");
+                        terminateProcessTree(child, "SIGKILL");
                     }
                 }, 5_000);
             }, input.timeoutMs);
@@ -385,35 +437,164 @@ async function executeBackendTestPipeline(input, meta) {
             const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
             const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
             const pytestTargets = mappedScripts.map(shellQuote).join(" ");
-            const pytestCommand = [
+            // Split into short bash -c commands (aligned with markdown-environment).
+            // A single ultra-long compound command has been observed on Windows to
+            // exit 0xC0000142 (STATUS_DLL_INIT_FAILED) in ~40ms with empty stdout/
+            // stderr and no diagnostics file. Keep pytest exactly once.
+            const commandPlan = [
+                "shell-bootstrap",
+                "python-identity",
+                "pytest-version",
+                "pytest-run",
+            ];
+            let preSpawnOk = false;
+            try {
+                await writeBackendTestExecuteDiagnosticsPreSpawn({
+                    runDir: meta.runDir,
+                    runId: meta.runId,
+                    cwd: input.cwd,
+                    mappedScripts,
+                    commandPlan: [...commandPlan],
+                });
+                preSpawnOk = true;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: [
+                        "backend-test markdown-execute-html shell failed",
+                        "failureCategory=invalid-output",
+                        `mappedScripts=${mappedScripts.join(",") || "<none>"}`,
+                        `preSpawnDiagnostics=failed`,
+                        `diagnostics=${BACKEND_TEST_EXECUTE_DIAGNOSTICS_REL}`,
+                        message,
+                    ].join("\n"),
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            // Append-only shell snippets; never overwrite the JS pre-spawn head.
+            const shellBootstrapCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty; refusing to write diagnostics under /reports" >&2; exit 2; fi',
                 'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                'echo "STEP=shell-bootstrap"',
+                'echo "- shellBootstrapAt: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date)" >> "${DIAG_FILE}"',
+                'echo "- shellPwd: $(pwd)" >> "${DIAG_FILE}"',
+                'echo "- shellHARNESS_DAG_RUN_DIR: ${HARNESS_DAG_RUN_DIR}" >> "${DIAG_FILE}"',
+                'echo "- shell: ${BASH:-bash} (${BASH_VERSION:-unknown})" >> "${DIAG_FILE}"',
+            ].join("; ");
+            const pythonIdentityCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty" >&2; exit 2; fi',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                'echo "STEP=resolve-python"',
                 'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
-                'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" >&2; exit 127; fi',
-                // Run pytest exactly once and emit the native pytest-html
-                // self-contained report. The HTML/facts renderers read per-case
-                // captured stdout (HTTP_REQUEST/HTTP_RESPONSE) directly from the
-                // pytest-html data-jsonblob island, so a JUnit XML report is no
-                // longer generated.
-                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
+                'echo "- command_v_python: $(command -v python || true)" >> "${DIAG_FILE}"',
+                'echo "- command_v_python3: $(command -v python3 || true)" >> "${DIAG_FILE}"',
+                'echo "- PYTHON_BIN: ${PYTHON_BIN:-<empty>}" >> "${DIAG_FILE}"',
+                'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+                'echo "STEP=python-identity"',
+                'if ! PYTHONUNBUFFERED=1 "${PYTHON_BIN}" -c "import sys; print(sys.executable); print(sys.version.splitlines()[0])" >> "${DIAG_FILE}" 2>&1; then echo "STEP=python-identity-failed" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+            ].join("; ");
+            const pytestVersionCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty" >&2; exit 2; fi',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
+                'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+                'echo "STEP=pytest-version"',
+                'if ! PYTHONUNBUFFERED=1 "${PYTHON_BIN}" -m pytest --version >> "${DIAG_FILE}" 2>&1; then echo "STEP=pytest-version-failed" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+            ].join("; ");
+            // Single pytest invocation; exit 0/1 + non-empty html are reportable.
+            const pytestRunCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty" >&2; exit 2; fi',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
+                'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+                'echo "STEP=pytest-run"',
+                `echo "- pytestCommand: python -m pytest ${mappedScripts.join(" ")} -v -p no:cacheprovider --html=reports/backend-test.html --self-contained-html" >> "\${DIAG_FILE}"`,
+                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
                 "STATUS=$?",
                 'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
-                // exit 0 (all pass) or 1 (assertion failures) with a valid
-                // pytest-html report are reportable; collection errors / crashes
-                // (exit >= 2) or a missing report surface as a pipeline error below.
+                'echo "- pytestExitCode: ${STATUS}" >> "${DIAG_FILE}"',
+                'if [ -f "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" ]; then echo "- pytestHtml: present ($(wc -c < "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" | tr -d " ") bytes)" >> "${DIAG_FILE}"; else echo "- pytestHtml: missing" >> "${DIAG_FILE}"; fi',
+                'echo "- finishedAt: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date)" >> "${DIAG_FILE}"',
+                'echo "STEP=pytest-finished status=${STATUS}"',
                 'if { [ "${STATUS}" -eq 0 ] || [ "${STATUS}" -eq 1 ]; } && [ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" ]; then exit 0; fi',
+                'echo "STEP=pipeline-failed status=${STATUS} html=$([ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" ] && echo present || echo missing)" >&2',
                 'exit "${STATUS}"',
             ].join("; ");
-            const results = await executePipelineCommands(input, meta, [pytestCommand]);
+            const pipelineCommands = [
+                shellBootstrapCommand,
+                pythonIdentityCommand,
+                pytestVersionCommand,
+                pytestRunCommand,
+            ];
+            const results = await executePipelineCommands(input, meta, pipelineCommands);
             if (!results.every((result) => result.ok)) {
-                const failure = results.find((result) => !result.ok);
-                return { ok: false, stdout: results.map((result) => result.stdout).join("\n"), stderr: failure.stderr, failureCategory: failure.failureCategory, durationMs: Date.now() - started };
+                const failureIndex = results.findIndex((result) => !result.ok);
+                const failure = results[failureIndex];
+                const combinedStdout = results.map((result) => result.stdout).join("\n");
+                let diagnosticsText = "";
+                try {
+                    diagnosticsText = await readFile(path.join(meta.runDir, "reports", "backend-test-execute-diagnostics.md"), "utf8");
+                }
+                catch {
+                    diagnosticsText = "";
+                }
+                const failedStep = failureIndex >= 0 && failureIndex < commandPlan.length
+                    ? commandPlan[failureIndex]
+                    : "unknown";
+                const stderrSummary = [
+                    "backend-test markdown-execute-html shell failed",
+                    `failureCategory=${failure.failureCategory}`,
+                    `exitCode=${failure.exitCode ?? "null"}`,
+                    `durationMs=${failure.durationMs}`,
+                    `failedCommandIndex=${failureIndex + 1}`,
+                    `failedStep=${failedStep}`,
+                    `commandPlanCount=${pipelineCommands.length}`,
+                    `preSpawnDiagnostics=${preSpawnOk ? "written" : "failed"}`,
+                    `mappedScripts=${mappedScripts.join(",") || "<none>"}`,
+                    `shellStdoutEmpty=${combinedStdout.trim().length === 0}`,
+                    `shellStderrEmpty=${failure.stderr.trim().length === 0}`,
+                    failure.stdoutArtifactPath
+                        ? `commandStdoutArtifact=${failure.stdoutArtifactPath}`
+                        : undefined,
+                    failure.stderrArtifactPath
+                        ? `commandStderrArtifact=${failure.stderrArtifactPath}`
+                        : undefined,
+                    `diagnostics=${BACKEND_TEST_EXECUTE_DIAGNOSTICS_REL}`,
+                    failure.stderr.trim() || "(shell stderr empty)",
+                    diagnosticsText.trim()
+                        ? `--- diagnostics ---\n${diagnosticsText.trim()}`
+                        : "(diagnostics file missing or empty)",
+                ]
+                    .filter((line) => Boolean(line))
+                    .join("\n");
+                return {
+                    ok: false,
+                    stdout: combinedStdout,
+                    stderr: stderrSummary,
+                    failureCategory: failure.failureCategory,
+                    durationMs: Date.now() - started,
+                };
             }
             const reportsDir = path.join(meta.runDir, "reports");
             const pytestHtmlContent = await readFile(path.join(reportsDir, "backend-test.html"), "utf8");
             const pytestExitCode = Number.parseInt((await readFile(path.join(reportsDir, "backend-test-pytest-exit.txt"), "utf8")).trim(), 10);
-            if (![0, 1].includes(pytestExitCode))
+            if (![0, 1].includes(pytestExitCode)) {
                 throw new Error(`pytest did not complete with a reportable exit code: ${pytestExitCode}`);
+            }
             const parsed = parsePytestHtmlReport(pytestHtmlContent);
+            // Bind Result v1 from the native pytest-html report BEFORE overwriting with the
+            // styled renderer (which drops the data-jsonblob island).
+            const resultArtifact = await materializeBackendTestResultFromPytestHtml({
+                runDir: meta.runDir,
+                htmlRelativePath: "reports/backend-test.html",
+                htmlContent: pytestHtmlContent,
+                pytestExitCode,
+            });
             const cases = await collectBackendTestHumanCaseCatalog(input.cwd);
             const caseValidationSummary = await readRequiredRunReport(reportsDir, "backend-md-case-validation.md");
             const traceabilitySummary = await readRequiredRunReport(reportsDir, "backend-test-traceability.md");
@@ -426,11 +607,52 @@ async function executeBackendTestPipeline(input, meta) {
                 traceabilitySummary,
             });
             const htmlPath = await writeRunReport(meta.runDir, "backend-test.html", htmlContent);
-            const facts = renderBackendTestFacts({ parsed, cases, pytestExitCode, htmlRelativePath: "reports/backend-test.html", htmlContent, caseValidationSummary, traceabilitySummary });
+            const facts = renderBackendTestFacts({
+                parsed,
+                cases,
+                pytestExitCode,
+                htmlRelativePath: "reports/backend-test.html",
+                htmlContent,
+                caseValidationSummary,
+                traceabilitySummary,
+            });
             const markdownPath = await writeRunReport(meta.runDir, "backend-test.md", facts);
             const factsPath = await writeRunReport(meta.runDir, "backend-test-facts.md", facts);
+            // Deterministic L-5 dashboard: machine-computed metrics (not Pi-generated).
+            // manifest is produced by an upstream finalize node; tolerate its absence
+            // so a minimal DAG without manifest still gets a degraded dashboard.
+            let manifestForL5 = {};
+            try {
+                const manifestPath = path.join(meta.runDir, "contracts", "backend-test-case-manifest.json");
+                manifestForL5 = JSON.parse(await readFile(manifestPath, "utf8"));
+            }
+            catch {
+                // manifest missing: L5 AC/automation metrics degrade to unavailable.
+            }
+            const l5Metrics = computeL5ReportMetrics({
+                result: { passed: parsed.passed, failed: parsed.failed, error: parsed.errors, skipped: parsed.skipped },
+                manifest: manifestForL5,
+                coverage: null,
+                criticalRiskCount: parsed.failed + parsed.errors > 0 ? 1 : 0,
+            });
+            const failureSummaries = parsed.cases
+                .filter((c) => c.status !== "passed")
+                .map((c) => {
+                const id = c.name.match(/BE-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}/)?.[0] ?? c.name;
+                return { caseId: id, title: c.name, message: c.message ?? c.status, script: `${c.classname.split("::")[0] ?? c.classname}` };
+            });
+            const l5Html = renderBackendTestL5Dashboard({
+                title: meta.spec.title,
+                objective: meta.spec.objective,
+                parsed,
+                metrics: l5Metrics,
+                caseValidationSummary,
+                traceabilitySummary,
+                failures: failureSummaries.length > 0 ? failureSummaries : undefined,
+            });
+            const l5Path = await writeRunReport(meta.runDir, "backend-test-l5-dashboard.html", l5Html);
             const sanitizedOutputs = results.map((result) => redactBackendTestOutput(result.stdout));
-            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `markdown=${markdownPath}`, `facts=${factsPath}`, facts);
+            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `markdown=${markdownPath}`, `facts=${factsPath}`, `l5-dashboard=${l5Path}`, `result=${resultArtifact.path}`, facts);
         }
         else if (pipeline === "contracts") {
             const wrapperPath = path.join(meta.runDir, "analyze-and-discover-backend-test-pi.json");
@@ -889,6 +1111,38 @@ async function executeFrontendVerificationBundle(input, meta) {
         };
     }
 }
+async function executeFrontendTestEvidenceValidation(input) {
+    const started = Date.now();
+    try {
+        const result = await validateFrontendCaseEvidence({ workspaceRoot: input.cwd });
+        const output = `frontend case evidence validation cases=${result.cases} findings=${result.issues.length}${result.issues.length ? ` issues=${JSON.stringify(result.issues)}` : ""}`;
+        if (result.hardFail) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend-test evidence hard-fail: ${JSON.stringify(result.issues)}`,
+                failureCategory: "nonzero-exit",
+                durationMs: Date.now() - started,
+            };
+        }
+        return {
+            ok: true,
+            stdout: output,
+            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 executeFrontendLintBaseline(input, meta) {
     const started = Date.now();
     const shell = input.task.shell;
@@ -989,6 +1243,9 @@ export async function executeDagShellNode(input, meta) {
             return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error), failureCategory: "invalid-output", durationMs: Date.now() - started };
         }
     }
+    if (shell?.frontendTestEvidenceValidation) {
+        return executeFrontendTestEvidenceValidation(input);
+    }
     if (shell?.backendTestPipeline) {
         return executeBackendTestPipelineWithWriteGuard(input, meta);
     }
@@ -1260,10 +1517,61 @@ export async function executeDagShellNode(input, meta) {
     if (!shell || commands.length === 0) {
         throw new Error(`shell task ${input.task.id} requires shell.preset, shell.verdictGate, and/or non-empty shell.commands`);
     }
+    const started = Date.now();
+    if (shell.mavenVerificationPlan) {
+        try {
+            assertMavenPlanFresh(input.cwd, shell.mavenVerificationPlan, { shellCommands: commands });
+        }
+        catch (error) {
+            const message = error instanceof MavenPlanStaleError
+                ? error.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            const staleMessage = message.includes("verification-plan-stale")
+                ? message
+                : `verification-plan-stale: ${message}`;
+            const staleResults = commands.map((command) => ({
+                command,
+                cwd: input.cwd,
+                durationMs: 0,
+                exitCode: null,
+                failureCategory: "verification-plan-stale",
+                ok: false,
+                stderr: staleMessage,
+                stderrBytes: Buffer.byteLength(staleMessage),
+                stderrTruncated: false,
+                stdout: "",
+                stdoutBytes: 0,
+                stdoutTruncated: false,
+                timedOut: false,
+            }));
+            await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", buildShellResultSummaryMarkdown({
+                nodeId: input.task.id,
+                runId: meta.runId,
+                rootCwd: input.cwd,
+                results: staleResults,
+            }));
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `${staleMessage}\nRegenerate/validate the DAG before running Maven verification.`,
+                failureCategory: "verification-plan-stale",
+                durationMs: Date.now() - started,
+                ...{
+                    commandResults: staleResults.map((result) => ({
+                        ok: result.ok,
+                        exitCode: result.exitCode,
+                        failureCategory: result.failureCategory,
+                        command: result.command,
+                    })),
+                },
+            };
+        }
+    }
     const cwd = resolveShellCwd(input.cwd, shell.cwd);
     const timeoutMs = shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
     const results = [];
-    const started = Date.now();
     let beforeStatus;
     try {
         beforeStatus = await readGitStatusPorcelain(input.cwd);

package/dist/executors/shell-verification.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { processTreeSpawnOptions, terminateProcessTree } from "./process-tree.js";
 export const DEFAULT_VERIFY_TIMEOUT_MS = 1_800_000;
 const VERIFY_ENV_ALLOWLIST = [
     "HOME",
@@ -142,6 +143,7 @@ export async function executeCommand(command, defaultTimeoutMs = DEFAULT_VERIFY_
         const child = spawn(binary, args, {
             cwd: command.cwd,
             env: command.env ?? process.env,
+            ...processTreeSpawnOptions(),
             stdio: ["ignore", "pipe", "pipe"],
         });
         let stdout = "";
@@ -184,10 +186,10 @@ export async function executeCommand(command, defaultTimeoutMs = DEFAULT_VERIFY_
         if (timeoutMs > 0) {
             timeoutHandle = setTimeout(() => {
                 timedOut = true;
-                child.kill("SIGTERM");
+                terminateProcessTree(child, "SIGTERM");
                 sigkillHandle = setTimeout(() => {
                     if (child.exitCode === null) {
-                        child.kill("SIGKILL");
+                        terminateProcessTree(child, "SIGKILL");
                     }
                 }, 5_000);
             }, timeoutMs);

package/dist/infrastructure/harness/task-store.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { taskConfigSchema } from "../../shared/types.js";
 import { appendJsonlLineAtomic, writeJsonAtomic, writeTextAtomic, } from "./atomic-write.js";
 function taskDir(repoRoot, taskId) {
     return path.join(repoRoot, ".harness", "tasks", taskId);
@@ -10,6 +11,27 @@ function taskFile(repoRoot, taskId, filename) {
 function taskWriteOptions(repoRoot) {
     return { repoRoot };
 }
+function describeTaskConfigValidationError(error) {
+    if (error &&
+        typeof error === "object" &&
+        "issues" in error &&
+        Array.isArray(error.issues)) {
+        return error.issues
+            .map((issue) => {
+            if (!issue || typeof issue !== "object")
+                return String(issue);
+            const pathValue = "path" in issue && Array.isArray(issue.path)
+                ? issue.path.map(String).join(".")
+                : "";
+            const message = "message" in issue && typeof issue.message === "string"
+                ? issue.message
+                : String(issue);
+            return pathValue ? `${pathValue}: ${message}` : message;
+        })
+            .join("; ");
+    }
+    return error instanceof Error ? error.message : String(error);
+}
 export function resolveTaskContextFromDir(taskDir) {
     const normalized = path.resolve(taskDir);
     const taskId = path.basename(normalized);
@@ -37,6 +59,15 @@ export function resolveTaskStateContext(statePath) {
     return { repoRoot, taskId };
 }
 export async function writeTaskConfig(repoRoot, taskId, config) {
+    try {
+        taskConfigSchema.parse(config);
+    }
+    catch (error) {
+        throw new Error([
+            `invalid task config for ${taskId}: ${describeTaskConfigValidationError(error)}`,
+            "`referenceDocs` must use `{ path, name? }[]`; `verifyCommands` must use `{ label, command, timeoutMs? }[]`.",
+        ].join(" "));
+    }
     await writeJsonAtomic(taskFile(repoRoot, taskId, "task.json"), config, taskWriteOptions(repoRoot));
 }
 export async function writeWorkflowState(repoRoot, taskId, state) {

package/dist/shared/operator/capabilities.js

@@ -61,7 +61,10 @@ const OFFICIAL_ACTIONS = [
         ...["init", "status", "run", "record-round", "add-signal", "closeout"].map((leaf) => [`loop${leaf.replace(/(^|-)(.)/g, (_m, _d, c) => c.toUpperCase())}`, `loop-agent loop ${leaf}`, leaf === "status" ? "read" : "mutation", "advanced"]),
         ...["list", "inspect", "save", "run", "diff", "replay"].map((leaf) => [`workflow${leaf[0].toUpperCase()}${leaf.slice(1)}`, `loop-agent workflow ${leaf}`, ["list", "inspect", "diff"].includes(leaf) ? "read" : "mutation", "advanced"]),
         ["workerFeatureReview", "agent-worker feature review", "read", "model-callable"],
+        ["workerFeatureScaffold", "agent-worker feature scaffold", "mutation", "advanced"],
         ["workerFeatureRun", "agent-worker feature run", "long-running", "human-gated-required"],
+        ["workerFeatureAdvance", "agent-worker feature advance", "long-running", "human-gated-required"],
+        ["workerFeatureDoctor", "agent-worker feature doctor", "read", "model-callable"],
         ["workerFeatureVerifyFinal", "agent-worker feature verify-final", "long-running", "human-gated-required"],
         ["workerFeatureDelivery", "agent-worker feature delivery", "mutation", "human-gated-required"],
         ["workerFeatureCloseout", "agent-worker feature closeout", "mutation", "human-gated-required"],
@@ -734,7 +737,10 @@ export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
     { command: "loop-agent stats", coverage: "model-callable", action: "stats", source: "loop-agent" },
     { command: "loop-agent stats context", coverage: "model-callable", action: "statsContext", source: "loop-agent" },
     { command: "agent-worker feature review", coverage: "model-callable", action: "workerFeatureReview", source: "agent-worker" },
+    { command: "agent-worker feature scaffold", coverage: "advanced", action: "workerFeatureScaffold", source: "agent-worker" },
     { command: "agent-worker feature run", coverage: "human-gated-required", action: "workerFeatureRun", source: "agent-worker" },
+    { command: "agent-worker feature advance", coverage: "human-gated-required", action: "workerFeatureAdvance", source: "agent-worker" },
+    { command: "agent-worker feature doctor", coverage: "model-callable", action: "workerFeatureDoctor", source: "agent-worker" },
     { command: "agent-worker feature verify-final", coverage: "human-gated-required", action: "workerFeatureVerifyFinal", source: "agent-worker" },
     { command: "agent-worker feature delivery", coverage: "human-gated-required", action: "workerFeatureDelivery", source: "agent-worker" },
     { command: "agent-worker feature closeout", coverage: "human-gated-required", action: "workerFeatureCloseout", source: "agent-worker" },