@tea-agent/loop-agent 0.24.10 → 0.25.0

package/dist/executors/shell-executor.js

@@ -1,9 +1,10 @@
 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";
@@ -18,13 +19,15 @@ import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } f
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
 import { materializeBackendTestResultFromPytestHtml, 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 { 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,64 +437,104 @@ async function executeBackendTestPipeline(input, meta) {
             const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
             const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
             const pytestTargets = mappedScripts.map(shellQuote).join(" ");
-            const mappedScriptDiagLines = mappedScripts
-                .map((script) => `echo "  - ${script.replaceAll('"', '\\"')}" >> "\${DIAG_FILE}"`)
-                .join("; ");
-            // Diagnostic-first single shell: keep pytest exactly once, but always
-            // emit STEP markers, mapped targets, interpreter identity, exit code
-            // and html presence so empty nonzero-exit failures remain auditable.
-            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 "# Backend Test Execute Diagnostics" > "${DIAG_FILE}"',
-                    'echo >> "${DIAG_FILE}"',
-                    'echo "- startedAt: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date)" >> "${DIAG_FILE}"',
-                    'echo "- pwd: $(pwd)" >> "${DIAG_FILE}"',
-                    'echo "- HARNESS_DAG_RUN_DIR: ${HARNESS_DAG_RUN_DIR}" >> "${DIAG_FILE}"',
-                    'echo "- shell: ${BASH:-bash} (${BASH_VERSION:-unknown})" >> "${DIAG_FILE}"',
-                    `echo "- mappedScriptCount: ${mappedScripts.length}" >> "\${DIAG_FILE}"`,
-                    'echo "- mappedScripts:" >> "${DIAG_FILE}"',
-                ].join("; "),
-                mappedScriptDiagLines || 'echo "  - <none>" >> "${DIAG_FILE}"',
+                '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)"',
-                [
-                    '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}"',
-                ].join("; "),
+                '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}"`,
-                // 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 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"',
-                [
-                    '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}"',
-                ].join("; "),
+                '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}"',
-                // 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.
                 '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);
+                const failureIndex = results.findIndex((result) => !result.ok);
+                const failure = results[failureIndex];
                 const combinedStdout = results.map((result) => result.stdout).join("\n");
                 let diagnosticsText = "";
                 try {
@@ -451,11 +543,18 @@ async function executeBackendTestPipeline(input, meta) {
                 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}`,
@@ -465,7 +564,7 @@ async function executeBackendTestPipeline(input, meta) {
                     failure.stderrArtifactPath
                         ? `commandStderrArtifact=${failure.stderrArtifactPath}`
                         : undefined,
-                    "diagnostics=reports/backend-test-execute-diagnostics.md",
+                    `diagnostics=${BACKEND_TEST_EXECUTE_DIAGNOSTICS_REL}`,
                     failure.stderr.trim() || "(shell stderr empty)",
                     diagnosticsText.trim()
                         ? `--- diagnostics ---\n${diagnosticsText.trim()}`
@@ -484,8 +583,9 @@ async function executeBackendTestPipeline(input, meta) {
             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).
@@ -507,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}`, `result=${resultArtifact.path}`, 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");
@@ -1376,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" },

package/dist/verification/maven/cache.js

@@ -0,0 +1,142 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { MAVEN_CACHE_SCHEMA_VERSION, MAVEN_PLANNER_VERSION, } from "./types.js";
+import { buildMavenWorkspaceGraph } from "./workspace-graph.js";
+const CACHE_FILE_NAME = "maven-workspace-graph.json";
+/** Directory names ignored during discovery and lightweight entry-list checks. */
+const SKIP_DIR_NAMES = new Set([
+    ".git",
+    ".harness",
+    "node_modules",
+    "target",
+    "dist",
+    "build",
+    ".idea",
+    ".vscode",
+    "coverage",
+    ".turbo",
+    ".next",
+]);
+export function defaultMavenCacheDir(repoRoot) {
+    return path.join(repoRoot, ".harness", "cache");
+}
+export function mavenGraphCachePath(cacheDir) {
+    return path.join(cacheDir, CACHE_FILE_NAME);
+}
+function isValidCachedGraph(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const graph = value;
+    return (graph.schemaVersion === MAVEN_CACHE_SCHEMA_VERSION &&
+        graph.plannerVersion === MAVEN_PLANNER_VERSION &&
+        typeof graph.fingerprint === "string" &&
+        Array.isArray(graph.pomPaths) &&
+        Array.isArray(graph.nodes));
+}
+/**
+ * Lightweight freshness probe: only stat previously recorded directories and
+ * file metadata. Does NOT re-walk the whole tree or re-parse POMs.
+ * Returns true when the cached graph can be reused as-is.
+ */
+export function isCachedGraphStillFresh(repoRoot, graph) {
+    if (graph.schemaVersion !== MAVEN_CACHE_SCHEMA_VERSION ||
+        graph.plannerVersion !== MAVEN_PLANNER_VERSION) {
+        return false;
+    }
+    const manifest = graph.manifest;
+    if (!manifest) {
+        // Old cache shape without manifest cannot prove lightweight freshness.
+        return false;
+    }
+    // Directory entry lists: any add/remove invalidates.
+    for (const dir of manifest.directories) {
+        const absDir = dir.path === "" ? repoRoot : path.join(repoRoot, ...dir.path.split("/"));
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true })
+                .filter((e) => {
+                if (SKIP_DIR_NAMES.has(e.name))
+                    return false;
+                try {
+                    return !e.isSymbolicLink();
+                }
+                catch {
+                    return true;
+                }
+            })
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            return false;
+        }
+        if (entries.length !== dir.entryNames.length)
+            return false;
+        for (let i = 0; i < entries.length; i += 1) {
+            if (entries[i] !== dir.entryNames[i])
+                return false;
+        }
+    }
+    // File metadata: size/mtime change triggers rebuild (content re-hash on rebuild).
+    for (const file of manifest.files) {
+        const abs = path.join(repoRoot, ...file.path.split("/"));
+        try {
+            const lst = lstatSync(abs);
+            if (lst.isSymbolicLink())
+                return false;
+            const st = statSync(abs);
+            if (st.size !== file.size)
+                return false;
+            if (st.mtimeMs !== file.mtimeMs)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Load cached graph when schema/planner versions match and lightweight
+ * directory/file metadata is unchanged. Full parse only on miss/stale.
+ */
+export function loadOrBuildMavenWorkspaceGraph(input) {
+    const cacheDir = input.cacheDir ?? defaultMavenCacheDir(input.repoRoot);
+    const cachePath = mavenGraphCachePath(cacheDir);
+    if (existsSync(cachePath)) {
+        try {
+            const raw = JSON.parse(readFileSync(cachePath, "utf8"));
+            if (isValidCachedGraph(raw) && isCachedGraphStillFresh(input.repoRoot, raw)) {
+                return raw;
+            }
+        }
+        catch {
+            // Fall through to rebuild.
+        }
+    }
+    const graph = buildMavenWorkspaceGraph(input.repoRoot);
+    writeGraphCache(cacheDir, graph);
+    return graph;
+}
+export function writeGraphCache(cacheDir, graph) {
+    mkdirSync(cacheDir, { recursive: true });
+    const payload = `${JSON.stringify(graph, null, 2)}\n`;
+    // Guard: never persist absolute host paths.
+    if (/[A-Za-z]:[\\/]/.test(payload) || payload.includes("\\\\")) {
+        // Absolute Windows paths are forbidden; re-check using graph fields only.
+        const serialized = JSON.stringify({
+            schemaVersion: graph.schemaVersion,
+            plannerVersion: graph.plannerVersion,
+            fingerprint: graph.fingerprint,
+            pomPaths: graph.pomPaths,
+            wrapperPaths: graph.wrapperPaths,
+            nodes: graph.nodes,
+            reactors: graph.reactors,
+            reactorRootByPomPath: graph.reactorRootByPomPath,
+            manifest: graph.manifest,
+        });
+        writeFileSync(mavenGraphCachePath(cacheDir), `${serialized}\n`, "utf8");
+        return;
+    }
+    writeFileSync(mavenGraphCachePath(cacheDir), payload, "utf8");
+}