@foldrun/core 0.4.0 → 0.6.0

package/dist/src/deploy.js

@@ -20,14 +20,42 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { saveWorkspace, workspaceDir, listRuns, parseFlow, WORKSPACE_DIRS, assertSafeName, notifyWorkspaceChanged, } from "./store.js";
+import { saveWorkspace, keptOnDeploy, workspaceDir, listRuns, parseFlow, parseToolDef, WORKSPACE_DIRS, assertSafeName, notifyWorkspaceChanged, } from "./store.js";
+import { lintFlow } from "./flow-lint.js";
+import { refNames } from "./refs.js";
+import matter from "gray-matter";
 import { conformanceIssues } from "./okf.js";
+import { timezoneProblem } from "./clock.js";
+import { webProblems, webWarnings, runnerEngines } from "./providers.js";
+import { readLimits } from "./limits.js";
+import { actionProblems } from "./web-actions.js";
+import { languageProblem } from "./language.js";
+import { localeProblems } from "./locale.js";
 import { repoDir } from "./gitrepo.js";
+import { entriesNoFollow } from "./paths.js";
 /** Directories a deploy never reads out of a source tree. */
 const NOT_SOURCE = new Set([".git", "node_modules", "runs", "outputs", ".foldrun", ".results"]);
 /** Files that are never part of a workspace, whatever directory they sit in. */
 const NOT_SOURCE_FILE = new Set([".DS_Store", "secrets.json"]);
 const IN_WORKSPACE_DIR = new RegExp(`^(${WORKSPACE_DIRS.join("|")})/`);
+/**
+ * Is this path, relative to a workspace root, one `readTree` would carry?
+ *
+ * The same question the walk above asks, asked of a path that is not on this
+ * machine — what the platform lists for a workspace, so `foldrun status` and
+ * `foldrun pull` compare like with like. Without it the comparison counted
+ * every run artefact and bookkeeping file the platform keeps as a local
+ * deletion, and every status was a wall of red.
+ */
+export function isSourcePath(rel) {
+    const norm = rel.replaceAll("\\", "/");
+    const parts = norm.split("/");
+    if (parts.some((p) => NOT_SOURCE.has(p)))
+        return false;
+    if (NOT_SOURCE_FILE.has(parts[parts.length - 1]))
+        return false;
+    return norm === "AGENTS.md" || norm === "project.md" || IN_WORKSPACE_DIR.test(norm);
+}
 /**
  * Read a directory into the file list a deploy ships.
  *
@@ -130,6 +158,72 @@ export function readTree(dir) {
  * not on disk yet. A deploy that would leave the workspace failing its own
  * checker should not be a deploy.
  */
+/** Best-effort warnings for a deploy: an agent's `web:` warnings (see
+ *  webWarnings), and the outward gate — a step whose agent grants
+ *  a workspace tool marked `outward: true` and has no `verify:`/gate. Reads
+ *  only the deployed files, so a library or gallery outward tool is not seen
+ *  here — `foldrun check`, which resolves every scope, remains the real gate.
+ *  Non-blocking by decision: the deploy proceeds and says so. */
+export function deployWarnings(files) {
+    const front = (content) => {
+        try {
+            return matter(content).data;
+        }
+        catch {
+            return {};
+        }
+    };
+    // Workspace tools that change something outside the workspace.
+    const outwardTools = new Set();
+    for (const f of files) {
+        const m = f.path.match(/^tools\/([^/]+?)(?:\/tool)?\.md$/);
+        if (!m)
+            continue;
+        const data = front(f.content);
+        const def = parseToolDef(data, m[1], f.content);
+        // `outward: true` is read off the frontmatter, the same test the runtime
+        // and the CLI use; parseToolDef does not fold it onto the def.
+        if (def && data.outward === true)
+            outwardTools.add(def.name ?? m[1]);
+    }
+    // Agents that grant one of them.
+    const outwardAgents = [];
+    const agentNames = [];
+    const out = [];
+    // The web: warnings check prints — the old session: key, and a pinned
+    // user agent behind the runner image's Chrome, which the platform knows
+    // from FOLDRUN_RUNNER_ENGINES (the deploy read it from the image).
+    const { chrome, chromium } = runnerEngines() ?? {};
+    for (const f of files) {
+        const m = f.path.match(/^agents\/([^/]+)\/agent\.md$/);
+        if (!m)
+            continue;
+        agentNames.push(m[1]);
+        const data = front(f.content);
+        if (refNames(data.tools).some((t) => outwardTools.has(t)))
+            outwardAgents.push(m[1]);
+        for (const w of webWarnings(data, { chrome, chromium }))
+            out.push({ where: f.path, message: w });
+    }
+    if (!outwardAgents.length)
+        return out;
+    for (const f of files) {
+        if (!/^flows\/[^/]+\.md$/.test(f.path))
+            continue;
+        let flow;
+        try {
+            flow = parseFlow(path.basename(f.path), f.content);
+        }
+        catch {
+            continue;
+        }
+        for (const w of lintFlow(flow, { agents: agentNames, outwardAgents })) {
+            if (w.kind === "outward")
+                out.push({ where: `${f.path}${w.line ? `:${w.line}` : ""}`, message: w.message });
+        }
+    }
+    return out;
+}
 export function deployIssues(files) {
     const issues = [];
     const at = (where, message) => issues.push({ where, message });
@@ -157,6 +251,40 @@ export function deployIssues(files) {
         if (m)
             agents.add(m[1]);
     }
+    // `timezone:` is read at four levels and a value nothing can parse falls
+    // silently through to the level above — so it is refused where it was
+    // written, not discovered as a date that is a day out.
+    for (const f of files) {
+        if (!/^(AGENTS\.md|agents\/[^/]+\/agent\.md)$/.test(f.path))
+            continue;
+        let front = {};
+        try {
+            front = matter(f.content).data;
+        }
+        catch {
+            continue; // unparseable frontmatter is its own report
+        }
+        const problem = timezoneProblem(front.timezone);
+        if (problem)
+            at(f.path, problem);
+        // `schedule:` on an agent or AGENTS.md runs nothing — only a flow has a
+        // clock. Refuse it where it was written rather than deploy it dead.
+        if (front.schedule !== undefined) {
+            at(f.path, "schedule: an agent has no schedule of its own — only a flow runs on a clock. Put schedule: on the flow that runs this agent, or remove it.");
+        }
+        // The same refusal check gives: a web key that cannot work never ships.
+        for (const w of [...webProblems(front), ...actionProblems(front)])
+            at(f.path, w);
+        // `limits:` that cannot be read — a count of 0, a word, web.<not an
+        // action> — would run uncapped where the author meant a cap.
+        for (const w of readLimits(front.limits).problems)
+            at(f.path, w);
+        const lang = languageProblem(front.language);
+        if (lang)
+            at(f.path, lang);
+        for (const w of localeProblems(front))
+            at(f.path, w);
+    }
     if (agents.size === 0) {
         at("agents/", "no agents — a workspace needs at least one agents/<name>/agent.md");
     }
@@ -184,6 +312,8 @@ export function deployIssues(files) {
         }
         if (parsed.steps.length === 0)
             at(f.path, "no steps");
+        for (const fp of parsed.frontProblems)
+            at(f.path, fp);
         for (const s of parsed.steps) {
             const target = s.subflow ?? s.agent;
             const known = s.subflow ? flowNames.has(target) : agents.has(target);
@@ -245,7 +375,7 @@ export function planDeploy(tenant, workspace, files) {
     const shipped = new Map(files.map((f) => [path.normalize(f.path), f.content]));
     const present = new Set();
     if (fs.existsSync(dir)) {
-        for (const entry of fs.readdirSync(dir, { recursive: true })) {
+        for (const entry of entriesNoFollow(dir)) {
             const rel = String(entry).split(path.sep).join("/");
             if (NOT_SOURCE.has(rel.split("/")[0]))
                 continue;
@@ -278,16 +408,18 @@ export function planDeploy(tenant, workspace, files) {
             updated.push(rel);
         }
     }
-    // What saveWorkspace will keep regardless — reporting these as removals
-    // would be a lie, and the alarming kind.
-    const kept = (rel) => /(^|\/)state\//.test(rel) || /(^|\/)memory\/[^/]+\.md$/.test(rel);
-    const removed = [...present].filter((rel) => !shipped.has(rel) && !kept(rel));
+    // What saveWorkspace will keep regardless — storage/, state/, agent
+    // memory, the platform's own files. Reporting these as removals would be
+    // a lie, and the alarming kind; one predicate serves both.
+    const shippedPaths = new Set(shipped.keys());
+    const removed = [...present].filter((rel) => !shipped.has(rel) && !keptOnDeploy(rel, shippedPaths));
     return {
         files,
         added: added.sort(),
         updated: updated.sort(),
         removed: removed.sort(),
         issues: deployIssues(files),
+        warnings: deployWarnings(files),
         blockedBy: runsInFlight(tenant, workspace),
     };
 }
@@ -351,6 +483,13 @@ export function deployWorkspace(tenant, workspace, files, opts = {}) {
     if (plan.issues.length > 0 || blocked) {
         return { ...plan, applied: false, commit: null, preserved: 0 };
     }
+    if (opts.expectRemoved) {
+        const ok = new Set(opts.expectRemoved.map((p) => path.normalize(p).split(path.sep).join("/")));
+        const unexpectedRemovals = plan.removed.filter((p) => !ok.has(p));
+        if (unexpectedRemovals.length) {
+            return { ...plan, applied: false, commit: null, preserved: 0, unexpectedRemovals };
+        }
+    }
     const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message });
     const commit = opts.commit ?? null;
     if (commit)

package/dist/src/egress.d.ts

@@ -36,6 +36,11 @@ export interface EgressGrant {
      *  API_KEY are two credentials, and one's refusal must not paint the
      *  other red. Absent for a secret whose origin the runner did not know. */
     healthKeys?: Record<string, string>;
+    /** The step's own timezone, from the clock cascade. The proxy is the only
+     *  party that sees an upstream response's headers, so it is the party
+     *  that has to put a rate-limit reset into words — and a reset time is
+     *  only useful in the calendar the step works to. See refusal.ts. */
+    timezone?: string;
 }
 export interface EgressLease {
     /** The base the pod sends through: `http://…/e/<token>`. */
@@ -66,11 +71,13 @@ export interface EgressHooks {
      *  policy in test-mode.ts to every request on this lease. Carried on the
      *  lease, not the request, because the pod is the party not trusted to
      *  say so. */
+    /** `step` — the step's index in run.steps; keys that step's operator inbox. */
     lease(args: {
         tenant: string;
         runId: string;
         grant: EgressGrant;
         test?: boolean;
+        step?: number;
     }): Promise<EgressLease | null>;
 }
 /** Strip a header set of the proxy's own and hop-by-hop headers. */

package/dist/src/egress.js

@@ -128,6 +128,12 @@ export function addGrant(grant, name, value, host) {
     if (existing) {
         if (!existing.hosts.includes(h))
             existing.hosts.push(h);
+        // A name granted again with a different value is a rotation: the
+        // runner re-grants the model key after awaitRotatedCredential, on the
+        // same grant object the lease holds by reference. Keeping the first
+        // value here meant the "retry on the new one" sent the revoked token —
+        // every 4-hourly refresh on 2026-09-18..22 failed the step it landed on.
+        existing.value = value;
     }
     else
         grant.secrets[name] = { value, hosts: [h] };

package/dist/src/eol.d.ts

@@ -0,0 +1,2 @@
+export declare const toLF: (raw: string) => string;
+export declare const asRaw: (raw: string, out: string) => string;

package/dist/src/eol.js

@@ -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) => raw.replace(/\r\n/g, "\n");
+export const asRaw = (raw, out) => (raw.includes("\r\n") ? out.replace(/\r?\n/g, "\r\n") : out);

package/dist/src/evals.d.ts

@@ -42,6 +42,11 @@ export interface EvalInfo {
      *  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[];
 }
 export declare function parseEval(file: string, raw: string): EvalInfo;

package/dist/src/evals.js

@@ -30,6 +30,7 @@
 // Deterministic checks run first and cost nothing. The judge only runs if
 // they pass — no point paying a model to grade output already known to be
 // wrong.
+import { sdkEnv } from "./step-exec.js";
 import fs from "node:fs";
 import path from "node:path";
 import { deployedCommit } from "./deploy.js";
@@ -139,6 +140,7 @@ export function parseEval(file, raw) {
         effort: resolveEffort(data.effort ?? "low"),
         trigger: data.trigger === "manual" ? "manual" : "deploy",
         live: data.live === true,
+        inputs: data.inputs === true,
         cases,
     };
 }
@@ -364,6 +366,8 @@ async function judge(rubric, output, model, effort) {
             tools: [],
             allowedTools: [],
             settingSources: [],
+            strictMcpConfig: true,
+            env: sdkEnv(undefined),
             maxTurns: 1,
         },
     });
@@ -419,7 +423,10 @@ async function checkAssertion(assertion, output, agentDir, model, effort) {
 export async function runEval(tenant, workspace, info) {
     const startedAt = new Date().toISOString();
     const results = [];
-    for (const testCase of info.cases) {
+    // 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 cases) {
         const target = info.flow ? null : info.agent;
         let runId = null;
         let output = "";
@@ -601,7 +608,7 @@ commit = null) {
         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");

package/dist/src/flow-lint.d.ts

@@ -10,11 +10,19 @@ export interface FlowWarning {
      *  `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;
 }
 /** What exists in the workspace, when the caller knows. Optional: the lint
  *  is useful without it, and a caller that has the lists gets the reference
  *  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[];
 }
 export declare function lintFlow(flow: FlowInfo, known?: KnownNames): FlowWarning[];

package/dist/src/flow-lint.js

@@ -10,6 +10,18 @@
 // Every check here is *structural*: it reasons about what a step can possibly
 // have in context, never about whether the model did a good job. Nothing is
 // blocked — flows still run, warnings are advisory.
+import { whenRowsPath } from "./store.js";
+import { timezoneProblem } from "./clock.js";
+/** 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 = [
+    ["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:"],
+];
 // Anaphora: phrases that only mean something if earlier output exists.
 // Deliberately conservative — a false warning is worse than a missed one,
 // because noisy warnings get ignored and then the real one is invisible too.
@@ -26,9 +38,40 @@ function looksLikeAddress(a) {
     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) {
+    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, known) {
     const warnings = [];
     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 ||
@@ -60,6 +103,20 @@ export function lintFlow(flow, known) {
                 "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)) {
@@ -153,6 +210,22 @@ export function lintFlow(flow, known) {
                     "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)) {
@@ -164,6 +237,29 @@ export function lintFlow(flow, known) {
                     "invent what it was asked to review rather than fail. Move it to a later group.",
             });
         }
+        // `../../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 && /\.\.\/\.\.\/(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.
@@ -177,6 +273,41 @@ export function lintFlow(flow, known) {
                     "always sees the document, not a pointer, even when the agent forgets to name it.",
             });
         }
+        // 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.
@@ -210,6 +341,42 @@ export function lintFlow(flow, known) {
                 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:`
@@ -249,7 +416,8 @@ export function lintFlow(flow, known) {
             });
         }
         // `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,
@@ -258,6 +426,23 @@ export function lintFlow(flow, known) {
                     "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
     // no way to divide the work — almost always a drag that landed wrong.
@@ -280,6 +465,43 @@ export function lintFlow(flow, known) {
                 });
             }
         }
+        // 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) => 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) => (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;
 }