@foldrun/core 0.3.0 → 0.5.0

package/src/eol.ts

@@ -0,0 +1,7 @@
+// Flow (and other markdown) rewrites work on LF text: the parser and the
+// line rules read "\n"-separated lines, and a CRLF line's trailing "\r"
+// defeats them (an option line never matched, so setting it again added a
+// second copy; a CRLF step line was no step at all). So each rewrite takes a
+// CRLF file as LF and gives it back as CRLF.
+export const toLF = (raw: string) => raw.replace(/\r\n/g, "\n");
+export const asRaw = (raw: string, out: string) => (raw.includes("\r\n") ? out.replace(/\r?\n/g, "\r\n") : out);

package/src/evals.ts

@@ -48,7 +48,7 @@ import {
   type Effort,
 } from "./store.ts";
 import { startFlowRun, loadFlow } from "./runner.ts";
-import { platform } from "./platform.ts";
+import { platform, platformQueues } from "./platform.ts";
 import type { FlowStep } from "./store.ts";
 
 export type Assertion =
@@ -80,6 +80,15 @@ export interface EvalInfo {
    *  `manual`: only when a person presses Run or the CLI asks — for a flow
    *  eval that costs a whole run and touches real systems every time. */
   trigger: "deploy" | "manual";
+  /** An eval's runs are test runs — nothing outward, state untouched —
+   *  unless the file says `live: true`. A flow eval that must really send
+   *  to prove itself opts in; nothing opts in by accident. */
+  live: boolean;
+  /** A file of saved inputs for a flow, not a test: `inputs: true`. Its
+   *  cases are named tasks the dashboard's "Run with…" and `foldrun invoke
+   *  --inputs` start the flow with; nothing is asserted, so no eval run,
+   *  deploy or `foldrun eval` ever runs them. */
+  inputs: boolean;
   cases: EvalCase[];
 }
 
@@ -187,6 +196,8 @@ export function parseEval(file: string, raw: string): EvalInfo {
     model: resolveModel(data.model ?? "fast"),
     effort: resolveEffort(data.effort ?? "low"),
     trigger: data.trigger === "manual" ? "manual" : "deploy",
+    live: data.live === true,
+    inputs: data.inputs === true,
     cases,
   };
 }
@@ -286,7 +297,8 @@ export function promoteRunToEval(
   let expect: string[];
   if (opts.expect && opts.expect.length > 0) {
     expect = opts.expect.map((line) => {
-      const m = oneLine(line).match(/^([a-z-]+):\s*(.*)$/);
+      const m = oneLine(line).match(/^([a-z-]+):(.*)$/);
+      if (m) m[2] = m[2].trim();
       if (!m || !(ASSERTION_TYPES as readonly string[]).includes(m[1]) || !m[2]) {
         throw refuse(
           `"${line}" is not an assertion — expected one of ${ASSERTION_TYPES.map((t) => `${t}:`).join(", ")} followed by a value`,
@@ -325,7 +337,7 @@ export function promoteRunToEval(
         409,
       );
     }
-    content = `${existing.replace(/\s+$/, "")}\n\n${caseText}`;
+    content = `${existing.trimEnd()}\n\n${caseText}`;
   } else {
     // A flow eval costs a whole run and touches real systems, so it waits
     // for a person to press Run rather than following every push.
@@ -389,16 +401,20 @@ export interface EvalResult {
   error?: string;
 }
 
-/** Wait for a run to finish, with a ceiling so a hung agent can't hang an eval. */
 /**
  * A web replica never drives a run: it has no route to the cluster API and
  * no right to create a pod, by design — so an eval started there (a push,
  * the Run button) queues its run for the worker like any other. From 29 Aug
  * every eval on the split platform died at "pod create failed: connection
  * refused" for exactly this reason. A single process — the CLI, a laptop,
- * FOLDRUN_ROLE unset — still drives it right here, as it always did.
+ * no platform registered — still drives it right here, as it always did.
+ *
+ * The test is whether a platform owns the queue, not which role this
+ * process was started as: on a worker the role read "worker", the eval
+ * started its run in-process, and the run never passed through the
+ * account cap or the lanes the platform enforces on every other run.
  */
-const runsViaQueue = () => process.env.FOLDRUN_ROLE === "web";
+const runsViaQueue = () => platformQueues();
 
 async function beginEvalRun(
   tenant: string,
@@ -407,8 +423,9 @@ async function beginEvalRun(
   flowName: string,
   model?: string | null,
   effort?: string | null,
+  test = true,
 ) {
-  if (!runsViaQueue()) return startFlowRun(tenant, workspace, steps, flowName, model, [], effort);
+  if (!runsViaQueue()) return startFlowRun(tenant, workspace, steps, flowName, model, [], effort, null, { test });
   // The job carries a model override but no effort one, and driveRun cannot
   // re-read a flow called `eval:<name>`. Put the flow's defaults onto the
   // steps that have none — which is what nearest-wins resolves to anyway.
@@ -417,7 +434,7 @@ async function beginEvalRun(
     ...(s.model || !model ? {} : { model }),
     ...(s.effort || !effort ? {} : { effort }),
   }));
-  return platform.enqueueFlowRun(tenant, workspace, withDefaults, flowName, model ?? null, []);
+  return platform.enqueueFlowRun(tenant, workspace, withDefaults, flowName, model ?? null, [], null, { test });
 }
 
 // Waits for as long as the run runs. There was a cap here (5 minutes, then
@@ -539,8 +556,11 @@ export async function runEval(
 ): Promise<EvalResult> {
   const startedAt = new Date().toISOString();
   const results: CaseResult[] = [];
+  // Saved inputs carry no assertions: running them would start and bill a
+  // run per case only to report every one failed. Nothing to grade.
+  const cases = info.inputs ? [] : info.cases;
 
-  for (const testCase of info.cases) {
+  for (const testCase of cases) {
     const target = info.flow ? null : info.agent;
     let runId: string | null = null;
     let output = "";
@@ -558,7 +578,9 @@ export async function runEval(
             ? { ...s, instruction: `${s.instruction}\n\n<run_task>\n${testCase.task}\n</run_task>` }
             : s,
         );
-        run = await beginEvalRun(tenant, workspace, steps, `eval:${info.name}`, flow.model, flow.effort);
+        // Test unless the eval OR the flow says live: an eval that runs a
+        // flow written `live: true` was written by someone who knew.
+        run = await beginEvalRun(tenant, workspace, steps, `eval:${info.name}`, flow.model, flow.effort, !(info.live || flow.live));
       } else {
         if (!target) throw new Error("this eval names neither an agent nor a flow");
         run = await beginEvalRun(
@@ -566,6 +588,9 @@ export async function runEval(
           workspace,
           [{ agent: target, instruction: testCase.task, group: 1, optional: false }],
           `eval:${info.name}`,
+          undefined,
+          undefined,
+          !info.live,
         );
       }
       runId = run.id;
@@ -752,7 +777,7 @@ export async function evaluateDeployed(
   if (!stamp) return { ran: 0, skipped: "no revision to stamp the result with" };
   // Only the evals that asked to run on deploy — a `trigger: manual` eval is
   // one a person runs on purpose, because it costs a whole flow run.
-  const evals = listEvals(tenant, workspace).filter((e) => e.trigger !== "manual");
+  const evals = listEvals(tenant, workspace).filter((e) => e.trigger !== "manual" && !e.inputs);
   if (evals.length === 0) return { ran: 0, skipped: "no evals" };
   const dir = path.join(workspaceDir(tenant, workspace), "evals", ".results");
   fs.mkdirSync(dir, { recursive: true });

package/src/flow-lint.ts

@@ -12,6 +12,19 @@
 // blocked — flows still run, warnings are advisory.
 
 import type { FlowInfo, FlowStep } from "./store.ts";
+import { whenRowsPath } from "./store.ts";
+import { timezoneProblem } from "./clock.ts";
+
+/** What a `[[flow:x]]` step's options are called in a flow file, for the
+ *  ones expandSubflows does not carry into the nested steps. */
+const SUBFLOW_DROPPED: [keyof FlowStep, string][] = [
+  ["approve", "an approval (!)"], ["when", "when:"], ["case", "case:"], ["else", "else:"],
+  ["retry", "retry:"], ["timeout", "timeout:"], ["verify", "verify:"], ["model", "model:"],
+  ["effort", "effort:"], ["onFail", "on-fail:"], ["waitSecs", "wait:"], ["waitFor", "wait:"],
+  ["ask", "ask:"], ["preview", "preview:"], ["delegate", "delegate:"], ["loop", "loop:"],
+  ["until", "until:"], ["each", "each:"], ["max", "max:"], ["output", "output:"],
+  ["schema", "schema:"], ["parallel", "parallel:"], ["maxTurns", "max_turns:"], ["limits", "limits:"],
+];
 
 export interface FlowWarning {
   /** Index into flow.steps, or null for a whole-flow warning. */
@@ -20,6 +33,13 @@ export interface FlowWarning {
   line?: number;
   message: string;
   detail: string;
+  /** "error" for a value the parser could not read — `timeout: abc` — which
+   *  `foldrun check` must fail on rather than note. Absent means advisory,
+   *  which every structural warning in this file is. */
+  level?: "error" | "warn";
+  /** A stable tag for warnings a caller wants to single out — the deploy
+   *  surfaces `kind: "outward"` as a non-blocking warning. */
+  kind?: string;
 }
 
 // Anaphora: phrases that only mean something if earlier output exists.
@@ -33,12 +53,63 @@ const REFERS_BACK =
  *  checks too. */
 export interface KnownNames {
   agents: string[];
+  /** Agents that hold a tool declaring `outward: true` — one that sends,
+   *  posts, buys or publishes. The caller resolves the grants; this file only
+   *  needs the answer. Absent means the caller did not look, and the outward
+   *  rule is skipped rather than guessed at. */
+  outwardAgents?: string[];
+}
+
+/** One @, something either side, a dot in the domain, no whitespace. Written
+ *  as string checks rather than a regex: the obvious pattern backtracks
+ *  polynomially on a domain full of dots, and a lint that can be made slow
+ *  by a flow file is a lint someone will turn off. */
+function looksLikeAddress(a: string): boolean {
+  const at = a.indexOf("@");
+  if (at < 1 || at !== a.lastIndexOf("@") || /\s/.test(a)) return false;
+  const domain = a.slice(at + 1);
+  const dot = domain.indexOf(".");
+  return dot > 0 && dot < domain.length - 1;
+}
+
+/** The assertion words a `verify:` may open with. Anything else is handed to
+ *  a shell — see `checkVerify` in step-exec.ts, which owns this list. */
+const VERIFY_ASSERTION = /^(contains|not-contains|matches|file|judge):\s/;
+
+/** What a shell command has that a sentence does not: an operator that only
+ *  means something to a shell, a path or bracket at the very start, or one
+ *  of the commands these flows actually reach for. Deliberately NOT any
+ *  punctuation a sentence might carry — the first version disqualified on
+ *  `;`, `,`, `'` and `"`, so "the reply opens with GOOD; a GOOD reply names
+ *  the SHA" read as shell and a guaranteed exit 127 sat in fix-desk unseen
+ *  by the very lint written to catch it. */
+const LOOKS_LIKE_SHELL =
+  /&&|\|\||\s\|\s|\$\(|\$\{|`|\s[<>]\s|\d?>[>&]?\s|^\[|^[.~/]|^\s*\b(test|grep|egrep|find|head|tail|cat|ls|node|npm|npx|bash|sh|zsh|python3?|jq|awk|sed|curl|git|make|exit|n=|[A-Za-z_]+=)/;
+
+/** A `verify:` that is a claim in English rather than a command. Conservative
+ *  on purpose, the same bargain as REFERS_BACK: it must have no assertion
+ *  prefix, nothing shell-shaped anywhere in it, and enough words to be a
+ *  sentence — so a bare `./check.sh` or a one-word command is left alone and
+ *  the warning only fires where the author plainly wrote prose. */
+function looksLikeProse(verify: string): boolean {
+  const v = verify.trim();
+  if (!v || VERIFY_ASSERTION.test(v)) return false;
+  if (LOOKS_LIKE_SHELL.test(v)) return false;
+  return v.split(/\s+/).length >= 4;
 }
 
 export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
   const warnings: FlowWarning[] = [];
   const agentNames = known ? new Set(known.agents) : null;
 
+  // A frontmatter enum the parser could not read, or a step line whose
+  // `[[target]]` is malformed — recorded by parseFlow, reported here at
+  // error level so `foldrun check` fails on it, the way a bad step option
+  // does. A value nothing can read is never a silent default.
+  for (const fp of flow.frontProblems ?? []) {
+    warnings.push({ step: null, level: "error", message: fp, detail: "The line is written but its value cannot be read, so a run would use a silent default instead of what the author meant. Write one of the values the option names, or a target in lower case, digits and dashes." });
+  }
+
   // Cron's oldest trap, and an expensive one: when day-of-month AND
   // day-of-week are both restricted they are OR'd, not AND'd — the scheduler
   // does it too, correctly (`domRestricted && dowRestricted` → `domOk ||
@@ -47,6 +118,86 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
   // eleven runs where one was meant. Nothing about the expression looks wrong,
   // which is exactly why it needs saying here rather than being discovered on
   // the bill.
+  // An approvers list only one word can satisfy. `approvers: [editors]` is
+  // a role that is not `admins` and not an address; mayApprove would then
+  // refuse every person, and the gate could only ever be answered by an
+  // emailed link. Said here rather than discovered at the gate.
+  const odd = (flow.approvers ?? []).filter((a) => a !== "admins" && !looksLikeAddress(a));
+  if (odd.length) {
+    warnings.push({
+      step: null,
+      message: `approvers: ${odd.join(", ")} — not an email address, and the only role word is admins`,
+      detail: "Each entry is an address that may answer this flow's gates, or the word `admins`. Anything else matches nobody, and a list nobody matches locks every gate.",
+    });
+  }
+  // A flow with an approvers list and no gate at all is a rule the author
+  // believes is in force and which does nothing — the worst kind of safety
+  // control.
+  if (flow.approvers?.length && !flow.steps.some((s) => s.approve || s.ask)) {
+    warnings.push({
+      step: null,
+      message: "approvers: is set but no step in this flow is a gate",
+      detail:
+        "Nothing here waits for a person, so the list has no effect. Mark the step that needs " +
+        "a second pair of eyes with `!` (or `approve: true`), or drop the approvers: line.",
+    });
+  }
+  // A zone nobody can read is two faults at once: the cron fires at the
+  // wrong hour, and every step's calendar quietly falls through to the level
+  // above. Both are invisible in a green run, so `foldrun check` refuses it.
+  const zoneProblem = timezoneProblem(flow.timezone);
+  if (zoneProblem) {
+    warnings.push({
+      step: null,
+      level: "error",
+      message: zoneProblem,
+      detail:
+        "This is the zone the schedule fires in AND the calendar every step in this flow works " +
+        "to. Unreadable, the schedule falls back to UTC and each step inherits the workspace's " +
+        "zone instead of this one.",
+    });
+  }
+  // A deadline on a gate that does not exist reads as a safety net and is not
+  // one. Same reasoning, said separately because the fix is different.
+  if (flow.approveWithin && !flow.steps.some((s) => s.approve || s.ask)) {
+    warnings.push({
+      step: null,
+      message: "approve_within: is set but no step in this flow is a gate",
+      detail: "Nothing waits for a person, so nothing can expire. Mark a step with `!`, or drop the line.",
+    });
+  }
+  // A throttle no schedule can ever trip: the flow cannot run more often
+  // than its cron fires, so a floor below that interval never fires either.
+  // Cheap to write, silently pointless, and a reader will believe it.
+  if (flow.throttle && flow.trigger === "schedule" && flow.schedule) {
+    warnings.push({
+      step: null,
+      message: `throttle: on a scheduled flow — check it is shorter than the schedule, or it will drop runs you meant to happen`,
+      detail:
+        "A schedule already decides how often this runs. A throttle longer than the gap between " +
+        "fires silently skips them; if that is what you want, say it in the cron instead.",
+    });
+  }
+  // `idempotency:` only has a delivery to read on a trigger that receives
+  // one. On a schedule or a chained flow there is no request and no field,
+  // so the key is inert.
+  if (flow.idempotency && flow.trigger !== "webhook" && flow.trigger !== "email") {
+    warnings.push({
+      step: null,
+      message: `idempotency: has nothing to read on trigger: ${flow.trigger}`,
+      detail:
+        "A delivery id comes off an incoming request, so this only does something for " +
+        "trigger: webhook or trigger: email. On any other trigger it is ignored.",
+    });
+  }
+  // `catchup:` is about a fire that was missed, which only a clock can miss.
+  if (flow.catchup && flow.trigger !== "schedule") {
+    warnings.push({
+      step: null,
+      message: `catchup: has no effect on trigger: ${flow.trigger}`,
+      detail: "Only a schedule can miss a fire. Every other trigger happens when it happens.",
+    });
+  }
   if (flow.schedule) {
     const [, , dom, , dow] = flow.schedule.trim().split(/\s+/);
     if (dom && dow && dom !== "*" && dow !== "*") {
@@ -63,6 +214,9 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
 
   // Trigger shapes that can never fire, said at check time rather than
   // discovered as a flow that "never runs".
+  if (flow.budgetProblem) {
+    warnings.push({ step: null, message: flow.budgetProblem, detail: "A flow's `budget:` is the most one run may spend — a number in USD, or `unlimited`. A cap over a day, week or month belongs in the workspace's or the account's AGENTS.md, where it means every run put together." });
+  }
   if (flow.trigger === "once" && !flow.at) {
     warnings.push({ step: null, message: "trigger: once needs an `at:` instant", detail: "Write `at: 2026-09-05T09:00:00+10:00` (ISO 8601). Without a readable instant this flow never fires." });
   }
@@ -87,6 +241,40 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
   flow.steps.forEach((step, i) => {
     const inFirstGroup = step.group === firstGroup;
 
+    // A value the parser refused. Not advisory: the run would go ahead on
+    // a number the author never wrote — `timeout: 15m` ran as one second
+    // for as long as this was a coercion — so the check fails instead.
+    for (const problem of step.problems ?? []) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        level: "error",
+        message: problem,
+        detail:
+          "The option is written but its value cannot be read, and a run would not do what the " +
+          "line says. Durations are seconds or 90s / 30m / 4h / 3d; counts are whole numbers " +
+          "within the key's cap (retry and loop at most 5, max at most 20).",
+      });
+    }
+
+    // An instruction written over more than one line. It is read in full
+    // now, but the parser had to decide where it stopped, and the line
+    // below a wrapped instruction is one edit away from being prose. Said
+    // out loud so an author who meant to wrap can see it, and one who did
+    // not can see what got joined on.
+    if (step.wrapped) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        message: `"${step.subflow ?? step.agent}" has an instruction spread over more than one line`,
+        detail:
+          "A step's instruction ends where the step ends: the indented lines directly under it " +
+          "are joined on, and the first blank line, option, heading, bullet or unindented line " +
+          "finishes it. Put the whole instruction on the step's own line — one line, however " +
+          "long — so what the agent is told does not depend on where the paragraph below begins.",
+      });
+    }
+
     // The first group starts with context = null. An instruction that points
     // at earlier output therefore points at nothing.
     if (inFirstGroup && step.instruction && REFERS_BACK.test(step.instruction)) {
@@ -100,6 +288,31 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
       });
     }
 
+    // `../../storage/…` still works everywhere; `workspace/storage/…` is the
+    // spelling that also works in a shell, and the one the docs teach. Said
+    // once per step, advisory — never an error on a path that resolves.
+    {
+      const rowsOf = step.when ? whenRowsPath(step.when) : null;
+      const spots = [
+        step.eachPath ? ["each: rows of", step.eachPath] : null,
+        rowsOf ? ["when: rows of", rowsOf] : null,
+        step.verify ? ["verify:", step.verify] : null,
+        step.schemaPath ? ["schema:", step.schemaPath] : null,
+        step.instruction ? ["the instruction", step.instruction] : null,
+      ].filter((x): x is [string, string] => !!x && /\.\.\/\.\.\/(storage|state)\b/.test(x[1]));
+      if (spots.length) {
+        warnings.push({
+          step: i,
+          line: step.line,
+          kind: "spelling",
+          message: `"${step.subflow ?? step.agent}" writes ../../storage or ../../state in ${spots.map((x) => x[0]).join(", ")}`,
+          detail:
+            "It still works. The documented spelling is workspace/storage/… and workspace/state/… — " +
+            "the same place, and it also resolves in the shell and in scripts.",
+        });
+      }
+    }
+
     // A gate with no `preview:` shows only the previous step's reply and
     // whatever files that reply happens to name. The person deciding sees a
     // summary, not the thing — unless the agent remembered.
@@ -115,6 +328,45 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
       });
     }
 
+    // A step that can act on the outside world, with nothing to say whether
+    // it did. The two answers are a check the runtime can fail on, or a
+    // person; either is fine, neither is not. This is the one lint here that
+    // is an error: every other structural warning costs a reread, and this
+    // one costs a send nobody can take back.
+    if (known?.outwardAgents?.includes(step.agent ?? "") && !step.verify && !step.approve && !step.ask) {
+      warnings.push({
+        step: step.group,
+        line: step.line,
+        level: "error",
+        kind: "outward",
+        message: `[[${step.agent}]] can act outside this workspace and this step has no verify: and no gate`,
+        detail:
+          "A step that sends, posts, buys or publishes needs one of two things: a `verify:` the " +
+          "runtime can fail the step on — a receipt file, a ledger row, the reply's own verdict " +
+          "line — or a person, with `!` or `ask:`. Without either, a step that sent nothing and a " +
+          "step that sent everything end the same way: reported as done.",
+      });
+    }
+
+    // retry: re-runs a failed step from the start. For a step that sends,
+    // a failure can come after the send — the verify: or the JSON check
+    // failed on a step whose email went — and the retry sends it again. The
+    // runner declines that one retry (see actedThenFailedCheck in runner.ts)
+    // but a crash mid-send still reruns; the author should know.
+    if (known?.outwardAgents?.includes(step.agent ?? "") && step.retry) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        kind: "outward",
+        message: `[[${step.agent}]] can act outside this workspace and this step has retry: ${step.retry}`,
+        detail:
+          "A retry runs the whole step again, sends included. The runner does not retry a failure " +
+          "that came from the check after the step's tools ran, but an attempt that failed mid-way — " +
+          "a timeout, a crash, a provider error after the first send — is retried and may repeat " +
+          "what it already did. Make the send idempotent (check a ledger before sending), or drop retry:.",
+      });
+    }
+
     // `each: items` fans out over DATA, and only an `output: json` step in
     // an earlier group produces any. Without one the step expands to
     // nothing every time, quietly — the exact failure this file exists for.
@@ -133,6 +385,64 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
       }
     }
 
+    // Two options that read another option to mean anything.
+    if (step.parallel && !step.each) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        message: `"${step.subflow ?? step.agent}" has parallel: but no each:`,
+        detail: "parallel: caps how many instances of a fan-out run at once. Without each: there is one instance, and the line does nothing.",
+      });
+    }
+    if ((step.schema !== undefined || step.schemaPath) && step.output !== "json") {
+      warnings.push({
+        step: i,
+        line: step.line,
+        message: `"${step.subflow ?? step.agent}" has schema: but no output: json`,
+        detail: "schema: describes the JSON value an output: json step returns. Without output: json nothing is parsed, so nothing is checked. Add `output: json`.",
+      });
+    }
+
+    // The step's own agent. `delegate:` and `on-fail:` are checked below and
+    // the step's target was not, which is the reference that stops the run
+    // rather than degrading it: the runner reaches the step, finds nothing to
+    // run and fails it with `agent "<name>" not found in workspace`. A
+    // scheduled flow does that at 3am, three times, before anyone looks.
+    if (agentNames && step.agent && !step.subflow && !agentNames.has(step.agent)) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        level: "error",
+        message: `[[${step.agent}]] is not an agent in this workspace`,
+        detail:
+          "This step has nothing to run. Every run of this flow fails here. Check the spelling " +
+          "against `agents/<name>/agent.md` — the name is the folder's, not the file's heading — " +
+          "or add the agent.",
+      });
+    }
+
+    // A `verify:` written as a sentence. Two dialects share the key: a line
+    // beginning `contains:`, `not-contains:`, `matches:`, `file:` or
+    // `judge:` is an assertion, and ANYTHING else is handed to a shell. So
+    // `verify: the reply names the clone it made` runs a program called
+    // `the`, exits 127, and fails a step that did its job perfectly — every
+    // run, with an error about bash that says nothing about the flow. The
+    // fix is one word: the same sentence behind `judge:` is graded by a
+    // model, which is what the author meant.
+    if (step.verify && looksLikeProse(step.verify)) {
+      warnings.push({
+        step: i,
+        line: step.line,
+        level: "error",
+        message: `verify: reads as a sentence, so it will be run as a shell command`,
+        detail:
+          `\`${step.verify.slice(0, 60)}${step.verify.length > 60 ? "…" : ""}\` has no assertion ` +
+          "prefix, so the runtime executes it: the first word becomes the program and the step " +
+          "fails with `command not found`. Put `judge: ` in front to have a model grade the " +
+          "claim, or write it as a shell command that exits 0 when the claim holds.",
+      });
+    }
+
     // A step's OTHER agent references — the ones no parser validates,
     // because they are options rather than the step's target. Both fail
     // silently and at the worst possible moment: a misspelled `delegate:`
@@ -176,7 +486,8 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
     }
 
     // `when:` tests the previous results, which the first group doesn't have.
-    if (inFirstGroup && step.when) {
+    // `when: rows of` reads a file instead, which may well exist already.
+    if (inFirstGroup && step.when && whenRowsPath(step.when) === null) {
       warnings.push({
         step: i,
         line: step.line,
@@ -186,6 +497,25 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
           "always be skipped. Move it after the step whose output it depends on.",
       });
     }
+
+    // A `[[flow:x]]` step is spliced in as the other flow's own steps, and
+    // only its `?` and its instruction survive the splice. Everything else
+    // written under it was dropped without a word — a `when:` that never
+    // gated, a `!` that never asked.
+    if (step.subflow) {
+      const dropped = SUBFLOW_DROPPED.filter(([field]) => step[field] !== undefined).map(([, name]) => name);
+      if (dropped.length) {
+        warnings.push({
+          step: i,
+          line: step.line,
+          message: `"flow:${step.subflow}" has ${dropped.join(", ")}, which a nested flow ignores`,
+          detail:
+            "A nested flow runs as its own steps, with their own options; what is written under the " +
+            "[[flow:…]] line is not applied to them. Put the option on the steps inside that flow, " +
+            "or make this an agent step.",
+        });
+      }
+    }
   });
 
   // The same agent twice in one parallel group gets two identical contexts and
@@ -209,6 +539,46 @@ export function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[] {
         });
       }
     }
+
+    // A gate parks its whole group, and on approval every step in it starts
+    // together. So `5. [[editor]]` beside `5! [[publisher]]` does not mean
+    // "edit, then ask, then publish": the editor waits for the approval too,
+    // and the publisher runs alongside it, reading files the editor has not
+    // written yet. medium-desk's publisher did exactly that on 2026-09-28
+    // (run-mukdjeh8-cr66): post.json was still empty when it started.
+    const gated = (s: FlowStep) => Boolean(s.approve || s.ask || s.waitFor === "event");
+    const gates = steps.filter(gated);
+    const others = steps.filter((s) => !gated(s));
+    if (gates.length && others.length) {
+      const name = (s: FlowStep) => (s.subflow ? `flow:${s.subflow}` : s.agent);
+      warnings.push({
+        step: flow.steps.indexOf(gates[0]),
+        line: gates[0].line,
+        message: `"${name(gates[0])}" waits for a person but shares number ${group} with "${others.map(name).join('", "')}"`,
+        detail:
+          "Steps with the same number run together. The gate holds all of them until it is " +
+          "approved, then they start at once — so the gated step cannot use what the others " +
+          `produce, and the approver sees none of it. To run the gated step after them, number it ${group + 1}.`,
+      });
+    }
+  }
+
+  // A number with nothing under it is harmless to the runner, which only
+  // orders groups, but it is almost always one step numbered twice: 3, 3, 4,
+  // 5, 5!, 7 is a renumbering that missed the 5! that was meant to be 6.
+  const numbers = [...byGroup.keys()].sort((a, b) => a - b);
+  for (let i = 1; i < numbers.length; i++) {
+    if (numbers[i] - numbers[i - 1] < 2) continue;
+    const missing = numbers[i - 1] + 1 === numbers[i] - 1 ? `${numbers[i - 1] + 1}` : `${numbers[i - 1] + 1} to ${numbers[i] - 1}`;
+    const shared = [...byGroup.entries()].filter(([, s]) => s.length > 1).map(([g]) => g);
+    warnings.push({
+      step: null,
+      message: `step numbers go from ${numbers[i - 1]} to ${numbers[i]}; nothing is numbered ${missing}`,
+      detail:
+        "The same number means \"run together\", so a gap usually means a step kept an old number " +
+        "after a renumbering" +
+        (shared.length ? ` — ${shared.map((g) => `number ${g}`).join(", ")} has more than one step; check whether one of them belongs in the gap.` : "."),
+    });
   }
 
   return warnings;