@tea-agent/loop-agent 0.26.1 → 0.26.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.26.2] - 2026-08-02
+
+### 重点更新
+
+- 后端测试在执行前新增有界的 pytest 收集修复机制，安全且精准地自动修复生成测试中的不一致问题
+- 全面加固 DAG 审查协议与前端契约边界，提升执行稳定性
+- 修复 Observe 看板轮询刷新时的交互状态保留问题，优化使用体验
+
+### 新增
+
+- 后端测试在业务 pytest 执行前新增有界的收集（collection）修复机制：仅对生成的测试目录中可唯一归因的语法、导入、模块或参数化不一致进行最多一次自动修复，且严格禁止修改生产代码或放宽断言
+
+### 改进
+
+- 加固 DAG 审查协议与追踪门禁，提升执行稳定性
+- 加固前端 DAG 契约边界
+- 稳定 Linux 环境下的测试收集固件（fixture）
+- 对齐受监督的 DAG 收尾拓扑结构
+
+### 修复
+
+- 修复 Observe 看板在轮询刷新时破坏 DAG 图视口 DOM 的问题，确保拖动与滚动状态不被销毁
+- 修复节点检查器在内容未变时重建内容的问题，现支持异步标签页安全恢复滚动位置
+
 ## [0.26.1] - 2026-08-02
 
 ### 新增

package/dist/application/dag/generate-task-dag.js

@@ -12,6 +12,9 @@ import { validateDagUseCase } from "./validate-dag.js";
 import { runDagUseCase } from "./run-dag.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { writeTaskConfig } from "../../infrastructure/harness/task-store.js";
+import { runFrontendPreflight } from "../../task/frontend-preflight.js";
+import { observeTaskContract } from "../../task/contract/observe.js";
+import { adoptTaskContract } from "../../task/contract/adopt.js";
 const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
 function buildValidateInput(repoRoot, dagPath, parsed) {
     return {
@@ -243,6 +246,36 @@ export async function generateTaskDagUseCase(input) {
     // before any expensive DAG generation or execution. Empty/consistent
     // repos stay compatible so the default DAG flow is unblocked.
     await assertExecPlanIndexConsistent(repoRoot);
+    const preflightTaskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
+    const frontendScope = await runFrontendPreflight({
+        repoRoot,
+        taskId: parsed.taskId,
+        taskConfig: preflightTaskConfig,
+    });
+    if (frontendScope) {
+        await writeTaskConfig(repoRoot, parsed.taskId, {
+            ...preflightTaskConfig,
+            allowedPaths: [
+                ...new Set([
+                    frontendScope.entrypoint,
+                    ...frontendScope.implementationPaths,
+                    ...frontendScope.testPaths,
+                ]),
+            ],
+        });
+        const state = await observeTaskContract({ repoRoot, taskId: parsed.taskId });
+        if (!state.ref || !state.observedCanonicalHash) {
+            throw new Error("frontend preflight could not reconcile the managed Task Contract");
+        }
+        await adoptTaskContract({
+            repoRoot,
+            taskId: parsed.taskId,
+            expectedRevision: state.ref.revision,
+            expectedObservedHash: state.observedCanonicalHash,
+            requestId: `frontend-preflight-${parsed.taskId}-${randomUUID()}`,
+            requestPayloadSha256: randomUUID().replaceAll("-", "").padEnd(64, "0"),
+        });
+    }
     const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
         outputPath: parsed.outputPath,
         template: "standard-dag",

package/dist/commands/task-source-prepare.js

@@ -18,6 +18,7 @@ const USAGE = `usage:
     [--task-kind <TaskKind>]
     [--feature-id <string>]
     [--allowed-path <glob>]...
+    [--allowed-root <glob>]...
     [--forbidden-path <glob>]...
     [--no-default-forbidden-paths]
     [--invariant <text>]...
@@ -113,6 +114,10 @@ export function parseTaskSourcePrepareArgs(args) {
             options.allowedPaths = pushList(options.allowedPaths, next());
             continue;
         }
+        if (token === "--allowed-root") {
+            options.allowedRoots = pushList(options.allowedRoots, next());
+            continue;
+        }
         if (token === "--forbidden-path") {
             options.forbiddenPaths = pushList(options.forbiddenPaths, next());
             continue;
@@ -264,6 +269,7 @@ function buildFlags(options) {
         taskKind: options.taskKind,
         featureId: options.featureId,
         allowedPaths: options.allowedPaths,
+        allowedRoots: options.allowedRoots,
         forbiddenPaths: options.forbiddenPaths,
         noDefaultForbiddenPaths: options.noDefaultForbiddenPaths,
         invariants: options.invariants,

package/dist/executors/shell-executor.js

@@ -24,6 +24,7 @@ import { materializeBackendTestExecutionContract } from "../workflows/dag/backen
 import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
 import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport } from "../workflows/dag/backend-test-result-contract.js";
 import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { assessBackendPytestCollection, assertBackendPytestCollectionFresh, buildBackendPytestAssetInventory, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
 import { computeL5ReportMetrics } from "../workflows/dag/l5-report-metrics.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
@@ -476,6 +477,114 @@ async function executeBackendTestPipeline(input, meta) {
                 };
             }
         }
+        else if (pipeline === "markdown-collection-assess") {
+            const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
+            const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts);
+            const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+            const targets = mappedScripts.map(shellQuote).join(" ");
+            const command = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --collect-only -q -p no:cacheprovider ${targets}`;
+            const [result] = await executePipelineCommands(input, meta, [command]);
+            if (!result)
+                throw new Error("backend pytest collection command did not produce a result");
+            if (["spawn-error", "timeout", "termination-unconfirmed"].includes(result.failureCategory ?? "")) {
+                return {
+                    ok: false,
+                    stdout: result.stdout,
+                    stderr: result.stderr || "backend pytest collection could not start",
+                    failureCategory: result.failureCategory,
+                    durationMs: Date.now() - started,
+                };
+            }
+            const facts = assessBackendPytestCollection({
+                phase: "initial",
+                mappedScripts,
+                inventory,
+                exitCode: result.exitCode ?? 2,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            });
+            const artifacts = await writeBackendPytestCollectionArtifacts({
+                runDir: meta.runDir,
+                stem: "initial",
+                facts,
+            });
+            outputs.push(`collectionFacts=${artifacts.factsPath}`, `collectionReport=${artifacts.reportPath}`);
+            return {
+                ok: true,
+                stdout: JSON.stringify({
+                    status: facts.status,
+                    repairEligible: facts.repairEligible,
+                    pytestExitCode: facts.pytestExitCode,
+                    collectedItemCount: facts.collectedItemCount,
+                    factsPath: "contracts/backend-test-pytest-collection-initial.json",
+                }),
+                stderr: "",
+                durationMs: Date.now() - started,
+            };
+        }
+        else if (pipeline === "markdown-collection-effective") {
+            const initial = await readBackendPytestCollectionFacts(path.join(meta.runDir, "contracts", "backend-test-pytest-collection-initial.json"));
+            let effective;
+            if (initial.status === "PASS") {
+                effective = await materializeEffectiveBackendPytestCollection({
+                    workspaceRoot: input.cwd,
+                    initial,
+                });
+            }
+            else if (initial.status === "REPAIRABLE") {
+                const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts);
+                const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+                const targets = mappedScripts.map(shellQuote).join(" ");
+                const command = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --collect-only -q -p no:cacheprovider ${targets}`;
+                const [result] = await executePipelineCommands(input, meta, [command]);
+                if (!result)
+                    throw new Error("backend pytest final collection command did not produce a result");
+                if (["spawn-error", "timeout", "termination-unconfirmed"].includes(result.failureCategory ?? "")) {
+                    return {
+                        ok: false,
+                        stdout: result.stdout,
+                        stderr: result.stderr || "backend pytest final collection could not start",
+                        failureCategory: result.failureCategory,
+                        durationMs: Date.now() - started,
+                    };
+                }
+                const finalFacts = assessBackendPytestCollection({
+                    phase: "final",
+                    mappedScripts,
+                    inventory,
+                    exitCode: result.exitCode ?? 2,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                });
+                effective = await materializeEffectiveBackendPytestCollection({
+                    workspaceRoot: input.cwd,
+                    initial,
+                    final: finalFacts,
+                });
+            }
+            else {
+                throw new Error("backend pytest collection is blocked and does not authorize repair");
+            }
+            const artifacts = await writeBackendPytestCollectionArtifacts({
+                runDir: meta.runDir,
+                stem: "effective",
+                facts: effective,
+            });
+            return {
+                ok: true,
+                stdout: JSON.stringify({
+                    status: effective.status,
+                    collectionSource: effective.collectionSource,
+                    repairAttempt: effective.repairAttempt,
+                    collectedItemCount: effective.collectedItemCount,
+                    factsPath: "contracts/backend-test-pytest-collection-effective.json",
+                    reportPath: artifacts.reportPath,
+                }),
+                stderr: "",
+                durationMs: Date.now() - started,
+            };
+        }
         else if (pipeline === "markdown-traceability") {
             let report;
             try {
@@ -542,6 +651,8 @@ async function executeBackendTestPipeline(input, meta) {
             outputs.push(`manifest=${manifestPath}`, `materializationStatus=${manifest.materializationStatus ?? "available"}`, `coverageSummary.explicitAcCount=${summary?.explicitAcCount ?? "unavailable"}`, `coverageSummary.coveredAcCount=${summary?.coveredAcCount ?? "unavailable"}`, `coverageSummary.caseCount=${summary?.caseCount ?? "unavailable"}`, `coverageSummary.generatedCount=${summary?.generatedCount ?? "unavailable"}`, `ruleCoverageSummary.ruleCount=${manifest.ruleCoverageSummary?.ruleCount ?? "unavailable"}`, `correspondenceSummary.exactCorrespondenceCount=${manifest.correspondenceSummary?.exactCorrespondenceCount ?? "unavailable"}`, `correspondenceSummary.primarySymbolCount=${manifest.correspondenceSummary?.primarySymbolCount ?? "unavailable"}`, `correspondenceSummary.testPoints=${manifest.correspondenceSummary?.mappedTestPointCount ?? "unavailable"}/${manifest.correspondenceSummary?.testPointCount ?? "unavailable"}`, `correspondenceSummary.variantTestPointCount=${manifest.correspondenceSummary?.variantTestPointCount ?? "unavailable"}`, `correspondenceSummary.assertionTestPointCount=${manifest.correspondenceSummary?.assertionTestPointCount ?? "unavailable"}`, `correspondenceSummary.crossCuttingTestPointCount=${manifest.correspondenceSummary?.crossCuttingTestPointCount ?? "unavailable"}`, `correspondenceSummary.unclassifiedTestPointCount=${manifest.correspondenceSummary?.unclassifiedTestPointCount ?? "unavailable"}`, `correspondenceSummary.duplicateBindingTestPointCount=${manifest.correspondenceSummary?.duplicateBindingTestPointCount ?? "unavailable"}`);
         }
         else if (pipeline === "markdown-execute-html") {
+            const effectiveCollection = await readBackendPytestCollectionFacts(path.join(meta.runDir, "contracts", "backend-test-pytest-collection-effective.json"));
+            await assertBackendPytestCollectionFresh(input.cwd, effectiveCollection);
             const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
             const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
             const pytestTargets = mappedScripts.map(shellQuote).join(" ");

package/dist/executors/shell-presets.js

@@ -15,7 +15,10 @@ function escapeShellSingleQuoted(value) {
 /**
  * Build a single shell command that reads `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`
  * (injected by the shell executor from runtime meta), parses a single candidate
- * verdict line from `assistantText ?? stdout`, and accepts only exact verdict values.
+ * verdict from `assistantText ?? stdout`, and accepts only exact verdict values.
+ * Sources:
+ * - verdict-line: line-based legacy VERDICT protocol
+ * - json-review-verdict: structured review JSON with verdict: pass/request-revision
  * Modes:
  * - first-non-empty: first non-empty line
  * - first-verdict-line: first line matching /^VERDICT:/ after trim and optional whole-line Markdown emphasis normalization
@@ -25,6 +28,7 @@ function escapeShellSingleQuoted(value) {
  */
 export function buildVerdictGateShellCommand(gate) {
     const gateLabel = gate.label ?? `${gate.fromNodeId} verdict`;
+    const source = gate.source ?? "verdict-line";
     const lineMode = gate.lineMode ?? "first-non-empty";
     const candidateNodeIds = [
         gate.fromNodeId,
@@ -32,8 +36,10 @@ export function buildVerdictGateShellCommand(gate) {
     ];
     const config = {
         label: gateLabel,
+        source,
         lineMode,
         accept: gate.accept,
+        routingAccept: gate.routingAccept ?? [],
         candidateNodeIds,
     };
     const configLiteral = escapeShellSingleQuoted(JSON.stringify(config));
@@ -48,10 +54,12 @@ export function buildVerdictGateShellCommand(gate) {
         'if(!file){console.error("missing "+cfg.label+" JSON output (tried: "+cfg.candidateNodeIds.join(", ")+")");process.exit(1);}',
         'const raw=JSON.parse(fs.readFileSync(file,"utf8"));',
         'const text=String(raw.assistantText ?? raw.stdout ?? "");',
+        'const extractJson=(value)=>{const text=String(value).trim();const fenced=[...text.matchAll(/```(?:json)?\\s*([\\s\\S]*?)\\s*```/gi)];const source=fenced.length===1?String(fenced[0][1]).trim():text;for(let start=0;start<source.length;start+=1){if(source[start]!=="{")continue;let depth=0,inString=false,escaped=false;for(let i=start;i<source.length;i+=1){const ch=source[i];if(inString){if(escaped){escaped=false;}else if(ch==="\\\\"){escaped=true;}else if(ch===String.fromCharCode(34)){inString=false;}continue;}if(ch===String.fromCharCode(34)){inString=true;continue;}if(ch==="{"){depth+=1;}else if(ch===String.fromCharCode(125)){depth-=1;if(depth===0){const candidate=source.slice(start,i+1);try{const parsed=JSON.parse(candidate);if(parsed&&typeof parsed==="object"&&!Array.isArray(parsed))return candidate;}catch{}break;}}}}return "";};',
+        'let first="";',
+        'if(cfg.source==="json-review-verdict"){const jsonText=extractJson(text);if(!jsonText){console.error(cfg.label+" gate blocked: missing JSON review verdict");process.exit(1);}let parsed;try{parsed=JSON.parse(jsonText);}catch(error){console.error(cfg.label+" gate blocked: invalid JSON review verdict: "+error.message);process.exit(1);}first=String(parsed&&parsed.verdict||"");}',
         'const normalize=(value)=>{const trimmed=String(value).trim();const emphasized=trimmed.match(/^\\*{1,3}\\s*(VERDICT:[^*]+?)\\s*\\*{1,3}$/);return (emphasized?emphasized[1]:trimmed).trim();};',
-        'const lines=text.split(/\\r?\\n/).map(normalize);',
-        'const first=cfg.lineMode==="first-verdict-line"? (lines.find((value)=>/^VERDICT:/.test(value))??"") : (lines.find((value)=>value.length>0)??"");',
-        'if(!cfg.accept.includes(first)){console.error(cfg.label+" gate blocked: "+(first||"missing VERDICT line"));process.exit(1);}',
+        'if(cfg.source!=="json-review-verdict"){const lines=text.split(/\\r?\\n/).map(normalize);first=cfg.lineMode==="first-verdict-line"? (lines.find((value)=>/^VERDICT:/.test(value))??"") : (lines.find((value)=>value.length>0)??"");}',
+        'const routing=Array.isArray(cfg.routingAccept)?cfg.routingAccept:[];if(!cfg.accept.includes(first)&&!routing.includes(first)){console.error(cfg.label+" gate blocked: "+(first|| (cfg.source==="json-review-verdict"?"missing JSON verdict":"missing VERDICT line")));process.exit(1);}',
         'process.stdout.write(first+"\\n");',
     ].join("");
     return `node -e '${escapeShellSingleQuoted(program)}' '${configLiteral}'`;

package/dist/task/config-types.js

@@ -104,6 +104,12 @@ const taskConfigObjectSchema = z.object({
     referenceMaxFilesPerRepo: z.number().int().positive().optional(),
     referenceMaxTotalFiles: z.number().int().positive().optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
+    /**
+     * Coarse repository roots used only by the frontend preflight scout. Before
+     * DAG generation, the scout must resolve these into the narrower
+     * `allowedPaths` consumed by writer nodes.
+     */
+    allowedRoots: z.array(z.string()).optional(),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     hardConstraints: z.array(z.string()).optional().default([]),
     autoCommitAfterVerify: z.boolean().optional().default(true),

package/dist/task/contract/constants.js

@@ -13,6 +13,7 @@ export const MANAGED_TASK_CONFIG_FIELDS = [
     "taskKind",
     "featureId",
     "allowedPaths",
+    "allowedRoots",
     "forbiddenPaths",
     "hardConstraints",
     "verifyCommands",

package/dist/task/contract/project.js

@@ -107,6 +107,11 @@ export function projectConstraintsMarkdown(draft) {
             lines.push(`- ${item}`);
         }
     }
+    if (draft.constraints.allowedRoots?.length) {
+        lines.push("", "## Allowed roots (preflight only)", "");
+        for (const item of draft.constraints.allowedRoots)
+            lines.push(`- ${item}`);
+    }
     lines.push("", "## Expected verification", "");
     if (draft.verification.commands.length === 0) {
         lines.push("- (none)");
@@ -148,6 +153,9 @@ export function mergeManagedTaskConfigFields(existing, draft) {
         title: draft.title,
         taskKind: draft.taskKind,
         allowedPaths: canonicalizePathArray(draft.constraints.allowedPaths),
+        ...(draft.constraints.allowedRoots !== undefined
+            ? { allowedRoots: canonicalizePathArray(draft.constraints.allowedRoots) }
+            : {}),
         forbiddenPaths: canonicalizePathArray(draft.constraints.forbiddenPaths),
         hardConstraints,
         verifyCommands: draft.verification.commands.map((cmd) => ({

package/dist/task/contract/schema.js

@@ -23,6 +23,7 @@ export const taskContractDraftConstraintsSchema = z
     .object({
     invariants: z.array(z.string()),
     allowedPaths: z.array(z.string()),
+    allowedRoots: z.array(z.string()).optional(),
     forbiddenPaths: z.array(z.string()),
     protectedUserChanges: z.array(z.string()).optional(),
     expectedVerification: z.array(z.string()).optional(),

package/dist/task/frontend-preflight.js

@@ -0,0 +1,131 @@
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { executePiStep } from "../executors/pi-executor.js";
+import { resolveDagPiModelConfig } from "../executors/dag-pi-executor.js";
+import { writeJsonAtomic } from "../infrastructure/harness/atomic-write.js";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+import { loadHarnessManifest } from "../governance/harness.js";
+import { resolveExecutorModelMatrices } from "../executors/model-routing.js";
+const frontendScopeSchema = z.object({
+    schemaVersion: z.literal(1),
+    entrypoint: z.string().min(1),
+    implementationPaths: z.array(z.string().min(1)).min(1),
+    testPaths: z.array(z.string().min(1)).min(1),
+    dataSource: z.string().min(1),
+});
+function isSafeRepositoryPath(value) {
+    return value.length > 0 &&
+        !path.isAbsolute(value) &&
+        !value.includes("\\") &&
+        !value.split("/").includes("..");
+}
+function parseScope(text) {
+    const candidates = [];
+    for (let start = text.indexOf("{"); start >= 0; start = text.indexOf("{", start + 1)) {
+        let depth = 0;
+        let quoted = false;
+        let escaped = false;
+        for (let index = start; index < text.length; index += 1) {
+            const char = text[index];
+            if (quoted) {
+                if (escaped)
+                    escaped = false;
+                else if (char === "\\")
+                    escaped = true;
+                else if (char === '"')
+                    quoted = false;
+                continue;
+            }
+            if (char === '"')
+                quoted = true;
+            else if (char === "{")
+                depth += 1;
+            else if (char === "}" && --depth === 0) {
+                try {
+                    candidates.push(JSON.parse(text.slice(start, index + 1)));
+                }
+                catch { /* continue */ }
+                break;
+            }
+        }
+    }
+    if (candidates.length === 0)
+        throw new Error("frontend preflight output contains no JSON object");
+    const parsed = frontendScopeSchema.parse(candidates.at(-1));
+    for (const candidate of [
+        parsed.entrypoint,
+        ...parsed.implementationPaths,
+        ...parsed.testPaths,
+    ]) {
+        if (!isSafeRepositoryPath(candidate)) {
+            throw new Error(`unsafe frontend preflight path: ${candidate}`);
+        }
+    }
+    return parsed;
+}
+function ensureWithinRoots(scope, roots) {
+    const candidates = [
+        scope.entrypoint,
+        ...scope.implementationPaths,
+        ...scope.testPaths,
+    ];
+    const outside = candidates.filter((candidate) => !roots.some((root) => pathMatchesPattern(candidate, root)));
+    if (outside.length > 0) {
+        throw new Error(`frontend preflight discovered paths outside allowedRoots: ${outside.join(", ")}`);
+    }
+}
+export async function runFrontendPreflight(input) {
+    if (input.taskConfig.taskKind !== "frontend-implementation" ||
+        (input.taskConfig.allowedRoots?.length ?? 0) === 0) {
+        return undefined;
+    }
+    const requirementPath = path.join(input.repoRoot, ".harness", "tasks", input.taskId, "source", "需求.md");
+    const requirement = await readFile(requirementPath, "utf8");
+    const manifest = await loadHarnessManifest(input.repoRoot);
+    const models = resolveExecutorModelMatrices(manifest);
+    const model = models.pi.MED;
+    const prompt = [
+        "You are a read-only frontend preflight scout. Inspect the target repository before its implementation DAG is generated.",
+        "Locate the existing UI surface that satisfies the requirement. Do not invent a new page when an existing surface exists.",
+        `Allowed roots: ${input.taskConfig.allowedRoots.join(", ")}`,
+        "Return exactly one JSON object and no Markdown or prose:",
+        '{"schemaVersion":1,"entrypoint":"relative/path","implementationPaths":["relative/glob-or-file"],"testPaths":["relative/glob-or-file"],"dataSource":"existing store/API/module"}',
+        "Every path must be repository-relative POSIX, must be inside allowed roots, and implementationPaths/testPaths must be the narrowest directories or files that own the existing behavior.",
+        "Requirement:",
+        requirement,
+    ].join("\n\n");
+    const result = await executePiStep({
+        attachedFiles: [requirementPath],
+        modelConfig: resolveDagPiModelConfig(model),
+        prompt,
+        repoRoot: input.repoRoot,
+        step: "analyze",
+        toolNames: ["read", "grep", "find", "ls"],
+        userMessage: "Perform the frontend preflight scout and return the required JSON.",
+        validateOutput: (assistantText) => {
+            try {
+                const scope = parseScope(assistantText);
+                ensureWithinRoots(scope, input.taskConfig.allowedRoots);
+                return [];
+            }
+            catch (error) {
+                return [error instanceof Error ? error.message : String(error)];
+            }
+        },
+    });
+    if (!result.ok) {
+        throw new Error(`frontend preflight failed: ${result.failureCategory}: ${result.stderr || result.assistantText}`);
+    }
+    const scope = parseScope(result.assistantText);
+    ensureWithinRoots(scope, input.taskConfig.allowedRoots);
+    const preflightDir = path.join(input.repoRoot, ".harness", "tasks", input.taskId, "preflight");
+    await mkdir(preflightDir, { recursive: true });
+    await writeJsonAtomic(path.join(preflightDir, "frontend-scope.json"), {
+        ...scope,
+        resolvedAt: new Date().toISOString(),
+        allowedRoots: input.taskConfig.allowedRoots,
+        model,
+    });
+    return scope;
+}

package/dist/task/runtime.js

@@ -201,10 +201,8 @@ export function parseTaskConfigForRuntime(rawConfig) {
     }
     return parsed;
 }
-export function deriveMaxFixLoops(complexity) {
-    if (complexity === 'small')
-        return 2;
-    return 3;
+export function deriveMaxFixLoops(_complexity) {
+    return 2;
 }
 export async function listTaskSourceFiles(repoRoot, taskId) {
     return listFilesRecursive(getTaskPaths(repoRoot, taskId).sourceDir);

package/dist/task/source-prepare/build-draft.js

@@ -65,6 +65,13 @@ function resolveAllowedPaths(input) {
         return n.ok ? n.value : raw.trim();
     });
 }
+function resolveAllowedRoots(input) {
+    const roots = input.flags.allowedRoots ?? input.baseDraft?.constraints.allowedRoots ?? input.existing?.allowedRoots;
+    return roots === undefined ? undefined : (cleanStringList(roots) ?? []).map((raw) => {
+        const normalized = normalizePreparePath(raw);
+        return normalized.ok ? normalized.value : raw.trim();
+    });
+}
 function resolveVerifyCommands(input) {
     if (input.flags.verifyCommands !== undefined) {
         return input.flags.verifyCommands.map((cmd) => ({
@@ -122,6 +129,7 @@ export function buildPrepareDraft(input) {
         baseDraft,
         existing: existingTaskConfig,
     });
+    const allowedRoots = resolveAllowedRoots({ flags, baseDraft, existing: existingTaskConfig });
     // D12: protected defaults always merge unless explicitly disabled.
     // Explicit --forbidden-path appends; does not replace defaults.
     const finalForbidden = mergeForbiddenPaths({
@@ -175,6 +183,7 @@ export function buildPrepareDraft(input) {
             forbiddenPaths: pathAssessment.forbidden.length > 0
                 ? pathAssessment.forbidden
                 : dedupeStable(finalForbidden),
+            ...(allowedRoots !== undefined ? { allowedRoots: dedupeStable(allowedRoots) } : {}),
         },
         verification: {
             commands: verifyCommands

package/dist/task/source-prepare/completeness.js

@@ -81,7 +81,7 @@ export function listPrepareGaps(input) {
             });
         }
     }
-    if (draft.constraints.allowedPaths.length === 0) {
+    if (draft.constraints.allowedPaths.length === 0 && !(draft.taskKind === "frontend-implementation" && (draft.constraints.allowedRoots?.length ?? 0) > 0)) {
         gaps.push({
             code: "EMPTY_ALLOWED_PATHS",
             level: "blocking",