@foldrun/core 2.5.0 → 2.7.0

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"];
@@ -82,6 +88,7 @@ const AGENTS_MD = [
     { 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 = [
@@ -175,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;
 }
 /**

package/dist/src/frontmatter-schema.js

@@ -1,7 +1,8 @@
 // Checking frontmatter against frontmatter-fields.ts: the values, not just
 // the names. Node-side (it reads store's parsers); the browser takes the
 // field list alone from frontmatter-fields.ts.
-import { FRONTMATTER } from "./frontmatter-fields.js";
+import { FRONTMATTER, JOBS } from "./frontmatter-fields.js";
+import { jobFold } from "./matter.js";
 import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS } from "./store.js";
 import { budgetProblem } from "./budget.js";
 import { cronProblem } from "./cron.js";
@@ -80,7 +81,33 @@ export function frontmatterProblems(kind, data, near) {
     const fields = FRONTMATTER[kind];
     const known = fields.map((f) => f.key);
     const out = [];
+    // 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)) {
+            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) {
@@ -95,7 +122,8 @@ export function frontmatterProblems(kind, data, near) {
                 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` });

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

@@ -0,0 +1,31 @@
+export interface KeySpan {
+    /** The key's line. */
+    at: number;
+    /** One past its last line. */
+    end: number;
+    /** What its line starts with. */
+    indent: string;
+    /** The block header's line, when it is inside one. */
+    block: number | null;
+}
+/** Thrown for a key a writer cannot edit in place: one that is, or may be,
+ *  inside a block not written one key per line (`guardrail: {…}`, an alias).
+ *  Rewriting it would mean re-serialising the person's YAML, and adding the
+ *  key at the top beside it would be a config/conflict — so the writer says
+ *  what to write instead. */
+export declare class InlineBlockError extends Error {
+    status: number;
+    constructor(key: string, block: string);
+}
+/**
+ * Where a key is written in frontmatter lines: at the top, or a direct child
+ * of one of the four job blocks (`guardrail:` and so on). Every writer that
+ * edits a key as text reads it here, so a file written in blocks is edited
+ * where it is — never given a second, flat copy that check would refuse as
+ * config/conflict. A key inside an inline block map throws InlineBlockError.
+ */
+export declare function keySpan(lines: string[], key: string): KeySpan | null;
+/** A block header left with nothing under it is removed with its last key.
+ *  Blank lines and comments between it and its next key do not count as
+ *  nothing: the header stays while any indented key follows them. */
+export declare function dropEmptyBlock(lines: string[], header: number): string[];

package/dist/src/frontmatter-text.js

@@ -0,0 +1,102 @@
+// Frontmatter edited as text, where it is written: at the top or inside one
+// of the four job blocks. No node imports — the flow canvas (flow-patterns.ts)
+// runs in the browser and edits frontmatter with it too.
+/** A block header on its own line — an anchor and a trailing `# comment`
+ *  allowed. */
+const JOB_BLOCK = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*(&\S+\s*)?(#.*)?$/;
+/** Any other block header: an inline map, an alias, a tag — a form these
+ *  writers do not edit. */
+const JOB_OTHER = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*\S/;
+/** An inline map closed on its own line: `guardrail: {network: [a.com]}`. */
+const JOB_ONE_LINE = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*\{.*\}\s*(#.*)?$/;
+const indentOf = (l) => l.match(/^[ \t]*/)?.[0].length ?? 0;
+/** Thrown for a key a writer cannot edit in place: one that is, or may be,
+ *  inside a block not written one key per line (`guardrail: {…}`, an alias).
+ *  Rewriting it would mean re-serialising the person's YAML, and adding the
+ *  key at the top beside it would be a config/conflict — so the writer says
+ *  what to write instead. */
+export class InlineBlockError extends Error {
+    status = 409;
+    constructor(key, block) {
+        super(`\`${key}\` may be inside \`${block}:\`, which is not written one key per line — write \`${block}:\` one key per line to change it here, or edit the file`);
+    }
+}
+/** A comment or blank line: neither ends a block nor is one of its keys. */
+const filler = (l) => l.trim() === "" || /^\s*#/.test(l);
+/**
+ * Where a key is written in frontmatter lines: at the top, or a direct child
+ * of one of the four job blocks (`guardrail:` and so on). Every writer that
+ * edits a key as text reads it here, so a file written in blocks is edited
+ * where it is — never given a second, flat copy that check would refuse as
+ * config/conflict. A key inside an inline block map throws InlineBlockError.
+ */
+export function keySpan(lines, key) {
+    const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const span = (at, indent, block) => {
+        let end = at + 1;
+        // The key continues while lines are indented deeper, are an item of its
+        // list written at its own indent (YAML allows `key:\n- a`), or are blank
+        // lines and comments inside it.
+        while (end < lines.length &&
+            (filler(lines[end]) ||
+                indentOf(lines[end]) > indent.length ||
+                (indentOf(lines[end]) === indent.length && /^[ \t]*-(\s|$)/.test(lines[end]))))
+            end++;
+        // Blank lines and comments at its foot, no deeper than the key, belong
+        // to what follows.
+        while (end > at + 1 && filler(lines[end - 1]) && (lines[end - 1].trim() === "" || indentOf(lines[end - 1]) <= indent.length))
+            end--;
+        return { at, end, indent, block };
+    };
+    // A key may be quoted: `"network": none`.
+    const named = `["']?${k}["']?\\s*:`;
+    const top = lines.findIndex((l) => new RegExp(`^${named}`).test(l));
+    if (top !== -1)
+        return span(top, "", null);
+    for (let h = 0; h < lines.length; h++) {
+        const other = !JOB_BLOCK.test(lines[h]) && JOB_OTHER.exec(lines[h]);
+        if (other) {
+            // One closed line can be read: refuse only if the key is in it. Any
+            // other form (a map over several lines, an alias) cannot be, so any
+            // key not found at the top is refused rather than added beside it.
+            if (!JOB_ONE_LINE.test(lines[h]) || new RegExp(`[{,]\\s*${named}`).test(lines[h]))
+                throw new InlineBlockError(key, other[1]);
+            continue;
+        }
+        if (!JOB_BLOCK.test(lines[h]))
+            continue;
+        // Its children sit at the indent of its first indented line; a deeper
+        // line of the same name belongs to one of them, not to the block.
+        // Comments and blank lines, indented or not, do not end it.
+        let child = -1;
+        let merged = false;
+        for (let n = h + 1; n < lines.length && (/^[ \t]/.test(lines[n]) || filler(lines[n])); n++) {
+            if (filler(lines[n]))
+                continue;
+            if (child === -1)
+                child = indentOf(lines[n]);
+            if (indentOf(lines[n]) !== child)
+                continue;
+            const m = new RegExp(`^([ \t]+)${named}`).exec(lines[n]);
+            if (m)
+                return span(n, m[1], h);
+            if (/^[ \t]+<<\s*:/.test(lines[n]))
+                merged = true;
+        }
+        // `<<: *policy` may bring the key in from elsewhere: not one this text
+        // edit can see, so it is refused rather than added beside it.
+        if (merged)
+            throw new InlineBlockError(key, JOB_BLOCK.exec(lines[h])[1]);
+    }
+    return null;
+}
+/** A block header left with nothing under it is removed with its last key.
+ *  Blank lines and comments between it and its next key do not count as
+ *  nothing: the header stays while any indented key follows them. */
+export function dropEmptyBlock(lines, header) {
+    let n = header + 1;
+    while (n < lines.length && filler(lines[n]))
+        n++;
+    const next = lines[n];
+    return next === undefined || !/^[ \t]+\S/.test(next) ? [...lines.slice(0, header), ...lines.slice(header + 1)] : lines;
+}

package/dist/src/judge-verdict.d.ts

@@ -0,0 +1,19 @@
+/** The line to end a judge prompt with. */
+export declare const JUDGE_VERDICT_INSTRUCTION = "Check each part against the text in a few short sentences. Then, on the last line and alone, write exactly PASS or FAIL \u2014 PASS only if every part holds.";
+/**
+ * The judge's verdict: the PASS or FAIL alone on its last line, with the
+ * reasoning before it as the detail. An answer in the old shape (the word
+ * first) still reads; one with no verdict at all is a FAIL that says so.
+ */
+export declare function judgeVerdict(text: string): {
+    passed: boolean;
+    detail: string;
+};
+/** `judge:` in AGENTS.md — the model and effort every judge in the workspace
+ *  grades with, unless an eval names its own. `model` is a tier or alias as
+ *  anywhere else; what is wrong with the block, in words, for check. */
+export declare function parseJudge(raw: unknown): {
+    model?: string;
+    effort?: string;
+    problems: string[];
+};

package/dist/src/judge-verdict.js

@@ -0,0 +1,54 @@
+// What a judge said: the PASS or FAIL alone on its last line, after its
+// reasoning. Shared by the eval judge (evals.ts) and a flow step's
+// `verify: judge:` (step-exec.ts), which ask for the same shape.
+//
+// The word comes last because, asked for it first, a judge commits before
+// it has looked and then argues the other way — "FAIL … which meets the
+// criterion" (vaza evals, 21 Oct 2026).
+import { EFFORT_LEVELS } from "./frontmatter-fields.js";
+/** The line to end a judge prompt with. */
+export const JUDGE_VERDICT_INSTRUCTION = "Check each part against the text in a few short sentences. Then, on the last line and alone, write exactly PASS or FAIL — PASS only if every part holds.";
+/**
+ * The judge's verdict: the PASS or FAIL alone on its last line, with the
+ * reasoning before it as the detail. An answer in the old shape (the word
+ * first) still reads; one with no verdict at all is a FAIL that says so.
+ */
+export function judgeVerdict(text) {
+    const lines = text.trim().split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const word = (l) => /^[*_`#\s]*(PASS|FAIL)[*_`.\s]*$/i.exec(l ?? "")?.[1]?.toUpperCase();
+    let verdict = word(lines[lines.length - 1]);
+    let reason = lines.slice(0, -1).join(" ");
+    if (!verdict) {
+        const first = /^[*_`#\s]*(PASS|FAIL)\b[*_`:.\s-]*(.*)$/i.exec(lines[0] ?? "");
+        if (first) {
+            verdict = first[1].toUpperCase();
+            reason = [first[2], ...lines.slice(1)].join(" ").trim();
+        }
+    }
+    if (!verdict)
+        return { passed: false, detail: `judge gave no PASS or FAIL: ${text.trim().slice(0, 300) || "nothing"}` };
+    // The end of the reasoning is the part that decided it.
+    const why = reason.length > 400 ? `…${reason.slice(-400)}` : reason;
+    return { passed: verdict === "PASS", detail: `${verdict}${why ? ` — ${why}` : ""}` };
+}
+/** `judge:` in AGENTS.md — the model and effort every judge in the workspace
+ *  grades with, unless an eval names its own. `model` is a tier or alias as
+ *  anywhere else; what is wrong with the block, in words, for check. */
+export function parseJudge(raw) {
+    if (raw === undefined || raw === null)
+        return { problems: [] };
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return { problems: ["judge: is a block — {model: fast | default | max, effort: low…max}"] };
+    const o = raw;
+    const problems = [];
+    for (const k of Object.keys(o))
+        if (k !== "model" && k !== "effort")
+            problems.push(`judge: ${k} — not a key; the keys are model and effort`);
+    const model = typeof o.model === "string" && o.model.trim() ? o.model.trim() : undefined;
+    if (o.model !== undefined && !model)
+        problems.push("judge: model — a tier (fast, default, max), an alias or a model id");
+    const effort = typeof o.effort === "string" && EFFORT_LEVELS.includes(o.effort.trim()) ? o.effort.trim() : undefined;
+    if (o.effort !== undefined && !effort)
+        problems.push(`judge: effort ${String(o.effort)} — low, medium, high, xhigh or max`);
+    return { ...(model ? { model } : {}), ...(effort ? { effort } : {}), problems };
+}

package/dist/src/matter.d.ts

@@ -1,8 +1,42 @@
 import grayMatter from "gray-matter";
+import { type Job } from "./frontmatter-fields.ts";
 type Options = NonNullable<Parameters<typeof grayMatter>[1]>;
+export interface JobFold {
+    /** A key lifted out of a block, and the block it was in. */
+    folded: Map<string, Job>;
+    /** A key set both at the top and inside a block: the top one is kept, and
+     *  check refuses the file (config/conflict). */
+    conflicts: Map<string, Job>;
+}
+/** What the fold did to this data, or null when it had no blocks. */
+export declare function jobFold(data: unknown): JobFold | null;
 declare function matter(input: string, options?: Options): grayMatter.GrayMatterFile<string>;
 declare namespace matter {
     var stringify: typeof grayMatter.stringify;
     var test: typeof grayMatter.test;
 }
+/**
+ * matter(), for the three files that hold configuration — an agent, a flow,
+ * AGENTS.md — with the four job blocks read as flat keys. Every reader of
+ * those files goes through this (tests/jobs.test.ts holds them to it);
+ * knowledge, memory, skills and every other document keep matter(), so a
+ * note's own `governance:` is its own (Codex debate, 21 Oct 2026).
+ */
+export declare function configMatter(input: string, options?: Options): grayMatter.GrayMatterFile<string>;
 export default matter;
+/** The first line of a YAML parse error, with where it is: what a person
+ *  needs to fix the file, without the parser's excerpt. */
+export declare function frontmatterErrorText(err: unknown): string;
+/** The 1-based file line a YAML parse error points at, when it says. The
+ *  text gray-matter hands the parser starts with the newline after the
+ *  opening `---`, so the parser's 0-based line is the file's 1-based one. */
+export declare function frontmatterErrorLine(err: unknown): number | undefined;
+/** Frontmatter as the runtime reads a skill: strictly first, then once more
+ *  with every unquoted value that holds a colon quoted (the commonest way a
+ *  hand-written SKILL.md breaks, and one other skills clients forgive), and
+ *  empty when even that fails. `lenient` says the second read was needed. */
+export declare function parseLenient(raw: string): {
+    data: Record<string, unknown>;
+    lenient: boolean;
+    failed: boolean;
+};