@tea-agent/loop-agent 0.31.0 → 0.32.0

package/dist/worker/run-task/run-task.js

@@ -6,7 +6,7 @@ import { getTaskPaths } from "../../task/runtime.js";
 import { formatDuration, noopProgressReporter, } from "../progress-reporter.js";
 import { redactForPreview, truncatePreview } from "../observability/events.js";
 import { controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
-import { materializeTaskSpec, } from "../materialize/harness-task-materializer.js";
+import { materializeTaskSpecV2, } from "../materialize/harness-task-materializer.js";
 import { preflightTargetRepo } from "../preflight.js";
 import { getTaskPoolRoot } from "../pool/run-store.js";
 import { checkRequiredOutputs } from "../outcomes/gate.js";
@@ -26,7 +26,12 @@ export async function runTaskSpec(options) {
     const commands = [];
     const progress = options.progress ?? noopProgressReporter;
     const taskId = options.taskSpec.id;
-    const eventCtx = { progress, workerRunId, taskId };
+    const eventCtx = {
+        progress,
+        workerRunId,
+        taskId,
+        featureId: options.taskSpec.feature_id,
+    };
     const recordingClient = new RecordingRunTaskClient(options.client, commands);
     const client = new ObservedRunTaskClient(recordingClient, eventCtx);
     if (options.preflight !== false) {
@@ -57,9 +62,9 @@ export async function runTaskSpec(options) {
     }
     const materializeStep = "materialize";
     const materializeStartedAt = Date.now();
-    const materializeManifest = await runObservedStep(eventCtx, materializeStep, async () => {
+    const materializeResult = await runObservedStep(eventCtx, materializeStep, async () => {
         progress.step("materialize harness task");
-        return materializeTaskSpec({
+        return materializeTaskSpecV2({
             repoRoot: options.repoRoot,
             taskSpec: options.taskSpec,
             taskSpecPath: options.taskSpecPath,
@@ -67,6 +72,14 @@ export async function runTaskSpec(options) {
             now,
         });
     });
+    const materializeManifest = materializeResult.manifest;
+    const materializeOutcome = materializeResult.outcome;
+    if (materializeOutcome.type === "recovery-required") {
+        throw new Error(`materialize recovery required (${materializeOutcome.recovery.recommendedAction}): ${materializeOutcome.recovery.reason}`);
+    }
+    if (materializeOutcome.type === "resume-existing") {
+        progress.note(`materialize resume-existing: revision ${materializeOutcome.revisionId}, run ${materializeOutcome.runId}`);
+    }
     progress.step(`materialized ${materializeManifest.harnessTaskId} in ${formatDuration(Date.now() - materializeStartedAt)}`);
     const taskArtifactsDir = path.join(options.repoRoot, ".harness", "tasks", materializeManifest.harnessTaskId, "artifacts");
     await mkdir(taskArtifactsDir, { recursive: true });
@@ -230,6 +243,9 @@ export async function runTaskSpec(options) {
         dagPath,
         runRecordPath,
         materializeManifest,
+        materializeOutcome,
+        lineageId: materializeManifest.lineageId,
+        revisionId: materializeManifest.revisionId,
         reportDecision,
         commands,
         ...(declaredArtifacts ? { declaredArtifacts } : {}),
@@ -317,6 +333,9 @@ export async function runTaskSpec(options) {
         dagPath,
         runRecordPath,
         materializeManifest,
+        materializeOutcome,
+        lineageId: materializeManifest.lineageId,
+        revisionId: materializeManifest.revisionId,
         reportDecision,
         commands,
         ...(declaredArtifacts ? { declaredArtifacts } : {}),
@@ -329,6 +348,7 @@ export async function runTaskSpec(options) {
         source: "artifact",
         label: "worker-run-record",
         workerRunId,
+        featureId: options.taskSpec.feature_id,
         taskId,
         artifactRefs: {
             runRecordPath,
@@ -496,6 +516,7 @@ function emitStepStarted(ctx, stepName) {
         spanId: `step:${ctx.workerRunId}:${stepName}`,
         parentSpanId: ctx.workerRunId,
         workerRunId: ctx.workerRunId,
+        featureId: ctx.featureId,
         taskId: ctx.taskId,
         status: "running",
     });
@@ -508,6 +529,7 @@ function emitStepFinished(ctx, stepName, status, durationMs) {
         spanId: `step:${ctx.workerRunId}:${stepName}`,
         parentSpanId: ctx.workerRunId,
         workerRunId: ctx.workerRunId,
+        featureId: ctx.featureId,
         taskId: ctx.taskId,
         status,
         durationMs,
@@ -760,6 +782,7 @@ class ObservedRunTaskClient {
                     source: "loop-agent-command",
                     label: options.artifactName,
                     workerRunId: this.eventCtx.workerRunId,
+                    featureId: this.eventCtx.featureId,
                     taskId: this.eventCtx.taskId,
                     pid: info.pid,
                     timeoutMs: options.timeoutMs,
@@ -783,6 +806,7 @@ class ObservedRunTaskClient {
                     source: "loop-agent-command",
                     label: options.artifactName,
                     workerRunId: this.eventCtx.workerRunId,
+                    featureId: this.eventCtx.featureId,
                     taskId: this.eventCtx.taskId,
                     message: `elapsed ${info.elapsedMs}ms`,
                 });
@@ -795,6 +819,7 @@ class ObservedRunTaskClient {
                 source: "loop-agent-command",
                 label: options.artifactName,
                 workerRunId: this.eventCtx.workerRunId,
+                featureId: this.eventCtx.featureId,
                 taskId: this.eventCtx.taskId,
                 exitCode: result.exitCode,
                 timedOut: result.timedOut,
@@ -810,6 +835,7 @@ class ObservedRunTaskClient {
                 source: "loop-agent-command",
                 label: options.artifactName,
                 workerRunId: this.eventCtx.workerRunId,
+                featureId: this.eventCtx.featureId,
                 taskId: this.eventCtx.taskId,
                 status: "failed",
                 message: errorMessage(error),
@@ -823,6 +849,7 @@ class ObservedRunTaskClient {
             source: "loop-agent-command",
             label,
             workerRunId: this.eventCtx.workerRunId,
+            featureId: this.eventCtx.featureId,
             taskId: this.eventCtx.taskId,
             outputPreview: redactForPreview(truncatePreview(chunk)),
         });

package/dist/worker/runner/run-ready.js

@@ -2,9 +2,13 @@ import { createHash } from "node:crypto";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import YAML from "yaml";
+import { controllerIdentityAnchor } from "../../shared/package-metadata.js";
 import { controllerIdentitiesMatch, controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
+import { buildPublishedControllerProtocolEnvelope } from "../loop-agent/controller-protocol.js";
 import { deriveFailureRoute, deriveFailureRouteFromError, } from "../pool/failure-routing.js";
 import { findRunByWorkerRunId, getTaskPoolRoot, readFeatureTaskPoolStates, recordTaskPoolRun, writeTaskPoolState, } from "../pool/run-store.js";
+import { releaseAttemptLease } from "../pool/attempt-lease.js";
+import { beginWorkerAttemptWithLease } from "../pool/begin-attempt-with-lease.js";
 import { readVerifiedOutcome } from "../outcomes/store.js";
 import { runTaskSpec, } from "../run-task/run-task.js";
 import { formatDuration, noopProgressReporter, } from "../progress-reporter.js";
@@ -100,6 +104,7 @@ export async function runReadyTasks(options) {
                     source: "worker",
                     label: `task ${taskId}: reuse existing run ${workerRunId}`,
                     batchRunId,
+                    featureId,
                     taskId,
                     workerRunId,
                     status: "reused",
@@ -116,32 +121,44 @@ export async function runReadyTasks(options) {
         }
         const taskStartedAt = Date.now();
         progress.task(`task ${index}/${total} ${taskId} "${taskSpec.title}" (${workerRunId})`);
-        emit(progress, {
-            type: "task.started",
-            source: "worker",
-            label: `task ${index}/${total} ${taskId}`,
-            batchRunId,
-            taskId,
-            workerRunId,
-            status: "running",
-        });
         progress.step(`materialize → task advance → report`);
         let result;
+        let leaseToken;
         try {
-            await writeTaskPoolState(options.repoRoot, {
-                schemaVersion: 2,
+            const begun = await beginWorkerAttemptWithLease({
+                repoRoot: options.repoRoot,
+                featureId,
+                taskId,
+                workerRunId,
+                batchRunId,
+                now,
+                ...(controllerIdentity
+                    ? {
+                        controllerAnchor: controllerIdentityAnchor(controllerIdentity),
+                        protocolEnvelope: buildPublishedControllerProtocolEnvelope(controllerIdentity.packageVersion),
+                    }
+                    : {}),
+                stateExtras: {
+                    ...(retryOfWorkerRunId ? { retryOfWorkerRunId } : {}),
+                },
+            });
+            leaseToken = begun.leaseRegistration.lease.token;
+            emit(progress, {
+                type: "task.started",
+                source: "worker",
+                label: `task ${index}/${total} ${taskId}`,
+                batchRunId,
                 featureId,
                 taskId,
-                status: "Running",
-                updatedAt: new Date().toISOString(),
                 workerRunId,
-                ...(retryOfWorkerRunId ? { retryOfWorkerRunId } : {}),
+                status: "running",
             });
             emit(progress, {
                 type: "state.updated",
                 source: "worker",
                 label: `task pool state: ${taskId} → Running`,
                 batchRunId,
+                featureId,
                 taskId,
                 workerRunId,
                 status: "running",
@@ -178,6 +195,7 @@ export async function runReadyTasks(options) {
                 source: "worker",
                 label: `task ${taskId} run-error`,
                 batchRunId,
+                featureId,
                 taskId,
                 workerRunId,
                 status: "failed",
@@ -215,6 +233,16 @@ export async function runReadyTasks(options) {
             }
             if (recorded)
                 await options.onTaskFinalized?.({ status: "run-error", taskSpec, workerRunId });
+            if (leaseToken) {
+                await releaseAttemptLease({
+                    repoRoot: options.repoRoot,
+                    featureId,
+                    taskId,
+                    token: leaseToken,
+                    workerRunId,
+                    now,
+                }).catch(() => { });
+            }
             tasks.push({
                 taskId,
                 workerRunId,
@@ -236,6 +264,7 @@ export async function runReadyTasks(options) {
             source: "worker",
             label: `task ${taskId} ${result.status}`,
             batchRunId,
+            featureId,
             taskId,
             workerRunId: result.workerRunId,
             status: result.status,
@@ -247,6 +276,7 @@ export async function runReadyTasks(options) {
                 source: "worker",
                 label: `failure routed: ${failure.category}`,
                 batchRunId,
+                featureId,
                 taskId,
                 workerRunId: result.workerRunId,
                 failureCategory: failure.category,
@@ -299,6 +329,16 @@ export async function runReadyTasks(options) {
                 status: result.status,
                 runRecordPath: result.runRecordPath,
             });
+            if (leaseToken) {
+                await releaseAttemptLease({
+                    repoRoot: options.repoRoot,
+                    featureId,
+                    taskId,
+                    token: leaseToken,
+                    workerRunId: result.workerRunId,
+                    now,
+                }).catch(() => { });
+            }
         }
         catch (error) {
             if (result.status !== "succeeded") {
@@ -344,6 +384,16 @@ export async function runReadyTasks(options) {
             catch {
                 // Best-effort; batch still reports record-error.
             }
+            if (leaseToken) {
+                await releaseAttemptLease({
+                    repoRoot: options.repoRoot,
+                    featureId,
+                    taskId,
+                    token: leaseToken,
+                    workerRunId: result.workerRunId,
+                    now,
+                }).catch(() => { });
+            }
             tasks.push({
                 taskId,
                 workerRunId: result.workerRunId,

package/dist/worker/runner/single-task-attempt.js

@@ -1,4 +1,8 @@
+import { controllerIdentityAnchor } from "../../shared/package-metadata.js";
+import { buildPublishedControllerProtocolEnvelope } from "../loop-agent/controller-protocol.js";
+import { releaseAttemptLease } from "../pool/attempt-lease.js";
 import { deriveFailureRoute, deriveFailureRouteFromError, } from "../pool/failure-routing.js";
+import { beginWorkerAttemptWithLease } from "../pool/begin-attempt-with-lease.js";
 import { recordTaskPoolRun, writeTaskPoolState } from "../pool/run-store.js";
 /**
  * Shared Worker attempt used by batch run-ready and Night Scheduler.
@@ -7,24 +11,33 @@ import { recordTaskPoolRun, writeTaskPoolState } from "../pool/run-store.js";
 export async function runSingleTaskAttempt(input) {
     const now = input.ctx.now ?? new Date();
     const { ctx } = input;
-    await writeTaskPoolState(ctx.controlRepoRoot, {
-        schemaVersion: 2,
+    const begun = await beginWorkerAttemptWithLease({
+        repoRoot: ctx.controlRepoRoot,
         featureId: ctx.featureId,
         taskId: ctx.taskId,
-        status: "Running",
-        updatedAt: now.toISOString(),
         workerRunId: ctx.workerRunId,
-        ...(ctx.night?.nightScheduleId
-            ? { nightScheduleId: ctx.night.nightScheduleId }
-            : {}),
-        ...(ctx.night?.admissionPath
-            ? { admissionPath: ctx.night.admissionPath }
-            : {}),
-        ...(ctx.night?.nightWorktreePath
-            ? { nightWorktreePath: ctx.night.nightWorktreePath }
+        batchRunId: ctx.batchRunId,
+        now,
+        ...(ctx.controllerIdentity
+            ? {
+                controllerAnchor: controllerIdentityAnchor(ctx.controllerIdentity),
+                protocolEnvelope: buildPublishedControllerProtocolEnvelope(ctx.controllerIdentity.packageVersion),
+            }
             : {}),
-        ...(ctx.night?.nightBranch ? { nightBranch: ctx.night.nightBranch } : {}),
+        stateExtras: {
+            ...(ctx.night?.nightScheduleId
+                ? { nightScheduleId: ctx.night.nightScheduleId }
+                : {}),
+            ...(ctx.night?.admissionPath
+                ? { admissionPath: ctx.night.admissionPath }
+                : {}),
+            ...(ctx.night?.nightWorktreePath
+                ? { nightWorktreePath: ctx.night.nightWorktreePath }
+                : {}),
+            ...(ctx.night?.nightBranch ? { nightBranch: ctx.night.nightBranch } : {}),
+        },
     });
+    const leaseToken = begun.leaseRegistration.lease.token;
     let result;
     try {
         result = await input.execute(ctx);
@@ -70,6 +83,14 @@ export async function runSingleTaskAttempt(input) {
                 : {}),
             ...(ctx.night?.nightBranch ? { nightBranch: ctx.night.nightBranch } : {}),
         });
+        await releaseAttemptLease({
+            repoRoot: ctx.controlRepoRoot,
+            featureId: ctx.featureId,
+            taskId: ctx.taskId,
+            token: leaseToken,
+            workerRunId: ctx.workerRunId,
+            now,
+        }).catch(() => { });
         return {
             status: "run-error",
             workerRunId: ctx.workerRunId,
@@ -137,6 +158,14 @@ export async function runSingleTaskAttempt(input) {
         ...(ctx.night?.nightBranch ? { nightBranch: ctx.night.nightBranch } : {}),
     };
     await writeTaskPoolState(ctx.controlRepoRoot, poolState);
+    await releaseAttemptLease({
+        repoRoot: ctx.controlRepoRoot,
+        featureId: ctx.featureId,
+        taskId: ctx.taskId,
+        token: leaseToken,
+        workerRunId: ctx.workerRunId,
+        now,
+    }).catch(() => { });
     return {
         status: result.status,
         workerRunId: result.workerRunId,

package/dist/worker/task-graph/acceptance-schema.js

@@ -21,6 +21,9 @@ export const acceptanceItemSchema = z
         implementation_task_refs: z.array(z.string().min(1)).optional(),
         verification_task_refs: z.array(z.string().min(1)).optional(),
         required_evidence: z.array(z.string().min(1)).optional(),
+        /** Phase 6: ADR 0007 authority / evidence kinds on required ACs. */
+        authority: z.string().min(1).optional(),
+        required_evidence_kinds: z.array(z.string().min(1)).optional(),
         integration: z
             .enum(["not-applicable", "mock-allowed", "real-required"])
             .optional(),

package/dist/workflows/dag/backend-test-pytest-collection.js

@@ -11,12 +11,16 @@ export const backendPytestCollectionFindingSchema = z.object({
     detail: z.string().min(1),
 }).strict();
 export const backendPytestCollectionFactsSchema = z.object({
-    schemaId: z.literal("backend-test-pytest-collection-v2"),
+    schemaId: z.literal("backend-test-pytest-collection-v3"),
     phase: z.enum(["initial", "final", "effective"]),
     status: z.enum(["PASS", "REPAIRABLE", "BLOCKED"]),
     repairEligible: z.boolean(),
     repairAttempt: z.number().int().min(0).max(1),
     collectionAttempted: z.boolean(),
+    fixtureResolutionAttempted: z.boolean(),
+    fixtureResolutionStatus: z.enum(["NOT_RUN", "PASS", "REPAIRABLE", "BLOCKED"]),
+    fixtureResolutionExitCode: z.number().int().nullable(),
+    repairPaths: z.array(z.string()),
     mappedScripts: z.array(z.string()).min(1),
     existingMappedScripts: z.array(z.string()),
     missingMappedScripts: z.array(z.string()),
@@ -28,17 +32,37 @@ export const backendPytestCollectionFactsSchema = z.object({
     findings: z.array(backendPytestCollectionFindingSchema),
     stdoutExcerpt: z.string(),
     stderrExcerpt: z.string(),
+    fixtureStdoutExcerpt: z.string(),
+    fixtureStderrExcerpt: z.string(),
     collectionSource: z.enum(["initial", "final"]).optional(),
 }).strict().superRefine((facts, context) => {
     if (facts.status === "PASS") {
-        if (!facts.collectionAttempted || facts.pytestExitCode !== 0 || facts.missingMappedScripts.length > 0 || facts.assetFiles.length === 0) {
-            context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest collection PASS requires attempted collection, exit 0, complete mapped scripts and bound assets" });
+        if (!facts.collectionAttempted || facts.pytestExitCode !== 0 || !facts.fixtureResolutionAttempted || facts.fixtureResolutionStatus !== "PASS" || facts.fixtureResolutionExitCode !== 0 || facts.missingMappedScripts.length > 0 || facts.assetFiles.length === 0) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest collection PASS requires collection and fixture-resolution PASS, complete mapped scripts and bound assets" });
         }
     }
     if (!facts.collectionAttempted && facts.pytestExitCode !== null) {
         context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest collection without an attempt cannot have an exit code" });
     }
+    if (!facts.fixtureResolutionAttempted && facts.fixtureResolutionExitCode !== null) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest fixture resolution without an attempt cannot have an exit code" });
+    }
 });
+export const backendTestExecutionReadinessSchema = z.object({
+    schemaId: z.literal("backend-test-execution-readiness-v1"),
+    status: z.enum(["PASS", "PARTIAL", "BLOCKED"]),
+    collectionStatus: z.literal("PASS"),
+    fixtureResolutionStatus: z.literal("PASS"),
+    scenarioParamStatus: z.enum(["PASS", "PARTIAL", "FAIL", "UNAVAILABLE"]),
+    repairAttempts: z.object({
+        collection: z.number().int().min(0).max(1),
+        scenarioParam: z.number().int().min(0).max(1),
+    }).strict(),
+    mappedScripts: z.array(z.string()).min(1),
+    collectedItemIds: z.array(z.string()),
+    fixtureIssues: z.array(z.string()),
+    assetHashes: z.record(z.string(), z.string().regex(SHA256)),
+}).strict();
 function repoRef(workspaceRoot, absolutePath) {
     return path.relative(workspaceRoot, absolutePath).replaceAll(path.sep, "/");
 }
@@ -106,6 +130,28 @@ function collectionItems(stdout) {
             return /^testcase\//.test(line.replaceAll("\\", "/"));
         }).map((line) => line.replaceAll("\\", "/")))];
 }
+function testcasePythonPaths(output) {
+    return [...new Set((output.replaceAll("\\", "/").match(/testcase\/[A-Za-z0-9_./-]+\.py/gi) ?? []).map((item) => item.replace(/:\d+$/, "")))].sort();
+}
+function classifyFixtureResolutionFailure(output) {
+    const normalized = output.replaceAll("\\", "/");
+    const paths = testcasePythonPaths(normalized);
+    const generatedProviderPaths = paths.filter((item) => /testcase\/(?:helpers|factories)\//.test(item));
+    if (/fixture ['"][^'"]+['"] not found/i.test(normalized) && generatedProviderPaths.length > 0) {
+        return {
+            status: "REPAIRABLE",
+            kind: "missing-generated-fixture",
+            detail: "generated pytest fixture dependency or plugin registration is incomplete",
+            repairPaths: generatedProviderPaths,
+        };
+    }
+    return {
+        status: "BLOCKED",
+        kind: "unresolved-fixture-dependency",
+        detail: "fixture resolution failed without a safely attributable generated provider",
+        repairPaths: paths,
+    };
+}
 function classifyCollectionFailure(output) {
     const normalized = output.replaceAll("\\", "/");
     const blockedPatterns = [
@@ -134,14 +180,19 @@ function classifyCollectionFailure(output) {
 }
 export function assessBackendPytestCollection(input) {
     const items = collectionItems(input.stdout);
-    if (input.exitCode === 0) {
+    const fixtureResolution = input.fixtureResolution ?? { exitCode: 0, stdout: "fixture resolution assumed by direct assessor", stderr: "" };
+    if (input.exitCode === 0 && fixtureResolution.exitCode === 0) {
         return backendPytestCollectionFactsSchema.parse({
-            schemaId: "backend-test-pytest-collection-v2",
+            schemaId: "backend-test-pytest-collection-v3",
             phase: input.phase,
             status: "PASS",
             repairEligible: false,
             repairAttempt: input.phase === "final" ? 1 : 0,
             collectionAttempted: true,
+            fixtureResolutionAttempted: true,
+            fixtureResolutionStatus: "PASS",
+            fixtureResolutionExitCode: 0,
+            repairPaths: [],
             mappedScripts: input.inventory.mappedScripts,
             existingMappedScripts: input.inventory.mappedScripts,
             missingMappedScripts: [],
@@ -153,16 +204,55 @@ export function assessBackendPytestCollection(input) {
             findings: [],
             stdoutExcerpt: bounded(input.stdout),
             stderrExcerpt: bounded(input.stderr),
+            fixtureStdoutExcerpt: bounded(fixtureResolution.stdout),
+            fixtureStderrExcerpt: bounded(fixtureResolution.stderr),
+        });
+    }
+    if (input.exitCode === 0) {
+        const classification = classifyFixtureResolutionFailure(`${fixtureResolution.stdout}\n${fixtureResolution.stderr}`);
+        return backendPytestCollectionFactsSchema.parse({
+            schemaId: "backend-test-pytest-collection-v3",
+            phase: input.phase,
+            status: classification.status,
+            repairEligible: input.phase === "initial" && classification.status === "REPAIRABLE",
+            repairAttempt: input.phase === "final" ? 1 : 0,
+            collectionAttempted: true,
+            fixtureResolutionAttempted: true,
+            fixtureResolutionStatus: classification.status,
+            fixtureResolutionExitCode: fixtureResolution.exitCode,
+            repairPaths: classification.repairPaths,
+            mappedScripts: input.inventory.mappedScripts,
+            existingMappedScripts: input.inventory.mappedScripts,
+            missingMappedScripts: [],
+            assetFiles: input.inventory.assetFiles,
+            inputHashes: input.inventory.inputHashes,
+            pytestExitCode: input.exitCode,
+            collectedItemCount: items.length,
+            collectedItemIds: items,
+            findings: [{
+                    kind: classification.kind,
+                    classification: "test-asset-defect",
+                    repairability: classification.status === "REPAIRABLE" ? "repairable" : "blocked",
+                    detail: classification.detail,
+                }],
+            stdoutExcerpt: bounded(input.stdout),
+            stderrExcerpt: bounded(input.stderr),
+            fixtureStdoutExcerpt: bounded(fixtureResolution.stdout),
+            fixtureStderrExcerpt: bounded(fixtureResolution.stderr),
         });
     }
     const classification = classifyCollectionFailure(`${input.stdout}\n${input.stderr}`);
     return backendPytestCollectionFactsSchema.parse({
-        schemaId: "backend-test-pytest-collection-v2",
+        schemaId: "backend-test-pytest-collection-v3",
         phase: input.phase,
         status: classification.status,
         repairEligible: input.phase === "initial" && classification.status === "REPAIRABLE",
         repairAttempt: input.phase === "final" ? 1 : 0,
         collectionAttempted: true,
+        fixtureResolutionAttempted: false,
+        fixtureResolutionStatus: "NOT_RUN",
+        fixtureResolutionExitCode: null,
+        repairPaths: testcasePythonPaths(`${input.stdout}\n${input.stderr}`),
         mappedScripts: input.inventory.mappedScripts,
         existingMappedScripts: input.inventory.mappedScripts,
         missingMappedScripts: [],
@@ -179,16 +269,22 @@ export function assessBackendPytestCollection(input) {
             }],
         stdoutExcerpt: bounded(input.stdout),
         stderrExcerpt: bounded(input.stderr),
+        fixtureStdoutExcerpt: "",
+        fixtureStderrExcerpt: "",
     });
 }
 export function assessMissingBackendPytestScripts(input) {
     return backendPytestCollectionFactsSchema.parse({
-        schemaId: "backend-test-pytest-collection-v2",
+        schemaId: "backend-test-pytest-collection-v3",
         phase: "initial",
         status: "REPAIRABLE",
         repairEligible: true,
         repairAttempt: 0,
         collectionAttempted: false,
+        fixtureResolutionAttempted: false,
+        fixtureResolutionStatus: "NOT_RUN",
+        fixtureResolutionExitCode: null,
+        repairPaths: [...input.missingMappedScripts],
         mappedScripts: [...input.mappedScripts],
         existingMappedScripts: [...input.existingMappedScripts],
         missingMappedScripts: [...input.missingMappedScripts],
@@ -205,6 +301,8 @@ export function assessMissingBackendPytestScripts(input) {
         })),
         stdoutExcerpt: "",
         stderrExcerpt: "",
+        fixtureStdoutExcerpt: "",
+        fixtureStderrExcerpt: "",
     });
 }
 export function renderBackendPytestCollectionReport(facts) {
@@ -219,6 +317,10 @@ export function renderBackendPytestCollectionReport(facts) {
         `- Repair attempt: ${facts.repairAttempt}`,
         `- Collection attempted: ${facts.collectionAttempted}`,
         `- Pytest exit code: ${facts.pytestExitCode ?? "not-run"}`,
+        `- Fixture resolution attempted: ${facts.fixtureResolutionAttempted}`,
+        `- Fixture resolution status: ${facts.fixtureResolutionStatus}`,
+        `- Fixture resolution exit code: ${facts.fixtureResolutionExitCode ?? "not-run"}`,
+        `- Repair paths: ${facts.repairPaths.join(", ") || "none"}`,
         `- Mapped scripts: ${facts.mappedScripts.length}`,
         `- Existing mapped scripts: ${facts.existingMappedScripts.length}`,
         `- Missing mapped scripts: ${facts.missingMappedScripts.length}`,
@@ -245,6 +347,18 @@ export function renderBackendPytestCollectionReport(facts) {
         facts.stderrExcerpt,
         "```",
         "",
+        "## Fixture Resolution stdout",
+        "",
+        "```text",
+        facts.fixtureStdoutExcerpt,
+        "```",
+        "",
+        "## Fixture Resolution stderr",
+        "",
+        "```text",
+        facts.fixtureStderrExcerpt,
+        "```",
+        "",
     ].join("\n");
 }
 export async function writeBackendPytestCollectionArtifacts(input) {
@@ -289,6 +403,47 @@ function assertSameInventory(expected, actual) {
             throw new Error(`backend pytest collection hash drift: ${file}`);
     }
 }
+export async function materializeBackendTestExecutionReadiness(input) {
+    if (input.effective.phase !== "effective" || input.effective.status !== "PASS" || input.effective.fixtureResolutionStatus !== "PASS") {
+        throw new Error("backend-test execution readiness requires effective collection and fixture-resolution PASS");
+    }
+    const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.effective.mappedScripts);
+    assertSameInventory(input.effective, current);
+    const status = input.scenarioParamStatus === "FAIL"
+        ? "BLOCKED"
+        : input.scenarioParamStatus === "PASS"
+            ? "PASS"
+            : "PARTIAL";
+    const readiness = backendTestExecutionReadinessSchema.parse({
+        schemaId: "backend-test-execution-readiness-v1",
+        status,
+        collectionStatus: "PASS",
+        fixtureResolutionStatus: "PASS",
+        scenarioParamStatus: input.scenarioParamStatus,
+        repairAttempts: {
+            collection: input.effective.repairAttempt,
+            scenarioParam: input.scenarioParamRepairAttempt,
+        },
+        mappedScripts: input.effective.mappedScripts,
+        collectedItemIds: input.effective.collectedItemIds,
+        fixtureIssues: input.effective.findings.filter((item) => /fixture/i.test(item.kind)).map((item) => item.detail),
+        assetHashes: input.effective.inputHashes,
+    });
+    const contractsDir = path.join(input.runDir, "contracts");
+    await mkdir(contractsDir, { recursive: true });
+    await writeFile(path.join(contractsDir, "backend-test-execution-readiness.json"), `${JSON.stringify(readiness, null, 2)}\n`, "utf8");
+    return readiness;
+}
+export async function readBackendTestExecutionReadiness(filePath) {
+    return backendTestExecutionReadinessSchema.parse(JSON.parse(await readFile(filePath, "utf8")));
+}
+export async function assertBackendTestExecutionReadinessFresh(workspaceRoot, readiness) {
+    if (!["PASS", "PARTIAL"].includes(readiness.status)) {
+        throw new Error(`backend pytest execution readiness is ${readiness.status}`);
+    }
+    const current = await buildBackendPytestAssetInventory(workspaceRoot, readiness.mappedScripts);
+    assertSameInventory({ mappedScripts: readiness.mappedScripts, assetFiles: Object.keys(readiness.assetHashes), inputHashes: readiness.assetHashes }, current);
+}
 export async function assertBackendPytestCollectionFresh(workspaceRoot, effective) {
     if (effective.phase !== "effective" || effective.status !== "PASS") {
         throw new Error("backend pytest execution requires effective collection PASS facts");