@foldrun/core 2.5.0 → 2.6.0

package/dist/src/agent-import.js

@@ -14,7 +14,7 @@
 // were about somebody else's desk.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "./matter.js";
+import { configMatter } from "./matter.js";
 import { assertSafeName, listWorkspaceFiles, readWorkspaceFile, writeWorkspaceFile, workspaceDir, workspaceTools, listWorkspaces, } from "./store.js";
 import { libraryDir, libraryTools } from "./library.js";
 import { isRuntimeTool, toolEntryName } from "./tool-names.js";
@@ -64,7 +64,7 @@ export function importAgent(tenant, from, agent, to, opts = {}) {
         let content = readWorkspaceFile(tenant, from, src);
         const rel = src.slice(`agents/${agent}/`.length);
         if (rel === "agent.md") {
-            front = matter(content).data;
+            front = configMatter(content).data;
             // The folder is the name flows address; a `name:` that disagrees with
             // it is the first thing check would complain about.
             if (name !== agent)

package/dist/src/agent-tools.js

@@ -16,7 +16,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import matter from "./matter.js";
+import { configMatter } from "./matter.js";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { resolveModel, resolveEffort } from "./store.js";
@@ -36,7 +36,7 @@ export function gatherConsults(workspaceRoot, names) {
             missing.push(name);
             continue;
         }
-        const parsed = matter(fs.readFileSync(file, "utf8"));
+        const parsed = configMatter(fs.readFileSync(file, "utf8"));
         consults.push({
             name,
             systemPrompt: `${parsed.content.trim()}\n\n` +

package/dist/src/agents-md.d.ts

@@ -1,8 +1,12 @@
+import { keySpan } from "./frontmatter-text.ts";
+export { keySpan };
 /** The frontmatter of a directory's AGENTS.md (or project.md), or {}. */
 export declare function readAgentsMdKeys(dir: string): Record<string, unknown>;
 /** The text of `content` with each key in `patch` replaced (or removed for
  *  null), everything else byte for byte as it was. A file with no
- *  frontmatter gets one. */
+ *  frontmatter gets one. Read back before it is returned (frontmatter-guard
+ *  .ts): an edit that would not parse, would change another key or would
+ *  double one into its block throws UnsafeEditError (409). */
 export declare function patchFrontmatter(content: string, patch: Record<string, unknown | null>): string;
 /** Apply a frontmatter patch to a directory's AGENTS.md, creating the file
  *  when the directory has none. Returns the new content. */

package/dist/src/agents-md.js

@@ -8,7 +8,11 @@
 // else in the file is untouched. Null removes the key.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "./matter.js";
+import matter, { configMatter } from "./matter.js";
+import { keySpan, dropEmptyBlock } from "./frontmatter-text.js";
+import { guardEdit } from "./frontmatter-guard.js";
+import { JOBS, FOLDABLE } from "./frontmatter-fields.js";
+export { keySpan };
 const FRONT = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n|$)/;
 /** The frontmatter of a directory's AGENTS.md (or project.md), or {}. */
 export function readAgentsMdKeys(dir) {
@@ -17,7 +21,7 @@ export function readAgentsMdKeys(dir) {
         if (!fs.existsSync(file))
             continue;
         try {
-            return (matter(fs.readFileSync(file, "utf8")).data ?? {});
+            return (configMatter(fs.readFileSync(file, "utf8")).data ?? {});
         }
         catch {
             return {};
@@ -34,8 +38,33 @@ function dumpKey(key, value) {
 }
 /** The text of `content` with each key in `patch` replaced (or removed for
  *  null), everything else byte for byte as it was. A file with no
- *  frontmatter gets one. */
+ *  frontmatter gets one. Read back before it is returned (frontmatter-guard
+ *  .ts): an edit that would not parse, would change another key or would
+ *  double one into its block throws UnsafeEditError (409). */
 export function patchFrontmatter(content, patch) {
+    // The guard reads the result folded (matter.ts configMatter), so a patch
+    // that writes a whole job block is checked as the keys it holds: each
+    // field the block may hold may change, and each one it sets reads back.
+    const changed = new Set();
+    const expect = {};
+    for (const [key, value] of Object.entries(patch)) {
+        changed.add(key);
+        const job = JOBS.find((j) => j.name === key)?.name;
+        if (!job) {
+            expect[key] = value;
+            continue;
+        }
+        for (const k of FOLDABLE[job])
+            changed.add(k);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            for (const [k, v] of Object.entries(value))
+                if (FOLDABLE[job].has(k))
+                    expect[k] = v;
+        }
+    }
+    return guardEdit(content, patchFrontmatterText(content, patch), [...changed], expect);
+}
+function patchFrontmatterText(content, patch) {
     const m = content.match(FRONT);
     let open = "---\n";
     let body = "";
@@ -50,22 +79,17 @@ export function patchFrontmatter(content, patch) {
     }
     let lines = body === "" ? [] : body.split("\n");
     for (const [key, value] of Object.entries(patch)) {
-        const at = lines.findIndex((l) => new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`).test(l));
-        let end = at;
-        if (at !== -1) {
-            end = at + 1;
-            // The block continues while lines are indented or blank-inside-block.
-            while (end < lines.length && (/^[ \t]/.test(lines[end]) || lines[end].trim() === ""))
-                end++;
-            // A blank line at the block's foot belongs to what follows.
-            while (end > at + 1 && lines[end - 1].trim() === "")
-                end--;
-        }
-        const replacement = value === null || value === undefined ? [] : dumpKey(key, value);
-        if (at === -1)
+        // Where it is written now — at the top or inside its job block — is
+        // where it is edited; a key written nowhere is added at the top.
+        const where = keySpan(lines, key);
+        const replacement = value === null || value === undefined ? [] : dumpKey(key, value).map((l) => `${where?.indent ?? ""}${l}`);
+        if (!where)
             lines = [...lines, ...replacement];
-        else
-            lines = [...lines.slice(0, at), ...replacement, ...lines.slice(end)];
+        else {
+            lines = [...lines.slice(0, where.at), ...replacement, ...lines.slice(where.end)];
+            if (!replacement.length && where.block !== null)
+                lines = dropEmptyBlock(lines, where.block);
+        }
     }
     const front = lines.length ? `${open}${lines.join("\n")}${close}` : "";
     if (!front)

package/dist/src/completions.js

@@ -9,7 +9,7 @@
 // go here. No React, no fetch — so the rules are testable and one component
 // renders them.
 import { PROVIDERS } from "./providers.js";
-import { FRONTMATTER } from "./frontmatter-fields.js";
+import { FRONTMATTER, JOBS, fieldsOfJob } from "./frontmatter-fields.js";
 const MODELS = [
     { label: "fast", hint: "haiku — cheap, for checks and triage" },
     { label: "default", hint: "sonnet — the working default" },
@@ -587,8 +587,30 @@ export function completionsAt(path, text, cursor, vocab) {
             };
         }
     }
-    // 6. An indented option under a flow step.
-    if (kind === "flow" && /^\s+[a-z]*$/.test(line) && line.trim().length >= 0) {
+    // 5b. An indented line inside one of the four job blocks (governance,
+    //     guardrail, observability, evaluation): that job's fields for this
+    //     kind of file — the block takes nothing else.
+    const fmClose = text.indexOf("\n---", text.indexOf("---") + 3);
+    const insideFrontmatter = text.startsWith("---") && (fmClose === -1 || cursor <= fmClose);
+    const nested = line.match(/^(\s+)([a-zA-Z_]*)$/);
+    if (insideFrontmatter && nested) {
+        const header = before.slice(0, lineStart).split("\n").reverse().find((l) => /^\S/.test(l));
+        const job = JOBS.find((j) => new RegExp(`^${j.name}\\s*:\\s*$`).test(header ?? ""));
+        if (job) {
+            const schemaKind = /(^|\/)AGENTS\.md$/.test(path) || path === "project.md" ? "agents-md" : SCHEMA_OF[kind];
+            const keys = new Set(schemaKind ? fieldsOfJob(schemaKind, job.name) : []);
+            const partial = nested[2] ?? "";
+            return {
+                from: cursor - partial.length,
+                query: partial,
+                items: filter(fieldsFor(path, kind).filter((c) => keys.has(c.label.split(".")[0])), partial),
+                title: `${job.title} — ${job.what}`,
+            };
+        }
+    }
+    // 6. An indented option under a flow step — the body's steps, never a
+    //    line inside the frontmatter.
+    if (kind === "flow" && !insideFrontmatter && /^\s+[a-z]*$/.test(line) && line.trim().length >= 0) {
         const partial = line.trim();
         return {
             from: cursor - partial.length,

package/dist/src/deploy.js

@@ -23,21 +23,24 @@ import path from "node:path";
 import { saveWorkspace, keptOnDeploy, workspaceDir, listRunSummaries, listWorkspaceFiles, parseFlow, parseToolDef, WORKSPACE_DIRS, assertSafeName, accountDir, frontmatterErrorText, } from "./store.js";
 import { readAgentsMdKeys } from "./agents-md.js";
 import { libraryTools } from "./library.js";
-import { lintFlow } from "./flow-lint.js";
+import { lintFlow, regexProblem } from "./flow-lint.js";
+import { parseEval } from "./evals.js";
 import { refNames } from "./refs.js";
-import matter from "./matter.js";
+import matter, { configMatter } from "./matter.js";
+import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.js";
 import { conformanceIssues } from "./okf.js";
 import { timezoneProblem } from "./clock.js";
 import { webProblems, webWarnings, runnerEngines } from "./providers.js";
 import { readLimits } from "./limits.js";
 import { parseAlerts } from "./alerts.js";
 import { parseTelemetry } from "./otel-config.js";
+import { parseJudge } from "./judge-verdict.js";
 import { networkProblems } from "./network.js";
 import { actionProblems } from "./web-actions.js";
 import { languageProblem } from "./language.js";
 import { localeProblems } from "./locale.js";
 import { entriesNoFollow } from "./paths.js";
-import { filterIgnored, findingFingerprint, ruleForWhere, scanFiles, scanRule } from "./scan.js";
+import { filterIgnored, findingFingerprint, ruleForWhere, scanFiles, scanRule, STRICT_FRONTMATTER_PATH } from "./scan.js";
 /** Directories a deploy never reads out of a source tree. */
 // `.cache` is what a run's tools leave in an agent's folder (HOME is that
 // folder): logs and font caches, never authored.
@@ -255,7 +258,7 @@ export function deployBlockMode(files, accountKeys) {
     let fromWorkspace = null;
     if (own) {
         try {
-            fromWorkspace = blockMode(matter(own.content).data.deploy_block);
+            fromWorkspace = blockMode(configMatter(own.content).data.deploy_block);
         }
         catch {
             // an AGENTS.md that does not parse is reported elsewhere
@@ -394,6 +397,41 @@ function structuralWarnings(files, extraOutward = []) {
         for (const w of webWarnings(data, { chrome, chromium }))
             out.push({ where: f.path, message: w });
     }
+    // An eval's `matches:` is the same JavaScript RegExp as a verify's; one
+    // that does not compile fails its case on every run. Read through
+    // parseEval, so a block scalar (`matches: |`) or a continued line is
+    // tested as the runtime will run it. The line is the item's own: the
+    // parsed assertions and the `- matches:` lines come in the same order.
+    for (const f of files) {
+        if (!/^evals\/[^/]+\.md$/.test(f.path))
+            continue;
+        let info;
+        try {
+            info = parseEval(f.path, f.content);
+        }
+        catch {
+            continue;
+        }
+        const lines = [];
+        f.content.split("\n").forEach((line, n) => { if (/^\s*-\s*matches:/.test(line))
+            lines.push(n + 1); });
+        // When a `- matches:` line sits outside a case (an example in the
+        // prose), the order no longer pairs up: name the file, not a wrong line.
+        const parsed = info.cases.reduce((n, c) => n + c.expect.filter((a) => a.type === "matches").length, 0);
+        const pairs = lines.length === parsed;
+        let k = 0;
+        for (const c of info.cases) {
+            for (const a of c.expect) {
+                if (a.type !== "matches")
+                    continue;
+                const at = pairs ? lines[k] : undefined;
+                k++;
+                const problem = regexProblem(a.value);
+                if (problem)
+                    out.push({ where: at ? `${f.path}:${at}` : f.path, message: `case "${c.name}": matches: ${problem}` });
+            }
+        }
+    }
     if (!outwardAgents.length)
         return out;
     for (const f of files) {
@@ -446,10 +484,11 @@ export function deployIssues(files) {
     // nothing said so — gray-matter's cache let a second parse pass — and one
     // such agent file kept the worker from booting for every account.
     // Definition files only: a skill is read leniently (an unquoted colon is
-    // quoted and retried, runner.ts safeMatter), and the markdown beside a
+    // quoted and retried, matter.ts parseLenient), and the markdown beside a
     // definition — references, a tool's README — is prose, not frontmatter.
+    // The scanner warns about skills and library files (config/invalid-frontmatter).
     for (const f of files) {
-        if (!/^(AGENTS\.md|agents\/[^/]+\/agent\.md|flows\/[^/]+\.md|tools\/[^/]+\.md|tools\/[^/]+\/tool\.md|evals\/[^/]+\.md|hooks\/[^/]+\/hook\.md|\.claude\/agents\/[^/]+\.md)$/.test(f.path))
+        if (!STRICT_FRONTMATTER_PATH.test(f.path))
             continue;
         if (!/^\uFEFF?---\r?\n/.test(f.content))
             continue;
@@ -460,6 +499,29 @@ export function deployIssues(files) {
             at(f.path, frontmatterErrorText(err));
         }
     }
+    // The four job blocks (frontmatter-fields.ts JOB_FIELDS): a setting
+    // written both at the top and in its block, or in another job's block, is
+    // a setting that does not do what the file says — a guardrail under
+    // governance: guards nothing — so the deploy refuses it as check does
+    // (config/conflict, config/misplaced; Codex debate, 21 Oct 2026).
+    for (const f of files) {
+        const kind = schemaKindOf(f.path);
+        if (kind !== "agent" && kind !== "flow" && kind !== "agents-md")
+            continue;
+        if (!/^\uFEFF?---\r?\n/.test(f.content))
+            continue;
+        let front;
+        try {
+            front = configMatter(f.content).data;
+        }
+        catch {
+            continue; // unparseable frontmatter is its own report
+        }
+        for (const p of frontmatterProblems(kind, front, () => null)) {
+            if (p.level === "error" && (p.rule === "config/conflict" || p.rule === "config/misplaced"))
+                at(f.path, `${p.message} [${p.rule}]`);
+        }
+    }
     // `timezone:` is read at four levels and a value nothing can parse falls
     // silently through to the level above — so it is refused where it was
     // written, not discovered as a date that is a day out.
@@ -471,7 +533,7 @@ export function deployIssues(files) {
             at(f.path, unopened);
         let front = {};
         try {
-            front = matter(f.content).data;
+            front = configMatter(f.content).data;
         }
         catch {
             continue; // unparseable frontmatter is its own report
@@ -502,6 +564,9 @@ export function deployIssues(files) {
         // written into it would ship in the file.
         for (const w of parseTelemetry(front.telemetry).problems)
             at(f.path, w);
+        // `judge:` that cannot be read would leave every judge on the default.
+        for (const w of parseJudge(front.judge).problems)
+            at(f.path, w);
         const lang = languageProblem(front.language);
         if (lang)
             at(f.path, lang);

package/dist/src/evals.d.ts

@@ -49,8 +49,20 @@ export interface EvalInfo {
     inputs: boolean;
     cases: EvalCase[];
 }
-export declare function parseEval(file: string, raw: string): EvalInfo;
+/** `defaults`: the workspace's `judge:` (AGENTS.md), used where the eval
+ *  names no model or effort of its own. */
+export declare function parseEval(file: string, raw: string, defaults?: {
+    model?: string;
+    effort?: string;
+}): EvalInfo;
 export declare function listEvals(tenant: string, workspace: string): EvalInfo[];
+/** `judge:` from AGENTS.md, field by field: the workspace's model (or
+ *  effort), else the account's — so a workspace that sets only an effort
+ *  keeps the account's model (Codex debate: the form says so). */
+export declare function judgeDefaults(tenant: string, workspace: string): {
+    model?: string;
+    effort?: string;
+};
 /**
  * Turn a finished run into a regression case.
  *
@@ -105,6 +117,15 @@ export interface EvalResult {
      *  answers. */
     error?: string;
 }
+/**
+ * The judge's environment: this process's, with the platform's model
+ * credential read live. The process's own CLAUDE_CODE_OAUTH_TOKEN is the copy
+ * it was handed at boot; the box refreshes the login every four hours and the
+ * old token is then revoked, so a judge on the boot copy failed with "OAuth
+ * token revoked" from the first refresh until the pod restarted, while the
+ * agent steps (which read the live file) kept working (2026-10-21).
+ */
+export declare function judgeProcessEnv(): Record<string, string | undefined>;
 export declare function runEval(tenant: string, workspace: string, info: EvalInfo): Promise<EvalResult>;
 /**
  * The latest result, and one line of history.

package/dist/src/evals.js

@@ -32,14 +32,17 @@
 // wrong.
 import { accountModelEnv, withModelEnv } from "./model-env.js";
 import { sdkEnv } from "./step-exec.js";
+import { platformModelEnv } from "./runner.js";
 import fs from "node:fs";
 import path from "node:path";
 import { deployedCommit } from "./deploy.js";
 import { latestRevisionId } from "./history.js";
 import matter from "./matter.js";
 import { spawn } from "node:child_process";
+import { judgeVerdict, JUDGE_VERDICT_INSTRUCTION, parseJudge } from "./judge-verdict.js";
+import { readAgentsMdKeys } from "./agents-md.js";
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import { workspaceDir, readRun, runVerdict, writeWorkspaceFile, resolveModel, resolveEffort, assertSafeName, } from "./store.js";
+import { workspaceDir, accountDir, readRun, runVerdict, writeWorkspaceFile, resolveModel, resolveEffort, assertSafeName, } from "./store.js";
 import { startFlowRun, loadFlow } from "./runner.js";
 import { platform, platformQueues } from "./platform.js";
 const ASSERTION_TYPES = ["contains", "not-contains", "matches", "file", "run", "judge"];
@@ -85,7 +88,9 @@ function readScalar(lines, start, inline, indent) {
     const first = inline.trim().replace(/^["']|["']$/g, "");
     return { value: [first, ...parts].join(" ").trim(), end: i };
 }
-export function parseEval(file, raw) {
+/** `defaults`: the workspace's `judge:` (AGENTS.md), used where the eval
+ *  names no model or effort of its own. */
+export function parseEval(file, raw, defaults = {}) {
     const { data, content } = matter(raw);
     const cases = [];
     let current = null;
@@ -137,8 +142,8 @@ export function parseEval(file, raw) {
         file,
         agent: typeof data.agent === "string" ? data.agent : null,
         flow: typeof data.flow === "string" ? data.flow : null,
-        model: resolveModel(data.model ?? "fast"),
-        effort: resolveEffort(data.effort ?? "low"),
+        model: resolveModel(data.model ?? defaults.model ?? "fast"),
+        effort: resolveEffort(data.effort ?? defaults.effort ?? "low"),
         trigger: data.trigger === "manual" ? "manual" : "deploy",
         live: data.live === true,
         inputs: data.inputs === true,
@@ -153,7 +158,17 @@ export function listEvals(tenant, workspace) {
         .readdirSync(dir)
         .filter((f) => f.endsWith(".md"))
         .sort()
-        .map((f) => parseEval(f, fs.readFileSync(path.join(dir, f), "utf8")));
+        .map((f) => parseEval(f, fs.readFileSync(path.join(dir, f), "utf8"), judgeDefaults(tenant, workspace)));
+}
+/** `judge:` from AGENTS.md, field by field: the workspace's model (or
+ *  effort), else the account's — so a workspace that sets only an effort
+ *  keeps the account's model (Codex debate: the form says so). */
+export function judgeDefaults(tenant, workspace) {
+    const ws = parseJudge(readAgentsMdKeys(workspaceDir(tenant, workspace)).judge);
+    const account = parseJudge(readAgentsMdKeys(accountDir(tenant)).judge);
+    const model = ws.model ?? account.model;
+    const effort = ws.effort ?? account.effort;
+    return { ...(model ? { model } : {}), ...(effort ? { effort } : {}) };
 }
 // ---------- promoting a run ----------
 /** An error a route can turn into the right status without knowing HTTP. */
@@ -365,12 +380,14 @@ function shell(command, cwd) {
         child.on("error", (err) => resolve({ code: null, out: String(err) }));
     });
 }
-// The judge gets the rubric and the output, and must answer with one word.
+// The judge gets the rubric and the output, and ends with one word.
 // Constrained output beats asking for a score: "PASS" or "FAIL" can't be
-// misread, where "7/10" needs a threshold nobody agreed on.
+// misread, where "7/10" needs a threshold nobody agreed on. The word comes
+// LAST, after the reasoning: asked for it first, the judge committed before
+// it had looked, then argued the other way — "FAIL … which meets the
+// criterion" (vaza evals, 21 Oct 2026).
 async function judge(rubric, output, model, effort, env) {
-    const prompt = `You are grading one piece of output against one criterion. Answer with exactly ` +
-        `PASS or FAIL on the first line, then one short sentence of reason.\n\n` +
+    const prompt = `You are grading one piece of output against one criterion. ${JUDGE_VERDICT_INSTRUCTION}\n\n` +
         `Criterion: ${rubric}\n\n<output>\n${output.slice(0, 20000)}\n</output>`;
     let text = "";
     const q = query({
@@ -396,7 +413,19 @@ async function judge(rubric, output, model, effort, env) {
     }
     return text.trim();
 }
-async function checkAssertion(assertion, output, agentDir, model, effort, judgeEnv = () => ({ env: sdkEnv(undefined) })) {
+/**
+ * The judge's environment: this process's, with the platform's model
+ * credential read live. The process's own CLAUDE_CODE_OAUTH_TOKEN is the copy
+ * it was handed at boot; the box refreshes the login every four hours and the
+ * old token is then revoked, so a judge on the boot copy failed with "OAuth
+ * token revoked" from the first refresh until the pod restarted, while the
+ * agent steps (which read the live file) kept working (2026-10-21).
+ */
+export function judgeProcessEnv() {
+    const live = Object.fromEntries(Object.entries(platformModelEnv()).filter(([, v]) => v !== undefined));
+    return sdkEnv({ ...process.env, ...live });
+}
+async function checkAssertion(assertion, output, agentDir, model, effort, judgeEnv = () => ({ env: judgeProcessEnv() })) {
     const hay = output.toLowerCase();
     switch (assertion.type) {
         case "contains": {
@@ -438,9 +467,9 @@ async function checkAssertion(assertion, output, agentDir, model, effort, judgeE
             catch (err) {
                 return { assertion, passed: false, detail: `judge not run — ${err instanceof Error ? err.message : String(err)}` };
             }
-            const verdict = await withModelEnv(m, (env) => judge(assertion.value, output, model, effort, env));
-            const passed = /^\s*PASS\b/i.test(verdict);
-            return { assertion, passed, detail: verdict.slice(0, 300) || "judge returned nothing" };
+            const text = await withModelEnv(m, (env) => judge(assertion.value, output, model, effort, env));
+            const { passed, detail } = judgeVerdict(text);
+            return { assertion, passed, detail };
         }
     }
 }
@@ -509,7 +538,7 @@ export async function runEval(tenant, workspace, info) {
             for (const a of cheap)
                 assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort));
             if (assertions.every((r) => r.passed)) {
-                const judgeEnv = () => accountModelEnv(tenant, workspace, () => sdkEnv(undefined));
+                const judgeEnv = () => accountModelEnv(tenant, workspace, judgeProcessEnv);
                 for (const a of judges)
                     assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort, judgeEnv));
             }

package/dist/src/flow-lint.d.ts

@@ -25,4 +25,18 @@ export interface KnownNames {
      *  rule is skipped rather than guessed at. */
     outwardAgents?: string[];
 }
+/** A `verify:` that is a claim in English rather than a command. Conservative
+ *  on purpose, the same bargain as REFERS_BACK: it must have no assertion
+ *  prefix, nothing shell-shaped anywhere in it, and enough words to be a
+ *  sentence — so a bare `./check.sh` or a one-word command is left alone and
+ *  the warning only fires where the author plainly wrote prose. */
+/**
+ * Why a `matches:` pattern will not compile, or null when it does. The
+ * runtime tests it as a JavaScript RegExp with the `i` flag (step-exec.ts,
+ * evals.ts), and a pattern that throws fails its check on every run with
+ * "invalid regular expression". The usual cause is another dialect: on
+ * 2026-10-21 Python's inline `(?m)` broke five eval checks on vaza, and
+ * nothing said so before they ran.
+ */
+export declare function regexProblem(pattern: string): string | null;
 export declare function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[];

package/dist/src/flow-lint.js

@@ -54,6 +54,27 @@ const LOOKS_LIKE_SHELL = /&&|\|\||\s\|\s|\$\(|\$\{|`|\s[<>]\s|\d?>[>&]?\s|^\[|^[
  *  prefix, nothing shell-shaped anywhere in it, and enough words to be a
  *  sentence — so a bare `./check.sh` or a one-word command is left alone and
  *  the warning only fires where the author plainly wrote prose. */
+/**
+ * Why a `matches:` pattern will not compile, or null when it does. The
+ * runtime tests it as a JavaScript RegExp with the `i` flag (step-exec.ts,
+ * evals.ts), and a pattern that throws fails its check on every run with
+ * "invalid regular expression". The usual cause is another dialect: on
+ * 2026-10-21 Python's inline `(?m)` broke five eval checks on vaza, and
+ * nothing said so before they ran.
+ */
+export function regexProblem(pattern) {
+    try {
+        new RegExp(pattern, "i");
+        return null;
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message.replace(/^Invalid regular expression: /, "") : String(err);
+        const inline = /\(\?[a-z]+\)/.test(pattern)
+            ? " — JavaScript has no inline flags like (?m); write (^|\\n) for the start of a line"
+            : "";
+        return `is not a valid JavaScript regular expression (${why})${inline}`;
+    }
+}
 function looksLikeProse(verify) {
     const v = verify.trim();
     if (!v || VERIFY_ASSERTION.test(v))
@@ -377,6 +398,20 @@ export function lintFlow(flow, known) {
                     "claim, or write it as a shell command that exits 0 when the claim holds.",
             });
         }
+        // A `verify: matches:` the runtime cannot compile fails the step on
+        // every run, whatever the agent did.
+        const verifyRe = step.verify ? /^matches:\s*(.*)$/.exec(step.verify.trim()) : null;
+        // The same normalisation checkVerify applies (step-exec.ts): one quote
+        // off each end, so the pattern checked is the pattern that runs.
+        const reProblem = verifyRe ? regexProblem(verifyRe[1].trim().replace(/^["']|["']$/g, "")) : null;
+        if (reProblem) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `verify: matches: ${reProblem}`,
+                detail: "The runtime tests matches: as a JavaScript regular expression, case-insensitive. One that does not compile fails this step on every run.",
+            });
+        }
         // A step's OTHER agent references — the ones no parser validates,
         // because they are options rather than the step's target. Both fail
         // silently and at the worst possible moment: a misspelled `delegate:`

package/dist/src/flow-patterns.js

@@ -24,6 +24,7 @@ import { joinGroup, splitToRail } from "./arrange.js";
 import { lintFlow } from "./flow-lint.js";
 import { toLF, asRaw } from "./eol.js";
 import { removalImpact, stepLabel } from "./step-removal.js";
+import { keySpan, InlineBlockError } from "./frontmatter-text.js";
 // ---------- flow files ----------
 /** A flow's steps as groups of indices into its parsed steps — what
  *  reorderFlowSteps and the arrange helpers take. */
@@ -437,14 +438,16 @@ function splitComment(value) {
     const m = value.match(/^(.*?)(\s+#.*)$/);
     return m ? { value: m[1], comment: m[2] } : { value, comment: "" };
 }
+/** Where a key is written — at the top or inside its job block
+ *  (frontmatter-text.ts) — with the text after its colon and its indent. */
 function keyLine(lines, close, key) {
-    const re = new RegExp(`^${key.replace(/[-]/g, "\\-")}:(.*)$`);
-    for (let i = 1; i < close; i++) {
-        const m = lines[i].match(re);
-        if (m)
-            return { index: i, rest: m[1] };
-    }
-    return null;
+    const where = keySpan(lines.slice(1, close), key);
+    if (!where)
+        return null;
+    const index = where.at + 1;
+    // Quoted or not, as keySpan matched it.
+    const m = lines[index].slice(where.indent.length).match(new RegExp(`^["']?${key.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&")}["']?\\s*:(.*)$`));
+    return m ? { index, rest: m[1], indent: where.indent } : null;
 }
 /** Block-style item lines under a key: `  - name`, until anything else. */
 function blockItems(lines, from, close) {
@@ -467,7 +470,17 @@ export function frontmatterList(raw, key) {
     const b = frontBounds(lines);
     if (!b)
         return [];
-    const k = keyLine(lines, b.close, key);
+    let k;
+    try {
+        k = keyLine(lines, b.close, key);
+    }
+    catch (err) {
+        // A block these text edits do not handle (frontmatter-text.ts) is the
+        // writer's to refuse; a read of it is empty, not an error.
+        if (err instanceof InlineBlockError)
+            return [];
+        throw err;
+    }
     if (!k)
         return [];
     const v = splitComment(k.rest).value.trim();
@@ -491,10 +504,12 @@ export function editFrontmatterList(raw, key, name, action) {
     const b = frontBounds(lines);
     if (!b)
         return action === "remove" ? raw : ["---", `${key}: [${name}]`, "---", ...lines].join(eol);
+    // Located first, so a key in a block these edits do not handle is refused
+    // (InlineBlockError) rather than read as an empty list.
+    const k = keyLine(lines, b.close, key);
     const has = frontmatterList(raw, key).includes(name);
     if ((action === "add") === has)
         return raw;
-    const k = keyLine(lines, b.close, key);
     if (!k) {
         lines.splice(b.close, 0, `${key}: [${name}]`);
         return lines.join(eol);
@@ -505,12 +520,12 @@ export function editFrontmatterList(raw, key, name, action) {
         // Flow style, or a lone scalar (read as a one-item list): that one line.
         const tokens = v.startsWith("[") ? v.replace(/^\[|\]$/g, "").split(",").map((t) => t.trim()).filter(Boolean) : [v];
         const next = action === "add" ? [...tokens, name] : tokens.filter((t) => itemName(t) !== name);
-        lines[k.index] = `${key}: [${next.join(", ")}]${comment}`;
+        lines[k.index] = `${k.indent}${key}: [${next.join(", ")}]${comment}`;
         return lines.join(eol);
     }
     const items = blockItems(lines, k.index, b.close);
     if (action === "add") {
-        const indent = items.length ? lines[items[0]].match(/^(\s*)-/)[1] : "  ";
+        const indent = items.length ? lines[items[0]].match(/^(\s*)-/)[1] : `${k.indent}  `;
         lines.splice(items.length ? items[items.length - 1] + 1 : k.index + 1, 0, `${indent}- ${name}`);
         return lines.join(eol);
     }
@@ -518,7 +533,7 @@ export function editFrontmatterList(raw, key, name, action) {
     for (const i of [...drop].reverse())
         lines.splice(i, 1);
     if (drop.length === items.length)
-        lines[k.index] = `${key}: []${comment}`;
+        lines[k.index] = `${k.indent}${key}: []${comment}`;
     return lines.join(eol);
 }
 const YAML_WORDS = /^(true|false|yes|no|on|off|null|~|y|n)$/i;
@@ -546,10 +561,10 @@ export function setFrontmatterScalar(raw, key, value) {
         const { value: v, comment } = splitComment(k.rest);
         let end = k.index + 1;
         if (/^\s*[|>][-+]?\d*\s*$/.test(v) || !v.trim()) {
-            while (end < b.close && /^\s+\S/.test(lines[end]))
+            while (end < b.close && (lines[end].match(/^\s*/)?.[0].length ?? 0) > k.indent.length && /\S/.test(lines[end]))
                 end++;
         }
-        lines.splice(k.index, end - k.index, `${line}${comment}`);
+        lines.splice(k.index, end - k.index, `${k.indent}${line}${comment}`);
         return lines.join(eol);
     }
     const name = keyLine(lines, b.close, "name");