@tea-agent/loop-agent 0.26.5-beta.2 → 0.27.1-beta.0

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

@@ -3,7 +3,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { getTaskPaths } from "../../task/runtime.js";
-import { formatDuration, noopProgressReporter } from "../progress-reporter.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";
@@ -33,12 +33,19 @@ export async function runTaskSpec(options) {
         const preflightStep = "preflight";
         const preflightStartedAt = Date.now();
         await runObservedStep(eventCtx, preflightStep, async () => {
-            progress.step("preflight: version + inspect + docs-audit + git-status" + (options.preflight && typeof options.preflight === "object" && options.preflight.runCheckRepo ? " + check-repo" : ""));
+            progress.step("preflight: version + inspect + docs-audit + git-status" +
+                (options.preflight &&
+                    typeof options.preflight === "object" &&
+                    options.preflight.runCheckRepo
+                    ? " + check-repo"
+                    : ""));
             const preflight = await preflightTargetRepo({
                 repoRoot: options.repoRoot,
                 client,
                 ...(typeof options.preflight === "object" ? options.preflight : {}),
-                ...(options.controllerExpectation ? { expectation: options.controllerExpectation } : {}),
+                ...(options.controllerExpectation
+                    ? { expectation: options.controllerExpectation }
+                    : {}),
             });
             if (!preflight.ok) {
                 progress.note(`preflight FAILED: ${preflight.code}`);
@@ -65,81 +72,95 @@ export async function runTaskSpec(options) {
     await mkdir(taskArtifactsDir, { recursive: true });
     const dagPath = path.join(taskArtifactsDir, `${workerRunId}-dag.json`);
     const runRecordPath = path.join(taskArtifactsDir, "worker-run-record.json");
-    const dagGenStep = "dag-run-task";
-    const dagGenStartedAt = Date.now();
-    await runObservedStep(eventCtx, dagGenStep, async () => {
-        progress.step("dag run-task: generate DAG");
-        await runRequiredCommand(options.repoRoot, client, "dag-run-task", [
-            "dag",
-            "run-task",
+    const canonicalDraftPath = getTaskPaths(options.repoRoot, materializeManifest.harnessTaskId).dagDraftPath;
+    // Standard lifecycle: task advance to writeSet gate (generate + strict validate).
+    const prepareStep = "task-advance-prepare";
+    const prepareStartedAt = Date.now();
+    let gateToken = await runObservedStep(eventCtx, prepareStep, async () => {
+        progress.step("task advance: generate/validate DAG and open writeSet gate");
+        const result = await runRequiredCommand(options.repoRoot, client, "task-advance-prepare", [
+            "task",
+            "advance",
             materializeManifest.harnessTaskId,
             "--profile",
             materializeManifest.loopAgentProfile,
-            "--strict-models",
-            "--output",
+            "--dag-output",
             dagPath,
-            "--cwd",
-            options.repoRoot,
+            "--json",
         ], true, undefined, eventCtx);
+        return extractWriteSetGateToken(result, materializeManifest.harnessTaskId);
     });
-    progress.step(`dag generated in ${formatDuration(Date.now() - dagGenStartedAt)}`);
+    progress.step(`task advance prepare finished in ${formatDuration(Date.now() - prepareStartedAt)}`);
     if (options.piModel) {
         const piModelStep = "pi-model-override";
         await runObservedStep(eventCtx, piModelStep, async () => {
             progress.step(`pi-model override: rewriting executorModels.pi → ${options.piModel}`);
+            // Rewrite both per-run copy and canonical draft so re-validate sees override.
+            await applyPiModelOverride(canonicalDraftPath, options.piModel);
             await applyPiModelOverride(dagPath, options.piModel);
         });
-    }
-    const validateStep = "dag-validate";
-    const validateStartedAt = Date.now();
-    await runObservedStep(eventCtx, validateStep, async () => {
-        progress.step("dag validate");
-        await runRequiredCommand(options.repoRoot, client, "dag-validate", [
-            "dag",
-            "validate",
-            "--dag",
-            dagPath,
-            ...strictModelsArgs(options.piModel),
-            "--strict-governance",
-            "--spine-task",
-            materializeManifest.harnessTaskId,
-        ], true, undefined, eventCtx);
-    });
-    progress.step(`dag validated in ${formatDuration(Date.now() - validateStartedAt)}`);
-    const canonicalDraftPath = getTaskPaths(options.repoRoot, materializeManifest.harnessTaskId).dagDraftPath;
-    await runObservedStep(eventCtx, "publish-canonical-dag-draft", async () => {
-        const dagBytes = await readFile(dagPath, "utf-8");
-        await writeTextAtomic(canonicalDraftPath, dagBytes, {
-            repoRoot: options.repoRoot,
+        // Re-open gate after draft rewrite (digest bound to DAG hash).
+        gateToken = await runObservedStep(eventCtx, "task-advance-revalidate", async () => {
+            progress.step("task advance: re-validate after piModel override (no strict-models)");
+            const result = await runRequiredCommand(options.repoRoot, client, "task-advance-revalidate", [
+                "task",
+                "advance",
+                materializeManifest.harnessTaskId,
+                "--profile",
+                materializeManifest.loopAgentProfile,
+                "--no-strict-models",
+                "--dag-output",
+                dagPath,
+                "--json",
+            ], true, undefined, eventCtx);
+            return extractWriteSetGateToken(result, materializeManifest.harnessTaskId);
         });
-    });
-    const runDagStep = "run-dag";
-    const runDagStartedAt = Date.now();
+    }
+    const runAdvanceStep = "task-advance-execute";
+    const runAdvanceStartedAt = Date.now();
     const dagEventsPath = path.join(getTaskPoolRoot(options.repoRoot), "observability", "runs", workerRunId, "dag-events.jsonl");
     await mkdir(path.dirname(dagEventsPath), { recursive: true }).catch(() => { });
-    await runObservedStep(eventCtx, runDagStep, async () => {
-        progress.step("run-dag: executing DAG nodes (this is the long step)");
-        await runDagWithEventsFallback(options.repoRoot, client, [
-            "run-dag",
-            "--dag",
-            dagPath,
-            "--cwd",
-            options.repoRoot,
-            "--run-id",
+    const workerAssociation = JSON.stringify({
+        schemaVersion: 1,
+        workerRunId,
+        featureId: options.taskSpec.feature_id,
+        taskId: options.taskSpec.id,
+    });
+    await runObservedStep(eventCtx, runAdvanceStep, async () => {
+        progress.step("task advance: approve writeSet gate and execute DAG (long step)");
+        const advanceResult = await runTaskAdvanceExecuteWithEventsFallback({
+            repoRoot: options.repoRoot,
+            client,
+            taskId: materializeManifest.harnessTaskId,
+            gateToken,
             workerRunId,
-            "--worker-association",
-            JSON.stringify({
-                schemaVersion: 1,
-                workerRunId,
-                featureId: options.taskSpec.feature_id,
-                taskId: options.taskSpec.id,
-            }),
-            "--events-jsonl",
+            workerAssociation,
             dagEventsPath,
-            ...maxConcurrentArgs(options.taskSpec),
-        ], resolveRunDagTimeoutMs(options.taskSpec), eventCtx);
+            maxConcurrent: options.taskSpec.loop_agent.max_concurrent,
+            timeoutMs: resolveRunDagTimeoutMs(options.taskSpec),
+            eventCtx,
+        });
+        // Terminal DAG failure is still a completed execute step for Worker: report
+        // decision + failure artifacts remain authoritative downstream.
+        if (!advanceResult.ok && !isTerminalTaskAdvanceFailure(advanceResult)) {
+            assertAdvanceExecuteOk(advanceResult, [
+                "task",
+                "advance",
+                materializeManifest.harnessTaskId,
+                "--approve-gate",
+                gateToken,
+            ]);
+        }
+        return advanceResult;
+    });
+    progress.step(`task advance execute finished in ${formatDuration(Date.now() - runAdvanceStartedAt)}`);
+    // Keep per-run DAG artifact aligned with canonical draft after execution prep.
+    await runObservedStep(eventCtx, "publish-per-run-dag-copy", async () => {
+        const dagBytes = await readFile(canonicalDraftPath, "utf-8");
+        await writeTextAtomic(dagPath, dagBytes, {
+            repoRoot: options.repoRoot,
+        });
     });
-    progress.step(`run-dag finished in ${formatDuration(Date.now() - runDagStartedAt)}`);
     const reportStep = "report-decision";
     let capturedReportJson;
     const reportDecision = await runObservedStep(eventCtx, reportStep, async () => {
@@ -171,7 +192,9 @@ export async function runTaskSpec(options) {
             artifactName: "dag-report-markdown",
         });
         return decision;
-    }, { statusForResult: (decision) => decision.succeeded ? "succeeded" : "failed" });
+    }, {
+        statusForResult: (decision) => decision.succeeded ? "succeeded" : "failed",
+    });
     const dagReportRun = extractDagReportRun(workerRunId, capturedReportJson);
     const declaredArtifacts = options.declaredArtifacts
         ? options.declaredArtifacts.map((entry) => ({
@@ -180,7 +203,9 @@ export async function runTaskSpec(options) {
             ...(entry.path ? { path: entry.path } : {}),
         }))
         : undefined;
-    let status = reportDecision.succeeded ? "succeeded" : "failed";
+    let status = reportDecision.succeeded
+        ? "succeeded"
+        : "failed";
     progress.step(`report decision: ${status} (${reportDecision.reason}${reportDecision.runStatus ? `, status=${reportDecision.runStatus}` : ""})`);
     const failureArtifacts = reportDecision.succeeded
         ? undefined
@@ -237,7 +262,10 @@ export async function runTaskSpec(options) {
     });
     if (!projection.ok) {
         status = "failed";
-        outcomeFailure = { category: projection.category, reason: projection.reason };
+        outcomeFailure = {
+            category: projection.category,
+            reason: projection.reason,
+        };
         progress.step(`outcome projection failed: ${projection.category} (${projection.reason})`);
     }
     else {
@@ -271,13 +299,10 @@ export async function runTaskSpec(options) {
         outcome = await writeOutcome(options.repoRoot, envelope);
     }
     if (status === "succeeded" && !options.skipSuccessFinalization) {
-        await runObservedStep(eventCtx, "promote-run", async () => {
-            progress.step("promote run");
-            await runRequiredCommand(options.repoRoot, client, "promote-run", ["promote-run", materializeManifest.harnessTaskId, "--run-id", workerRunId], true, undefined, eventCtx);
-        });
-        await runObservedStep(eventCtx, "closeout-task", async () => {
-            progress.step("closeout task");
-            await runRequiredCommand(options.repoRoot, client, "closeout-task", ["closeout", "task", materializeManifest.harnessTaskId], true, undefined, eventCtx);
+        await runObservedStep(eventCtx, "task-advance-closeout", async () => {
+            progress.step("task advance: promote + closeout");
+            // Lifecycle closeout path; advance is idempotent when run already associated.
+            await runRequiredCommand(options.repoRoot, client, "task-advance-closeout", ["task", "advance", materializeManifest.harnessTaskId, "--json"], true, undefined, eventCtx);
         });
     }
     const record = {
@@ -351,47 +376,111 @@ async function runRequiredCommand(repoRoot, client, artifactName, args, expectJs
     }
     return result;
 }
+function extractWriteSetGateToken(result, taskId) {
+    const root = result.json;
+    if (!root || typeof root !== "object") {
+        throw new Error(`task advance prepare did not return JSON for ${taskId}; cannot approve writeSet gate`);
+    }
+    const envelope = root;
+    const payload = envelope.result && typeof envelope.result === "object"
+        ? envelope.result
+        : envelope;
+    const gate = payload.gate && typeof payload.gate === "object"
+        ? payload.gate
+        : undefined;
+    const id = typeof gate?.id === "string" ? gate.id : undefined;
+    const digest = typeof gate?.digest === "string" ? gate.digest : undefined;
+    if (!id || !digest) {
+        const lifecycleState = typeof payload.lifecycleState === "string"
+            ? payload.lifecycleState
+            : "unknown";
+        throw new Error(`task advance prepare for ${taskId} did not open a writeSet gate (lifecycleState=${lifecycleState})`);
+    }
+    return `${id}:${digest}`;
+}
 /**
- * `--events-jsonl` is additive observability. Older published controllers do
- * not know the flag; their parser rejects before any DAG node can execute, so
- * retrying the exact command without it is safe and preserves the same run id.
+ * `--events-jsonl` is additive observability. Older published controllers may
+ * reject the flag; retry without it, keeping the same run id / gate digest.
  */
-function assertRunDagCommandOk(result, args) {
-    if (!result.ok) {
+function assertAdvanceExecuteOk(result, args) {
+    if (!result.ok && !isTerminalTaskAdvanceFailure(result)) {
         throw new Error(`loop-agent command failed: ${args.join(" ")}`);
     }
 }
-async function runDagWithEventsFallback(repoRoot, client, args, timeoutMs, eventCtx) {
-    const result = await client.run(args, {
-        cwd: repoRoot,
-        artifactName: "run-dag",
+function readTaskAdvancePayload(result) {
+    const root = result.json;
+    if (!root || typeof root !== "object")
+        return null;
+    const envelope = root;
+    if (envelope.result && typeof envelope.result === "object") {
+        return envelope.result;
+    }
+    return envelope;
+}
+/**
+ * Terminal DAG failure from `task advance --approve-gate` is an expected
+ * worker path: CLI may return non-zero / outcome=blocked while still writing
+ * a completed run that `dag report` can diagnose.
+ */
+function isTerminalTaskAdvanceFailure(result) {
+    const payload = readTaskAdvancePayload(result);
+    if (!payload)
+        return false;
+    const lifecycleState = typeof payload.lifecycleState === "string" ? payload.lifecycleState : "";
+    if (lifecycleState === "run-failed" ||
+        lifecycleState === "needs-attention" ||
+        lifecycleState === "awaiting-decision") {
+        return true;
+    }
+    const run = payload.run && typeof payload.run === "object"
+        ? payload.run
+        : null;
+    const runStatus = typeof run?.status === "string" ? run.status : "";
+    const runLifecycle = typeof run?.lifecycle === "string" ? run.lifecycle : "";
+    return (runStatus === "failed" ||
+        runStatus === "partial_failed" ||
+        (runLifecycle === "completed" && runStatus !== "finished"));
+}
+async function runTaskAdvanceExecuteWithEventsFallback(input) {
+    const baseArgs = [
+        "task",
+        "advance",
+        input.taskId,
+        "--approve-gate",
+        input.gateToken,
+        "--run-id",
+        input.workerRunId,
+        "--worker-association",
+        input.workerAssociation,
+        "--max-concurrent",
+        String(input.maxConcurrent),
+        "--skip-finalize",
+        "--json",
+    ];
+    const withEvents = [...baseArgs, "--events-jsonl", input.dagEventsPath];
+    const result = await input.client.run(withEvents, {
+        cwd: input.repoRoot,
+        artifactName: "task-advance-execute",
         expectJson: true,
-        timeoutMs,
+        timeoutMs: input.timeoutMs,
     });
-    if (result.ok)
+    if (result.ok || isTerminalTaskAdvanceFailure(result))
         return result;
-    if (!rejectsEventsJsonl(result) || !args.includes("--events-jsonl")) {
-        assertRunDagCommandOk(result, args);
+    if (!rejectsEventsJsonl(result)) {
+        assertAdvanceExecuteOk(result, withEvents);
     }
-    const fallbackArgs = withoutFlagAndValue(args, "--events-jsonl");
-    eventCtx.progress.note("run-dag controller does not support --events-jsonl; retrying without DAG event stream");
-    const fallback = await client.run(fallbackArgs, {
-        cwd: repoRoot,
-        artifactName: "run-dag-events-fallback",
+    input.eventCtx.progress.note("task advance controller does not support --events-jsonl; retrying without DAG event stream");
+    const fallback = await input.client.run(baseArgs, {
+        cwd: input.repoRoot,
+        artifactName: "task-advance-execute-events-fallback",
         expectJson: true,
-        timeoutMs,
+        timeoutMs: input.timeoutMs,
     });
-    assertRunDagCommandOk(fallback, fallbackArgs);
+    assertAdvanceExecuteOk(fallback, baseArgs);
     return fallback;
 }
 function rejectsEventsJsonl(result) {
-    return /unknown run-dag flag:\s*--events-jsonl/i.test(`${result.stderr}\n${result.stdout}`);
-}
-function withoutFlagAndValue(args, flag) {
-    const index = args.indexOf(flag);
-    if (index < 0)
-        return args;
-    return [...args.slice(0, index), ...args.slice(index + 2)];
+    return /unknown (?:run-dag|dag execute|task advance) flag:\s*--events-jsonl|unknown flag --events-jsonl/i.test(`${result.stderr}\n${result.stdout}`);
 }
 function emit(progress, input) {
     const structured = progress;
@@ -479,7 +568,10 @@ async function collectFailureArtifacts(input) {
 }
 function isPathInside(root, target) {
     const relative = path.relative(root, target);
-    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    return (relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
 }
 /** Exported for unit tests: map DAG report JSON into Worker report decision. */
 export function decideFromReport(workerRunId, result) {
@@ -553,7 +645,9 @@ function extractDagReportRun(workerRunId, result) {
         ...(readString(node, "nodeId") || readString(node, "id")
             ? { id: readString(node, "nodeId") ?? readString(node, "id") }
             : {}),
-        ...(readString(node, "status") ? { status: readString(node, "status") } : {}),
+        ...(readString(node, "status")
+            ? { status: readString(node, "status") }
+            : {}),
         ...(readString(node, "failureCategory")
             ? { failureCategory: readString(node, "failureCategory") }
             : {}),
@@ -567,10 +661,14 @@ function extractDagReportRun(workerRunId, result) {
             ? { structuredArtifactPath: readString(node, "structuredArtifactPath") }
             : {}),
         ...(readString(node, "structuredArtifactSha256")
-            ? { structuredArtifactSha256: readString(node, "structuredArtifactSha256") }
+            ? {
+                structuredArtifactSha256: readString(node, "structuredArtifactSha256"),
+            }
             : {}),
         ...(readString(node, "structuredArtifactSchemaId")
-            ? { structuredArtifactSchemaId: readString(node, "structuredArtifactSchemaId") }
+            ? {
+                structuredArtifactSchemaId: readString(node, "structuredArtifactSchemaId"),
+            }
             : {}),
     }));
     return {
@@ -733,19 +831,13 @@ class ObservedRunTaskClient {
 function commandRecordName(args, artifactName) {
     if (args[0] === "new-task")
         return "new-task";
+    if (args[0] === "task" && args[1] === "advance") {
+        return artifactName.startsWith("task-advance-")
+            ? artifactName
+            : "task-advance";
+    }
     return artifactName;
 }
-function maxConcurrentArgs(taskSpec) {
-    return ["--max-concurrent", String(taskSpec.loop_agent.max_concurrent)];
-}
-/**
- * When a smoke `piModel` override is active, drop `--strict-models` so the
- * non-canonical `executorModels.pi` rewrite passes `dag validate`. Governance,
- * forbidden-executor and spine audits are still enforced by their own flags.
- */
-function strictModelsArgs(piModel) {
-    return piModel ? [] : ["--strict-models"];
-}
 /**
  * Rewrite `executorModels.pi.{LOW,MED,HIGH}` in an already-generated DAG JSON
  * so every pi executor node resolves to the smoke override model.

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

@@ -125,7 +125,7 @@ export async function runReadyTasks(options) {
             workerRunId,
             status: "running",
         });
-        progress.step(`materialize → dag-run-task → validate → run-dag → report`);
+        progress.step(`materialize → task advance → report`);
         let result;
         try {
             await writeTaskPoolState(options.repoRoot, {

package/dist/workflows/dag/backend-test-markdown-workflow.js

@@ -43,6 +43,17 @@ async function exists(filePath) {
         return false;
     }
 }
+async function mappedScriptExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
 async function existingPaths(root, candidates) {
     const found = [];
     for (const candidate of candidates) {
@@ -685,9 +696,24 @@ export async function validateBackendMarkdownTraceability(workspaceRoot) {
         ...(findings.length > 0 ? findings.map((finding) => `- ${finding}`) : ["- None"]),
     ].join("\n") + "\n");
 }
-export async function collectBackendTestMappedPytestScripts(workspaceRoot) {
+export async function resolveBackendTestMappedPytestScripts(workspaceRoot) {
     const files = await markdownFiles(workspaceRoot);
-    const scripts = new Set();
+    const expectedScripts = new Set();
+    const existingScripts = new Set();
+    const missingScripts = new Set();
+    const scriptOwners = new Map();
+    const recordScript = (script, owner, present) => {
+        const previousOwner = scriptOwners.get(script);
+        if (previousOwner && previousOwner !== owner) {
+            throw new Error(`conflicting Markdown pytest mapping: ${previousOwner} and ${owner} both map ${script}`);
+        }
+        scriptOwners.set(script, owner);
+        expectedScripts.add(script);
+        if (present)
+            existingScripts.add(script);
+        else
+            missingScripts.add(script);
+    };
     for (const file of files) {
         if (path.basename(file).toLowerCase() === "readme.md")
             continue;
@@ -703,10 +729,11 @@ export async function collectBackendTestMappedPytestScripts(workspaceRoot) {
         // Prefer explicit mappings, but recover to the deterministic module stem path
         // when the model wrote the correct one-to-one file while Markdown still names
         // a drifted script (common: health.md maps test_health.py but writer emitted
-        // test_be_health.py for BE-HEALTH.md, or the reverse).
+        // test_be_health.py for BE-HEALTH.md, or the reverse). If neither exists, the
+        // deterministic module path is the only path a bounded repair may create.
         if (mappedFromModule.size === 0) {
-            if (await exists(path.resolve(workspaceRoot, expectedScript))) {
-                scripts.add(expectedScript);
+            if (await mappedScriptExists(path.resolve(workspaceRoot, expectedScript))) {
+                recordScript(expectedScript, relativeFile, true);
             }
             continue;
         }
@@ -714,32 +741,31 @@ export async function collectBackendTestMappedPytestScripts(workspaceRoot) {
             if (!isSafeBackendPytestScript(script, workspaceRoot)) {
                 throw new Error(`unsafe mapped pytest script: ${script}`);
             }
-            if (await exists(path.resolve(workspaceRoot, script))) {
-                scripts.add(script);
+            if (await mappedScriptExists(path.resolve(workspaceRoot, script))) {
+                recordScript(script, relativeFile, true);
                 continue;
             }
-            if (isSafeBackendPytestScript(expectedScript, workspaceRoot) &&
-                (await exists(path.resolve(workspaceRoot, expectedScript)))) {
-                scripts.add(expectedScript);
-                continue;
+            if (!isSafeBackendPytestScript(expectedScript, workspaceRoot)) {
+                throw new Error(`unsafe mapped pytest script: ${expectedScript}`);
             }
-            throw new Error(`mapped pytest script is missing: ${script} (module one-to-one path ${expectedScript} also missing)`);
+            recordScript(expectedScript, relativeFile, await mappedScriptExists(path.resolve(workspaceRoot, expectedScript)));
         }
     }
-    if (scripts.size === 0) {
+    if (expectedScripts.size === 0) {
         throw new Error("no pytest scripts are mapped by final Markdown cases");
     }
-    const safeScripts = [];
-    for (const script of unique([...scripts]).sort()) {
-        if (!isSafeBackendPytestScript(script, workspaceRoot)) {
-            throw new Error(`unsafe mapped pytest script: ${script}`);
-        }
-        if (!(await exists(path.resolve(workspaceRoot, script)))) {
-            throw new Error(`mapped pytest script is missing: ${script}`);
-        }
-        safeScripts.push(script);
+    return {
+        expectedScripts: unique(expectedScripts),
+        existingScripts: unique(existingScripts),
+        missingScripts: unique(missingScripts),
+    };
+}
+export async function collectBackendTestMappedPytestScripts(workspaceRoot) {
+    const resolution = await resolveBackendTestMappedPytestScripts(workspaceRoot);
+    if (resolution.missingScripts.length > 0) {
+        throw new Error(`mapped pytest script is missing: ${resolution.missingScripts[0]}`);
     }
-    return safeScripts;
+    return resolution.existingScripts;
 }
 function cleanCaseTitle(rawHeading, id) {
     return rawHeading