@foldrun/core 2.5.0 → 2.6.0

package/src/deploy.ts

@@ -38,21 +38,24 @@ import {
 } from "./store.ts";
 import { readAgentsMdKeys } from "./agents-md.ts";
 import { libraryTools } from "./library.ts";
-import { lintFlow } from "./flow-lint.ts";
+import { lintFlow, regexProblem } from "./flow-lint.ts";
+import { parseEval } from "./evals.ts";
 import { refNames } from "./refs.ts";
-import matter from "./matter.ts";
+import matter, { configMatter } from "./matter.ts";
+import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.ts";
 import { conformanceIssues } from "./okf.ts";
 import { timezoneProblem } from "./clock.ts";
 import { webProblems, webWarnings, runnerEngines } from "./providers.ts";
 import { readLimits } from "./limits.ts";
 import { parseAlerts } from "./alerts.ts";
 import { parseTelemetry } from "./otel-config.ts";
+import { parseJudge } from "./judge-verdict.ts";
 import { networkProblems } from "./network.ts";
 import { actionProblems } from "./web-actions.ts";
 import { languageProblem } from "./language.ts";
 import { localeProblems } from "./locale.ts";
 import { entriesNoFollow } from "./paths.ts";
-import { filterIgnored, findingFingerprint, ruleForWhere, scanFiles, scanRule, type ScanFinding, type ScanOptions } from "./scan.ts";
+import { filterIgnored, findingFingerprint, ruleForWhere, scanFiles, scanRule, STRICT_FRONTMATTER_PATH, type ScanFinding, type ScanOptions } from "./scan.ts";
 
 /** 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
@@ -321,7 +324,7 @@ export function deployBlockMode(files: DeployFile[], accountKeys: Record<string,
   let fromWorkspace: DeployBlockMode | null = null;
   if (own) {
     try {
-      fromWorkspace = blockMode((matter(own.content).data as Record<string, unknown>).deploy_block);
+      fromWorkspace = blockMode((configMatter(own.content).data as Record<string, unknown>).deploy_block);
     } catch {
       // an AGENTS.md that does not parse is reported elsewhere
     }
@@ -450,6 +453,32 @@ function structuralWarnings(files: DeployFile[], extraOutward: Iterable<string>
     if (refNames(data.tools).some((t: string) => outwardTools.has(t))) outwardAgents.push(m[1]);
     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: number[] = [];
+    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) {
     if (!/^flows\/[^/]+\.md$/.test(f.path)) continue;
@@ -496,10 +525,11 @@ export function deployIssues(files: DeployFile[]): DeployIssue[] {
   // 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)) continue;
+    if (!STRICT_FRONTMATTER_PATH.test(f.path)) continue;
     if (!/^\uFEFF?---\r?\n/.test(f.content)) continue;
     try {
       matter(f.content);
@@ -508,6 +538,26 @@ export function deployIssues(files: DeployFile[]): DeployIssue[] {
     }
   }
 
+  // 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: Record<string, unknown>;
+    try {
+      front = configMatter(f.content).data as Record<string, unknown>;
+    } 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.
@@ -517,7 +567,7 @@ export function deployIssues(files: DeployFile[]): DeployIssue[] {
     if (unopened) at(f.path, unopened);
     let front: Record<string, unknown> = {};
     try {
-      front = matter(f.content).data as Record<string, unknown>;
+      front = configMatter(f.content).data as Record<string, unknown>;
     } catch {
       continue; // unparseable frontmatter is its own report
     }
@@ -541,6 +591,8 @@ export function deployIssues(files: DeployFile[]): DeployIssue[] {
     // `telemetry:` that cannot be read would never send — and a token
     // 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);
     for (const w of localeProblems(front)) at(f.path, w);

package/src/evals.ts

@@ -34,15 +34,19 @@
 import { accountModelEnv, withModelEnv } from "./model-env.ts";
 import type { TranslatorSpec } from "./translator.ts";
 import { sdkEnv } from "./step-exec.ts";
+import { platformModelEnv } from "./runner.ts";
 import fs from "node:fs";
 import path from "node:path";
 import { deployedCommit } from "./deploy.ts";
 import { latestRevisionId } from "./history.ts";
 import matter from "./matter.ts";
 import { spawn } from "node:child_process";
+import { judgeVerdict, JUDGE_VERDICT_INSTRUCTION, parseJudge } from "./judge-verdict.ts";
+import { readAgentsMdKeys } from "./agents-md.ts";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import {
   workspaceDir,
+  accountDir,
   readRun,
   runVerdict,
   writeWorkspaceFile,
@@ -146,7 +150,9 @@ function readScalar(
   return { value: [first, ...parts].join(" ").trim(), end: i };
 }
 
-export 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 function parseEval(file: string, raw: string, defaults: { model?: string; effort?: string } = {}): EvalInfo {
   const { data, content } = matter(raw);
   const cases: EvalCase[] = [];
   let current: EvalCase | null = null;
@@ -197,8 +203,8 @@ export function parseEval(file: string, raw: string): EvalInfo {
     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,
@@ -213,7 +219,18 @@ export function listEvals(tenant: string, workspace: string): EvalInfo[] {
     .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: string, workspace: string): { model?: string; effort?: string } {
+  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 ----------
@@ -484,9 +501,12 @@ function shell(command: string, cwd: string): Promise<{ code: number | null; out
   });
 }
 
-// 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: string,
   output: string,
@@ -495,8 +515,7 @@ async function judge(
   env: Record<string, string | undefined>,
 ): Promise<AssertionResult["detail"] & string> {
   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` +
+    `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 = "";
@@ -523,13 +542,26 @@ async function judge(
   return text.trim();
 }
 
+/**
+ * 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(): Record<string, string | undefined> {
+  const live = Object.fromEntries(Object.entries(platformModelEnv()).filter(([, v]) => v !== undefined));
+  return sdkEnv({ ...process.env, ...live });
+}
+
 async function checkAssertion(
   assertion: Assertion,
   output: string,
   agentDir: string,
   model: string,
   effort: Effort | null,
-  judgeEnv: () => { env: Record<string, string | undefined>; translator?: TranslatorSpec | null } = () => ({ env: sdkEnv(undefined) }),
+  judgeEnv: () => { env: Record<string, string | undefined>; translator?: TranslatorSpec | null } = () => ({ env: judgeProcessEnv() }),
 ): Promise<AssertionResult> {
   const hay = output.toLowerCase();
   switch (assertion.type) {
@@ -570,9 +602,9 @@ async function checkAssertion(
       } 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 };
     }
   }
 }
@@ -653,7 +685,7 @@ export async function runEval(
       const judges = testCase.expect.filter((a) => a.type === "judge");
       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));
       } else {
         for (const a of judges) {

package/src/flow-lint.ts

@@ -91,6 +91,27 @@ const LOOKS_LIKE_SHELL =
  *  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: string): string | null {
+  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: string): boolean {
   const v = verify.trim();
   if (!v || VERIFY_ASSERTION.test(v)) return false;
@@ -443,6 +464,21 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
       });
     }
 
+    // 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/src/flow-patterns.ts

@@ -25,6 +25,7 @@ import { joinGroup, splitToRail, type Groups } from "./arrange.ts";
 import { lintFlow } from "./flow-lint.ts";
 import { toLF, asRaw } from "./eol.ts";
 import { removalImpact, stepLabel, type RemovalImpact } from "./step-removal.ts";
+import { keySpan, InlineBlockError } from "./frontmatter-text.ts";
 
 // ---------- flow files ----------
 
@@ -474,13 +475,15 @@ function splitComment(value: string): { value: string; comment: string } {
   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: string[], close: number, key: string) {
-  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. */
@@ -502,7 +505,15 @@ export function frontmatterList(raw: string, key: string): string[] {
   const lines = raw.split(eolOf(raw));
   const b = frontBounds(lines);
   if (!b) return [];
-  const k = keyLine(lines, b.close, key);
+  let k: ReturnType<typeof keyLine>;
+  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();
   if (v.startsWith("[")) return v.replace(/^\[|\]$/g, "").split(",").map(itemName).filter(Boolean);
@@ -523,9 +534,11 @@ export function editFrontmatterList(raw: string, key: string, name: string, acti
   const lines = raw.split(eol);
   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);
@@ -536,18 +549,18 @@ export function editFrontmatterList(raw: string, key: string, name: string, acti
     // 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);
   }
   const drop = items.filter((i) => blockItemName(lines[i]) === name);
   for (const i of [...drop].reverse()) lines.splice(i, 1);
-  if (drop.length === items.length) lines[k.index] = `${key}: []${comment}`;
+  if (drop.length === items.length) lines[k.index] = `${k.indent}${key}: []${comment}`;
   return lines.join(eol);
 }
 
@@ -577,9 +590,9 @@ export function setFrontmatterScalar(raw: string, key: string, value: string): s
     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])) 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");

package/src/frontmatter-fields.ts

@@ -34,8 +34,33 @@ export interface FieldSpec {
   legacy?: boolean;
   /** One line: what it is. The completion's hint. */
   help: string;
+  /** Which of the four jobs it does, when it does one (set from JOB_FIELDS
+   *  below, not by hand): the block it may also be written in. */
+  job?: Job;
 }
 
+/**
+ * The four jobs of running agents — governance, guardrail, observability,
+ * evaluation (the owner's choice of words, 21 Oct 2026). A field that does
+ * one may be written flat, as always, or inside a block of that name:
+ *
+ *   guardrail:
+ *     limits: {repeat: 5}
+ *     network: [api.example.com]
+ *
+ * reads exactly as `limits:` and `network:` at the top. matter.ts folds the
+ * blocks as it parses, so every reader sees flat keys; check reports a key
+ * set both ways (config/conflict) or in the wrong block.
+ */
+export type Job = "governance" | "guardrail" | "observability" | "evaluation";
+
+export const JOBS: readonly { name: Job; title: string; what: string }[] = [
+  { name: "governance", title: "Governance", what: "who answers for it and what it may spend, decide and ship" },
+  { name: "guardrail", title: "Guardrail", what: "what it may reach and call, and what stops it" },
+  { name: "observability", title: "Observability", what: "what is recorded, and who is told" },
+  { name: "evaluation", title: "Evaluation", what: "how its work is judged" },
+];
+
 export type SchemaKind = "agent" | "agents-md" | "flow" | "tool" | "skill" | "eval" | "hook";
 
 /** What can start a flow. store.ts re-exports it; parseFlow and the editor
@@ -109,6 +134,7 @@ const AGENTS_MD: FieldSpec[] = [
   { key: "network_enforce", type: "boolean", help: "true: a site off a step's network: list is refused, not only named in the trace. The account's or the workspace's true is enough" },
   { key: "telemetry", type: "object", validated: true, help: "send each run as an OpenTelemetry trace — otlp: <https …/v1/traces>, headers: { authorization: ${SECRET} }" },
   { key: "deploy_block", type: "string", values: ["none", "secrets", "security"], help: "refuse a deploy on scanner findings: secrets (a key written in) or security (any security warning)" },
+  { key: "judge", type: "object", validated: true, help: "the model every judge: here grades with — {model: fast | default | max, effort}; an eval's own model: wins" },
   { key: "schedule", type: ["string", "object"], validated: true, legacy: true, help: "refused: only a flow has a clock" },
 ];
 
@@ -209,10 +235,55 @@ const SAID_WHAT_IT_IS: FieldSpec[] = [
   { key: "type", type: "string", validated: true, legacy: true, help: "no longer read — the path says what this is" },
 ];
 
+/** Which fields each job holds, per kind of file. One table: the blocks'
+ *  help, the fold, the editor's completions and check all read it. */
+const JOB_FIELDS: Partial<Record<SchemaKind, Partial<Record<Job, readonly string[]>>>> = {
+  agent: {
+    governance: ["owner", "budget"],
+    guardrail: ["limits", "network", "hooks", "disallowedTools", "permissionMode", "secrets"],
+  },
+  flow: {
+    governance: ["owner", "approvers", "approve_within", "budget", "priority"],
+    guardrail: ["throttle", "debounce", "overlap", "disable_after", "live"],
+    observability: ["issues", "sla"],
+  },
+  "agents-md": {
+    governance: ["owner", "budget", "priority", "concurrency", "deploy_block"],
+    guardrail: ["limits", "network", "network_enforce", "hooks"],
+    observability: ["alerts", "telemetry", "notify", "capture"],
+    evaluation: ["judge"],
+  },
+};
+
+/** The fields of one kind that do this job, in schema order. */
+export function fieldsOfJob(kind: SchemaKind, job: Job): string[] {
+  return [...(JOB_FIELDS[kind]?.[job] ?? [])];
+}
+
+/** Every key any kind lets a block hold, per job — what matter.ts may lift
+ *  out of a block without knowing which kind of file it is reading. */
+export const FOLDABLE: Readonly<Record<Job, ReadonlySet<string>>> = Object.fromEntries(
+  JOBS.map(({ name }) => [name, new Set(Object.values(JOB_FIELDS).flatMap((byJob) => byJob?.[name] ?? []))]),
+) as unknown as Record<Job, ReadonlySet<string>>;
+
+/** A kind's fields with their jobs set, and a block field per job it has. */
+function withJobs(kind: SchemaKind, fields: FieldSpec[]): FieldSpec[] {
+  const byJob = JOB_FIELDS[kind] ?? {};
+  const jobOf = new Map<string, Job>();
+  for (const [job, keys] of Object.entries(byJob) as [Job, readonly string[]][]) for (const k of keys) jobOf.set(k, job);
+  const tagged = fields.map((f) => (jobOf.has(f.key) ? { ...f, job: jobOf.get(f.key)! } : f));
+  const blocks: FieldSpec[] = JOBS.filter((j) => (byJob[j.name]?.length ?? 0) > 0).map((j) => ({
+    key: j.name,
+    type: "object",
+    help: `${j.title} — ${j.what}: ${byJob[j.name]!.join(", ")}, as one block`,
+  }));
+  return [...tagged, ...blocks];
+}
+
 export const FRONTMATTER: Readonly<Record<SchemaKind, readonly FieldSpec[]>> = {
-  agent: [...AGENT, ...SAID_WHAT_IT_IS],
-  "agents-md": AGENTS_MD,
-  flow: [...FLOW, ...SAID_WHAT_IT_IS],
+  agent: withJobs("agent", [...AGENT, ...SAID_WHAT_IT_IS]),
+  "agents-md": withJobs("agents-md", AGENTS_MD),
+  flow: withJobs("flow", [...FLOW, ...SAID_WHAT_IT_IS]),
   tool: [...TOOL, ...SAID_WHAT_IT_IS.filter((f) => f.key !== "type")],
   skill: [...SKILL, ...SAID_WHAT_IT_IS],
   eval: [...EVAL, ...SAID_WHAT_IT_IS],

package/src/frontmatter-guard.ts

@@ -0,0 +1,70 @@
+// The last word on every frontmatter edit made as text (agents-md.ts
+// patchFrontmatter, network.ts setNetworkSetting, the canvas's list and
+// scalar edits): the result is read back the way a run reads it, and the
+// edit is refused — the file left as it was — unless it parses, set what it
+// said it set, left everything else as it was, and made no key both flat and
+// in its block. The text writers handle the shapes people write; this makes
+// a shape they do not handle a refusal, never a broken or doubled file
+// (Codex debate, 21 Oct 2026).
+
+import { isDeepStrictEqual } from "node:util";
+import { configMatter, jobFold } from "./matter.ts";
+
+/** A write the guard refused. 409: the file is fine, this edit is not. */
+export class UnsafeEditError extends Error {
+  status = 409;
+  constructor(why: string) {
+    super(`not saved — ${why}. Edit the file itself, or write its blocks one key per line`);
+  }
+}
+
+const front = (text: string) => configMatter(text).data as Record<string, unknown>;
+
+/** What a changed key must read back as: a value (null: absent), or a test
+ *  of what it reads as, for a writer whose output form is its own (a canvas
+ *  list, a scalar YAML may type). */
+export type Expect = unknown | ((value: unknown) => boolean);
+
+/**
+ * `after` if it is `before` with only `changed` keys different and each
+ * `expect`ed key reading back as expected; throws UnsafeEditError otherwise.
+ * Checked on every call — an edit that changed nothing must still have done
+ * what it said — and refused when `before` cannot be read, since nothing
+ * then could be compared.
+ */
+export function guardEdit(before: string, after: string, changed: readonly string[], expect: Record<string, Expect> = {}): string {
+  let was: Record<string, unknown>;
+  try {
+    was = front(before);
+  } catch {
+    throw new UnsafeEditError("the frontmatter does not parse as it is, so this edit could not be checked — fix the file first");
+  }
+  let now: Record<string, unknown>;
+  try {
+    now = front(after);
+  } catch (err) {
+    throw new UnsafeEditError(`the result would not parse (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`);
+  }
+  const conflictsBefore = jobFold(was)?.conflicts ?? new Map();
+  for (const [k, block] of jobFold(now)?.conflicts ?? new Map()) {
+    if (!conflictsBefore.has(k)) throw new UnsafeEditError(`\`${k}\` would be written both at the top and inside \`${block}:\``);
+  }
+  for (const [k, want] of Object.entries(expect)) {
+    const ok = typeof want === "function" ? (want as (v: unknown) => boolean)(now[k]) : isDeepStrictEqual(now[k], want === null ? undefined : want);
+    if (!ok) throw new UnsafeEditError(`\`${k}\` would not read back as written`);
+  }
+  for (const k of new Set([...Object.keys(was), ...Object.keys(now)])) {
+    if (changed.includes(k)) continue;
+    if (!isDeepStrictEqual(was[k], now[k])) throw new UnsafeEditError(`\`${k}\` would change too`);
+  }
+  return after;
+}
+
+/** The front of `text` as a run reads it, or null when it does not parse. */
+export function readFront(text: string): Record<string, unknown> | null {
+  try {
+    return front(text);
+  } catch {
+    return null;
+  }
+}

package/src/frontmatter-schema.ts

@@ -2,7 +2,8 @@
 // the names. Node-side (it reads store's parsers); the browser takes the
 // field list alone from frontmatter-fields.ts.
 
-import { FRONTMATTER, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
+import { FRONTMATTER, JOBS, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
+import { jobFold } from "./matter.ts";
 import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS } from "./store.ts";
 import { budgetProblem } from "./budget.ts";
 import { cronProblem } from "./cron.ts";
@@ -65,8 +66,8 @@ const CHECKS: Partial<Record<SchemaKind, Record<string, (value: unknown) => stri
 
 export interface FieldProblem {
   key: string;
-  rule: "config/unknown-field" | "config/wrong-type" | "config/invalid-value" | "config/missing-field";
-  level: "warn" | "info";
+  rule: "config/unknown-field" | "config/wrong-type" | "config/invalid-value" | "config/missing-field" | "config/conflict" | "config/misplaced";
+  level: "error" | "warn" | "info";
   message: string;
 }
 
@@ -97,7 +98,31 @@ export function frontmatterProblems(
   const fields = FRONTMATTER[kind];
   const known = fields.map((f) => f.key);
   const out: FieldProblem[] = [];
+  // The four job blocks (matter.ts folds them): a key set both ways, and a
+  // key left in a block that does not hold it.
+  const fold = jobFold(data);
+  for (const [key, job] of fold?.conflicts ?? []) {
+    out.push({ key, rule: "config/conflict", level: "error", message: `\`${key}:\` is set twice — at the top and inside \`${job}:\`. Only the top one would be read; keep one` });
+  }
+  for (const { name: job } of JOBS) {
+    const block = data[job];
+    if (!block || typeof block !== "object" || Array.isArray(block)) continue;
+    for (const inner of Object.keys(block as Record<string, unknown>)) {
+      const spec = fields.find((f) => f.key === inner);
+      const message = spec?.job
+        ? `\`${inner}:\` is a ${spec.job} field, not a ${job} one — move it into \`${spec.job}:\` or to the top. Inside \`${job}:\` it is not read`
+        : spec
+          ? `\`${inner}:\` belongs to none of the four jobs — write it at the top. Inside \`${job}:\` it is not read`
+          : `\`${inner}:\` inside \`${job}:\` is not a field foldrun reads${belongsIn(inner, kind) ? ` here — it is read in ${belongsIn(inner, kind)}` : ""}; it is ignored`;
+      // A real setting in the wrong block is a setting silently not applied
+      // — a guardrail written under governance: guards nothing — so it is an
+      // error (Codex debate). A word foldrun does not read at all is a note.
+      out.push({ key: inner, rule: "config/misplaced", level: spec ? "error" : "info", message });
+    }
+  }
   for (const [key, value] of Object.entries(data)) {
+    // A block holding only misplaced keys is reported above, key by key.
+    if (JOBS.some((j) => j.name === key) && value && typeof value === "object" && !Array.isArray(value)) continue;
     const spec = fields.find((f) => f.key === key);
     const check = CHECKS[kind]?.[key];
     if (!spec) {
@@ -110,7 +135,8 @@ export function frontmatterProblems(
         // it is an option of a flow's step.
         out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\` is not read on an agent — it is a step option: indent it under the step in the flow (\`   ${key}: ${shown(value)}\`). Here it is ignored` });
       } else if (home) {
-        out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\` is read in ${home}, not in ${kind === "agents-md" ? "AGENTS.md" : kind === "eval" ? "an eval" : `a ${kind}`} — here it is ignored` });
+        const where = fold?.folded.get(key);
+        out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\`${where ? ` (inside \`${where}:\`)` : ""} is read in ${home}, not in ${kind === "agents-md" ? "AGENTS.md" : kind === "eval" ? "an eval" : `a ${kind}`} — here it is ignored` });
       } else {
         out.push({ key, rule: "config/unknown-field", level: "info", message: `\`${key}:\` is not a field foldrun reads; it is ignored` });
       }