@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.3

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

@@ -98,6 +98,13 @@ export function isEphemeralToolCachePath(filePath) {
     const normalized = normalizePath(filePath);
     if (!normalized)
         return false;
+    // CodeGraph extension sync side effect (plan 2026-08-21 D7): a loaded
+    // pi-codegraph extension keeps an existing .codegraph/ index fresh at
+    // session start; those index files are extension-owned run state, not
+    // writer output, so they never count as write-guard violations.
+    if (normalized === ".codegraph" || normalized.startsWith(".codegraph/")) {
+        return true;
+    }
     if (normalized === ".pytest_cache" ||
         normalized.startsWith(".pytest_cache/")) {
         return true;
@@ -117,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/shared/dag-prompt-override.js

@@ -0,0 +1,28 @@
+/**
+ * Internal switch for the experimental "rerun failed node with an edited
+ * prompt" capability. Default is OFF; nothing may depend on it being enabled.
+ * The switch is deliberately env-based (no harness.json surface) while the
+ * feature is internal.
+ */
+export const DAG_RERUN_PROMPT_OVERRIDE_ENV = "HARNESS_DAG_RERUN_PROMPT_OVERRIDE";
+/** Upper bound for an override input body (characters). */
+export const MAX_DAG_RERUN_PROMPT_OVERRIDE_CHARS = 65_536;
+export function isDagRerunPromptOverrideEnabled(env = process.env) {
+    const value = env[DAG_RERUN_PROMPT_OVERRIDE_ENV];
+    return value === "1" || value === "true";
+}
+export const DAG_RERUN_PROMPT_ADDENDUM_TAG = "operator_addendum";
+/**
+ * Compose the final subtask_prompt for a rerun override.
+ * - "replace": the operator text becomes the whole prompt (advanced mode).
+ * - "append" (recommended): the frozen base prompt is kept verbatim and the
+ *   operator addendum is appended in a clearly marked block, mirroring the
+ *   rerunFeedback / retry_instruction augmentation semantics — small diffs,
+ *   no risk of dropping template scaffolding.
+ */
+export function composeDagPromptOverridePrompt(input) {
+    if (input.mode === "replace") {
+        return input.text;
+    }
+    return `${input.basePrompt}\n\n<${DAG_RERUN_PROMPT_ADDENDUM_TAG}>\n${input.text.trim()}\n</${DAG_RERUN_PROMPT_ADDENDUM_TAG}>\n`;
+}

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

@@ -1155,6 +1155,19 @@ export function buildOperatorCapabilitiesDocument() {
             modelCallable: "always",
             humanConfirmation: "none",
         },
+        {
+            action: "dagPromptOverrideConfig",
+            cli: "console dag-prompt-override-config",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [],
+            description: "Read-only probe of the experimental prompt-override rerun switch (env-gated, default off). The browser Recovery UI hides the failed-node prompt editor unless this returns enabled=true. Never mutates.",
+            inputParams: [],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
         {
             action: "dagRerunPlan",
             cli: "loop-agent dag rerun --run-id <id> --from-node <node> --plan --json",
@@ -1177,6 +1190,12 @@ export function buildOperatorCapabilitiesDocument() {
                     required: true,
                     description: "node id to rerun from (prefer failed/attention node from dagReport primaryFailure.nodeId)",
                 },
+                {
+                    name: "promptOverrides",
+                    type: "array",
+                    required: false,
+                    description: "experimental (switch off by default): [{nodeId, prompt, mode?}] — mode append (recommended) keeps the frozen base prompt and appends the text as a marked addendum block, replace swaps the whole subtask_prompt; only FAILED nodes inside the reset closure are admitted and the planHash binds the composed change",
+                },
             ],
             modelCallable: "always",
             humanConfirmation: "none",
@@ -1219,6 +1238,12 @@ export function buildOperatorCapabilitiesDocument() {
                     required: true,
                     description: "why continue from this node (e.g. provider flake; resume from review-pi)",
                 },
+                {
+                    name: "promptOverrides",
+                    type: "array",
+                    required: false,
+                    description: "experimental (switch off by default): must match the dagRerunPlan promptOverrides exactly (same mode/text); the planHash already binds them, any drift is rejected",
+                },
             ],
             // always: fresh eligible dagRerun plans are model-callable (2026-08-11).
             // The CLI keeps enforcing parent lifecycle, fromNode, planHash,
@@ -1822,6 +1847,13 @@ export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
         source: "loop-agent",
         exclusionReason: "Not exposed to Operator Chat in M5.",
     },
+    {
+        command: "loop-agent init model-catalog",
+        coverage: "excluded",
+        action: null,
+        source: "loop-agent",
+        exclusionReason: "Not exposed to Operator Chat in M5.",
+    },
     {
         command: "loop-agent init doctor",
         coverage: "excluded",

package/dist/shared/playwright-cli-command-policy.js

@@ -9,6 +9,7 @@ export const PLAYWRIGHT_CLI_ALLOWED_COMMANDS = [
     "goto",
     "snapshot",
     "find",
+    "find-unique",
     "click",
     "dblclick",
     "fill",
@@ -35,6 +36,20 @@ export const PLAYWRIGHT_CLI_ALLOWED_COMMANDS = [
     "requests",
     "request",
 ];
+/**
+ * Parse the match count from a playwright-cli find output. The CLI prints
+ * `Found N match(es) for "...":` on success and `No matches found for "...".`
+ * on zero — both with exit code 0, so the count is the only assertion signal.
+ * Returns undefined when the output shape is unrecognized (e.g. error pages).
+ */
+export function parsePlaywrightCliFindMatchCount(output) {
+    const found = /Found\s+(\d+)\s+match(?:es)?\s+for\b/i.exec(output);
+    if (found)
+        return Number(found[1]);
+    if (/No matches found for\b/i.test(output))
+        return 0;
+    return undefined;
+}
 const allowedCommandSet = new Set(PLAYWRIGHT_CLI_ALLOWED_COMMANDS);
 export function isPlaywrightCliCommand(value) {
     return allowedCommandSet.has(value);

package/dist/shared/update/console-notifier.js

@@ -0,0 +1,100 @@
+import { createInterface } from "node:readline/promises";
+import semver from "semver";
+import { acquireUpdateLock, readUpdateState, updateLockPath, updateStatePath, writeUpdateState, } from "./state.js";
+export async function runConsoleDailyUpdateCheck(options) {
+    void options.writeStdout;
+    void options.packageRoot;
+    void options.cwd;
+    const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+    const now = options.now ?? (() => new Date());
+    try {
+        if (!canPromptInteractively(options))
+            return;
+        const statePath = updateStatePath(options.homeDir);
+        const today = formatLocalDate(now());
+        const existing = await readUpdateState(statePath);
+        if (existing.lastPromptedLocalDate === today)
+            return;
+        const release = await acquireUpdateLock(updateLockPath(options.homeDir), {
+            now,
+        });
+        if (!release)
+            return;
+        try {
+            const state = await readUpdateState(statePath);
+            if (state.lastPromptedLocalDate === today)
+                return;
+            const check = await options.client.latestVersionCheck();
+            if (!check.ok)
+                return;
+            if (!semver.gt(check.version, options.currentVersion))
+                return;
+            const parsedLatest = semver.parse(check.version);
+            if (!parsedLatest || parsedLatest.prerelease.length > 0)
+                return;
+            await markPromptedToday(statePath, state, today);
+            const answer = await ask(options, `loop-agent 有新版本：${options.currentVersion} → ${check.version}\n现在更新到 ${check.version}？[y/N] `);
+            if (!isYes(answer))
+                return;
+            const proof = await options.client.canAutoInstall();
+            if (!proof.ok) {
+                writeStderr(`当前 loop-agent 不是由此 npm 的正式全局安装管理，无法自动升级。\n请运行：npm install -g @tea-agent/loop-agent@${check.version}\n`);
+                return;
+            }
+            const install = await options.client.installExact(check.version);
+            if (!install.ok) {
+                writeStderr(`loop-agent 更新失败：${install.reason}\n`);
+                return;
+            }
+            const verified = await options.client.verifyInstalled(check.version);
+            if (!verified.ok) {
+                writeStderr(`loop-agent 已尝试安装，但验证失败：${verified.reason}\n`);
+                return;
+            }
+            writeStderr(`loop-agent 已更新到 ${check.version}；新版本将在下一次命令调用时完全生效。\n`);
+        }
+        finally {
+            await release().catch(() => undefined);
+        }
+    }
+    catch (error) {
+        writeStderr(`loop-agent 更新检查已跳过：${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function canPromptInteractively(options) {
+    if (!options.stdinIsTTY || !options.stderrIsTTY)
+        return false;
+    if (options.env.CI)
+        return false;
+    if (options.env.LOOP_AGENT_DISABLE_UPDATE_CHECK === "1")
+        return false;
+    return true;
+}
+function formatLocalDate(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+async function markPromptedToday(statePath, state, today) {
+    await writeUpdateState(statePath, {
+        ...state,
+        lastPromptedLocalDate: today,
+    });
+}
+async function ask(options, prompt) {
+    if (options.readLine) {
+        options.writeStderr?.(prompt);
+        return options.readLine(prompt);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(prompt);
+    }
+    finally {
+        rl.close();
+    }
+}
+function isYes(answer) {
+    return /^(y|yes)$/i.test(answer.trim());
+}

package/dist/{cli → shared}/update/npm-client.js

@@ -3,25 +3,48 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import semver from "semver";
 const PACKAGE_NAME = "@tea-agent/loop-agent";
+export const DEFAULT_NPM_QUERY_TIMEOUT_MS = 15_000;
 export function createNpmUpdateClient(options) {
     const npmCommand = options.npmCommand ?? "npm";
     const loopAgentCommand = options.loopAgentCommand ?? "loop-agent";
     const runner = options.runner ?? runCommand;
-    const timeoutMs = options.timeoutMs ?? 1500;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_NPM_QUERY_TIMEOUT_MS;
+    const cwd = options.cwd;
     const env = options.env;
+    const latestVersionCheck = async () => {
+        let result;
+        try {
+            result = await runner(npmCommand, ["view", PACKAGE_NAME, "dist-tags.latest", "--json"], { timeoutMs, cwd, env });
+        }
+        catch {
+            return { ok: false, reason: "spawn-failure" };
+        }
+        if (result.timedOut)
+            return { ok: false, reason: "timeout" };
+        if (result.exitCode === null) {
+            return { ok: false, reason: "spawn-failure" };
+        }
+        if (result.exitCode !== 0) {
+            return { ok: false, reason: "command-failed" };
+        }
+        const version = parseNpmViewLatest(result.stdout);
+        return version
+            ? { ok: true, version }
+            : { ok: false, reason: "invalid-response" };
+    };
     return {
         async latestVersion() {
-            const result = await runner(npmCommand, ["view", PACKAGE_NAME, "dist-tags.latest", "--json"], { timeoutMs, env });
-            if (result.exitCode !== 0 || result.timedOut)
-                return undefined;
-            return parseNpmViewLatest(result.stdout);
+            const result = await latestVersionCheck();
+            return result.ok ? result.version : undefined;
         },
+        latestVersionCheck,
         async canAutoInstall() {
             return proveGlobalNpmInstall({
                 currentVersion: options.currentVersion,
                 packageRoot: options.packageRoot,
                 npmCommand,
                 runner,
+                cwd,
                 env,
                 timeoutMs,
             });
@@ -29,17 +52,25 @@ export function createNpmUpdateClient(options) {
         async installExact(version) {
             if (!isStrictRelease(version))
                 return { ok: false, reason: "invalid-version" };
-            const result = await runner(npmCommand, buildExactInstallArgs(version), { timeoutMs: Math.max(timeoutMs, 120000), env });
+            const result = await runner(npmCommand, buildExactInstallArgs(version), {
+                timeoutMs: Math.max(timeoutMs, 120000),
+                cwd,
+                env,
+            });
             if (result.exitCode !== 0 || result.timedOut)
                 return { ok: false, reason: "install-failed" };
             return { ok: true };
         },
         async verifyInstalled(version) {
-            const list = await runner(npmCommand, ["list", "-g", PACKAGE_NAME, "--depth=0", "--json"], { timeoutMs, env });
+            const list = await runner(npmCommand, ["list", "-g", PACKAGE_NAME, "--depth=0", "--json"], { timeoutMs, cwd, env });
             if (list.exitCode !== 0 || !verifyNpmListVersion(list.stdout, version)) {
                 return { ok: false, reason: "npm-list-version-mismatch" };
             }
-            const pathVersion = await runner(loopAgentCommand, ["--version"], { timeoutMs, env });
+            const pathVersion = await runner(loopAgentCommand, ["--version"], {
+                timeoutMs,
+                cwd,
+                env,
+            });
             if (pathVersion.exitCode !== 0 || !verifyPathVersion(pathVersion.stdout, version)) {
                 return { ok: false, reason: "path-version-mismatch" };
             }
@@ -80,6 +111,7 @@ export function verifyPathVersion(stdout, expectedVersion) {
 async function proveGlobalNpmInstall(options) {
     const root = await options.runner(options.npmCommand, ["root", "-g"], {
         timeoutMs: options.timeoutMs,
+        cwd: options.cwd,
         env: options.env,
     });
     if (root.exitCode !== 0 || root.timedOut)
@@ -113,6 +145,7 @@ function isStrictRelease(version) {
 async function runCommand(command, args, options) {
     return new Promise((resolve) => {
         const child = spawn(command, [...args], {
+            cwd: options.cwd,
             env: options.env ? { ...process.env, ...options.env } : process.env,
             stdio: ["ignore", "pipe", "pipe"],
             shell: false,

package/dist/{cli → shared}/update/state.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 export function updateStatePath(homeDir) {
     return path.join(homeDir, ".loop-agent", "update-state.json");
@@ -18,6 +18,7 @@ export async function readUpdateState(statePath) {
             latestVersion: stringOrUndefined(parsed.latestVersion),
             dismissedVersion: stringOrUndefined(parsed.dismissedVersion),
             retryAfter: stringOrUndefined(parsed.retryAfter),
+            lastPromptedLocalDate: stringOrUndefined(parsed.lastPromptedLocalDate),
         };
     }
     catch {
@@ -36,28 +37,55 @@ export async function acquireUpdateLock(lockPath, options = {}) {
     await mkdir(path.dirname(lockPath), { recursive: true });
     try {
         await mkdir(lockPath);
+        return await claimLock(lockPath, now);
+    }
+    catch {
+        if (await isFreshLock(lockPath, now, staleMs))
+            return undefined;
+        try {
+            await rm(lockPath, { recursive: true, force: true });
+            await mkdir(lockPath);
+            return await claimLock(lockPath, now);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+async function claimLock(lockPath, now) {
+    try {
         await writeFile(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: now().toISOString() }), "utf-8");
         return async () => {
             await rm(lockPath, { recursive: true, force: true });
         };
     }
+    catch {
+        await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+        return undefined;
+    }
+}
+async function isFreshLock(lockPath, now, staleMs) {
+    try {
+        const ownerRaw = await readFile(path.join(lockPath, "owner.json"), "utf-8");
+        const owner = JSON.parse(ownerRaw);
+        if (typeof owner.at !== "string")
+            return false;
+        const at = Date.parse(owner.at);
+        if (!Number.isFinite(at))
+            return false;
+        return now().getTime() - at <= staleMs;
+    }
     catch {
         try {
-            const ownerRaw = await readFile(path.join(lockPath, "owner.json"), "utf-8");
-            const owner = JSON.parse(ownerRaw);
-            if (owner.at && now().getTime() - Date.parse(owner.at) > staleMs) {
-                await rm(lockPath, { recursive: true, force: true });
-                await mkdir(lockPath);
-                await writeFile(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: now().toISOString() }), "utf-8");
-                return async () => {
-                    await rm(lockPath, { recursive: true, force: true });
-                };
-            }
+            const info = await stat(lockPath);
+            const mtime = Number.isFinite(info.mtimeMs)
+                ? info.mtimeMs
+                : info.mtime.getTime();
+            return now().getTime() - mtime <= staleMs;
         }
         catch {
-            return undefined;
+            return false;
         }
-        return undefined;
     }
 }
 function emptyState() {

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",
@@ -76,13 +76,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. */

package/dist/task/contract/project.js

@@ -170,6 +170,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),