@tea-agent/loop-agent 0.39.3 → 0.40.0-beta.1

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

@@ -4,16 +4,18 @@ import { readFile } from "node:fs/promises";
 import { writeDagNodeJsonArtifact, writeTextArtifactFile, } from "../infrastructure/harness/artifact-store.js";
 import { executePiStep, resolvePiBackend, } from "./pi-executor.js";
 import { resolveDagPiExtensions, } from "./pi-extension-resolver.js";
-import { buildPiWriterToolPolicyContext, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
+import { buildPiWriterToolPolicyContext, createPiReaderCustomTools, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
 import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND_CAPABILITY_REGISTRY, resolveCaseIdFromWriteSet, resolveEvidenceDirFromWriteSet, } from "./pi-playwright-cli-tool.js";
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
+import { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
 import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
-import { frontendTestLayoutFromSpec, } from "../workflows/dag/frontend-test-layout.js";
+import { frontendTestLayoutFromSpec } from "../workflows/dag/frontend-test-layout.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
+import { writeEffectiveContextReceipt } from "../workflows/dag/context-receipt.js";
 /**
  * Writer classification for a length-stopped thinking-only attempt: the model
  * exhausted its output budget thinking but never issued a write/edit tool call
@@ -181,6 +183,9 @@ export function resolveDagPiStepName(task) {
     return resolvePiExecutorStep(resolveDagPiPersona(task));
 }
 export function resolveDagPiToolNames(task) {
+    if ((task.readSet?.length ?? 0) > 0) {
+        return isDagPiWriteTask(task) ? ["read", "edit", "write"] : ["read"];
+    }
     if (!isDagPiWriteTask(task))
         return [...DAG_PI_READONLY_TOOLS];
     const tools = [...DAG_PI_WRITE_TOOLS];
@@ -237,6 +242,9 @@ export function buildDagPiUserMessage(task, persona, step) {
         `You are executing hybrid DAG node "${task.id}" (role=${role}, piPersona=${persona}, piStep=${step}, writePolicy=${writePolicy}).`,
         "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
         "Use read-only tools only. Do not edit, write, or commit repository files.",
+        (task.readSet?.length ?? 0) > 0
+            ? `Strict read set: ${task.readSet.join(", ")}. The read tool rejects every other repository path; do not search for substitutes.`
+            : undefined,
         "Return your conclusion as plain Markdown text suitable for downstream DAG nodes.",
         "Do not wrap the output in code fences and do not add conversational preamble.",
     ].join(" ");
@@ -446,9 +454,28 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         };
     }
     let beforeStatus;
+    let beforeWorkspaceSnapshot;
     let beforePathFingerprints;
-    /** tools-only: keep SDK path sandbox; skip git baseline + post-diff write-guard hard fail. */
-    const skipGitWriteGuard = isWriteTask && input.task.writeGuardPolicy === "tools-only";
+    /** tools-only and filesystem-only keep the tool sandbox but skip Git baseline. */
+    const filesystemOnly = isWriteTask && meta.spec.backendTestWorkspaceControl === "filesystem-only";
+    const skipGitWriteGuard = isWriteTask && (input.task.writeGuardPolicy === "tools-only" || filesystemOnly);
+    if (isWriteTask && filesystemOnly) {
+        try {
+            beforeWorkspaceSnapshot = await captureWorkspaceWriteSnapshot({
+                rootCwd: input.cwd,
+                paths: input.task.writeSet ?? input.task.allowedPaths,
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `workspace filesystem baseline unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "write-guard",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
     if (isWriteTask && !skipGitWriteGuard) {
         try {
             beforeStatus = await writeGuardDependencies.readGitStatusPorcelain(input.cwd, { phase: "pi-writer-before" });
@@ -490,12 +517,24 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     let playwrightToolContext;
     if (allowsPlaywrightCli && !isWriteTask) {
         return {
-            ok: false, stdout: "", stderr: "pi command capability requires an explicit bounded write tool profile", failureCategory: "tool-policy", durationMs: Date.now() - started,
+            ok: false,
+            stdout: "",
+            stderr: "pi command capability requires an explicit bounded write tool profile",
+            failureCategory: "tool-policy",
+            durationMs: Date.now() - started,
         };
     }
-    if (isWriteTask || allowsPlaywrightCli) {
+    const strictReadSet = (input.task.readSet?.length ?? 0) > 0;
+    if (isWriteTask || allowsPlaywrightCli || strictReadSet) {
         try {
             const customTools = [];
+            if (strictReadSet) {
+                const readContext = buildPiWriterToolPolicyContext({
+                    repoRoot: input.cwd,
+                    readSet: input.task.readSet,
+                });
+                customTools.push(...(await createPiReaderCustomTools(readContext)));
+            }
             if (isWriteTask) {
                 const policyContext = buildPiWriterToolPolicyContext({
                     repoRoot: input.cwd,
@@ -503,6 +542,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     writeSet: input.task.writeSet,
                     forbiddenPaths: input.task.forbiddenPaths,
                     writePolicy: input.task.writePolicy,
+                    readSet: input.task.readSet,
                 });
                 customTools.push(...(await createPiWriterCustomTools(policyContext)));
             }
@@ -607,19 +647,42 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         const piExtensionPaths = piExtensionsResolution && resolvePiBackend() !== "cli-only"
             ? piExtensionsResolution.resolved.flatMap((entry) => entry.entryPaths)
             : undefined;
+        const modelConfig = resolveDagPiModelConfig(input.model, input.thinking ? { thinking: input.thinking } : undefined);
+        const toolNames = resolveDagPiToolNames(input.task);
+        const userMessage = buildDagPiUserMessage(input.task, persona, step);
+        await writeEffectiveContextReceipt({
+            runDir: meta.runDir,
+            runId: meta.runId,
+            nodeId: input.task.id,
+            attempt,
+            task: input.task,
+            spec: meta.spec,
+            repoRoot: input.cwd,
+            systemPrompt: input.prompt,
+            userMessage,
+            resolvedModel: `${modelConfig.provider}/${modelConfig.model}`,
+            resolvedSkills: input.resolvedSkills ?? [],
+            resolvedExtensions: piExtensionsResolution && resolvePiBackend() !== "cli-only"
+                ? piExtensionsResolution.resolved.map((entry) => entry.id)
+                : [],
+            activeTools: toolNames,
+        });
         result = await piStepFn({
             attachedFiles: [],
-            modelConfig: resolveDagPiModelConfig(input.model, input.thinking ? { thinking: input.thinking } : undefined),
+            modelConfig,
             prompt: input.prompt,
             repoRoot: input.cwd,
             step,
-            toolNames: resolveDagPiToolNames(input.task),
-            userMessage: buildDagPiUserMessage(input.task, persona, step),
+            toolNames,
+            userMessage,
             sessionEventsPath: path.join(meta.runDir, input.task.id, "session-events.jsonl"),
             // Absolute max wall clock from adaptive liveness policy (defaults to 4h).
             timeoutMs: input.timeoutMs,
             stallTimeoutMs: input.stallTimeoutMs,
             abortGraceMs: input.abortGraceMs,
+            ...(input.task.contextBudget
+                ? { contextBudget: input.task.contextBudget }
+                : {}),
             ...(writerToolPolicy ? { writerToolPolicy } : {}),
             ...(piExtensionPaths && piExtensionPaths.length > 0
                 ? { piExtensionPaths }
@@ -668,6 +731,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         persona,
         step,
     });
+    if (input.task.id === "generate-backend-md-plan-pi" && result.assistantText?.trim()) {
+        await writeTextArtifactFile(path.join(meta.runDir, input.task.id, "plan.md"), result.assistantText.trim() + "\n");
+    }
     const mapped = mapPiResultToDagNodeResult(result, input.task.writerOutcomePolicy
         ? WRITER_OUTCOME_PROTOCOL_LINE
         : input.task.firstProtocolLine);
@@ -678,6 +744,27 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     let writeGuardViolations = [];
     let changeManifestAfterStatus;
     let changeManifestChangedFiles;
+    let afterWorkspaceSnapshot;
+    if (filesystemOnly && beforeWorkspaceSnapshot) {
+        try {
+            afterWorkspaceSnapshot = await captureWorkspaceWriteSnapshot({
+                rootCwd: input.cwd,
+                paths: input.task.writeSet ?? input.task.allowedPaths,
+            });
+            changeManifestChangedFiles = diffWorkspaceWriteSnapshots(beforeWorkspaceSnapshot, afterWorkspaceSnapshot);
+            const guard = validateShellWriteGuardFromDiff({
+                changedFiles: changeManifestChangedFiles,
+                task: input.task,
+                concurrentSiblingWriteSets: meta.concurrentSiblingWriteSets,
+            });
+            writeGuardOk = guard.ok;
+            writeGuardViolations = guard.violations;
+        }
+        catch (error) {
+            writeGuardOk = false;
+            writeGuardViolations = [`workspace snapshot unavailable: ${error instanceof Error ? error.message : String(error)}`];
+        }
+    }
     if (beforeStatus !== undefined) {
         let recoveryEvidence;
         let removalPendingRecheck;
@@ -850,7 +937,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         }
     }
     if (writeGuardOk &&
-        beforeStatus !== undefined &&
+        (beforeStatus !== undefined || beforeWorkspaceSnapshot !== undefined) &&
         changeManifestChangedFiles !== undefined) {
         await persistWriterChangeManifest({
             runDir: meta.runDir,
@@ -860,13 +947,12 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             approvalSourceNodeId: input.task.resolvedFinalWriteSetApproval?.approvalSourceNodeId,
             approvalDigest: input.task.resolvedFinalWriteSetApproval?.approvalDigest,
             changedFiles: changeManifestChangedFiles,
-            beforeStatus,
-            afterStatus: changeManifestAfterStatus ?? "",
+            beforeStatus: beforeStatus ?? JSON.stringify(beforeWorkspaceSnapshot),
+            afterStatus: changeManifestAfterStatus ?? JSON.stringify(afterWorkspaceSnapshot),
         });
     }
     let completenessFailure;
-    if (writeGuardOk &&
-        isBackendTestCompletenessRetryCandidate(input.task)) {
+    if (writeGuardOk && isBackendTestCompletenessRetryCandidate(input.task)) {
         try {
             const writerRole = backendTestWriterProgressRoleForTask(input.task.id);
             const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
@@ -879,7 +965,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             const progress = isBackendTestShardChildTask(input.task)
                 ? await assessBackendTestShardChildCompleteness({
                     workspaceRoot: input.cwd,
-                    role: writerRole === "pytest-generate" ? "pytest-generate" : "md-generate",
+                    role: writerRole === "pytest-generate"
+                        ? "pytest-generate"
+                        : "md-generate",
                     writeSet: input.task.writeSet ?? [],
                 })
                 : isBackendTestMdPlanTask(input.task)
@@ -925,7 +1013,10 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             };
         }
     }
-    if (mapped.ok && writeGuardOk && !writerOutcomeViolation && !completenessFailure) {
+    if (mapped.ok &&
+        writeGuardOk &&
+        !writerOutcomeViolation &&
+        !completenessFailure) {
         return mapped;
     }
     const writerThinkingExhausted = isWriterThinkingExhausted(result, mapped, changeManifestChangedFiles);
@@ -1331,9 +1422,7 @@ async function persistWriterChangeManifest(input) {
         ...(input.approvalSourceNodeId
             ? { approvalSourceNodeId: input.approvalSourceNodeId }
             : {}),
-        ...(input.approvalDigest
-            ? { approvalDigest: input.approvalDigest }
-            : {}),
+        ...(input.approvalDigest ? { approvalDigest: input.approvalDigest } : {}),
         changedFiles: input.changedFiles,
         beforeStatusSha256: createHash("sha256")
             .update(input.beforeStatus)

package/dist/executors/pi-executor.js

@@ -1005,12 +1005,14 @@ export function shouldRetryWithFallback(stderr, stdout) {
     return ["quota", "rate-limit", "unavailable", "network"].includes(category);
 }
 export function classifyPiFailure(input) {
+    if (input.exitCode === 0 && input.assistantText.trim())
+        return "success";
+    if (input.stderr.toLowerCase().includes("context-budget-exhausted:"))
+        return "context-budget-exhausted";
     if (input.timedOut)
         return "timeout";
     if (input.outputTooLarge)
         return "output-too-large";
-    if (input.exitCode === 0 && input.assistantText.trim())
-        return "success";
     const combined = `${input.stderr}\n${input.stdout}`.toLowerCase();
     // Prefer explicit rate-limit / HTTP 429 before generic "limit" quota phrases.
     // Chinese gateways often say "请求频率已达到限制" without English "rate limit".

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

@@ -212,6 +212,9 @@ async function createSdkSession(sdk, input, shared) {
     const model = input.provider && input.model
         ? await resolveModel(modelRuntime, input.provider, input.model)
         : undefined;
+    if (input.provider && input.model && !model) {
+        throw new Error(`pi SDK model unavailable: ${input.provider}/${input.model}; refusing to fall back to the session default`);
+    }
     // Inject rate-limit-tolerant auto-retry settings for the session lifecycle.
     // Prefer SettingsManager.inMemory so harness runs do not depend on ~/.pi or
     // project .pi/settings.json being present/trusted.
@@ -485,6 +488,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 +543,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 +634,7 @@ export async function executeSingleSdkAttempt(options) {
         });
         let resolveStall;
         let resolveSettlement;
+        let resolveContextBudget;
         let settled = false;
         let abortConfirmed = true;
         const persistRuntimeNote = (event) => {
@@ -655,6 +665,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 +712,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 +737,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 +752,7 @@ export async function executeSingleSdkAttempt(options) {
                 settlementPromise,
                 ...(timeoutPromise ? [timeoutPromise] : []),
                 ...(stallPromise ? [stallPromise] : []),
+                ...(contextBudgetPromise ? [contextBudgetPromise] : []),
             ]);
         };
         const disposeSession = async () => {
@@ -737,7 +780,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

@@ -41,6 +41,7 @@ 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");
@@ -915,6 +925,7 @@ async function executeBackendTestPipeline(input, meta) {
                 effective = await materializeEffectiveBackendPytestCollection({
                     workspaceRoot: input.cwd,
                     initial,
+                    layout: backendLayout,
                 });
             }
             else if (initial.status === "REPAIRABLE") {
@@ -974,6 +985,7 @@ async function executeBackendTestPipeline(input, meta) {
                     workspaceRoot: input.cwd,
                     initial,
                     final: finalFacts,
+                    layout: backendLayout,
                 });
             }
             else {
@@ -1036,6 +1048,7 @@ async function executeBackendTestPipeline(input, meta) {
                 scenarioParamRepairAttempt: scenarioFacts.repairAttempt,
                 eligibility,
                 eligibilityInputHashes,
+                layout: backendLayout,
             });
             return {
                 ok: true,
@@ -1144,7 +1157,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 +1732,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/{worker → infrastructure}/console/app-data.js

@@ -38,6 +38,8 @@ export function openConsoleAppData(options) {
         confirmations: path.join(repoNamespace, "confirmations"),
         dagReceipts: path.join(repoNamespace, "dag-receipts"),
         staged: path.join(repoNamespace, "staged"),
+        contextExports: path.join(repoNamespace, "context-exports"),
+        artifactRevisions: path.join(repoNamespace, "artifact-revisions"),
         assessments: path.join(repoNamespace, "assessments"),
         interviews: path.join(repoNamespace, "interviews"),
         chats: path.join(repoNamespace, "chats"),
@@ -51,6 +53,8 @@ export function openConsoleAppData(options) {
         paths.confirmations,
         paths.dagReceipts,
         paths.staged,
+        paths.contextExports,
+        paths.artifactRevisions,
         paths.assessments,
         paths.interviews,
         paths.chats,