@tea-agent/loop-agent 0.40.0-next.1 → 0.40.0-next.11

package/dist/executors/pi-sdk-executor.js

@@ -485,6 +485,9 @@ function extractSdkUsageSample(event) {
     const responseKey = responseKeyCandidates.find((value) => typeof value === "string" && value.length > 0);
     return responseKey ? { responseKey, tokens } : { tokens };
 }
+function maxSdkContextTokens(samples) {
+    return samples.reduce((maximum, sample) => Math.max(maximum, sample.tokens), 0);
+}
 function aggregateSdkTokenUsage(samples) {
     const identified = new Map();
     let anonymousMaximum = 0;
@@ -537,6 +540,9 @@ export async function executeSingleSdkAttempt(options) {
     const stdoutPreview = new BoundedTextPreview("stdout");
     const stdoutCollector = createPiJsonlStreamCollector();
     const usageSamples = [];
+    let observedTurns = 0;
+    let contextBudgetExhausted = false;
+    let contextBudgetDetail = "";
     // Writer-thinking-exhausted diagnosis evidence (AC-002). Collected in the
     // subscribe callback regardless of shouldPersistSessionEvent filtering, so a
     // length-stopped thinking-only attempt with no persisted write tool calls is
@@ -625,6 +631,7 @@ export async function executeSingleSdkAttempt(options) {
         });
         let resolveStall;
         let resolveSettlement;
+        let resolveContextBudget;
         let settled = false;
         let abortConfirmed = true;
         const persistRuntimeNote = (event) => {
@@ -655,6 +662,30 @@ export async function executeSingleSdkAttempt(options) {
                 clearTimeout(stallHandle);
             stallHandle = setTimeout(() => resolveStall?.("stall"), stallTimeoutMs);
         };
+        const checkContextBudget = () => {
+            if (contextBudgetExhausted || !options.contextBudget)
+                return;
+            // Context protection follows the largest provider-reported response
+            // snapshot, not cumulative billing usage across turns. Summing repeated
+            // input contexts would abort healthy multi-turn sessions far below the
+            // model's actual context window.
+            const observedTokens = maxSdkContextTokens(usageSamples);
+            const turnExceeded = options.contextBudget.maxTurns !== undefined &&
+                observedTurns >= options.contextBudget.maxTurns;
+            const tokenExceeded = options.contextBudget.maxTokens !== undefined &&
+                observedTokens >= options.contextBudget.maxTokens;
+            if (!turnExceeded && !tokenExceeded)
+                return;
+            contextBudgetExhausted = true;
+            contextBudgetDetail = [
+                "context-budget-exhausted:",
+                `observedTurns=${observedTurns}`,
+                `observedTokens=${observedTokens}`,
+                `maxTurns=${options.contextBudget.maxTurns ?? "unbounded"}`,
+                `maxTokens=${options.contextBudget.maxTokens ?? "unbounded"}`,
+            ].join(" ");
+            resolveContextBudget?.("context-budget");
+        };
         unsubscribe = session.subscribe((event) => {
             if (event.type === "agent_settled" && !settled) {
                 settled = true;
@@ -678,6 +709,9 @@ export async function executeSingleSdkAttempt(options) {
             const usageSample = extractSdkUsageSample(event);
             if (usageSample)
                 usageSamples.push(usageSample);
+            if (event.type === "turn_end")
+                observedTurns += 1;
+            checkContextBudget();
             // Capture writer-thinking-exhausted evidence BEFORE the
             // shouldPersistSessionEvent filter: thinking_delta is intentionally
             // excluded from persisted JSONL, but must still count toward the
@@ -700,6 +734,11 @@ export async function executeSingleSdkAttempt(options) {
         const runTurn = async (userMessage) => {
             const settlementPromise = resetSettlement();
             const stallPromise = resetStallPromise();
+            const contextBudgetPromise = options.contextBudget
+                ? new Promise((resolve) => {
+                    resolveContextBudget = resolve;
+                })
+                : null;
             const promptPromise = session.prompt(userMessage);
             // A settlement event is permitted to win the race while prompt() remains
             // pending. Observe a later rejection so it never becomes unhandled.
@@ -710,6 +749,7 @@ export async function executeSingleSdkAttempt(options) {
                 settlementPromise,
                 ...(timeoutPromise ? [timeoutPromise] : []),
                 ...(stallPromise ? [stallPromise] : []),
+                ...(contextBudgetPromise ? [contextBudgetPromise] : []),
             ]);
         };
         const disposeSession = async () => {
@@ -737,7 +777,12 @@ export async function executeSingleSdkAttempt(options) {
             : options.userMessage;
         let continuesSent = 0;
         let raced = await runTurn(promptMessage);
-        if (raced === "stall") {
+        if (raced === "context-budget") {
+            appendStderr(contextBudgetDetail);
+            abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
+            await disposeSession();
+        }
+        else if (raced === "stall") {
             abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
             const withinAbsoluteTimeout = timeoutMs <= 0 || Date.now() - startedAt < timeoutMs;
             const canContinue = abortConfirmed &&

package/dist/executors/pi-writer-tool-policy.js

@@ -154,6 +154,28 @@ function assertMkdirRelative(relative, ctx) {
         throw new PiWriterPathDeniedError("forbidden", relative || ".");
     }
 }
+export async function assertReadablePath(targetPath, ctx) {
+    const raw = String(targetPath ?? "").trim();
+    if (!raw)
+        throw new PiWriterPathDeniedError("empty-path", targetPath ?? "");
+    const repoRoot = path.resolve(ctx.repoRoot);
+    const absoluteTarget = path.isAbsolute(raw)
+        ? path.resolve(raw)
+        : path.resolve(repoRoot, raw);
+    if (!isPathInside(repoRoot, absoluteTarget)) {
+        throw new PiWriterPathDeniedError("outside-repo", raw);
+    }
+    const effective = await resolveEffectiveMutationTarget(repoRoot, absoluteTarget);
+    const relative = repoRelativePath(repoRoot, absoluteTarget, raw, false);
+    const effectiveRelative = repoRelativePath(effective.realRoot, effective.absoluteTarget, raw, false);
+    const readSet = ctx.readSet ?? [];
+    for (const candidate of [relative, effectiveRelative]) {
+        if (readSet.length === 0 || !matchesAnyPattern(candidate, readSet)) {
+            throw new PiWriterPathDeniedError("read-outside-read-set", candidate, "path is outside the node readSet");
+        }
+    }
+    return relative;
+}
 /**
  * Assert a mutation target is writable under the DAG writer policy.
  * Returns the normalized lexical repo-relative path on success.
@@ -201,11 +223,30 @@ export async function assertMkdirPath(dirPath, ctx) {
     assertMkdirRelative(effectiveRelative, ctx);
     return lexicalRelative;
 }
+export function createPiReaderFsOperations(ctx) {
+    return {
+        readFile: async (absolutePath) => {
+            await assertReadablePath(absolutePath, ctx);
+            return fsReadFile(absolutePath);
+        },
+        access: async (absolutePath) => {
+            await assertReadablePath(absolutePath, ctx);
+            await fsAccess(absolutePath);
+        },
+    };
+}
 /** Build FS operations that enforce writer policy before mutations. */
 export function createPiWriterFsOperations(ctx) {
+    const strictReadSet = (ctx.readSet?.length ?? 0) > 0;
     return {
-        readFile: (absolutePath) => fsReadFile(absolutePath),
+        readFile: async (absolutePath) => {
+            if (strictReadSet)
+                await assertReadablePath(absolutePath, ctx);
+            return fsReadFile(absolutePath);
+        },
         access: async (absolutePath) => {
+            if (strictReadSet)
+                await assertReadablePath(absolutePath, ctx);
             await fsAccess(absolutePath);
         },
         writeFile: async (absolutePath, content) => {
@@ -218,6 +259,20 @@ export function createPiWriterFsOperations(ctx) {
         },
     };
 }
+export async function createPiReaderCustomTools(ctx) {
+    const sdk = (await import("@earendil-works/pi-coding-agent"));
+    const createReadToolDefinition = sdk.createReadToolDefinition;
+    if (typeof createReadToolDefinition !== "function") {
+        throw new Error("pi read tool policy unavailable: createReadToolDefinition missing from SDK");
+    }
+    const read = createReadToolDefinition(path.resolve(ctx.repoRoot), {
+        operations: createPiReaderFsOperations(ctx),
+    });
+    if (read?.name !== "read") {
+        throw new Error("pi read tool policy unavailable: SDK tool must be named read");
+    }
+    return [read];
+}
 /**
  * Create same-name custom edit/write tool definitions that override built-ins
  * via Pi SDK customTools registration. Fails closed when SDK factories are missing.
@@ -262,5 +317,6 @@ export function buildPiWriterToolPolicyContext(input) {
         writeSet: input.writeSet ?? [],
         forbiddenPaths: input.forbiddenPaths ?? [],
         writePolicy: input.writePolicy ?? "exclusive",
+        readSet: input.readSet ?? [],
     };
 }

package/dist/executors/shell-executor.js

@@ -32,15 +32,16 @@ import { materializeBackendTestExecutionContract } from "../workflows/dag/backen
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
 import { frontendTestLayoutFromSpec, } from "../workflows/dag/frontend-test-layout.js";
 import { backendTestGapDocSchema, ingestBackendTestGap, } from "../workflows/dag/backend-test-gap-fill.js";
-import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
+import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, classifyBackendTestCorrespondenceRepair, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
 import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport, } from "../workflows/dag/backend-test-result-contract.js";
 import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, resolveBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, hasBlockingBackendMarkdownModuleStemFindings, inspectBackendTestEnvironment, markdownFiles, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { applyDeterministicScenarioParamRepairs, assessBackendScenarioParamConsistency, classifyBackendTestFailureWithScenarioParam, readBackendScenarioParamFacts, renderBackendTestFailureAnalysis, writeBackendScenarioParamArtifacts, writeScenarioParamRepairAudit, } from "../workflows/dag/backend-test-scenario-param.js";
-import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, buildBackendTestItemEligibility, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
+import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, buildBackendTestItemEligibility, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, summarizeBackendTestExclusions, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.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 { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
 import { parseAndValidateFinalWriteSetApproval, } from "../workflows/dag/node-execution.js";
 import { buildShellProcessEnv } from "./shell-verification.js";
 import { readRunState } from "../workflows/dag/run-store.js";
@@ -539,13 +540,22 @@ async function executeBackendTestPipeline(input, meta) {
     const started = Date.now();
     // Plan A: prefer the frozen layout carried by the compiled spec; fall back
     // to the historical default for hand-written legacy DAGs.
-    const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
+    const baseBackendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
         ? {
             testRoot: meta.spec.backendTestLayout.testRoot,
             markdownRel: meta.spec.backendTestLayout.markdownRel,
             scriptRel: meta.spec.backendTestLayout.scriptRel,
         }
         : undefined);
+    const markdownPlanArtifact = path.join(meta.runDir, "generate-backend-md-plan-pi", "plan.md");
+    const backendLayout = existsSync(markdownPlanArtifact)
+        ? {
+            ...baseBackendLayout,
+            readmePath: path
+                .relative(input.cwd, markdownPlanArtifact)
+                .replaceAll(path.sep, "/"),
+        }
+        : baseBackendLayout;
     try {
         if (!pipeline)
             throw new Error("missing backend-test pipeline id");
@@ -860,26 +870,49 @@ async function executeBackendTestPipeline(input, meta) {
                 const correspondenceFactsPath = path.join(contractsDir, "backend-test-markdown-pytest-correspondence-initial.json");
                 await writeFile(correspondenceFactsPath, JSON.stringify(correspondence.facts, null, 2), "utf8");
                 outputs.push(`initialCorrespondence=${correspondenceReportPath}`, `initialCorrespondenceFacts=${correspondenceFactsPath}`);
-                if (correspondence.facts.status === "FAIL" && facts.status === "PASS") {
-                    const correspondenceRepairPaths = Array.from(new Set(correspondence.facts.entries
-                        .filter((entry) => entry.status !== "EXACT_1_TO_1")
-                        .flatMap((entry) => [entry.expectedScript, ...entry.actualScripts])
-                        .filter((candidate) => candidate.startsWith("testcase/") && candidate.endsWith(".py")))).sort();
-                    if (correspondenceRepairPaths.length > 0) {
-                        facts.status = "REPAIRABLE";
-                        facts.repairEligible = true;
-                        facts.repairPaths = Array.from(new Set([...facts.repairPaths, ...correspondenceRepairPaths])).sort();
+                if (correspondence.facts.status === "FAIL") {
+                    const repair = classifyBackendTestCorrespondenceRepair(correspondence.facts, backendLayout);
+                    if (repair.markdownBlockingEntries.length > 0) {
+                        facts.status = "BLOCKED";
+                        facts.repairEligible = false;
+                        facts.repairPaths = [];
                         facts.findings.push({
-                            kind: "markdown-pytest-correspondence",
+                            kind: "markdown-correspondence-contract",
                             classification: "test-asset-defect",
-                            repairability: "repairable",
-                            detail: correspondence.facts.entries
-                                .filter((entry) => entry.status !== "EXACT_1_TO_1")
-                                .flatMap((entry) => entry.findings)
+                            repairability: "blocked",
+                            detail: repair.markdownBlockingEntries
+                                .map((entry) => `${entry.caseId ?? "unknown Case"}: ${entry.reasonCodes.join(", ")}`)
                                 .join("; ")
-                                .slice(0, 12_000) || "Markdown-to-pytest correspondence is incomplete",
+                                .slice(0, 12_000),
                         });
                     }
+                    else if (repair.pytestRepairPaths.length > 0 &&
+                        (facts.status === "PASS" || facts.status === "REPAIRABLE")) {
+                        facts.status = "REPAIRABLE";
+                        facts.repairEligible = true;
+                        facts.repairPaths = Array.from(new Set([...facts.repairPaths, ...repair.pytestRepairPaths])).sort();
+                        const repairEntries = correspondence.facts.entries.filter((entry) => repair.pytestRepairEntries.some((candidate) => candidate.caseId === entry.caseId));
+                        for (const entry of repairEntries.slice(0, 40)) {
+                            const classified = repair.pytestRepairEntries.find((candidate) => candidate.caseId === entry.caseId);
+                            facts.findings.push({
+                                kind: "markdown-pytest-correspondence",
+                                classification: "test-asset-defect",
+                                repairability: "repairable",
+                                detail: entry.findings.join("; ").slice(0, 2_000) || "Markdown-to-pytest correspondence is incomplete",
+                                ...(entry.caseId ? { caseId: entry.caseId } : {}),
+                                reasonCodes: classified?.reasonCodes ?? [],
+                                repairPaths: classified?.paths ?? [],
+                                payloadExpectedPaths: Array.from(new Set([
+                                    ...entry.payloadAssessment.requiredPaths,
+                                    ...entry.payloadAssessment.allowedPaths,
+                                ])).sort(),
+                                payloadObservedPaths: entry.payloadAssessment.observedPaths,
+                                payloadMissingPaths: entry.payloadAssessment.missingPaths,
+                                payloadUnexpectedPaths: entry.payloadAssessment.unexpectedPaths,
+                                payloadEnumMismatches: entry.payloadAssessment.enumMismatches,
+                            });
+                        }
+                    }
                 }
             }
             catch (error) {
@@ -902,6 +935,19 @@ async function executeBackendTestPipeline(input, meta) {
                     collectedItemCount: facts.collectedItemCount,
                     missingMappedScripts: facts.missingMappedScripts,
                     repairPaths: facts.repairPaths,
+                    repairFindings: facts.findings.map((finding) => ({
+                        kind: finding.kind,
+                        repairability: finding.repairability,
+                        detail: finding.detail,
+                        ...(finding.caseId ? { caseId: finding.caseId } : {}),
+                        ...(finding.reasonCodes ? { reasonCodes: finding.reasonCodes } : {}),
+                        ...(finding.repairPaths ? { repairPaths: finding.repairPaths } : {}),
+                        ...(finding.payloadExpectedPaths ? { payloadExpectedPaths: finding.payloadExpectedPaths } : {}),
+                        ...(finding.payloadObservedPaths ? { payloadObservedPaths: finding.payloadObservedPaths } : {}),
+                        ...(finding.payloadMissingPaths ? { payloadMissingPaths: finding.payloadMissingPaths } : {}),
+                        ...(finding.payloadUnexpectedPaths ? { payloadUnexpectedPaths: finding.payloadUnexpectedPaths } : {}),
+                        ...(finding.payloadEnumMismatches ? { payloadEnumMismatches: finding.payloadEnumMismatches } : {}),
+                    })),
                     factsPath: "contracts/backend-test-pytest-collection-initial.json",
                 }),
                 stderr: "",
@@ -915,6 +961,7 @@ async function executeBackendTestPipeline(input, meta) {
                 effective = await materializeEffectiveBackendPytestCollection({
                     workspaceRoot: input.cwd,
                     initial,
+                    layout: backendLayout,
                 });
             }
             else if (initial.status === "REPAIRABLE") {
@@ -974,6 +1021,7 @@ async function executeBackendTestPipeline(input, meta) {
                     workspaceRoot: input.cwd,
                     initial,
                     final: finalFacts,
+                    layout: backendLayout,
                 });
             }
             else {
@@ -999,6 +1047,7 @@ async function executeBackendTestPipeline(input, meta) {
                 })
                 : { eligibleItemIds: effective.collectedItemIds, excludedItems: [] };
             const eligibilityInputHashes = Object.fromEntries((correspondence?.facts.inputFiles ?? []).map((item) => [item.path, item.sha256]));
+            const exclusionSummary = summarizeBackendTestExclusions(eligibility.excludedItems);
             const eligibilityFactsPath = path.join(meta.runDir, "contracts", "backend-test-execution-eligibility.json");
             await mkdir(path.dirname(eligibilityFactsPath), { recursive: true });
             await writeFile(eligibilityFactsPath, `${JSON.stringify({
@@ -1009,6 +1058,9 @@ async function executeBackendTestPipeline(input, meta) {
                 excludedItemCount: eligibility.excludedItems.length,
                 eligibleItemIds: eligibility.eligibleItemIds,
                 excludedItems: eligibility.excludedItems,
+                exclusionSummary,
+                pytestSpawned: false,
+                businessTestBodyExecutedCount: 0,
                 inputHashes: eligibilityInputHashes,
             }, null, 2)}\n`, "utf8");
             const eligibilityReportPath = await writeRunReport(meta.runDir, "backend-test-execution-eligibility.md", [
@@ -1021,6 +1073,10 @@ async function executeBackendTestPipeline(input, meta) {
                 `- Collected items: ${effective.collectedItemIds.length}`,
                 `- Eligible items: ${eligibility.eligibleItemIds.length}`,
                 `- Excluded items: ${eligibility.excludedItems.length}`,
+                `- Excluded Cases: ${exclusionSummary.excludedCaseCount}`,
+                `- Exclusion categories: ${Object.entries(exclusionSummary.excludedByReason).map(([category, count]) => `${category}=${count}`).join("; ") || "none"}`,
+                "- pytest spawned: false",
+                "- Business test bodies executed: 0",
                 "",
                 "## Excluded Items",
                 "",
@@ -1036,6 +1092,7 @@ async function executeBackendTestPipeline(input, meta) {
                 scenarioParamRepairAttempt: scenarioFacts.repairAttempt,
                 eligibility,
                 eligibilityInputHashes,
+                layout: backendLayout,
             });
             return {
                 ok: true,
@@ -1048,6 +1105,9 @@ async function executeBackendTestPipeline(input, meta) {
                     executionReadinessStatus: readiness.status,
                     eligibleItemCount: readiness.eligibleItemIds.length,
                     excludedItemCount: readiness.excludedItems.length,
+                    exclusionSummary: readiness.exclusionSummary,
+                    pytestSpawned: readiness.pytestSpawned,
+                    businessTestBodyExecutedCount: readiness.businessTestBodyExecutedCount,
                     factsPath: "contracts/backend-test-pytest-collection-effective.json",
                     readinessPath: "contracts/backend-test-execution-readiness.json",
                     reportPath: artifacts.reportPath,
@@ -1059,7 +1119,7 @@ async function executeBackendTestPipeline(input, meta) {
         else if (pipeline === "markdown-traceability") {
             let report;
             try {
-                report = await validateBackendMarkdownTraceability(input.cwd);
+                report = await validateBackendMarkdownTraceability(input.cwd, backendLayout);
             }
             catch (error) {
                 report = `# Backend Test Traceability\n\n## Status\n\nFAIL\n\n## Findings\n\n- Traceability validation could not complete: ${error instanceof Error ? error.message : String(error)}\n`;
@@ -1144,7 +1204,7 @@ async function executeBackendTestPipeline(input, meta) {
         }
         else if (pipeline === "markdown-execute-html") {
             const executionReadiness = await readBackendTestExecutionReadiness(path.join(meta.runDir, "contracts", "backend-test-execution-readiness.json"));
-            await assertBackendTestExecutionReadinessFresh(input.cwd, executionReadiness);
+            await assertBackendTestExecutionReadinessFresh(input.cwd, executionReadiness, backendLayout);
             const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd, backendLayout);
             let eligibleItemIds = executionReadiness.eligibleItemIds;
             // Plan D gap-fill executeScope=affected: when a gap plan exists in
@@ -1719,6 +1779,33 @@ async function executeBackendTestPipeline(input, meta) {
     }
 }
 async function executeBackendTestPipelineWithWriteGuard(input, meta) {
+    if (meta.spec.backendTestWorkspaceControl === "filesystem-only") {
+        const paths = input.task.writeSet ?? input.task.allowedPaths;
+        let beforeSnapshot;
+        try {
+            beforeSnapshot = await captureWorkspaceWriteSnapshot({ rootCwd: input.cwd, paths });
+        }
+        catch (error) {
+            return { ok: false, stdout: "", stderr: `workspace filesystem baseline unavailable: ${error instanceof Error ? error.message : String(error)}`, failureCategory: "write-guard", durationMs: 0 };
+        }
+        const result = await executeBackendTestPipeline(input, meta);
+        try {
+            const afterSnapshot = await captureWorkspaceWriteSnapshot({ rootCwd: input.cwd, paths });
+            const guard = validateShellWriteGuard({
+                changedPaths: diffWorkspaceWriteSnapshots(beforeSnapshot, afterSnapshot),
+                writePolicy: input.task.writePolicy,
+                writeSet: input.task.writeSet,
+                allowedPaths: input.task.allowedPaths,
+                forbiddenPaths: input.task.forbiddenPaths,
+            });
+            if (!guard.ok)
+                return { ...result, ok: false, stderr: [result.stderr, `filesystem write guard failed: ${guard.violations.join(", ")}`].filter(Boolean).join("\n\n"), failureCategory: "write-guard" };
+            return result;
+        }
+        catch (error) {
+            return { ...result, ok: false, stderr: [result.stderr, `filesystem write guard failed: ${error instanceof Error ? error.message : String(error)}`].filter(Boolean).join("\n\n"), failureCategory: "write-guard" };
+        }
+    }
     let beforeStatus;
     try {
         beforeStatus = await readGitStatusPorcelain(input.cwd);

package/dist/executors/workspace-write-snapshot.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+const normalize = (value) => value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+function rootBeforeWildcard(pattern) {
+    const value = normalize(pattern);
+    const wildcard = value.search(/[?*]/);
+    if (wildcard < 0)
+        return path.posix.dirname(value);
+    const prefix = value.slice(0, wildcard);
+    return prefix.slice(0, prefix.lastIndexOf("/")) || ".";
+}
+async function walk(rootCwd, relative, files) {
+    let entries;
+    try {
+        entries = await readdir(path.resolve(rootCwd, relative), { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if ([".git", ".harness", "node_modules"].includes(entry.name))
+            continue;
+        const child = normalize(path.posix.join(relative, entry.name));
+        if (entry.isDirectory())
+            await walk(rootCwd, child, files);
+        else if (entry.isFile())
+            files.add(child);
+    }
+}
+export async function captureWorkspaceWriteSnapshot(input) {
+    const candidates = new Set();
+    for (const pattern of input.paths) {
+        await walk(input.rootCwd, rootBeforeWildcard(pattern), candidates);
+        if (!/[?*]/.test(pattern)) {
+            try {
+                if ((await lstat(path.resolve(input.rootCwd, pattern))).isFile())
+                    candidates.add(normalize(pattern));
+            }
+            catch { /* absent target */ }
+        }
+    }
+    const files = {};
+    let totalBytes = 0;
+    for (const relative of [...candidates].filter((file) => input.paths.some((pattern) => pathMatchesPattern(file, pattern))).sort()) {
+        if (Object.keys(files).length >= 20_000)
+            throw new Error("workspace snapshot file limit exceeded");
+        const absolute = path.resolve(input.rootCwd, relative);
+        const stat = await lstat(absolute);
+        if (!stat.isFile())
+            throw new Error(`workspace snapshot encountered non-regular file: ${relative}`);
+        totalBytes += stat.size;
+        if (totalBytes > 64 * 1024 * 1024)
+            throw new Error("workspace snapshot byte limit exceeded");
+        files[relative] = { size: stat.size, sha256: createHash("sha256").update(await readFile(absolute)).digest("hex") };
+    }
+    const body = JSON.stringify(files);
+    return { schemaVersion: 1, controlMode: "filesystem-only", files, sha256: createHash("sha256").update(body).digest("hex") };
+}
+export function diffWorkspaceWriteSnapshots(before, after) {
+    const paths = new Set([...Object.keys(before.files), ...Object.keys(after.files)]);
+    return [...paths].sort().filter((file) => {
+        const left = before.files[file];
+        const right = after.files[file];
+        return !left || !right || left.size !== right.size || left.sha256 !== right.sha256;
+    });
+}

package/dist/governance/checks.js

@@ -8,6 +8,7 @@ import { buildTaskReadModel } from '../task/read-model.js';
 const SKIP_DIRS = new Set([
     '.git',
     '.harness',
+    '.scratch',
     'node_modules',
     'dist',
     'coverage',

package/dist/infrastructure/harness/atomic-write.js

@@ -2,6 +2,29 @@ import { copyFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/pr
 import path from "node:path";
 import { assertHarnessWriteAllowed, } from "./completed-facts-guard.js";
 let atomicWriteSequence = 0;
+function isTransientJsonReadError(error) {
+    if (error instanceof SyntaxError)
+        return true;
+    if (!error || typeof error !== "object" || !("code" in error))
+        return false;
+    const code = String(error.code ?? "");
+    return code === "EBUSY" || code === "EPERM" || code === "EACCES";
+}
+export async function readJsonWithTransientRetry(targetPath, options = {}) {
+    const attempts = Math.max(1, Math.floor(options.attempts ?? 6));
+    const delayMs = Math.max(0, Math.floor(options.delayMs ?? 20));
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            return JSON.parse(await readFile(targetPath, "utf-8"));
+        }
+        catch (error) {
+            if (attempt === attempts || !isTransientJsonReadError(error))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, delayMs * attempt));
+        }
+    }
+    throw new Error("unreachable transient JSON read state");
+}
 async function writeAtomic(targetPath, content, options) {
     assertHarnessWriteAllowed(targetPath, options);
     const resolved = options?.repoRoot && !path.isAbsolute(targetPath)

package/dist/shared/dag-prompt-override.js

@@ -1,15 +1,14 @@
 /**
  * Internal switch for the experimental "rerun failed node with an edited
- * prompt" capability. Default is OFF; nothing may depend on it being enabled.
- * The switch is deliberately env-based (no harness.json surface) while the
- * feature is internal.
+ * prompt" capability. The feature is enabled by default; the environment
+ * variable remains as an emergency kill switch while the feature is internal.
  */
 export const DAG_RERUN_PROMPT_OVERRIDE_ENV = "HARNESS_DAG_RERUN_PROMPT_OVERRIDE";
 /** Upper bound for an override input body (characters). */
 export const MAX_DAG_RERUN_PROMPT_OVERRIDE_CHARS = 65_536;
 export function isDagRerunPromptOverrideEnabled(env = process.env) {
-    const value = env[DAG_RERUN_PROMPT_OVERRIDE_ENV];
-    return value === "1" || value === "true";
+    const value = env[DAG_RERUN_PROMPT_OVERRIDE_ENV]?.trim().toLowerCase();
+    return value !== "0" && value !== "false" && value !== "off";
 }
 export const DAG_RERUN_PROMPT_ADDENDUM_TAG = "operator_addendum";
 /**