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

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

@@ -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,
@@ -1059,7 +1072,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 +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/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";
 /**

package/dist/shared/update/npm-client.js

@@ -11,10 +11,10 @@ export function createNpmUpdateClient(options) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_NPM_QUERY_TIMEOUT_MS;
     const cwd = options.cwd;
     const env = options.env;
-    const latestVersionCheck = async () => {
+    const distTagVersionCheck = async (channel) => {
         let result;
         try {
-            result = await runner(npmCommand, ["view", PACKAGE_NAME, "dist-tags.latest", "--json"], { timeoutMs, cwd, env });
+            result = await runner(npmCommand, ["view", PACKAGE_NAME, `dist-tags.${channel}`, "--json"], { timeoutMs, cwd, env });
         }
         catch {
             return { ok: false, reason: "spawn-failure" };
@@ -27,17 +27,19 @@ export function createNpmUpdateClient(options) {
         if (result.exitCode !== 0) {
             return { ok: false, reason: "command-failed" };
         }
-        const version = parseNpmViewLatest(result.stdout);
+        const version = parseNpmViewDistTag(result.stdout, channel);
         return version
             ? { ok: true, version }
             : { ok: false, reason: "invalid-response" };
     };
+    const latestVersionCheck = () => distTagVersionCheck("latest");
     return {
         async latestVersion() {
             const result = await latestVersionCheck();
             return result.ok ? result.version : undefined;
         },
         latestVersionCheck,
+        distTagVersionCheck,
         async canAutoInstall() {
             return proveGlobalNpmInstall({
                 currentVersion: options.currentVersion,
@@ -49,10 +51,11 @@ export function createNpmUpdateClient(options) {
                 timeoutMs,
             });
         },
-        async installExact(version) {
-            if (!isStrictRelease(version))
+        async installExact(version, channel = "latest") {
+            if (!isAllowedChannelVersion(version, channel)) {
                 return { ok: false, reason: "invalid-version" };
-            const result = await runner(npmCommand, buildExactInstallArgs(version), {
+            }
+            const result = await runner(npmCommand, buildExactInstallArgs(version, channel), {
                 timeoutMs: Math.max(timeoutMs, 120000),
                 cwd,
                 env,
@@ -79,6 +82,13 @@ export function createNpmUpdateClient(options) {
     };
 }
 export function parseNpmViewLatest(stdout) {
+    return parseNpmViewDistTag(stdout, "latest");
+}
+/**
+ * `latest` stays stable-only. `next` is explicitly selected by a human and
+ * may legitimately be a SemVer prerelease, but remains an exact version.
+ */
+export function parseNpmViewDistTag(stdout, channel) {
     const trimmed = stdout.trim();
     let value = trimmed;
     try {
@@ -89,11 +99,12 @@ export function parseNpmViewLatest(stdout) {
     }
     if (typeof value !== "string")
         return undefined;
-    return isStrictRelease(value) ? value : undefined;
+    return isAllowedChannelVersion(value, channel) ? value : undefined;
 }
-export function buildExactInstallArgs(version) {
-    if (!isStrictRelease(version))
-        throw new Error(`invalid release version: ${version}`);
+export function buildExactInstallArgs(version, channel = "latest") {
+    if (!isAllowedChannelVersion(version, channel)) {
+        throw new Error(`invalid ${channel} version: ${version}`);
+    }
     return ["install", "-g", `${PACKAGE_NAME}@${version}`, "--no-fund", "--no-audit"];
 }
 export function verifyNpmListVersion(stdout, expectedVersion) {
@@ -106,7 +117,13 @@ export function verifyNpmListVersion(stdout, expectedVersion) {
     }
 }
 export function verifyPathVersion(stdout, expectedVersion) {
-    return stdout.trim() === expectedVersion;
+    // `loop-agent --version` may append a build provenance marker. The release
+    // version itself must still match exactly; accepting no other trailing form
+    // keeps PATH verification bound to the requested stable package.
+    return new RegExp(`^${escapeRegExp(expectedVersion)}(?: \\(build [^)]+\\))?$`).test(stdout.trim());
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 async function proveGlobalNpmInstall(options) {
     const root = await options.runner(options.npmCommand, ["root", "-g"], {
@@ -142,6 +159,11 @@ function isStrictRelease(version) {
     const parsed = semver.parse(version);
     return Boolean(parsed && parsed.prerelease.length === 0);
 }
+function isAllowedChannelVersion(version, channel) {
+    if (channel === "latest")
+        return isStrictRelease(version);
+    return Boolean(semver.valid(version));
+}
 async function runCommand(command, args, options) {
     return new Promise((resolve) => {
         const child = spawn(command, [...args], {

package/dist/task/config-types.js

@@ -147,6 +147,8 @@ export const backendTestConfigSchema = z
     gapDoc: z.string().min(1).optional(),
     /** gap-fill pytest execution scope: only affected items (default) or all eligible. */
     executeScope: z.enum(["affected", "all"]).optional(),
+    /** Backend-test-only workspace mutation control; omitted means Git guard. */
+    workspaceControl: z.enum(["git", "filesystem-only"]).optional(),
 })
     .strict()
     .optional();
@@ -237,5 +239,13 @@ export const taskConfigSchema = z.preprocess((raw) => {
     if ("executor" in obj || "cursorModel" in obj) {
         throw new Error(CURSOR_TASK_FIELD_REMOVED_ERROR);
     }
+    const backendTest = obj.backendTest;
+    if (backendTest &&
+        typeof backendTest === "object" &&
+        !Array.isArray(backendTest) &&
+        "workspaceControl" in backendTest &&
+        obj.taskKind !== "backend-test") {
+        throw new Error("backendTest.workspaceControl is only valid when taskKind is backend-test");
+    }
     return raw;
 }, taskConfigObjectSchema);

package/dist/task/contract/apply.js

@@ -232,8 +232,11 @@ export async function applyTaskContract(input) {
         // Re-parse through schema to ensure full TaskConfig shape for hash stability
         const fullConfig = parseTaskConfigForRuntime(mergedConfig);
         const taskConfigContent = serializeTaskConfigForDisk(fullConfig);
-        const requirementContent = projectRequirementMarkdown(input.draft);
+        const requirementContent = projectRequirementMarkdown(input.draft, input.requirementLedger);
         const constraintsContent = projectConstraintsMarkdown(input.draft);
+        const requirementLedgerContent = input.requirementLedger !== undefined
+            ? `${JSON.stringify(input.requirementLedger, null, 2)}\n`
+            : undefined;
         // Validate references manifest hash if present (do not modify)
         const paths = getTaskPaths(input.repoRoot, input.taskId);
         const manifestText = await readFile(getSourceManifestPath(paths.sourceDir), "utf-8").catch(() => null);
@@ -241,6 +244,7 @@ export async function applyTaskContract(input) {
             requirementBytes: requirementContent,
             constraintsBytes: constraintsContent,
             referenceManifestBytes: manifestText,
+            requirementLedgerBytes: requirementLedgerContent,
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({
@@ -277,6 +281,9 @@ export async function applyTaskContract(input) {
                 constraintsContent,
                 taskConfigContent,
                 contractRef: nextRef,
+                ...(requirementLedgerContent !== undefined
+                    ? { requirementLedgerContent }
+                    : {}),
             },
         });
         await appendRequestLedgerEntry({
@@ -312,6 +319,9 @@ export async function applyTaskContract(input) {
             changedFiles: [
                 "source/需求.md",
                 "source/执行约束.md",
+                ...(requirementLedgerContent !== undefined
+                    ? ["source/requirement-ledger.json"]
+                    : []),
                 "task.json",
                 "contract.json",
             ],

package/dist/task/contract/constants.js

@@ -29,3 +29,5 @@ export const TRANSACTIONS_DIRNAME = TRANSACTIONS_DIR_NAME;
 export const REQUEST_LEDGER_BASENAME = REQUEST_LEDGER_FILE_NAME;
 export const REQUIREMENT_FILE_NAME = "需求.md";
 export const CONSTRAINTS_FILE_NAME = "执行约束.md";
+/** Source fidelity ledger (20260824-frontend-source-fidelity-ledger-v1). */
+export const REQUIREMENT_LEDGER_FILE_NAME = "requirement-ledger.json";

package/dist/task/contract/hash.js

@@ -35,6 +35,9 @@ export function computeSourceHashes(input) {
     if (input.referenceManifestBytes) {
         sourceHashes.referenceManifestSha256 = sha256Utf8(input.referenceManifestBytes);
     }
+    if (input.requirementLedgerBytes) {
+        sourceHashes.requirementLedgerSha256 = sha256Utf8(input.requirementLedgerBytes);
+    }
     return sourceHashes;
 }
 export function refMatchesObserved(ref, observedCanonicalHash) {