@foldrun/core 2.5.0 → 2.6.0

package/src/runner.ts

@@ -10,7 +10,7 @@ import { hookNames } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import matter from "./matter.ts";
+import matter, { parseLenient, configMatter } from "./matter.ts";
 import { spawn } from "node:child_process";
 import {
   knownPrice, executeStep, extractJson, stepCeiling, stepCeilingFor, type EventExtra } from "./step-exec.ts";
@@ -21,6 +21,7 @@ import { eventUrl } from "./webhook.ts";
 import { runStepInContainer, sizeLimits, killRunSandboxes, type StepTiming } from "./run-container.ts";
 import { hostSafeEnv, platformApiUrl } from "./host-env.ts";
 import { resolveModelCredential, credentialLine, accountModelBlock, isClaudeLoginToken, isModelEnvName, DECLARED_ENV_PREFIX } from "./model-credential.ts";
+import { parseJudge } from "./judge-verdict.ts";
 import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.ts";
 import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute, type EgressGrant } from "./egress.ts";
 import { explainRefusal, isRefusalStatus, refusalFromLine, supplyNote, type SupplyState } from "./refusal.ts";
@@ -70,6 +71,7 @@ import {
   checkFormatVersion,
   readRun,
   writeRun,
+  isRescueRecord,
   runSummary,
   verdictOf,
   type FlowStep,
@@ -335,28 +337,9 @@ const toTags = (v: unknown): string[] =>
 // rather than dropping the skill, so a cross-client skill still loads here.
 function safeMatter(raw: string): { data: Record<string, unknown> } {
   // gray-matter caches a *failed* parse as a hollow success; ./matter.ts
-  // parses every call, so the throw below is deterministic and the fallback
-  // fires every time (it used to clear gray-matter's cache here for that).
-  try {
-    return matter(raw) as { data: Record<string, unknown> };
-  } catch {
-    const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    if (fm) {
-      const fixed = fm[1].replace(
-        /^([A-Za-z0-9_-]+):[ \t]+(?!["'>|])(.*:.*)$/gm,
-        (_m, k: string, v: string) => `${k}: ${JSON.stringify(v)}`,
-      );
-      try {
-        // A function replacer, not a string: a fixed block containing `$&` or
-        // `$$` (a value with those in it) would otherwise be treated as a
-        // replacement pattern and splice the whole frontmatter into itself.
-        return matter(raw.replace(fm[1], () => fixed)) as { data: Record<string, unknown> };
-      } catch {
-        /* fall through */
-      }
-    }
-    return { data: {} };
-  }
+  // parses every call, so the strict read throws every time and the lenient
+  // one (shared with check, which warns about it) fires every time.
+  return { data: parseLenient(raw).data };
 }
 
 // Both layouts: <root>/<name>/SKILL.md (Agent Skills standard) and the flat
@@ -452,7 +435,7 @@ export function readAgentsMd(dir: string): { data: Record<string, unknown>; body
     const file = path.join(dir, name);
     if (!fs.existsSync(file)) continue;
     try {
-      const parsed = matter(fs.readFileSync(file, "utf8"));
+      const parsed = configMatter(fs.readFileSync(file, "utf8"));
       return { data: parsed.data as Record<string, unknown>, body: withoutAgentRules(parsed.content).trim() };
     } catch {
       return null;
@@ -855,7 +838,7 @@ export function agentContext(
   // agentDir is <data>/<tenant>/projects/<workspace>/agents/<agent>, so the
   // workspace a secret should resolve against is two levels up.
   const workspace = path.basename(path.resolve(agentDir, "..", ".."));
-  const { data: front, content: body } = matter(
+  const { data: front, content: body } = configMatter(
     fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"),
   );
   // The prompt's sections, by name and by how often they change. Added in
@@ -2089,6 +2072,15 @@ async function runStep(
   // AGENTS.md — every model call always; each tool call's input and output
   // unless it says `metadata`.
   const capture: "metadata" | "full" = workspaceFrontmatter(agentDir, tenant).capture === "metadata" ? "metadata" : "full";
+  // `judge:` (AGENTS.md): the model and effort every `verify: judge:` here
+  // grades with — field by field, the workspace's else the account's.
+  const { judgeModel, judgeEffort } = (() => {
+    const ws = parseJudge(readAgentsMd(workspaceRootOf(agentDir))?.data?.judge);
+    const account = parseJudge(readAgentsMd(accountDir(tenant))?.data?.judge);
+    const model = ws.model ?? account.model;
+    const effort = resolveEffort(ws.effort ?? account.effort ?? "");
+    return { judgeModel: model ? resolveModel(model) : undefined, judgeEffort: effort ?? undefined };
+  })();
   // A step that pours out content stops being recorded past this — its
   // calls keep their names, sizes and times (FOL-54 step 4).
   let capturedChars = 0;
@@ -2857,6 +2849,8 @@ async function runStep(
           budgetNote: stepBudgetNote,
           price: tokenPrice,
           verify: step.verify,
+          ...(judgeModel ? { judgeModel } : {}),
+          ...(judgeEffort ? { judgeEffort } : {}),
           output: step.output,
           schema: resolvedSchema ?? undefined,
           maxTurns: step.maxTurns,
@@ -2913,6 +2907,9 @@ async function runStep(
         emit: pushWatching,
         // Stamps the sandbox, so stopping this run can destroy it.
         runId,
+        // A step still waiting for room has no sandbox to destroy; the
+        // executor asks this before it creates one (pod-room.ts).
+        ...(stopRequested ? { stopRequested } : {}),
         size,
         // The pod's network, for the executor's own wall (the k8s tier's
         // network policy): a filtered pod reaches the proxy and DNS only.
@@ -3252,6 +3249,8 @@ async function runStep(
         budgetNote: stepBudgetNote,
         price: tokenPrice,
         verify: step.verify,
+        ...(judgeModel ? { judgeModel } : {}),
+        ...(judgeEffort ? { judgeEffort } : {}),
         output: step.output,
         schema: resolvedSchema ?? undefined,
         maxTurns: step.maxTurns,
@@ -3455,7 +3454,7 @@ export function copyTreeBytes(from: string, to: string) {
 function openApiSources(agentDir: string, tenant: string): string[] {
   const out = new Set<string>();
   try {
-    const { data } = matter(fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"));
+    const { data } = configMatter(fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"));
     const front = data as { apis?: unknown; tools?: unknown };
     for (const api of parseApis(front.apis)) if (api.openapi?.startsWith("https://")) out.add(api.openapi);
     const workspace = path.basename(path.resolve(agentDir, "..", ".."));
@@ -4080,10 +4079,30 @@ function driveRunInner(
    *
    * The flag is one-way: nothing here clears it, so the read-modify-write can
    * only ever turn a stop on, never off.
+   *
+   * And once it is on, this copy may not undo what stopRun wrote: the run
+   * stays failed, and steps that had not started stay skipped. Before
+   * 21 Oct 2026 only the flag came across, so the next save put the record
+   * back to `running` with its steps pending; a second stop then answered
+   * "failed" instead of "already failed", and the group kept starting pods
+   * (medium-desk run-mvho48wp-99e1). A step running in THIS process is left
+   * as it is: its sandbox is gone, it ends on its own, and records how.
    */
   const save = () => {
-    if (!run.stopRequested && readRun(tenant, workspace, run.id)?.stopRequested) {
-      run.stopRequested = true;
+    const disk = run.stopRequested ? null : readRun(tenant, workspace, run.id);
+    if (disk?.stopRequested) run.stopRequested = true;
+    if (run.stopRequested) {
+      if (run.status !== "completed" && run.status !== "failed") {
+        run.status = "failed";
+        run.finishedAt ??= disk?.finishedAt ?? new Date().toISOString();
+      }
+      run.parkedAt = null;
+      for (const s of run.steps) {
+        if (s.status === "pending" || s.status === "awaiting-approval") {
+          s.status = "skipped";
+          s.skipReason ??= "run stopped";
+        }
+      }
     }
     writeRun(tenant, workspace, run);
   };
@@ -4301,13 +4320,20 @@ function driveRunInner(
         for (let i = gi - 1; i >= 0; i--) if (groupData[i] !== undefined) return groupData[i];
         return undefined;
       };
-      const dataOf = (group: StepRecord[]): unknown => {
+      // A rescue's result already stands on the step it took over, so the
+      // three handoffs below read the flow's steps only: counting the rescue
+      // too handed the next group the same output twice, or a stale one
+      // from an evaluator loop's earlier cycle.
+      const flowStepsOf = (group: StepRecord[]) => group.filter((s) => !isRescueRecord(s));
+      const dataOf = (all: StepRecord[]): unknown => {
+        const group = flowStepsOf(all);
         const carrying = group.filter((s) => s.status === "completed" && s.data !== undefined);
         if (carrying.length === 0) return undefined;
         if (carrying.length === 1 && !carrying[0].item) return carrying[0].data;
         return carrying.map((s) => ({ agent: s.agent, ...(s.item ? { item: s.item } : {}), data: s.data }));
       };
-      const resultsOf = (group: StepRecord[]): string | null => {
+      const resultsOf = (all: StepRecord[]): string | null => {
+        const group = flowStepsOf(all);
         const results = group
           .filter((s) => s.status === "completed" && s.result)
           .map((s) =>
@@ -4321,8 +4347,8 @@ function driveRunInner(
       };
       // What each step concluded — its final turn — for the handoffs that
       // should read a conclusion rather than a transcript (`each: lines`).
-      const conclusionsOf = (group: StepRecord[]): string | null => {
-        const out = group
+      const conclusionsOf = (all: StepRecord[]): string | null => {
+        const out = flowStepsOf(all)
           .filter((s) => s.status === "completed" && (s.conclusion || s.result))
           .map((s) => s.conclusion || s.result!);
         return out.length ? out.join("\n") : null;
@@ -4709,7 +4735,7 @@ function driveRunInner(
           save();
           if (freshGroup.every((s) => s.status !== "pending")) {
             // everything in this group was rejected
-            if (freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom)) {
+            if (freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isRescueRecord(s))) {
               run.status = "failed";
               break;
             }
@@ -4723,7 +4749,11 @@ function driveRunInner(
         // itself mid-turn at its share, so a fan-out of twenty cannot end
         // twenty steps over — the shares sum to what was left. Between
         // groups the check above still refuses to start the next one.
-        const launching = freshGroup.filter((s) => s.status === "pending");
+        // A rescue record is the on-fail of a step in this group, not a step
+        // of the flow: one left pending by a drive that died is picked up by
+        // rescueStep below, never launched alongside the group (21 Oct 2026:
+        // a resumed run launched 77 leftover fixers at once).
+        const launching = freshGroup.filter((s) => s.status === "pending" && !isRescueRecord(s));
         // tools: [peers] — what each step of the group is told about the
         // others, and the bus they share when they run in this process.
         const peerBus = localPeerBus();
@@ -4788,7 +4818,7 @@ function driveRunInner(
                 // lead's reply or for a slot — must not start it: the
                 // between-groups check runs only once this group is over,
                 // and save() is what carries the flag in from the record.
-                if (lead || pool) {
+                {
                   save();
                   if (run.stopRequested) {
                     step.status = "skipped";
@@ -4968,6 +4998,13 @@ function driveRunInner(
         // runs out of cycles below, which used to fail the run without ever
         // reaching the step's on-fail (medium-desk's claim-trimmer was
         // written for exactly that case and could never run).
+        // A rescue hears a stop the way a group step does: its model loop and
+        // its executor's wait for room both poll this (no sandbox exists yet
+        // for a stop to destroy while it waits).
+        const stopPoll = () => {
+          save();
+          return run.stopRequested === true;
+        };
         const rescueStep = async (step: StepRecord): Promise<void> => {
           if (!step.onFail) return;
           const rescuerDir = path.join(pDir, "agents", step.onFail);
@@ -4979,6 +5016,38 @@ function driveRunInner(
             });
             return;
           }
+          // One rescue per failure, across drives. A worker that died
+          // mid-rescue left an unfinished record behind it; the drive that
+          // resumes picks that one up instead of splicing another — a crash
+          // loop used to add one per restart (blog-desk run-mvh1zra7-ae4k,
+          // ~80). The leftover carries the same instruction, built from the
+          // same failure, and a running one may still hold a sandbox to
+          // re-attach to, so it is THE rescue; any further unfinished copies
+          // are superseded. A FINISHED rescue is history, never reused: it
+          // answered an earlier failure — an evaluator loop's previous cycle
+          // — not this one.
+          const leftovers: StepRecord[] = [];
+          for (let j = run.steps.indexOf(step) + 1; j < run.steps.length && isRescueRecord(run.steps[j]); j++) {
+            const r = run.steps[j];
+            if (r.agent === step.onFail && (r.rescueOf === undefined || r.rescueOf === step.agent) && (r.status === "pending" || r.status === "running")) {
+              leftovers.push(r);
+            }
+          }
+          const resumed = leftovers[0];
+          for (const r of leftovers.slice(1)) {
+            r.status = "skipped";
+            r.skipReason = "superseded on resume — one rescue per failure";
+          }
+          if (resumed) {
+            step.events.push({ t: new Date().toISOString(), type: "info", text: `resuming the rescue by [[${step.onFail}]] that an earlier drive started` });
+            resumed.rescueOf ??= step.agent;
+            resumed.attempts = Math.max(1, resumed.attempts ?? 0);
+            resumed.status = "running";
+            save();
+            await runStep(rescuerDir, tenant, resumed, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, null, undefined, run.test === true, stopPoll, flowTimezone, run.steps.indexOf(resumed));
+            settleRescue(step, resumed);
+            return;
+          }
           step.events.push({
             t: new Date().toISOString(),
             type: "info",
@@ -4995,6 +5064,7 @@ function driveRunInner(
           const owesMarker = step.until ? `\nThe step's loop ended without its marker: your reply must end with a line saying ${step.until}.` : "";
           const rescue: StepRecord = {
             agent: step.onFail,
+            rescueOf: step.agent,
             instruction:
               `${step.instruction}\n\n<rescue>\nYou are taking this step over: [[${step.agent}]] attempted it and failed. ` +
               `Its failure, for whatever it is worth:\n${failure}${approved}${owesMarker}\n</rescue>`,
@@ -5025,7 +5095,11 @@ function driveRunInner(
           rescue.attempts = 1;
           rescue.status = "running";
           save();
-          await runStep(rescuerDir, tenant, rescue, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, null, undefined, run.test === true, undefined, flowTimezone, run.steps.indexOf(rescue));
+          await runStep(rescuerDir, tenant, rescue, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, null, undefined, run.test === true, stopPoll, flowTimezone, run.steps.indexOf(rescue));
+          settleRescue(step, rescue);
+        };
+        // What a rescue's end means for the step it took over.
+        const settleRescue = (step: StepRecord, rescue: StepRecord): void => {
           // runStep mutates rescue.status; widen past TS's "running" narrowing.
           const rescueOutcome: string = rescue.status;
           if (rescueOutcome === "completed") {
@@ -5057,7 +5131,10 @@ function driveRunInner(
         // here: the person chose to start after it. Counting it stopped
         // fix-desk's "re-run from the verifier" (run-muwfi5jn-4217) in under
         // a second, before the one step it was asked to run.
-        const requiredFailed = freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom);
+        // A rescue record's own failure is already on the step it took over
+        // ("also failed"); counted here it would fail a group whose step a
+        // later rescue completed.
+        const requiredFailed = freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isRescueRecord(s));
         if (requiredFailed) {
           run.status = "failed";
           break;
@@ -5133,6 +5210,10 @@ function driveRunInner(
             });
             for (const s of [...ordered[gi - 1], ...freshGroup]) {
               if (s.status === "skipped" && s.each) continue; // an expanded template stays expanded
+              // A rescue answered its own failure and stays as it ended: reset
+              // to pending it read as an interrupted rescue, and the next
+              // cycle's failure was handed the old one's instructions.
+              if (isRescueRecord(s)) continue;
               s.status = "pending";
               s.result = null;
             }

package/src/scan.ts

@@ -27,7 +27,7 @@
 // reported, because "why is this allowed?" is the question a reviewer asks.
 
 import crypto from "node:crypto";
-import matter from "./matter.ts";
+import matter, { frontmatterErrorLine, frontmatterErrorText, parseLenient, configMatter } from "./matter.ts";
 import { refNames } from "./refs.ts";
 import { resolveNetwork } from "./network.ts";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.ts";
@@ -223,6 +223,35 @@ export const SCAN_RULES: readonly ScanRule[] = [
       "`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",
@@ -601,17 +630,31 @@ export function nearestField(key: string, known: readonly string[]): string | nu
 }
 
 function keyLine(lines: string[], key: string): number | undefined {
-  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: string): Record<string, unknown> | null {
+function frontOf(content: string, filePath?: string): Record<string, unknown> | null {
   if (!/^?---\r?\n/.test(content)) return null;
   try {
-    return matter(content).data as Record<string, unknown>;
+    // 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 as Record<string, unknown>;
   } catch {
     return null; // a frontmatter YAML cannot read is check's finding, not ours
   }
@@ -773,6 +816,16 @@ 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. */
@@ -833,9 +886,34 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
     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: unknown = 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) {
       for (const p of frontmatterProblems(schema, data, nearestField)) {
@@ -859,7 +937,7 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
   }
   // 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/src/starter.ts

@@ -62,6 +62,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}
@@ -492,6 +508,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/src/step-exec.ts

@@ -8,6 +8,7 @@
 // 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.ts";
 import { runHook, runToolCallHooks, matchesTool, hookLine, resolveHooks, type HookDef, type HookRecord } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
@@ -133,6 +134,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";
@@ -1066,6 +1072,8 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
         data,
         modelEnv: opts.env,
         signal: halt.signal,
+        ...(opts.judgeModel ? { judgeModel: opts.judgeModel } : {}),
+        ...(opts.judgeEffort ? { judgeEffort: opts.judgeEffort } : {}),
       });
     } finally {
       for (const t of clocks) clearTimeout(t);
@@ -1170,6 +1178,9 @@ export async function checkVerify(
     /** 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;
@@ -1233,9 +1244,9 @@ export async function checkVerify(
       // 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: "" };
@@ -1243,8 +1254,8 @@ export async function checkVerify(
 
 /**
  * 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: string, reply: string, work: string): string {
   const shown = reply.slice(0, 20_000);
@@ -1253,8 +1264,7 @@ export function judgePrompt(rubric: string, reply: string, work: string): string
       `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` +
+    `You are grading a reply against one requirement. ${JUDGE_VERDICT_INSTRUCTION}\n\nRequirement: ${rubric}\n\n` +
     context +
     `<reply>\n${shown}\n</reply>`
   );
@@ -1266,6 +1276,8 @@ async function judgeReply(
   work: string,
   env: Record<string, string | undefined>,
   signal?: AbortSignal,
+  model = "haiku",
+  effort?: Effort,
 ): Promise<string> {
   const texts: string[] = [];
   const abortController = new AbortController();
@@ -1275,7 +1287,8 @@ async function judgeReply(
     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: [],