@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.11

package/dist/executors/shell-write-guard.js

@@ -124,6 +124,13 @@ export function isEphemeralToolCachePath(filePath) {
     if (normalized === ".coverage" || normalized.startsWith(".coverage.")) {
         return true;
     }
+    // vite/vitest runtime caches live under node_modules/.vite (e.g.
+    // node_modules/.vite/vitest/results.json). node_modules is the gitignored
+    // dependency tree — tool cache writes there are never a writer's product
+    // change and must not trip the write guard.
+    if (normalized.startsWith("node_modules/.vite/")) {
+        return true;
+    }
     if (/(?:^|\/)__pycache__(?:\/|$)/.test(normalized))
         return true;
     if (/\.(?:pyc|pyo)$/.test(normalized))

package/dist/infrastructure/console/operation-store.js

@@ -1,5 +1,9 @@
 import { randomBytes } from "node:crypto";
 import path from "node:path";
+import { assertFrontendSplitProjectionSuccessor, frontendSplitProjectionSchema, } from "../../workflows/dag/frontend-split-application-service.js";
+import { buildFrontendHumanDecisionProjection, consumeFrontendHumanDecision, materializeFrontendHumanDecision, parseFrontendHumanDecisionProjection, parseFrontendHumanDecisionReceipt, } from "../../workflows/dag/frontend-human-decision.js";
+import { buildFrontendSplitAggregateCloseout, computeFrontendSplitDigest, finalizeFrontendSplitAggregate, frontendCommittedFactRefSchema, frontendSplitChildCloseoutFactsSchema, initializeFrontendSplitParent, } from "../../workflows/dag/frontend-split-orchestrator.js";
+import { frontendCloseoutFactsSchema, frontendTestHandoffSchema, } from "../../workflows/dag/frontend-closeout.js";
 import { listJsonFiles, readJsonIfExists, sha256Json, writeSecureJson, } from "./app-data.js";
 export const TERMINAL_OPERATION_STATES = new Set(["succeeded", "failed", "timed-out", "restarting"]);
 function operationFile(appData, operationId) {
@@ -15,16 +19,21 @@ export function computeActionPayloadHash(action, actionParams) {
 export function newOperationId() {
     return `op_${randomBytes(12).toString("hex")}`;
 }
+const sharedWriteChains = new Map();
 export class OperationStore {
     appData;
-    /**
-     * Per-key write lock. Concurrent update/save/create on the same operation
-     * or clientRequestId must not race rename() into the same JSON path
-     * (Windows EPERM) or last-write-wins lost patches.
-     */
-    writeChains = new Map();
+    /** Shared per-store-root, per-key write lock. Multiple OperationStore instances
+     * in one worker process must observe the same CAS critical section. */
+    writeChains;
     constructor(appData) {
         this.appData = appData;
+        const root = path.resolve(appData.operations);
+        let chains = sharedWriteChains.get(root);
+        if (!chains) {
+            chains = new Map();
+            sharedWriteChains.set(root, chains);
+        }
+        this.writeChains = chains;
     }
     serialize(key, op) {
         const prev = this.writeChains.get(key) ?? Promise.resolve();
@@ -66,6 +75,7 @@ export class OperationStore {
                 payloadHash,
                 state: "queued",
                 createdAt: now,
+                revision: 1,
                 taskId: input.taskId,
                 cliArgs: input.cliArgs,
                 ...(input.externalCommand
@@ -77,11 +87,61 @@ export class OperationStore {
             return { kind: "created", operation };
         });
     }
+    /**
+     * Idempotently materialize a split child/integration operation with a
+     * caller-specified deterministic operationId (from the split manifest).
+     * Unlike create() (random op_<hex> id) and save/update (no create), this is
+     * the durable cross-restart idempotency boundary for the production
+     * FrontendSplitTaskMaterializer backend: an existing operation file with the
+     * same taskId + payloadHash is returned as {created:false}; any drift fails
+     * closed instead of overwriting or silently diverging.
+     */
+    async ensureSplitMaterializedOperation(input) {
+        return this.serialize(input.operationId, async () => {
+            const existing = await this.get(input.operationId);
+            if (existing) {
+                if (existing.taskId !== input.taskId ||
+                    existing.payloadHash !== input.payloadHash) {
+                    throw new Error("frontend split operation materialization payload drift");
+                }
+                return { operation: existing, created: false };
+            }
+            const now = new Date().toISOString();
+            const operation = {
+                schemaVersion: 1,
+                operationId: input.operationId,
+                clientRequestId: `split:${input.operationId}`,
+                action: input.action,
+                actionParams: input.actionParams,
+                payloadHash: input.payloadHash,
+                state: "queued",
+                createdAt: now,
+                revision: 1,
+                taskId: input.taskId,
+                ...(input.cliArgs ? { cliArgs: input.cliArgs } : {}),
+            };
+            await writeSecureJson(operationFile(this.appData, input.operationId), operation);
+            return { operation, created: true };
+        });
+    }
     async get(operationId) {
         return readJsonIfExists(operationFile(this.appData, operationId));
     }
     async save(operation) {
         return this.serialize(operation.operationId, async () => {
+            const current = await this.get(operation.operationId);
+            if (current?.revision !== undefined && operation.revision !== current.revision)
+                throw new Error("operation revision may not be changed by save");
+            if (operation.frontendHumanDecision !== undefined || current?.frontendHumanDecision !== undefined) {
+                if (!current || JSON.stringify(operation) !== JSON.stringify(current))
+                    throw new Error("human-decision projection may only be mutated by canonical CAS");
+                return current;
+            }
+            if (operation.frontendSplit !== undefined || current?.frontendSplit !== undefined) {
+                if (!current || JSON.stringify(operation) !== JSON.stringify(current))
+                    throw new Error("split projection may only be mutated by compareAndSwapFrontendSplit");
+                return current;
+            }
             await writeSecureJson(operationFile(this.appData, operation.operationId), operation);
             return operation;
         });
@@ -92,6 +152,10 @@ export class OperationStore {
             if (!current) {
                 throw new Error(`operation not found: ${operationId}`);
             }
+            if ("frontendHumanDecision" in patch || (current.frontendHumanDecision !== undefined && ("state" in patch || "frontendExecution" in patch)))
+                throw new Error("human-decision projection may only be mutated by canonical CAS");
+            if ("frontendSplit" in patch || "revision" in patch || (current.frontendSplit !== undefined && ("state" in patch || "frontendExecution" in patch)))
+                throw new Error("split projection may only be mutated by compareAndSwapFrontendSplit");
             const next = {
                 ...current,
                 ...patch,
@@ -106,6 +170,162 @@ export class OperationStore {
             return next;
         });
     }
+    async materializeFrontendHumanDecision(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            if (!current || current.revision === undefined || current.revision !== input.expectedRecordRevision) {
+                const fallback = current?.frontendHumanDecision ?? buildFrontendHumanDecisionProjection({ status: "active", operationId: input.operationId, runId: input.envelope.runId, revision: Math.max(1, input.expectedRecordRevision) });
+                return { outcome: "rejected", reason: "record revision conflict or legacy record", projection: fallback };
+            }
+            const projection = current.frontendHumanDecision ?? buildFrontendHumanDecisionProjection({ status: "active", operationId: current.operationId, runId: input.envelope.runId, revision: current.revision });
+            const result = materializeFrontendHumanDecision({ projection, envelope: input.envelope, expectedRecordRevision: input.expectedRecordRevision, expectedProjectionDigest: input.expectedProjectionDigest });
+            if (result.outcome !== "applied")
+                return result;
+            const record = { ...current, revision: result.projection.revision, frontendHumanDecision: result.projection, state: "running" };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return result;
+        });
+    }
+    async consumeFrontendHumanDecision(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            if (!current || current.revision === undefined || !current.frontendHumanDecision) {
+                const fallback = buildFrontendHumanDecisionProjection({ status: "active", operationId: input.operationId, runId: input.receipt.runId, revision: Math.max(1, input.expectedRecordRevision) });
+                return { outcome: "rejected", reason: "record has no mutable human-decision projection", projection: fallback };
+            }
+            const projection = parseFrontendHumanDecisionProjection(current.frontendHumanDecision);
+            if (current.revision !== input.expectedRecordRevision)
+                return { outcome: "rejected", reason: "record revision conflict", projection };
+            const result = consumeFrontendHumanDecision({ projection, receipt: input.receipt, expectedRecordRevision: input.expectedRecordRevision, expectedProjectionDigest: input.expectedProjectionDigest, currentTargetDigest: input.currentTargetDigest, now: input.now });
+            if (result.outcome !== "applied")
+                return result;
+            const record = { ...current, revision: result.projection.revision, frontendHumanDecision: result.projection };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return result;
+        });
+    }
+    async initializeFrontendHumanApprovedSplit(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            const fallback = current?.frontendHumanDecision ?? buildFrontendHumanDecisionProjection({ status: "active", operationId: input.operationId, runId: input.receipt.runId, revision: Math.max(1, input.expectedRecordRevision) });
+            if (!current || current.revision === undefined || current.revision !== input.expectedRecordRevision || !current.frontendHumanDecision || !current.frontendExecution || current.frontendSplit)
+                return { outcome: "rejected", reason: "record is not an authoritative pending single-task split", projection: fallback };
+            const humanProjection = parseFrontendHumanDecisionProjection(current.frontendHumanDecision);
+            if (humanProjection.status !== "blocked-human" || humanProjection.envelope.kind !== "split-materialization-approval" || humanProjection.digest !== input.expectedProjectionDigest)
+                return { outcome: "rejected", reason: "pending split envelope conflict", projection: humanProjection };
+            const receipt = parseFrontendHumanDecisionReceipt(input.receipt);
+            if (receipt.kind !== "split-materialization-approval")
+                return { outcome: "rejected", reason: "receipt is not a split approval", projection: humanProjection };
+            if (JSON.stringify(current.frontendExecution) !== JSON.stringify(input.execution) || input.execution.kind !== "single-task")
+                return { outcome: "rejected", reason: "single-task execution conflict", projection: humanProjection };
+            const consumed = consumeFrontendHumanDecision({ projection: humanProjection, receipt, expectedRecordRevision: input.expectedRecordRevision, expectedProjectionDigest: input.expectedProjectionDigest, currentTargetDigest: input.currentTargetDigest, now: input.now });
+            if (consumed.outcome !== "applied")
+                return consumed;
+            const initialized = initializeFrontendSplitParent({
+                execution: input.execution,
+                manifest: input.manifest,
+                expectedOperationRevision: input.execution.operationRevision,
+                successorOperationRevision: consumed.projection.revision,
+                envelopeTargetDigest: humanProjection.envelope.targetDigest,
+                activeWriterOperationId: input.activeWriterOperationId,
+                activeProviderOperationId: input.activeProviderOperationId,
+                authorization: { mode: "human", envelope: humanProjection.envelope, receipt },
+            });
+            if (initialized.outcome !== "applied")
+                return { outcome: "rejected", reason: initialized.reason, projection: humanProjection };
+            const splitProjection = frontendSplitProjectionSchema.parse({ revision: consumed.projection.revision, execution: initialized.execution, manifest: input.manifest, parent: initialized.parent });
+            const { frontendExecution: _singleTask, ...withoutSingleTask } = current;
+            const record = { ...withoutSingleTask, revision: consumed.projection.revision, frontendHumanDecision: consumed.projection, frontendSplit: splitProjection, state: "running" };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return { outcome: "applied", projection: splitProjection, humanDecision: consumed.projection };
+        });
+    }
+    async compareAndSwapFrontendSplit(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            if (!current || current.revision === undefined || current.revision !== input.expectedRevision)
+                return { outcome: "conflict" };
+            const currentProjection = current.frontendSplit;
+            if (currentProjection) {
+                if (currentProjection.execution.digest !== input.expectedExecutionDigest || currentProjection.parent.digest !== input.expectedParentDigest)
+                    return { outcome: "conflict" };
+            }
+            else if (input.expectedExecutionDigest || input.expectedParentDigest)
+                return { outcome: "conflict" };
+            const next = currentProjection
+                ? assertFrontendSplitProjectionSuccessor(currentProjection, input.next)
+                : frontendSplitProjectionSchema.parse(input.next);
+            if (next.revision !== current.revision + 1 || next.parent.operationId !== input.operationId)
+                throw new Error("split CAS next revision or operation binding mismatch");
+            const state = next.parent.operationState === "success" ? "succeeded" : next.parent.operationTerminal !== undefined ? "failed" : current.state;
+            const record = { ...current, revision: next.revision, frontendSplit: next, state };
+            await writeSecureJson(operationFile(this.appData, input.operationId), record);
+            return { outcome: "applied", projection: next };
+        });
+    }
+    async loadChildCloseoutFacts(input) {
+        const factsDir = input.closeoutRef.ref;
+        const facts = await readJsonIfExists(path.join(factsDir, "frontend-closeout-facts.json"));
+        if (facts === undefined)
+            return frontendSplitChildCloseoutFactsSchema.parse({ childId: input.childId, residualRisks: [], frontendTestHandoffRef: undefined });
+        const parsedFacts = frontendCloseoutFactsSchema.parse(facts);
+        if (computeFrontendSplitDigest(parsedFacts) !== input.closeoutRef.digest)
+            throw new Error(`child closeout facts digest mismatch: ${input.childId}`);
+        const handoff = await readJsonIfExists(path.join(factsDir, "frontend-test-handoff.json"));
+        const frontendTestHandoffRef = handoff === undefined ? undefined : computeFrontendSplitDigest(frontendTestHandoffSchema.parse(handoff));
+        return frontendSplitChildCloseoutFactsSchema.parse({ childId: input.childId, residualRisks: parsedFacts.residualRisks ?? [], frontendTestHandoffRef });
+    }
+    async settleFrontendSplitAggregate(input) {
+        return this.serialize(input.operationId, async () => {
+            const record = await this.get(input.operationId);
+            if (!record || record.revision === undefined || record.revision !== input.expectedRevision || !record.frontendSplit)
+                return { outcome: "conflict" };
+            const authoritative = frontendSplitProjectionSchema.parse(record.frontendSplit);
+            if (authoritative.parent.operationId !== input.operationId
+                || authoritative.revision !== input.expectedRevision
+                || authoritative.execution.digest !== input.expectedExecutionDigest
+                || authoritative.parent.digest !== input.expectedParentDigest
+                || authoritative.manifest.digest !== input.expectedManifestDigest
+                || authoritative.candidateBinding?.digest !== input.expectedCandidateBindingDigest
+                || authoritative.integrationBinding?.digest !== input.expectedIntegrationBindingDigest)
+                return { outcome: "conflict" };
+            if (!authoritative.candidateBinding)
+                return { outcome: "conflict" };
+            const expectedAggregate = buildFrontendSplitAggregateCloseout(authoritative.parent, authoritative.manifest, authoritative.candidateBinding, authoritative.integrationBinding, input.childCloseoutFacts);
+            if (JSON.stringify(expectedAggregate) !== JSON.stringify(input.aggregate))
+                return { outcome: "conflict" };
+            const transaction = await input.prepareAggregate({
+                operationId: authoritative.parent.operationId,
+                aggregate: expectedAggregate,
+            });
+            try {
+                const committedRef = frontendCommittedFactRefSchema.parse(transaction.committedRef);
+                const finalized = finalizeFrontendSplitAggregate(authoritative.parent, expectedAggregate, committedRef);
+                const next = assertFrontendSplitProjectionSuccessor(authoritative, { ...authoritative, revision: authoritative.revision + 1, parent: finalized.parent, execution: finalized.execution, aggregateCloseout: { value: expectedAggregate, committedRef } });
+                const nextRecord = { ...record, revision: next.revision, frontendSplit: next, state: "succeeded" };
+                await transaction.commit({
+                    parentRecordPath: operationFile(this.appData, record.operationId),
+                    parentRecord: nextRecord,
+                });
+                return { outcome: "applied", projection: next };
+            }
+            catch (error) {
+                await transaction.rollback();
+                throw error;
+            }
+        });
+    }
+    async initializeFrontendSplit(expectedRevision, projectionValue) {
+        const projection = frontendSplitProjectionSchema.parse(projectionValue);
+        return this.serialize(projection.parent.operationId, async () => {
+            const current = await this.get(projection.parent.operationId);
+            if (!current || current.revision === undefined || current.revision !== expectedRevision || current.frontendSplit !== undefined || projection.revision !== expectedRevision + 1)
+                return { outcome: "conflict" };
+            const record = { ...current, revision: projection.revision, frontendSplit: projection };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return { outcome: "applied", projection };
+        });
+    }
     async list() {
         const files = await listJsonFiles(this.appData.operations);
         const ops = [];

package/dist/shared/dag-failure-category.js

@@ -47,10 +47,22 @@ const RAW_TO_NORMALIZED = {
     "verify-failure": "validation",
     "test-failure": "validation",
     "verification-plan-stale": "validation",
+    "read-burst": "validation",
+    // Writer persisted real file changes but the final provider call hit a
+    // context overflow; verification never ran. Distinct from empty-output so
+    // the report shows partial success instead of a spec issue.
+    "partial-success-with-context-overflow": "validation",
+    // Writer burned an excessive token budget (unconverged read-edit-test loop)
+    // and still failed; distinct from empty-output for accurate reporting.
+    "writer-budget-exhausted": "validation",
     network: "executor",
     quota: "executor",
     "rate-limit": "executor",
     unavailable: "executor",
+    // Context window overflow (400 request-too-large): the session needs
+    // compaction / fresh context before retrying — an executor-side
+    // environment condition, not a plan-quality defect.
+    "context-overflow": "executor",
     // Deterministic capability/policy refusal: missing verified launcher JS
     // entry, capability allowlist rejection, or missing bounded write tool
     // profile. These are environment/config defects the operator repairs

package/dist/shared/openspec-spec.js

@@ -12,6 +12,19 @@ export const OPENSPEC_SPEC_DIRS = [
     "openspec/project-specs",
     "ai_workspace",
 ];
+/** Default roots used when a frontend task does not declare specRoots. */
+export const DEFAULT_FRONTEND_SPEC_ROOTS = OPENSPEC_SPEC_DIRS;
+/** A task-owned spec root must be a normalized, repo-relative POSIX directory. */
+export function isValidFrontendSpecRoot(value) {
+    return (Boolean(value) &&
+        !value.includes("\\") &&
+        !value.startsWith("/") &&
+        !value.includes("//") &&
+        !value.split("/").some((segment) => !segment ||
+            segment === "." ||
+            segment === ".." ||
+            /\s/.test(segment)));
+}
 /** Allowed spec file extensions (case-insensitive). */
 export const OPENSPEC_SPEC_EXT_RE = /\.(md|mdx|json|yaml|yml)$/i;
 /**
@@ -43,14 +56,17 @@ export function isGovernanceSubtreePath(filePath, governanceRoot) {
  * directories.  `filePath` must be a repo-relative POSIX path (backslashes are
  * normalised internally).  Directory names are case-sensitive.
  */
-export function isOpenspecSpecPath(filePath) {
+export function isFrontendSpecPath(filePath, specRoots = DEFAULT_FRONTEND_SPEC_ROOTS) {
     const normalized = filePath.replaceAll("\\", "/");
-    for (const dir of OPENSPEC_SPEC_DIRS) {
+    for (const dir of specRoots) {
         if (normalized === dir || normalized.startsWith(dir + "/"))
             return true;
     }
     return false;
 }
+export function isOpenspecSpecPath(filePath) {
+    return isFrontendSpecPath(filePath);
+}
 /**
  * Returns `true` when `filename` (the basename only, not a full path) has an
  * allowed frontend specification extension.
@@ -59,10 +75,13 @@ export function isValidOpenspecExtension(filename) {
     return OPENSPEC_SPEC_EXT_RE.test(filename);
 }
 /** Returns `true` for a supported file inside a canonical openspec spec dir. */
-export function isOpenspecSpecFilePath(filePath) {
-    return (isOpenspecSpecPath(filePath) &&
+export function isFrontendSpecFilePath(filePath, specRoots = DEFAULT_FRONTEND_SPEC_ROOTS) {
+    return (isFrontendSpecPath(filePath, specRoots) &&
         isValidOpenspecExtension(filePath.replaceAll("\\", "/")));
 }
+export function isOpenspecSpecFilePath(filePath) {
+    return isFrontendSpecFilePath(filePath);
+}
 /**
  * Returns `true` when free-form search input references a canonical frontend
  * specification directory with exact lowercase directory names.
@@ -123,3 +142,50 @@ export function extractTaskSourceOpenspecPaths(markdown, governanceRoot = DEFAUL
         !isGovernanceSubtreePath(token, governanceRoot))
         .sort();
 }
+/**
+ * Extract explicit specification-file citations for a task's frozen spec roots.
+ * This is intentionally path-only: source preparation decides which roots are
+ * normative, while DAG execution only consumes that frozen configuration.
+ */
+export function extractTaskSourceFrontendSpecPaths(markdown, specRoots, governanceRoot = DEFAULT_OPENSPEC_GOVERNANCE_ROOT) {
+    if (!markdown)
+        return [];
+    const raw = new Set();
+    const collect = (token) => {
+        const normalized = normalizeCitationToken(token);
+        if (normalized)
+            raw.add(normalized);
+    };
+    for (const match of markdown.matchAll(/`([^`\n]+)`/g))
+        collect(match[1] ?? "");
+    for (const match of markdown.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g))
+        collect(match[1] ?? "");
+    for (const root of specRoots) {
+        const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        for (const match of markdown.matchAll(new RegExp(`(?:^|[\\s\"'([>])(${escaped}/[A-Za-z0-9._/-]+)`, "g"))) {
+            collect(match[1] ?? "");
+        }
+    }
+    return [...raw]
+        .filter((token) => isFrontendSpecFilePath(token, specRoots) && !isGovernanceSubtreePath(token, governanceRoot))
+        .sort();
+}
+/**
+ * Source-preparation helper for explicitly named normative directories. A root
+ * is inferred only on a line that declares a spec/规范/design-system intent;
+ * arbitrary Markdown links never silently broaden task configuration.
+ */
+export function extractDeclaredFrontendSpecRoots(markdown) {
+    const roots = new Set();
+    for (const line of markdown.split(/\r?\n/)) {
+        if (!/(?:规范|规约|标准|设计系统|\bspec(?:ification)?\b|\bdesign[ -]?system\b|\bguidelines?\b|\brules?\b)/i.test(line))
+            continue;
+        for (const match of line.matchAll(/`([^`]+)`|\[[^\]]+\]\(([^)\s]+)\)/g)) {
+            const raw = (match[1] ?? match[2] ?? "").replaceAll("\\", "/").replace(/\/+$/, "");
+            if (!raw || !isValidFrontendSpecRoot(raw))
+                continue;
+            roots.add(isValidOpenspecExtension(raw) ? raw.split("/").slice(0, -1).join("/") : raw);
+        }
+    }
+    return [...roots].filter(isValidFrontendSpecRoot).sort();
+}

package/dist/shared/operator/capabilities.js

@@ -2240,6 +2240,13 @@ export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
         source: "loop-agent",
         note: "server-side read-only run-facts check (ineligible plan / explicit rerun-task recommendation) replaces the browser Human Gate (2026-08-11).",
     },
+    {
+        command: "loop-agent dag follow-up",
+        coverage: "excluded",
+        action: null,
+        source: "loop-agent",
+        exclusionReason: "Frontend review recovery helper is a direct advanced CLI composition (create/import task and optional advance), not an Operator action endpoint.",
+    },
     {
         command: "loop-agent dag reconcile-tasks",
         coverage: "human-gated-required",

package/dist/task/config-types.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { isOpenspecSpecFilePath } from "../shared/openspec-spec.js";
+import { DEFAULT_FRONTEND_SPEC_ROOTS, isFrontendSpecFilePath, isValidFrontendSpecRoot, } from "../shared/openspec-spec.js";
 export const taskFlowSchema = z.enum([
     "auto",
     "micro",
@@ -77,13 +77,27 @@ export const frontendOpenspecPolicySchema = z.enum(["cited", "scan-strict"]);
  */
 export const frontendOpenspecConfigSchema = z.object({
     policy: frontendOpenspecPolicySchema.optional().default("cited"),
+    /**
+     * Repo-relative directories containing frontend normative files. These are
+     * frozen in task.json during contract preparation, before DAG generation.
+     */
+    specRoots: z
+        .array(z.string().refine((candidate) => isValidFrontendSpecRoot(candidate), "frontendOpenspec.specRoots entries must be normalized repo-relative directories"))
+        .optional(),
     requiredReadPaths: z
-        .array(z
-        .string()
-        .refine((candidate) => !candidate.includes("\\") &&
-        isOpenspecSpecFilePath(candidate), "frontendOpenspec.requiredReadPaths entries must be repo-relative supported files under openspec/schemas/, openspec/project-specs/, or ai_workspace/"))
+        .array(z.string())
         .optional()
         .default([]),
+}).superRefine((value, ctx) => {
+    const roots = value.specRoots ?? DEFAULT_FRONTEND_SPEC_ROOTS;
+    if (new Set(roots).size !== roots.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "frontendOpenspec.specRoots must not contain duplicates", path: ["specRoots"] });
+    }
+    for (const required of value.requiredReadPaths) {
+        if (!isFrontendSpecFilePath(required, roots)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "frontendOpenspec.requiredReadPaths entries must be repo-relative supported files under frontendOpenspec.specRoots", path: ["requiredReadPaths"] });
+        }
+    }
 });
 /** Batch limits and gate profile for the browser-driven frontend test DAG.
  * Token fields are post-case stop thresholds, not model-provider hard caps. */
@@ -131,6 +145,75 @@ export const frontendTestConfigSchema = z.object({
         .strict()
         .optional(),
 });
+const backendTestBudgetProofSchema = z
+    .object({
+    groupId: z.string().min(1),
+    estimatedCaseCount: z.number().int().positive(),
+    estimatedTestPointCount: z.number().int().positive(),
+    estimatedOutputChars: z.number().int().positive(),
+    maxOutputCharsPerWriter: z.number().int().positive(),
+    estimatorVersion: z.literal("backend-test-output-estimator-v1"),
+    inputSha256: z.string().regex(/^[a-f0-9]{64}$/),
+})
+    .strict();
+const backendTestModuleLayoutEntrySchema = z
+    .object({
+    stem: z.string().regex(/^[a-z][a-z0-9_]*$/),
+    businessResource: z.string().min(1),
+    markdownPath: z.string().min(1),
+    pytestPath: z.string().min(1),
+    ownedOperations: z.array(z.string().regex(/^(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) \/\S+$/)).min(1),
+    splitReason: z.enum([
+        "explicit-user-layout",
+        "primary-business-resource",
+        "independent-business-resource",
+        "output-budget",
+    ]),
+    budgetProof: backendTestBudgetProofSchema.optional(),
+})
+    .strict()
+    .superRefine((entry, ctx) => {
+    const safe = (value) => !value.startsWith("/") &&
+        !value.startsWith("\\") &&
+        !value.includes("..") &&
+        !value.includes("\\");
+    if (!safe(entry.markdownPath) || !entry.markdownPath.endsWith(".md")) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["markdownPath"], message: "must be a safe repository-relative .md path" });
+    }
+    if (!safe(entry.pytestPath) || !entry.pytestPath.endsWith(".py")) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["pytestPath"], message: "must be a safe repository-relative .py path" });
+    }
+    if (entry.splitReason === "output-budget" && !entry.budgetProof) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["budgetProof"], message: "is required for output-budget split" });
+    }
+    if (entry.splitReason !== "output-budget" && entry.budgetProof) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["budgetProof"], message: "is only valid for output-budget split" });
+    }
+});
+const backendTestModuleLayoutSchema = z
+    .object({
+    schemaId: z.literal("backend-test-module-layout-v1"),
+    mode: z.enum(["explicit-file-layout", "business-resource-layout"]),
+    modules: z.array(backendTestModuleLayoutEntrySchema).min(1).max(8),
+})
+    .strict()
+    .superRefine((layout, ctx) => {
+    for (const key of ["stem", "markdownPath", "pytestPath"]) {
+        const seen = new Set();
+        for (let index = 0; index < layout.modules.length; index += 1) {
+            const value = layout.modules[index][key];
+            if (seen.has(value))
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["modules", index, key], message: `duplicate ${key}` });
+            seen.add(value);
+        }
+    }
+    if (layout.mode === "explicit-file-layout") {
+        layout.modules.forEach((entry, index) => {
+            if (entry.splitReason !== "explicit-user-layout")
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["modules", index, "splitReason"], message: "explicit-file-layout requires explicit-user-layout" });
+        });
+    }
+});
 /** Backend-test artifact layout and pipeline mode configuration (plan A/B/D). */
 export const backendTestConfigSchema = z
     .object({
@@ -152,6 +235,8 @@ export const backendTestConfigSchema = z
     workspaceControl: z.enum(["git", "filesystem-only"]).optional(),
     /** Per-command timeout for the readiness-authorized pytest/HTML execution node. */
     executeTimeoutMs: z.number().int().min(60_000).max(7_200_000).optional(),
+    /** Optional strict physical/business module layout; authoritative over model-derived layout. */
+    moduleLayout: backendTestModuleLayoutSchema.optional(),
 })
     .strict()
     .optional();
@@ -210,6 +295,21 @@ const taskConfigObjectSchema = z.object({
     maxFixLoops: z.number().int().min(0).optional().default(2),
     /** Supervised DAG convergence is opt-in until runtime smoke evidence is stronger. */
     convergence: convergenceConfigSchema.optional().default({ enabled: false }),
+    /** Frontend recovery continuation quota. Bounds how many times a failed
+     * frontend run may auto-recover via M6 recovery operations (1 = current
+     * default; raise to 2-3 for more tolerance of transient verify failures). */
+    frontendRecovery: z
+        .object({
+        maxContinuations: z
+            .number()
+            .int()
+            .min(1)
+            .max(5)
+            .optional()
+            .default(1),
+    })
+        .strict()
+        .optional(),
     /** Outer loop auto mode never writes by default; DAG execute requires this policy plus path/writeSet gates. */
     loopAutoExecutionPolicy: loopAutoExecutionPolicySchema
         .optional()

package/dist/task/contract/adopt.js

@@ -90,6 +90,10 @@ export async function adoptTaskContract(input) {
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(state.ref?.sourceHashes.requirementLedgerSha256 &&
+                bytes.requirementLedgerBytes !== null
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({

package/dist/task/contract/import-revision.js

@@ -45,6 +45,10 @@ export async function refreshManagedContractAfterImport(input) {
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(state2.ref.sourceHashes.requirementLedgerSha256 &&
+                bytes.requirementLedgerBytes !== null
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({

package/dist/task/contract/project.js

@@ -184,6 +184,9 @@ export function mergeManagedTaskConfigFields(existing, draft) {
             command: cmd.command,
             ...(cmd.timeoutMs !== undefined ? { timeoutMs: cmd.timeoutMs } : {}),
         })),
+        ...(draft.frontendOpenspec !== undefined
+            ? { frontendOpenspec: draft.frontendOpenspec }
+            : {}),
     };
     if (draft.featureId !== undefined) {
         next.featureId = draft.featureId;

package/dist/task/contract/schema.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { backendTestConfigSchema, taskKindSchema, taskVerifyCommandSchema, } from "../config-types.js";
+import { backendTestConfigSchema, frontendOpenspecConfigSchema, taskKindSchema, taskVerifyCommandSchema, } from "../config-types.js";
 import { TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_CANONICALIZER_VERSION, TASK_CONTRACT_DRAFT_SCHEMA_VERSION, TASK_CONTRACT_PROJECTION_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
 const sha256Schema = z
     .string()
@@ -74,6 +74,7 @@ export const taskContractDraftSchema = z
     openQuestions: z.array(z.string()).optional(),
     assumptions: z.array(z.string()).optional(),
     hardConstraints: z.array(z.string()).optional(),
+    frontendOpenspec: frontendOpenspecConfigSchema.optional(),
     interviewAssessmentRef: z
         .object({
         draftSha256: z.string().min(1),