@tea-agent/loop-agent 0.26.0 → 0.26.2

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/executors/shell-write-guard.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { lstat, readlink } from "node:fs/promises";
+import { constants, createReadStream } from "node:fs";
+import { access, lstat, readlink } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../shared/git-progress.js";
 async function sha256File(filePath) {
@@ -164,40 +164,176 @@ export function validateShellWriteGuard(input) {
     }
     return { ok: violations.length === 0, violations };
 }
+export class GitStatusUnavailableError extends Error {
+    diagnostics;
+    constructor(input) {
+        const last = input.attempts.at(-1);
+        const exitCode = last?.exitCode === undefined ? "unavailable" : String(last.exitCode);
+        const signal = last?.signal ?? "unavailable";
+        const phase = input.phase ?? "unspecified";
+        super(`git status failed after ${input.attempts.length} attempts (phase=${phase}, exit code=${exitCode}, exit code hex=${last?.exitCodeHex ?? "unavailable"}, signal=${signal}, cwd=${path.resolve(input.cwd)}): ${last?.detail ?? "unknown error"}`);
+        this.name = "GitStatusUnavailableError";
+        this.diagnostics = {
+            schemaVersion: 1,
+            phase,
+            cwd: path.resolve(input.cwd),
+            platform: input.platform ?? process.platform,
+            executableCandidates: input.executableCandidates ?? [],
+            requiredWindowsEnvironment: input.requiredWindowsEnvironment ?? requiredWindowsEnvironment(process.env),
+            attempts: input.attempts,
+        };
+    }
+}
+function requiredWindowsEnvironment(env) {
+    return {
+        SystemRootPresent: Boolean(env.SystemRoot ?? env.SYSTEMROOT),
+        windirPresent: Boolean(env.windir ?? env.WINDIR),
+        ComSpecPresent: Boolean(env.ComSpec ?? env.COMSPEC),
+        PATHEXTPresent: Boolean(env.PATHEXT),
+    };
+}
+function errorExitCode(error) {
+    if (error &&
+        typeof error === "object" &&
+        "exitCode" in error &&
+        typeof error.exitCode === "number") {
+        return error.exitCode;
+    }
+    return undefined;
+}
+function errorSignal(error) {
+    if (error &&
+        typeof error === "object" &&
+        "signal" in error &&
+        typeof error.signal === "string") {
+        return error.signal;
+    }
+    return null;
+}
+function formatWindowsExitCode(exitCode) {
+    if (exitCode === undefined)
+        return undefined;
+    return `0x${(exitCode >>> 0).toString(16).padStart(8, "0").toUpperCase()}`;
+}
+function isWindowsDllInitializationFailure(platform, exitCode) {
+    return platform === "win32" && exitCode !== undefined && (exitCode >>> 0) === 0xc0000142;
+}
+function boundedErrorDetail(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return detail.length <= 1000 ? detail : `${detail.slice(0, 1000)}...[truncated]`;
+}
+export function deriveSameInstallationGitCandidates(primary) {
+    const normalized = path.win32.normalize(primary);
+    const lower = normalized.toLowerCase();
+    let fallback;
+    if (lower.endsWith("\\mingw64\\bin\\git.exe")) {
+        const root = path.win32.resolve(path.win32.dirname(normalized), "..", "..");
+        fallback = path.win32.join(root, "cmd", "git.exe");
+    }
+    else if (lower.endsWith("\\cmd\\git.exe")) {
+        const root = path.win32.resolve(path.win32.dirname(normalized), "..");
+        fallback = path.win32.join(root, "mingw64", "bin", "git.exe");
+    }
+    return Array.from(new Set([normalized, ...(fallback ? [fallback] : [])]));
+}
+async function resolveGitExecutableCandidates(platform, env) {
+    if (platform !== "win32")
+        return ["git"];
+    const pathValue = env.PATH ?? env.Path ?? "";
+    for (const rawEntry of pathValue.split(path.delimiter)) {
+        const entry = rawEntry.trim().replace(/^"|"$/g, "");
+        if (!entry)
+            continue;
+        const candidate = path.win32.join(entry, "git.exe");
+        try {
+            await access(candidate, constants.X_OK);
+            const sameInstallation = deriveSameInstallationGitCandidates(candidate);
+            const existing = [];
+            for (const executable of sameInstallation) {
+                try {
+                    await access(executable, constants.X_OK);
+                    existing.push(executable);
+                }
+                catch {
+                    // Optional same-installation fallback is absent.
+                }
+            }
+            if (existing.length > 0)
+                return existing;
+        }
+        catch {
+            // Keep searching PATH entries.
+        }
+    }
+    return ["git"];
+}
 export async function readGitStatusPorcelain(cwd, options = {}) {
-    const attempts = Math.max(1, options.attempts ?? 5);
-    const retryDelayMs = Math.max(0, options.retryDelayMs ?? 150);
-    let lastError;
-    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    return readGitStatusPorcelainWithDependencies(cwd, options, {
+        platform: process.platform,
+        resolveExecutableCandidates: () => resolveGitExecutableCandidates(process.platform, process.env),
+        runAttempt: readGitStatusPorcelainOnce,
+        sleep: async (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
+        now: Date.now,
+        env: process.env,
+    });
+}
+export async function readGitStatusPorcelainWithDependencies(cwd, options, dependencies) {
+    const candidates = await dependencies.resolveExecutableCandidates();
+    const executableCandidates = candidates.length > 0 ? candidates : ["git"];
+    const normalMaxAttempts = Math.max(1, options.attempts ?? 5);
+    const transientMaxAttempts = Math.max(1, options.attempts ?? 10);
+    const normalRetryBaseMs = Math.max(0, options.retryDelayMs ?? 150);
+    const transientRetryBaseMs = Math.max(0, options.retryDelayMs ?? 250);
+    const attemptDiagnostics = [];
+    for (let attempt = 1; attempt <= transientMaxAttempts; attempt += 1) {
+        const executable = executableCandidates[(attempt - 1) % executableCandidates.length];
+        const startedAt = dependencies.now();
         try {
-            return await readGitStatusPorcelainOnce(cwd);
+            return await dependencies.runAttempt(cwd, executable);
         }
         catch (error) {
-            lastError = error;
-            if (attempt < attempts && retryDelayMs > 0) {
-                await new Promise((resolve) => setTimeout(resolve, retryDelayMs * attempt));
-            }
+            const exitCode = errorExitCode(error);
+            const transient = isWindowsDllInitializationFailure(dependencies.platform, exitCode);
+            attemptDiagnostics.push({
+                attempt,
+                executable,
+                ...(exitCode === undefined ? {} : { exitCode }),
+                ...(formatWindowsExitCode(exitCode)
+                    ? { exitCodeHex: formatWindowsExitCode(exitCode) }
+                    : {}),
+                signal: errorSignal(error),
+                durationMs: Math.max(0, dependencies.now() - startedAt),
+                ...(transient
+                    ? { transientKind: "windows-dll-init-failed" }
+                    : {}),
+                detail: boundedErrorDetail(error),
+            });
+            const maxAttempts = transient ? transientMaxAttempts : normalMaxAttempts;
+            if (attempt >= maxAttempts)
+                break;
+            const delayMs = transient
+                ? Math.min(4000, transientRetryBaseMs * 2 ** (attempt - 1))
+                : normalRetryBaseMs * attempt;
+            if (delayMs > 0)
+                await dependencies.sleep(delayMs);
         }
     }
-    const detail = lastError instanceof Error ? lastError.message : String(lastError);
-    const exitCode = lastError instanceof Error &&
-        "exitCode" in lastError &&
-        typeof lastError.exitCode === "number"
-        ? String(lastError.exitCode)
-        : "unavailable";
-    const signal = lastError instanceof Error &&
-        "signal" in lastError &&
-        typeof lastError.signal === "string"
-        ? lastError.signal
-        : "unavailable";
-    throw new Error(`git status failed after ${attempts} attempts (exit code=${exitCode}, signal=${signal}, cwd=${path.resolve(cwd)}): ${detail}`, { cause: lastError });
+    throw new GitStatusUnavailableError({
+        cwd,
+        phase: options.phase,
+        platform: dependencies.platform,
+        executableCandidates,
+        requiredWindowsEnvironment: requiredWindowsEnvironment(dependencies.env ?? process.env),
+        attempts: attemptDiagnostics,
+    });
 }
-function readGitStatusPorcelainOnce(cwd) {
+function readGitStatusPorcelainOnce(cwd, executable) {
     return new Promise((resolve, reject) => {
-        const child = spawn("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
+        const child = spawn(executable, ["status", "--porcelain=v1", "--untracked-files=all"], {
             cwd,
             env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
             stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
         });
         let stdout = "";
         let stderr = "";

package/dist/sidecars/cursor-prompt/executor.js

@@ -29,7 +29,7 @@ export function resolveArtifactWriteDir(options) {
 }
 export function buildArtifactPathPrompt(writeDir) {
     if (!writeDir)
-        return `After changes, write artifacts/修改记录.md and artifacts/验证结果.md with verification evidence.
+        return `After changes, write artifacts/修改记录.md and artifacts/验证结果.md with verification evidence.
 ${ARTIFACT_INSTRUCTIONS}`;
     return [
         `After changes, write the following files:`,

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);