@foldrun/core 2.5.0 → 2.6.0

package/dist/src/scan.js

@@ -26,7 +26,7 @@
 // The reason is required: an ignore without one ignores nothing and is itself
 // reported, because "why is this allowed?" is the question a reviewer asks.
 import crypto from "node:crypto";
-import matter from "./matter.js";
+import matter, { frontmatterErrorLine, frontmatterErrorText, parseLenient, configMatter } from "./matter.js";
 import { refNames } from "./refs.js";
 import { resolveNetwork } from "./network.js";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.js";
@@ -159,6 +159,32 @@ export const SCAN_RULES = [
         help: "`effort: extreme`, `size: giant`, `trigger: sometimes`, a cron the scheduler cannot read: each is ignored or falls back, " +
             "so the agent or flow quietly does something else. The message lists what the field takes.",
     },
+    {
+        id: "config/conflict",
+        category: "config",
+        level: "error",
+        title: "A field set twice: at the top and inside its job block",
+        help: "`limits:` at the top and `limits:` inside `guardrail:` cannot both be meant. The top one would be read and the other " +
+            "quietly ignored, so the file is refused until one is removed.",
+    },
+    {
+        id: "config/misplaced",
+        category: "config",
+        level: "error",
+        title: "A field inside the wrong job block",
+        help: "Each of the four blocks (governance, guardrail, observability, evaluation) holds its own fields. A setting written in " +
+            "another block is not read — a guardrail under governance: guards nothing — so the file is refused until it is moved " +
+            "to the block the message names, or to the top. A word foldrun does not read at all is only a note.",
+    },
+    {
+        id: "config/invalid-frontmatter",
+        category: "config",
+        level: "warn",
+        title: "Frontmatter that YAML cannot read",
+        help: "A value with a colon followed by a space (`description: the format (Markdown, ::: directives)`) ends the YAML. " +
+            "foldrun reads a skill like that by quoting the value, but the dashboard editor and the source API refuse to save it, " +
+            "and other tools that read the file may not. Quote the value: `description: \"…\"`.",
+    },
     {
         id: "config/missing-field",
         category: "config",
@@ -544,17 +570,35 @@ export function nearestField(key, known) {
     return bestD <= allowed ? best : null;
 }
 function keyLine(lines, key) {
-    const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`);
-    const i = lines.findIndex((l) => re.test(l));
-    return i >= 0 ? i + 1 : undefined;
+    const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const top = new RegExp(`^${k}\\s*:`);
+    const i = lines.findIndex((l) => top.test(l));
+    if (i >= 0)
+        return i + 1;
+    // A key inside one of the four job blocks: indented, under its header.
+    const inner = new RegExp(`^\\s+${k}\\s*:`);
+    let inBlock = false;
+    for (let n = 0; n < lines.length; n++) {
+        const l = lines[n];
+        if (/^(governance|guardrail|observability|evaluation)\s*:\s*(#.*)?$/.test(l))
+            inBlock = true;
+        else if (/^\S/.test(l))
+            inBlock = false;
+        else if (inBlock && inner.test(l))
+            return n + 1;
+    }
+    return undefined;
 }
 /** Read-only: gray-matter caches by content, so two files with the same
  *  text share one object, and writing to it would leak between them. */
-function frontOf(content) {
+function frontOf(content, filePath) {
     if (!/^?---\r?\n/.test(content))
         return null;
     try {
-        return matter(content).data;
+        // An agent, a flow or AGENTS.md reads its job blocks as flat keys, as
+        // the runtime does; every other document is read as written.
+        const kind = filePath ? schemaKindOf(filePath) : null;
+        return (kind === "agent" || kind === "flow" || kind === "agents-md" ? configMatter(content) : matter(content)).data;
     }
     catch {
         return null; // a frontmatter YAML cannot read is check's finding, not ours
@@ -683,6 +727,14 @@ const VENDORED = /(?:^|\/)(?:node_modules|\.venv|venv|site-packages|__pycache__|
  *  since a key in a log here is a key in the workspace (seen live on
  *  17 Oct 2026: zero-width characters in a CLI MCP log, reported as hidden
  *  text). */
+/** The definition files a deploy refuses outright when their frontmatter does
+ *  not parse (deploy.ts deployIssues): the workspace's own, by these paths.
+ *  Everything else the platform reads frontmatter from — skills, and the
+ *  account library's agents, tools and hooks — is the scanner's to report. */
+export const STRICT_FRONTMATTER_PATH = /^(AGENTS\.md|agents\/[^/]+\/agent\.md|flows\/[^/]+\.md|tools\/[^/]+\.md|tools\/[^/]+\/tool\.md|evals\/[^/]+\.md|hooks\/[^/]+\/hook\.md|\.claude\/agents\/[^/]+\.md)$/;
+/** A skill file in either layout the runtime discovers: <name>/SKILL.md, or
+ *  the flat <name>.md, under skills/ or .agents/skills/, in the library too. */
+const SKILL_FILE = /(?:^|\/)skills\/(?:[^/]+\/SKILL\.md|[^/]+\.md)$/;
 const RUNTIME_WRITTEN = /(?:^|\/)(?:\.cache|\.npm|\.local|\.pnpm-store|\.yarn|\.foldrun)\//;
 /** Text files only — a PNG read as UTF-8 is noise to every rule here. */
 function isText(f) {
@@ -740,9 +792,35 @@ export function scanFiles(files, options = {}) {
         scanContent(f, lines, push);
         scanSupplyChain(f, lines, push);
         const schema = schemaKindOf(f.path);
+        // Frontmatter YAML cannot read. Until 2026-10-21 nothing reported it for
+        // a skill or a library file: frontOf below reads it as "no frontmatter"
+        // and moves on, and the deploy's own refusal covers only the workspace's
+        // definition files. A vaza.ai skill with `description: … (Markdown,
+        // frontmatter, ::: directives) …` deployed clean, ran (the runtime quotes
+        // the value and retries), and was refused by the source API on its next
+        // save.
+        if ((schema || SKILL_FILE.test(f.path)) && !STRICT_FRONTMATTER_PATH.test(f.path) && /^\uFEFF?---\r?\n/.test(f.content)) {
+            let err = null;
+            try {
+                matter(f.content);
+            }
+            catch (e) {
+                err = e;
+            }
+            if (err) {
+                const isSkill = schema === "skill" || SKILL_FILE.test(f.path);
+                const read = parseLenient(f.content);
+                const what = isSkill && !read.failed
+                    ? "foldrun reads this skill anyway by quoting the value, but the dashboard editor and the source API refuse to save it, and other skills clients may not load it"
+                    : isSkill
+                        ? "the runtime reads it as empty, so the skill has no name or description and is never loaded"
+                        : "the runtime cannot read this file";
+                push("config/invalid-frontmatter", f.path, frontmatterErrorLine(err), `config/invalid-frontmatter ${frontmatterErrorText(err)}`, `${frontmatterErrorText(err)} ${what === "the runtime cannot read this file" ? "The runtime cannot read this file" : what.replace(/^foldrun/, "foldrun").replace(/^the/, "The")}.`);
+            }
+        }
         // A skill with no frontmatter at all is the clearest one that never
         // loads: read it as empty, so its required fields are reported.
-        const data = schema || docKind(f.path) ? (frontOf(f.content) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
+        const data = schema || docKind(f.path) ? (frontOf(f.content, f.path) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
         if (!data)
             continue;
         if (schema) {
@@ -770,7 +848,7 @@ export function scanFiles(files, options = {}) {
     }
     // project.md is the older name the runtime still reads (Codex review, FOL-58).
     const workspaceMd = files.find((f) => f.path === "AGENTS.md") ?? files.find((f) => f.path === "project.md");
-    scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
+    scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content, "AGENTS.md")?.network : undefined });
     for (const m of more.values()) {
         findings.push({ rule: m.rule, level: m.level ?? scanRule(m.rule)?.level ?? "warn", file: m.file, message: `and ${m.n} more like this in this file, not listed`, fingerprint: m.hash.digest("hex").slice(0, 16), truncated: true });
     }

package/dist/src/starter.js

@@ -55,6 +55,22 @@ foldrun_version: "0.1"
 #
 # The token is sent as a bearer credential. A gateway that wants it as a key
 # header asks for that by name: headers: { x-api-key: \${THE_SECRET} }.
+#
+# The four jobs of running agents, each a block — or write the same keys at
+# the top; one place or the other, never both:
+#
+# governance:          # who answers for it, what it may spend and ship
+#   owner: you@example.com
+#   budget: 60/month
+#   deploy_block: secrets
+# guardrail:           # what agents may reach and call
+#   limits: {calls: 300, repeat: 5}
+#   network: trusted
+# observability:       # what is recorded, and who is told
+#   notify: {email: you@example.com, events: [failed]}
+#   alerts: {failure_rate: 30%}
+# evaluation:          # how work is judged
+#   judge: {model: fast}
 ---
 
 # ${account}
@@ -476,6 +492,13 @@ runtime:                    # only if scripts need packages
 You research a topic and report what you found...
 \`\`\`
 
+The fields that do one of the four jobs of running agents may be grouped
+under it — \`governance:\` (owner, budget), \`guardrail:\` (limits, network,
+hooks, disallowedTools, permissionMode, secrets), and in AGENTS.md also
+\`observability:\` (alerts, telemetry, notify, capture) and \`evaluation:\`
+(judge). A block reads exactly as the same keys at the top; a key written
+both ways is refused (\`config/conflict\`). \`foldrun docs four-jobs\`.
+
 Only \`name\` and the prose are required. Every other field widens or narrows
 what the agent can reach, and the default is narrow.
 

package/dist/src/step-exec.d.ts

@@ -104,6 +104,11 @@ export interface ExecOptions {
      *  `matches: re`, `file: path`, `judge: sentence`) — see checkVerify. */
     verify?: string;
     verifyEnv?: Record<string, string>;
+    /** The model `verify: judge:` grades with — the workspace's `judge:` from
+     *  AGENTS.md, resolved; absent, the fast tier. */
+    judgeModel?: string;
+    /** And how long it thinks — `judge: {effort}`; absent, the SDK's default. */
+    judgeEffort?: Effort;
     /** `output: json` — the reply must carry one JSON value; extracting it is
      *  part of finishing the step, and failing to is failing the step. */
     output?: "json";
@@ -301,14 +306,17 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
     /** The step's own model environment, for `judge:` — it grades on the
      *  fast tier through the same credential the step rode. */
     modelEnv?: Record<string, string | undefined>;
+    /** The judge's model and effort (the workspace's `judge:`). */
+    judgeModel?: string;
+    judgeEffort?: Effort;
     /** Ends a shell check or a judge mid-way: the step's clock ran out, or a
      *  person asked the run to stop. */
     signal?: AbortSignal;
 }): Promise<VerifyVerdict>;
 /**
  * A toolless, fast-tier grading call: does the reply satisfy the sentence?
- * Same shape as the eval judge, and answered with one word first so the
- * verdict is a prefix test rather than a reading.
+ * Same shape as the eval judge: reasoning first, then the verdict alone on
+ * the last line (judge-verdict.ts says why).
  */
 export declare function judgePrompt(rubric: string, reply: string, work: string): string;
 /**

package/dist/src/step-exec.js

@@ -7,6 +7,7 @@
 // assembles the system prompt and builds MCP servers, then hands this the
 // results. That is what lets the same function run somewhere the vault, the
 // library and the account do not exist.
+import { judgeVerdict, JUDGE_VERDICT_INSTRUCTION } from "./judge-verdict.js";
 import { runHook, runToolCallHooks, matchesTool, hookLine, resolveHooks } from "./hooks.js";
 import fs from "node:fs";
 import os from "node:os";
@@ -901,6 +902,8 @@ async function executeStepInner(opts, runQuery) {
                 data,
                 modelEnv: opts.env,
                 signal: halt.signal,
+                ...(opts.judgeModel ? { judgeModel: opts.judgeModel } : {}),
+                ...(opts.judgeEffort ? { judgeEffort: opts.judgeEffort } : {}),
             });
         }
         finally {
@@ -1045,17 +1048,17 @@ export async function checkVerify(agentDir, verify, ctx) {
             // GOOD` on a reply that did (fix-desk, run-muwevg72-7mza): the joined
             // text opened with the narration before it.
             const reply = ctx.conclusion?.trim() ? ctx.conclusion : output;
-            const verdict = await judgeReply(value, reply, output, ctx.modelEnv ?? {}, ctx.signal);
-            const ok = /^\s*PASS\b/i.test(verdict);
-            return { ok, headline: ok ? "PASS" : "FAIL", detail: verdict.slice(0, 300) };
+            const said = await judgeReply(value, reply, output, ctx.modelEnv ?? {}, ctx.signal, ctx.judgeModel, ctx.judgeEffort);
+            const { passed: ok, detail } = judgeVerdict(said);
+            return { ok, headline: ok ? "PASS" : "FAIL", detail };
         }
     }
     return { ok: false, headline: `unknown check "${kind}"`, detail: "" };
 }
 /**
  * A toolless, fast-tier grading call: does the reply satisfy the sentence?
- * Same shape as the eval judge, and answered with one word first so the
- * verdict is a prefix test rather than a reading.
+ * Same shape as the eval judge: reasoning first, then the verdict alone on
+ * the last line (judge-verdict.ts says why).
  */
 export function judgePrompt(rubric, reply, work) {
     const shown = reply.slice(0, 20_000);
@@ -1063,12 +1066,11 @@ export function judgePrompt(rubric, reply, work) {
         ? `Everything the step wrote while working, for context. "The reply" means only the reply block below, ` +
             `never this:\n<work>\n${work.slice(-20_000)}\n</work>\n\n`
         : "";
-    return (`You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
-        `first word, then one sentence of reason.\n\nRequirement: ${rubric}\n\n` +
+    return (`You are grading a reply against one requirement. ${JUDGE_VERDICT_INSTRUCTION}\n\nRequirement: ${rubric}\n\n` +
         context +
         `<reply>\n${shown}\n</reply>`);
 }
-async function judgeReply(rubric, reply, work, env, signal) {
+async function judgeReply(rubric, reply, work, env, signal, model = "haiku", effort) {
     const texts = [];
     const abortController = new AbortController();
     if (signal?.aborted)
@@ -1078,7 +1080,8 @@ async function judgeReply(rubric, reply, work, env, signal) {
         const q = query({
             prompt: judgePrompt(rubric, reply, work),
             options: {
-                model: "haiku",
+                model,
+                ...(effort ? { effort } : {}),
                 systemPrompt: "You grade text against a stated requirement. Be strict and literal.",
                 tools: [],
                 settingSources: [],

package/dist/src/store.d.ts

@@ -3,6 +3,7 @@ import type { BrowserPodOutcome } from "./browser-pod.ts";
 import { singleWorkspace } from "./paths.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
+import { frontmatterErrorText } from "./matter.ts";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
  * for the CLI: `foldrun probe` used to import gray-matter itself, which is
@@ -640,9 +641,7 @@ export interface AgentAssets {
 }
 export declare function agentAssets(tenant: string, workspace: string, agent: string): AgentAssets;
 export declare function listAgents(tenant: string, workspace: string): AgentInfo[];
-/** 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;
+export { frontmatterErrorText };
 /** The option keys a step actually has. An indented `word: rest` that is
  *  NOT one of these is a line of the instruction — "Warning: do not
  *  publish" is prose that happens to contain a colon, and it used to be
@@ -1069,6 +1068,14 @@ export interface StepAttempt {
 export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns">;
 export { type TokenUsage, type PromptLayerRecord, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.ts";
 import { type TokenUsage, type PromptLayerRecord } from "./tokens.ts";
+/** The marker rescueStep puts in a rescue's instruction; how a rescue record
+ *  written before `rescueOf` existed is still recognised. */
+export declare const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
+/** Is this record an on-fail rescue rather than a step of the flow? */
+export declare function isRescueRecord(step: {
+    rescueOf?: string;
+    instruction?: string | null;
+}): boolean;
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1228,6 +1235,13 @@ export interface StepRecord {
      *  actually executed in. Carried steps provide context and are never
      *  billed again — the original run's ledger line already paid for them. */
     carriedFrom?: string;
+    /** Set on an on-fail rescue record (runner.ts rescueStep): the agent of the
+     *  failed step it took over. A rescue is not a step of the flow: a resumed
+     *  drive must not launch it as one of its group, and a re-run must not
+     *  copy it as work (21 Oct 2026: one rerun carried 77 fixers as pending
+     *  steps). Records written before this field are recognised by their
+     *  instruction's `<rescue>` block instead — see isRescueRecord. */
+    rescueOf?: string;
     /**
      * Sandbox seconds this step rented, and how many of them were cold start.
      * Set only on the isolated path — an in-process step rents nothing, so

package/dist/src/store.js

@@ -27,7 +27,7 @@ import { recordRevision, registerTreeReader } from "./history.js";
 import { dataRoot, singleWorkspace, singleAccountRoot, entriesNoFollow } from "./paths.js";
 import { platform } from "./platform.js";
 import { toLF, asRaw } from "./eol.js";
-import matter from "./matter.js";
+import matter, { frontmatterErrorText, configMatter } from "./matter.js";
 import { readAgentsMdKeys } from "./agents-md.js";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
@@ -39,7 +39,7 @@ import { readAgentsMdKeys } from "./agents-md.js";
  * the runtime, and there is nothing to fail to import.
  */
 export function readFrontmatter(file) {
-    return matter(fs.readFileSync(file, "utf8")).data;
+    return configMatter(fs.readFileSync(file, "utf8")).data;
 }
 import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.js";
 import { refNames } from "./refs.js";
@@ -1126,7 +1126,7 @@ export function listAgents(tenant, workspace) {
         let data = {};
         let frontmatterError;
         try {
-            ({ data } = matter(fs.readFileSync(path.join(dir, name, "agent.md"), "utf8")));
+            ({ data } = configMatter(fs.readFileSync(path.join(dir, name, "agent.md"), "utf8")));
         }
         catch (err) {
             frontmatterError = frontmatterErrorText(err);
@@ -1181,12 +1181,9 @@ export function listAgents(tenant, workspace) {
         };
     });
 }
-/** 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 function frontmatterErrorText(err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return `frontmatter does not parse — ${msg.split("\n")[0].trim()}. Quote a value that contains a colon followed by a space.`;
-}
+// Kept here for callers that import it from the store; it lives in matter.ts
+// so the scanner can use it without the store.
+export { frontmatterErrorText };
 /** The body of a file whose frontmatter would not parse: what follows the
  *  closing fence, so a flow's steps can still be read and shown. */
 function bodyAfterFrontmatter(raw) {
@@ -1360,7 +1357,7 @@ export function parseFlow(file, raw) {
     let content;
     let frontError = null;
     try {
-        ({ data, content } = matter(raw));
+        ({ data, content } = configMatter(raw));
     }
     catch (err) {
         frontError = frontmatterErrorText(err);
@@ -2658,6 +2655,13 @@ export function sumAttempts(tries) {
 }
 export { tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.js";
 import { sumTokens } from "./tokens.js";
+/** The marker rescueStep puts in a rescue's instruction; how a rescue record
+ *  written before `rescueOf` existed is still recognised. */
+export const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
+/** Is this record an on-fail rescue rather than a step of the flow? */
+export function isRescueRecord(step) {
+    return !!step.rescueOf || (step.instruction ?? "").includes(RESCUE_MARKER);
+}
 // ---------------------------------------------------------------- captured calls
 //
 // What each tool call took and gave (FOL-54 step 4), beside the run under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/agent-import.ts

@@ -15,7 +15,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "./matter.ts";
+import { configMatter } from "./matter.ts";
 import {
   assertSafeName,
   listWorkspaceFiles,
@@ -99,7 +99,7 @@ export function importAgent(
     let content = readWorkspaceFile(tenant, from, src);
     const rel = src.slice(`agents/${agent}/`.length);
     if (rel === "agent.md") {
-      front = matter(content).data as Record<string, unknown>;
+      front = configMatter(content).data as Record<string, unknown>;
       // The folder is the name flows address; a `name:` that disagrees with
       // it is the first thing check would complain about.
       if (name !== agent) content = content.replace(/^(---\r?\n(?:[\s\S]*?\r?\n)?)name:[^\n]*$/m, `$1name: ${name}`);

package/src/agent-tools.ts

@@ -17,7 +17,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import matter from "./matter.ts";
+import { configMatter } from "./matter.ts";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { resolveModel, resolveEffort, type Effort } from "./store.ts";
@@ -51,7 +51,7 @@ export function gatherConsults(
       missing.push(name);
       continue;
     }
-    const parsed = matter(fs.readFileSync(file, "utf8"));
+    const parsed = configMatter(fs.readFileSync(file, "utf8"));
     consults.push({
       name,
       systemPrompt:

package/src/agents-md.ts

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

package/src/completions.ts

@@ -10,7 +10,7 @@
 // renders them.
 
 import { PROVIDERS } from "./providers.ts";
-import { FRONTMATTER, type SchemaKind } from "./frontmatter-fields.ts";
+import { FRONTMATTER, JOBS, fieldsOfJob, type SchemaKind } from "./frontmatter-fields.ts";
 
 export interface Vocabulary {
   agents: string[];
@@ -660,8 +660,31 @@ export function completionsAt(
     }
   }
 
-  // 6. An indented option under a flow step.
-  if (kind === "flow" && /^\s+[a-z]*$/.test(line) && line.trim().length >= 0) {
+  // 5b. An indented line inside one of the four job blocks (governance,
+  //     guardrail, observability, evaluation): that job's fields for this
+  //     kind of file — the block takes nothing else.
+  const fmClose = text.indexOf("\n---", text.indexOf("---") + 3);
+  const insideFrontmatter = text.startsWith("---") && (fmClose === -1 || cursor <= fmClose);
+  const nested = line.match(/^(\s+)([a-zA-Z_]*)$/);
+  if (insideFrontmatter && nested) {
+    const header = before.slice(0, lineStart).split("\n").reverse().find((l) => /^\S/.test(l));
+    const job = JOBS.find((j) => new RegExp(`^${j.name}\\s*:\\s*$`).test(header ?? ""));
+    if (job) {
+      const schemaKind = /(^|\/)AGENTS\.md$/.test(path) || path === "project.md" ? "agents-md" : SCHEMA_OF[kind];
+      const keys = new Set(schemaKind ? fieldsOfJob(schemaKind, job.name) : []);
+      const partial = nested[2] ?? "";
+      return {
+        from: cursor - partial.length,
+        query: partial,
+        items: filter(fieldsFor(path, kind).filter((c) => keys.has(c.label.split(".")[0]!)), partial),
+        title: `${job.title} — ${job.what}`,
+      };
+    }
+  }
+
+  // 6. An indented option under a flow step — the body's steps, never a
+  //    line inside the frontmatter.
+  if (kind === "flow" && !insideFrontmatter && /^\s+[a-z]*$/.test(line) && line.trim().length >= 0) {
     const partial = line.trim();
     return {
       from: cursor - partial.length,