@foldrun/core 2.4.0 → 2.6.0

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 "gray-matter";
+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, 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. */
@@ -198,16 +213,27 @@ function layoutTask(task) {
  * regressions file when there is one, so a flow collects its cases in one
  * place instead of one file per press.
  */
-export function promoteRunToEval(tenant, workspace, runId, opts = {}) {
+export function promoteRunToEval(tenant, workspace, runId, 
+/** `should`: what a run that went wrong should have done, in a sentence —
+ *  the judge's claim for the case (FOL-72 step 10). */
+opts = {}) {
     const run = readRun(tenant, workspace, runId);
     if (!run)
         throw refuse(`run ${runId} not found`, 404);
-    if (run.status !== "completed") {
-        throw refuse(`only a completed run can become an eval — this one is ${run.status}`, 409);
+    if (run.status !== "completed" && run.status !== "failed") {
+        throw refuse(`only a finished run can become an eval — this one is ${run.status}`, 409);
+    }
+    // A run that went wrong is the test worth having most — but its own answer
+    // is the wrong one to hold the next run to, so it needs to be told what
+    // was right (FOL-72 step 10).
+    const should = oneLine(opts.should ?? "");
+    const wentWrong = run.status === "failed" || ["BAD", "BLOCKED"].includes(runVerdict(run) ?? "");
+    if (wentWrong && !should && !(opts.expect && opts.expect.length)) {
+        throw refuse("this run went wrong, so its answer is not the one to keep — say what it should have done (`should`, a sentence for the judge) or give `expect` lines", 409);
     }
     const produced = run.steps.filter((s) => (s.result ?? "").trim());
     const last = produced[produced.length - 1];
-    if (!last)
+    if (!last && !should && !(opts.expect && opts.expect.length))
         throw refuse("this run produced no result to hold the next one to", 409);
     if (run.steps.length === 0 || !run.steps[0].instruction?.trim()) {
         throw refuse("this run has no task on record", 409);
@@ -239,6 +265,9 @@ export function promoteRunToEval(tenant, workspace, runId, opts = {}) {
             return `${m[1]}: ${m[2]}`;
         });
     }
+    else if (should) {
+        expect = [`judge: ${should.slice(0, 400)}`];
+    }
     else {
         const conclusion = oneLine(run.summary?.trim() || (last.result ?? "")).slice(0, 200);
         expect = [`judge: reaches the same conclusion as the recorded run: ${conclusion}`];
@@ -351,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({
@@ -382,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": {
@@ -424,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 };
         }
     }
 }
@@ -495,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");

package/dist/src/frontmatter-fields.d.ts

@@ -15,13 +15,40 @@ 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 declare const JOBS: readonly {
+    name: Job;
+    title: string;
+    what: string;
+}[];
 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
  *  read this one. */
 export declare const FLOW_TRIGGERS: readonly ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
 /** The effort levels; store.ts re-exports it with the aliases beside. */
 export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+/** The fields of one kind that do this job, in schema order. */
+export declare function fieldsOfJob(kind: SchemaKind, job: Job): string[];
+/** 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 declare const FOLDABLE: Readonly<Record<Job, ReadonlySet<string>>>;
 export declare const FRONTMATTER: Readonly<Record<SchemaKind, readonly FieldSpec[]>>;
 /** Which schema a workspace-relative path is read with, or null. */
 export declare function schemaKindOf(p: string): SchemaKind | null;

package/dist/src/frontmatter-fields.js

@@ -15,6 +15,12 @@
 //     in the docs.
 //
 // A new field is added here first, then read.
+export const JOBS = [
+    { 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" },
+];
 /** What can start a flow. store.ts re-exports it; parseFlow and the editor
  *  read this one. */
 export const FLOW_TRIGGERS = ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
@@ -24,6 +30,7 @@ const LOCALE = { validated: true };
 const AGENT = [
     { key: "name", type: "string", help: "kebab-case; the folder is the identity" },
     { key: "description", type: "string", help: "what it does and when — other agents and people read it" },
+    { key: "owner", type: "string", help: "the person accountable for it — an email or a name; else the workspace's, else the account's" },
     { key: "model", type: "string", help: "fast | default | max, an alias, or a full model id" },
     { key: "effort", type: "string", values: EFFORT_LEVELS, help: "how long it thinks" },
     { key: "size", type: "string", values: ["small", "large", "heavy"], help: "the sandbox it rents; anything else becomes large" },
@@ -59,6 +66,7 @@ const AGENTS_MD = [
     { key: "mdagent_version", type: ["string", "number"], legacy: true, help: "older spelling of foldrun_version" },
     { key: "name", type: "string", help: "the workspace's name" },
     { key: "description", type: "string", help: "shown in the workspace list" },
+    { key: "owner", type: "string", help: "the person accountable for every agent and flow here that names none" },
     { key: "provider", type: "object", help: "the model endpoint every agent here uses unless it names its own" },
     { key: "runtime", type: "object", help: "packages for agents that declare none" },
     { key: "web", type: "object", validated: true, help: "web.browse defaults" },
@@ -75,17 +83,25 @@ const AGENTS_MD = [
     { key: "budget", type: ["number", "string"], help: "USD per month, or N/day | N/week | N/month" },
     { key: "priority", type: "string", values: ["high", "normal", "low"], help: "account: where its runs stand in the queue" },
     { key: "concurrency", type: ["number", "string"], help: "account: runs at once" },
+    { key: "alerts", type: "object", validated: true, help: "thresholds that tell notify: — failure_rate (30%), min_runs, credits_day, run_minutes, stale_days, cost_spike, runs_per_hour, new_host" },
+    { key: "capture", type: "string", values: ["full", "metadata"], help: "what runs record of each tool call: full (its input and output, secrets masked) or metadata (name, size and time only)" },
+    { 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" },
 ];
 const FLOW = [
     { key: "name", type: "string", help: "the flow's name" },
     { key: "description", type: "string", help: "what it is for" },
+    { key: "owner", type: "string", help: "the person accountable for it — an email or a name; else the workspace's, else the account's" },
     { key: "trigger", type: "string", values: FLOW_TRIGGERS, help: "what starts it; any other value never fires" },
     { key: "schedule", type: "string", help: "cron, when trigger: schedule" },
     { key: "timezone", type: "string", validated: true, help: "the zone its schedule reads in" },
     { key: "model", type: "string", help: "every step's model unless the step says" },
     { key: "effort", type: "string", values: EFFORT_LEVELS, help: "every step's effort unless the step says" },
     { key: "overlap", type: "string", validated: true, help: "skip | queue" },
+    { key: "issues", type: "string", values: ["stay-open", "auto-close"], help: "what a good run does to this flow's open issues: stay-open (the default — a person resolves them) or auto-close" },
     { key: "priority", type: "string", validated: true, help: "high | normal | low" },
     { key: "catchup", type: "string", validated: true, help: "last | none" },
     { key: "on", type: "string", validated: true, help: "trigger: flow — completed | failed | blocked | any" },
@@ -166,10 +182,51 @@ const SAID_WHAT_IT_IS = [
     { key: "kind", type: "string", validated: true, legacy: true, help: "no longer read — the path says what this is" },
     { 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 = {
+    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, job) {
+    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 = Object.fromEntries(JOBS.map(({ name }) => [name, new Set(Object.values(JOB_FIELDS).flatMap((byJob) => byJob?.[name] ?? []))]));
+/** A kind's fields with their jobs set, and a block field per job it has. */
+function withJobs(kind, fields) {
+    const byJob = JOB_FIELDS[kind] ?? {};
+    const jobOf = new Map();
+    for (const [job, keys] of Object.entries(byJob))
+        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 = 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 = {
-    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/dist/src/frontmatter-guard.d.ts

@@ -0,0 +1,19 @@
+/** A write the guard refused. 409: the file is fine, this edit is not. */
+export declare class UnsafeEditError extends Error {
+    status: number;
+    constructor(why: string);
+}
+/** 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 declare function guardEdit(before: string, after: string, changed: readonly string[], expect?: Record<string, Expect>): string;
+/** The front of `text` as a run reads it, or null when it does not parse. */
+export declare function readFront(text: string): Record<string, unknown> | null;

package/dist/src/frontmatter-guard.js

@@ -0,0 +1,67 @@
+// 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.js";
+/** A write the guard refused. 409: the file is fine, this edit is not. */
+export class UnsafeEditError extends Error {
+    status = 409;
+    constructor(why) {
+        super(`not saved — ${why}. Edit the file itself, or write its blocks one key per line`);
+    }
+}
+const front = (text) => configMatter(text).data;
+/**
+ * `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, after, changed, expect = {}) {
+    let was;
+    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;
+    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(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) {
+    try {
+        return front(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/frontmatter-schema.d.ts

@@ -2,8 +2,8 @@ import { type SchemaKind } from "./frontmatter-fields.ts";
 export { FRONTMATTER, schemaKindOf, type FieldSpec, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
 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;
 }
 /**