@foldrun/core 0.3.0 → 0.5.0

package/src/store.ts

@@ -20,11 +20,15 @@
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 
+import type { BrowserPodOutcome } from "./browser-pod.ts";
 import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader, type RevisionFile } from "./history.ts";
-import { dataRoot, singleWorkspace } from "./paths.ts";
+import { dataRoot, singleWorkspace, singleAccountRoot, entriesNoFollow } from "./paths.ts";
 import { platform } from "./platform.ts";
+import { toLF, asRaw } from "./eol.ts";
+import type { TestEffect } from "./test-mode.ts";
+import type { OperatorEvent } from "./operator.ts";
 import matter from "gray-matter";
 
 /**
@@ -39,14 +43,22 @@ import matter from "gray-matter";
 export function readFrontmatter(file: string): Record<string, unknown> {
   return matter(fs.readFileSync(file, "utf8")).data as Record<string, unknown>;
 }
-import { ownToolNames, legacyUseNames } from "./tool-names.ts";
+import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.ts";
 import { refNames } from "./refs.ts";
+import { parseBudget, budgetProblem } from "./budget.ts";
+import { timezoneProblem } from "./clock.ts";
+import { parseStepLimits, readLimits } from "./limits.ts";
+import { webProblems, webWarnings, runnerEngines } from "./providers.ts";
+import { actionProblems } from "./web-actions.ts";
+import { languageProblem } from "./language.ts";
+import { localeProblems } from "./locale.ts";
 import {
   readBundle, syncIndex, appendLog, provenanceMarks, syncWorkspaceBundles,
 } from "./okf.ts";
 import { readTransport, KINDS } from "./kinds.ts";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS, type WireFormat, type AuthShape } from "./providers.ts";
 import { starterFiles, accountFiles } from "./starter.ts";
+import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.ts";
 
 // Where workspaces live. The hosted app keeps many under data/; the CLI runs
 // against one folder, which is what `foldrun run ./my-desk` has to mean.
@@ -181,13 +193,14 @@ export function workspaceDir(tenant: string, workspace: string) {
  * The account root — where `library/`, account secrets and the account-wide
  * AGENTS.md live.
  *
- * On a laptop there is no account, so it is the workspace's parent: `my-desk/`
- * sits beside `library/` and an `AGENTS.md` covering everything there. Same
- * rule libraryDir uses, so the two never disagree about where "up" is.
+ * On a laptop it is wherever `singleAccountRoot` says: the workspace's parent
+ * for a flat `my-desk/`, and the account root two levels up for a workspace
+ * inside `my-account/workspaces/`. Same rule libraryDir uses, so the two never
+ * disagree about where "up" is.
  */
 export function accountDir(tenant: string) {
   const single = singleWorkspace();
-  if (single) return path.resolve(single, "..");
+  if (single) return singleAccountRoot()!;
   assertSafeName(tenant, "tenant");
   return path.join(dataRoot(), tenant);
 }
@@ -300,15 +313,38 @@ export function assertCanonicalCase(rel: string) {
  * next deploy or silently handed to every container — both invisible until
  * someone is bitten.
  */
-export const PLATFORM_FILES = ["secrets.json", "hooks.json", "hook-deliveries.jsonl", ".repo.json"];
+// trigger-log.jsonl: the scheduler's record of why a flow did or did not
+// fire (trigger-log.ts). Before it was listed here every deploy erased it.
+export const PLATFORM_FILES = ["secrets.json", "hooks.json", "hook-deliveries.jsonl", ".repo.json", "trigger-log.jsonl"];
 
 /** True for anything the platform, not the author or the agent, writes. */
 export function isPlatformPath(rel: string): boolean {
   const norm = rel.replaceAll("\\", "/");
   if (PLATFORM_FILES.includes(norm)) return true;
+  // The vault's lock and in-flight temp files (secrets.ts#mutateVaultFile)
+  // are the vault, as far as anything outside the platform is concerned.
+  if (/(^|\/)secrets\.json\./.test(norm)) return true;
+  if (norm === "trigger-log.jsonl.tmp") return true;
   return norm === "runs" || norm.startsWith("runs/") || norm === ".foldrun" || norm.startsWith(".foldrun/");
 }
 
+/** What a deploy keeps whatever it ships — the rule above saveWorkspace's
+ *  body. planDeploy reports removals through the same test, so a plan never
+ *  lists a file the save would keep. */
+export function keptOnDeploy(rel: string, shipped: ReadonlySet<string>): boolean {
+  return (
+    // Platform bookkeeping (the vault, hook rotation state, the delivery
+    // log, the trigger log, run history) — losing any of it on deploy
+    // silently breaks something: agents lose secrets, a rotated hook
+    // un-rotates, the record of why a schedule skipped is gone.
+    isPlatformPath(rel) ||
+    /(^|\/)state\//.test(rel) ||
+    rel === STORAGE_DIR ||
+    rel.startsWith(`${STORAGE_DIR}/`) ||
+    (/(^|\/)memory\/[^/]+\.md$/.test(rel) && !shipped.has(rel))
+  );
+}
+
 export function saveWorkspace(
   tenant: string,
   workspace: string,
@@ -370,15 +406,7 @@ export function saveWorkspace(
   // about it. Before this, every deploy silently erased everything the agents
   // had learned.
   const shipped = new Set(files.map((f) => path.normalize(f.path)));
-  const isAgentOwned = (rel: string) =>
-    // Platform bookkeeping (the vault, hook rotation state, the delivery
-    // log, run history) — losing any of it on deploy silently breaks
-    // something: agents lose secrets, a rotated hook un-rotates.
-    isPlatformPath(rel) ||
-    /(^|\/)state\//.test(rel) ||
-    rel === STORAGE_DIR ||
-    rel.startsWith(`${STORAGE_DIR}/`) ||
-    (/(^|\/)memory\/[^/]+\.md$/.test(rel) && !shipped.has(rel));
+  const isAgentOwned = (rel: string) => keptOnDeploy(rel, shipped);
 
   // What is there now, for the revision: every editable file's content
   // before this save replaces the tree.
@@ -396,7 +424,7 @@ export function saveWorkspace(
   const snapshot = fs.existsSync(dir) ? fs.mkdtempSync(path.join(dataRoot(), ".keep-")) : null;
   const preserved: string[] = [];
   if (snapshot) {
-    for (const entry of fs.readdirSync(dir, { recursive: true })) {
+    for (const entry of entriesNoFollow(dir)) {
       const rel = String(entry).split(path.sep).join("/");
       const from = path.join(dir, rel);
       try {
@@ -543,10 +571,15 @@ export interface McpSpec {
   headers: Record<string, string>;
 }
 
+/** `outward: true` in a tool's frontmatter: this one sends, posts, buys,
+ *  publishes or uploads. It changes nothing at run time — `check` uses it to
+ *  insist the step that grants it has a verify or a gate. */
+export type OutwardMark = { outward?: boolean };
+
 export type ToolDef =
-  | { kind: "http"; name: string; spec: ApiSpec }
-  | { kind: "script"; name: string; spec: Record<string, unknown> }
-  | { kind: "mcp"; name: string; spec: McpSpec };
+  | ({ kind: "http"; name: string; spec: ApiSpec } & OutwardMark)
+  | ({ kind: "script"; name: string; spec: Record<string, unknown> } & OutwardMark)
+  | ({ kind: "mcp"; name: string; spec: McpSpec } & OutwardMark);
 
 /**
  * The program inside a single-file script tool: the first fenced block whose
@@ -582,6 +615,16 @@ export function fencedCodeBlock(
   return null;
 }
 
+/**
+ * `outward: true` — this tool changes something that is not ours: it sends,
+ * posts, buys, publishes, uploads. The runtime does not treat it differently;
+ * `check` does, because the step that uses one is the step where a silent
+ * failure costs something that cannot be taken back. See `lintFlow`.
+ */
+export function toolIsOutward(data: Record<string, unknown>): boolean {
+  return data.outward === true;
+}
+
 export function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null {
   const name = typeof data.name === "string" ? data.name : fallbackName;
   // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -649,6 +692,76 @@ export function parseToolDef(data: Record<string, unknown>, fallbackName: string
  *
  * Flat files keep working unchanged — the shape is a migration, not a break.
  */
+/**
+ * A folder tool's `requirements.txt` and `package.json`, as a `runtime:`
+ * block. Requirement lines only: comments and blanks are left out, and so
+ * are options — whole option lines (`-r`, `--index-url`, `-e`) and the ones
+ * a requirement carries (`--hash=…`). Options never reach the installer,
+ * which takes them from the same argv as its operands; their NAMES are kept
+ * in `ignored`, never their values (an index URL can carry a password), so
+ * the build log can say what was not applied. Anything else that is not a
+ * requirement is refused later by parseRuntime with a log line, the same as
+ * it would be in tool.md. `dependencies` only — a tool's dev dependencies
+ * are its author's, not its runtime's.
+ */
+export function folderRuntime(folder: string): Record<string, unknown> | null {
+  const out: { packages?: string[]; npm?: string[]; node?: boolean; ignored?: string[] } = {};
+  const req = path.join(folder, "requirements.txt");
+  if (fs.existsSync(req)) {
+    const packages: string[] = [];
+    const ignored = new Set<string>();
+    // Logical lines: a trailing backslash continues onto the next, which is
+    // how pip-compile --generate-hashes writes every pin. Read line by line,
+    // `pandas==2.1 \` became `pandas==2.1\`, was refused as invalid, and
+    // its hash lines were dropped as options: a hash-pinned file installed
+    // nothing at all.
+    const logical = fs.readFileSync(req, "utf8").replace(/\\\r?\n/g, " ").split(/\r?\n/);
+    for (const raw of logical) {
+      const line = raw.replace(/(^|\s)#.*$/, "").trim();
+      if (!line) continue;
+      // The requirement is what comes before its first option.
+      const [head, ...opts] = line.split(/\s+(?=-)/);
+      for (const o of line.startsWith("-") ? [line, ...opts] : opts) ignored.add(o.split(/[\s=]/)[0]);
+      if (line.startsWith("-")) continue;
+      const requirement = head.replace(/\s+/g, "");
+      if (requirement) packages.push(requirement);
+    }
+    if (packages.length) out.packages = packages;
+    if (ignored.size) out.ignored = [...ignored];
+  }
+  const pkg = path.join(folder, "package.json");
+  if (fs.existsSync(pkg)) {
+    try {
+      const deps = (JSON.parse(fs.readFileSync(pkg, "utf8")) as { dependencies?: Record<string, string> }).dependencies ?? {};
+      const npm = Object.entries(deps).map(([name, range]) => (range && range !== "*" && range !== "latest" ? `${name}@${range}` : name));
+      if (npm.length) {
+        out.npm = npm;
+        out.node = true;
+      }
+    } catch {
+      // An unreadable package.json declares nothing; tool.md still can.
+    }
+  }
+  return out.packages || out.npm || out.ignored ? out : null;
+}
+
+/** tool.md's own `runtime:` plus what the folder's files add. */
+function mergeRuntimeBlocks(own: unknown, extra: Record<string, unknown>): Record<string, unknown> {
+  const base = own && typeof own === "object" && !Array.isArray(own) ? { ...(own as Record<string, unknown>) } : {};
+  const list = (v: unknown) => (Array.isArray(v) ? v.map(String) : []);
+  const packages = [...new Set([...list(base.packages ?? base.pip), ...list(extra.packages)])];
+  const npm = [...new Set([...list(base.npm), ...list(extra.npm)])];
+  const ignored = [...new Set([...list(base.ignored), ...list(extra.ignored)])];
+  delete base.pip;
+  return {
+    ...base,
+    ...(packages.length ? { packages } : {}),
+    ...(npm.length ? { npm } : {}),
+    ...(ignored.length ? { ignored } : {}),
+    ...(extra.node && base.node === undefined ? { node: true } : {}),
+  };
+}
+
 function readToolDir(dir: string, scope: "workspace" | "account" = "workspace"): Record<string, ToolDef> {
   if (!fs.existsSync(dir)) return {};
   const out: Record<string, ToolDef> = {};
@@ -675,8 +788,17 @@ function readToolDir(dir: string, scope: "workspace" | "account" = "workspace"):
       if (folder && typeof d.run === "string" && !/^(workspace|account|shared|library)\//.test(d.run)) {
         d.run = `${scope}/tools/${folder}/${d.run.replace(/^\.\//, "")}`;
       }
+      // The ecosystem's own dependency files, beside the code that needs them,
+      // count as `runtime:` — a tool copied out of a repo keeps working.
+      if (folder) {
+        const extra = folderRuntime(path.join(dir, folder));
+        if (extra) d.runtime = mergeRuntimeBlocks(d.runtime, extra);
+      }
       const def = parseToolDef(d, fallbackName, content);
-      if (def) out[def.name] = def;
+      // `outward: true` rides on the definition so a caller that resolved the
+      // grants — `check` — can ask which agents can act outside the workspace
+      // without reading every tool file a second time.
+      if (def) out[def.name] = toolIsOutward(d) ? { ...def, outward: true } : def;
       else broken.push(`${fallbackName}: no base, run, command or fenced code block — nothing to call`);
     } catch (err) {
       // A malformed definition must not fail every run in the workspace. But
@@ -753,7 +875,9 @@ export interface ApiSpec {
   openapi?: string;
   /** Which of the document's operations to expose — operationIds or
    *  `"METHOD /path"` strings. Absent: every operation, capped at 60.
-   *  Present: only these, and the generic `call_<api>` tool is withheld. */
+   *  Present: only these, and the generic `call_<api>` tool is withheld —
+   *  always. If none of them resolve (document missing, moved, or an
+   *  operation renamed) the API gets no tools that run: it fails closed. */
   operations?: string[];
   /** Calls per second this API may see from one step: `count` is the burst
    *  the bucket holds, `perSec` the refill rate. `"5/s"` → {5, 5};
@@ -781,14 +905,52 @@ export interface AgentInfo {
   /** Names still written under the removed `use:` key. Nothing is granted
    *  for them; `foldrun check` and the run log say what to write instead. */
   legacyUse: string[];
+  /** Retired built-in names still in `tools:` (files, bash) — granted, but
+   *  `check` says what to write instead. */
+  retiredTools: string[];
   /** Colleagues this agent may consult mid-run (`agents:`) — each becomes a
    *  consult_<name> tool. The team's edges, as the author drew them. */
   consults: string[];
+  /** Colleagues this agent may DELEGATE to (`subagents:`) — each runs with
+   *  its own context and its own tools, no wider than this agent's. */
+  subagents: string[];
   /** The `skills:` allowlist, or null when the field is absent — which is
    *  not the same thing: absent inherits every skill in scope, an empty
    *  list withholds all of them. */
   skills: string[] | null;
   secrets: string[];
+  /** `budget:` — the most this agent may spend in ONE run, in USD, across
+   *  every step it takes in it; null is no cap. Per run and nothing else:
+   *  an agent has no calendar, the workspace and the account do. */
+  budget: number | null;
+  /** What is wrong with the `budget:` line, or null. */
+  budgetProblem: string | null;
+  /** `timezone:` — the calendar this agent works to, nearest-wins over its
+   *  flow's, its workspace's and the account's. Null inherits. */
+  timezone: string | null;
+  /** What is wrong with the `timezone:` line, or null. */
+  timezoneProblem: string | null;
+  languageProblem: string | null;
+  /** region:/currency:/units:/calendar: values that cannot be read. */
+  localeProblems: string[];
+  /** `web:` values that cannot work. The run says
+   *  so in its trail and carries on; check and deploy say so first. */
+  webProblems: string[];
+  /** `web:` that works but should change — the old `session:` key, a pinned
+   *  user agent behind the runner image's Chrome (when this process knows
+   *  that Chrome: FOLDRUN_RUNNER_ENGINES). Warnings, never refusals. */
+  webWarnings: string[];
+  /** `schedule:` written on an agent, which nothing runs — only a flow has
+   *  a clock. The message, or null when there is no such line. */
+  scheduleProblem: string | null;
+  /** `limits:` — the agent's own per-step call limits, as readable. */
+  limits: Record<string, number>;
+  /** What is wrong with the `limits:` block's shape; key-vs-grant problems
+   *  need the tool lists, and `check` adds them (limits.ts limitKeyProblems). */
+  limitProblems: string[];
+  /** Tools this agent declares inline rather than in `tools:` — `apis:`,
+   *  `scripts:` and `mcpServers:` names — which a limit may also name. */
+  inlineTools: string[];
 }
 
 // Recognised HTTP verbs a tool may declare. Deliberately NOT named
@@ -974,7 +1136,7 @@ export function parseApis(raw: unknown): ApiSpec[] {
     out.push({
       name: name.replace(/[^a-zA-Z0-9_]/g, "_"),
       ...(Number(e.timeout) > 0 ? { timeout: Number(e.timeout) } : {}),
-      base: base.replace(/\/+$/, ""),
+      base: trimSlashes(base),
       description: typeof e.description === "string" ? e.description : "",
       headers: asRecordLocal(e.headers),
       query: asRecordLocal(e.query),
@@ -992,6 +1154,11 @@ export function parseApis(raw: unknown): ApiSpec[] {
 export interface FlowStep {
   agent: string;
   instruction: string;
+  /** The instruction was written over more than one line and the parser
+   *  joined them. It runs, but `foldrun check` says so: a wrapped
+   *  instruction is one editor keystroke away from being a paragraph of
+   *  prose the parser has to guess about. */
+  wrapped?: boolean;
   group: number; // steps sharing a group number run in parallel
   optional: boolean; // "2?" — failure doesn't fail the flow
   /** Set when the step targets another flow (`[[flow:name]]`) instead of an agent. */
@@ -1003,11 +1170,14 @@ export interface FlowStep {
   effort?: string;
   /** Pause for a human before running this step. */
   approve?: boolean;
-  /** Run only if the previous results contain this text (case-insensitive).
-   *  Independent: every matching `when:` step in a group runs. */
+  /** Run only if the previous group's result has a line beginning with
+   *  this marker (case-insensitive). The previous group is the nearest
+   *  earlier one that produced a result. Independent: every matching
+   *  `when:` step in a group runs. */
   when?: string;
   /** Exclusive routing: of a group's `case:` steps, only the FIRST whose
-   *  text appears in the previous results runs; the rest are routed past. */
+   *  marker leads a line of the previous group's result runs; the rest are
+   *  routed past. */
   case?: string;
   /** The route of last resort: runs only when none of its group's `case:`
    *  steps matched. */
@@ -1069,9 +1239,32 @@ export interface FlowStep {
    *  cannot, and hands the value to the next group losslessly — the narrow
    *  move the grammar ADR allowed instead of variables. */
   output?: "json";
+  /** `schema:` — the JSON Schema an `output: json` value must satisfy,
+   *  written inline (one-line JSON, or a YAML block under the key) and
+   *  checked where the reply is; a value that does not fit fails the step
+   *  with the field named. */
+  schema?: Record<string, unknown> | boolean;
+  /** `schema: <path>` — the same, in a file under the workspace, read when
+   *  the step runs. */
+  schemaPath?: string;
+  /** `parallel:` — how many of an `each:` step's instances run at once.
+   *  Unset is all of them, which is what fan-out always did. */
+  parallel?: number;
+  /** `max_turns:` — the most model turns this step may take before it is
+   *  stopped, beside `budget:` (money) and `timeout:` (time). */
+  maxTurns?: number;
+  /** `limits: {web.search: 10}` — this step's call limits, over the agent's
+   *  (nearest wins per key). See limits.ts. */
+  limits?: Record<string, number>;
   /** 1-indexed line in the flow file. Diagnostics without a line make you
    *  search; every real linter emits file:line. */
   line?: number;
+  /** What is wrong with an option's VALUE, in the author's words — `timeout:
+   *  abc`, `retry: 9`, `each: columns`. The parser keeps the step (a run
+   *  still has a shape) and the lint reports each of these as an error, so
+   *  `foldrun check` fails on a value that would otherwise be read as
+   *  something the author never wrote: `timeout: 15m` used to be one second. */
+  problems?: string[];
 }
 
 export interface FlowInfo {
@@ -1103,11 +1296,16 @@ export interface FlowInfo {
    *  that crosses it is the last one that runs. Null: no cap of its own
    *  (the workspace's monthly `budget:` still applies). */
   budget: number | null;
+  /** What is wrong with the `budget:` line, or null. */
+  budgetProblem: string | null;
   /** `trigger: flow` — start when this other flow of the workspace finishes,
    *  with `on:` saying which endings count. The finished run's summary and
    *  result become this run's task. */
   after: string | null;
-  on: "completed" | "failed" | "any";
+  /** `blocked` is a completed run whose verdict is BLOCKED — the work
+   *  refused itself. `completed` no longer includes those: a follow-up to a
+   *  publish that did not happen should not run as if it had. */
+  on: "completed" | "failed" | "blocked" | "any";
   /** `trigger: once` — an ISO 8601 instant; fires the first tick at or after
    *  it, once, then never again. */
   at: string | null;
@@ -1125,6 +1323,85 @@ export interface FlowInfo {
   /** `trigger: storage` — a path prefix under storage/; a file landing
    *  there starts the flow with the path as its task. */
   path: string | null;
+
+  // ---- how often a trigger is allowed to become a run ----
+  //
+  // Everything above says what starts a flow. These four say how many of
+  // those starts are real. They are orchestration, so they are keys; they
+  // are literals, so nothing is evaluated; and each answers a question a
+  // person can only answer about their own flow, which is the test the
+  // grammar applies before it grows.
+
+  /** `idempotency:` — the name of the field that identifies a delivery, so
+   *  the same one twice starts one run. A header on the request
+   *  ("x-github-delivery"), or "body:<key>" for a top-level field of a JSON
+   *  body. A name, never an expression: the value is read from the delivery,
+   *  not computed from it. Null: every delivery is its own event. */
+  idempotency: string | null;
+  /** `debounce:` — seconds of quiet before a fired trigger becomes a run.
+   *  A burst of deliveries, storage writes or watched changes collapses into
+   *  one run once they stop. The task is the LAST event's, since that is the
+   *  state the flow is reacting to. Null: every event starts a run. */
+  debounce: number | null;
+  /** `throttle:` — the least time between two runs of this flow. A trigger
+   *  arriving inside the window is dropped, and the trace of the run that
+   *  held the window says how many. Null: no floor. */
+  throttle: number | null;
+  /** `catchup:` — what a scheduled flow does about a fire it missed while
+   *  the platform was not running. "last" is the behaviour that always
+   *  applied: one make-up run for however many were missed. "none" skips
+   *  them, for a flow whose moment has passed by the time anyone notices.
+   *  Null reads as "last". */
+  catchup: "last" | "none" | null;
+
+  // ---- when to stop trusting the flow ----
+
+  /** `disable_after:` — consecutive failed runs after which the platform
+   *  stops firing this flow's schedule and says so. A nightly desk that has
+   *  failed all week is not going to fix itself, and every one of those runs
+   *  costs money and sends mail. Null: never quarantined. */
+  disableAfter: number | null;
+  /** `pause_when:` — a marker (DONE, NOTHING LEFT) that, leading a line of
+   *  any step's reply in the flow's latest run, pauses its schedule: the
+   *  work is finished, so firing again would only spend money saying so.
+   *  Derived from that run, like disable_after, so a run that finds work
+   *  again (a person clicking Run after adding some) lifts it by itself.
+   *  Null: never paused. */
+  pauseWhen: string | null;
+  /** `sla:` — seconds a run of this flow is expected to take. A run still
+   *  going well past it is reported once, as a notification, and keeps
+   *  running: this is a smoke alarm, not a timeout. Null: no expectation. */
+  sla: number | null;
+
+  // ---- who may answer a gate, and for how long it waits ----
+
+  /** `approvers:` — the email addresses that may decide this flow's gates,
+   *  or the single word "admins" for anyone at admin or above. Empty means
+   *  the account's existing rule: any member who can run the workspace.
+   *  Nobody may approve their own run's gate whatever this says. */
+  approvers: string[] | null;
+  /** `approve_within:` — how long a gate waits for a person before the run
+   *  is rejected and fails. A gate with no expiry holds its run, and its
+   *  place in the account's concurrency, for as long as nobody looks.
+   *  Null: it waits indefinitely, which stays the default. */
+  approveWithin: number | null;
+
+  /** `live: true` — this flow's runs are real even where the platform would
+   *  default them to test: in a preview workspace, and as an eval's subject.
+   *  Only ever an opt-out of the safe default, never the other way round. */
+  live: boolean;
+
+  /** `description:` — one line on what this flow is for, shown in listings
+   *  and the trace. Read here so a documented, scaffolded field means
+   *  something rather than sitting in every file unread. */
+  description: string | null;
+
+  /** Flow-level frontmatter values the parser could not read — a bad
+   *  `overlap:`/`priority:`/`catchup:`/`on:`/`signature:`, or a step line
+   *  whose `[[target]]` is malformed. Errors, the way a bad step option is,
+   *  rather than a silent default. */
+  frontProblems: string[];
+
   steps: FlowStep[];
 }
 
@@ -1175,6 +1452,38 @@ export function agentAssets(tenant: string, workspace: string, agent: string): A
   return { skills, memory };
 }
 
+/** `schedule:` on an agent runs nothing — only a flow has a clock. Named so
+ *  it fails loudly rather than deploying clean and never firing. */
+function agentScheduleProblem(data: Record<string, unknown>): string | null {
+  return data.schedule !== undefined
+    ? "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."
+    : null;
+}
+
+/** A per-run `budget:` as a number, or null. A period other than "run"
+ *  written here is a mistake the lint names; it is not silently a cap. */
+function runBudget(raw: unknown): number | null {
+  const b = parseBudget(raw, "run");
+  return b && b.period === "run" ? b.usd : null;
+}
+
+/** The names an agent's inline tool fields grant: `apis:`, `scripts:` (an
+ *  object's name, or a file's base name) and `mcpServers:`. */
+function inlineToolNames(data: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  if (Array.isArray(data.apis)) {
+    for (const a of data.apis) if (a && typeof a === "object" && typeof (a as { name?: unknown }).name === "string") out.push((a as { name: string }).name);
+  }
+  if (Array.isArray(data.scripts)) {
+    for (const sc of data.scripts) {
+      if (typeof sc === "string") out.push(path.basename(sc).replace(/\.[^.]+$/, ""));
+      else if (sc && typeof sc === "object" && typeof (sc as { name?: unknown }).name === "string") out.push((sc as { name: string }).name);
+    }
+  }
+  if (data.mcpServers && typeof data.mcpServers === "object") out.push(...Object.keys(data.mcpServers));
+  return out;
+}
+
 export function listAgents(tenant: string, workspace: string): AgentInfo[] {
   const dir = path.join(workspaceDir(tenant, workspace), "agents");
   if (!fs.existsSync(dir)) return [];
@@ -1194,27 +1503,97 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
         apis: parseApis(data.apis),
         ownTools: ownToolNames(data),
         legacyUse: legacyUseNames(data),
+        retiredTools: retiredToolNames(data),
         consults: refNames(data.agents),
+        subagents: refNames(data.subagents),
         skills: data.skills === undefined ? null : refNames(data.skills),
         secrets: Array.isArray(data.secrets) ? data.secrets.map(String) : [],
+        budget: runBudget(data.budget),
+        budgetProblem: budgetProblem(data.budget, ["run"]),
+        timezone: typeof data.timezone === "string" ? data.timezone : null,
+        timezoneProblem: timezoneProblem(data.timezone),
+        languageProblem: languageProblem(data.language),
+        localeProblems: localeProblems(data),
+        webProblems: [...webProblems(data), ...actionProblems(data)],
+        webWarnings: webWarnings(data, { chrome: runnerEngines()?.chrome, chromium: runnerEngines()?.chromium }),
+        scheduleProblem: agentScheduleProblem(data),
+        ...(() => { const l = readLimits(data.limits); return { limits: l.limits, limitProblems: l.problems }; })(),
+        inlineTools: inlineToolNames(data),
       };
     });
 }
 
 // A step targets an agent — `[[writer]]` — or another flow — `[[flow:digest]]`,
 // which is how one flow triggers another.
-const STEP_RE = /^\s*(\d+)([?!])?\.?\s+\[\[(flow:)?([a-z0-9-]+)\]\]\s*(?:[—–-]\s*)?(.*)$/;
-
-const OPTION_RE = /^\s+([a-z-]+):\s*(.+)$/;
+// `(\S.*|)` rather than `(.*)`: the instruction either starts with a
+// non-space or is empty, so the `\s*` before it has exactly one way to
+// match. With `(.*)` both could own the same spaces, which is quadratic on
+// a line of them — and a flow file is customer input.
+const STEP_RE = /^\s*(\d+)([?!])?\.?\s+\[\[(flow:)?([a-z0-9-]+)\]\]\s*(?:[—–-]\s*)?(\S.*|)$/;
+
+// One quantifier after the colon; the value is trimmed by unquote(). A key
+// with nothing after it is an option with an empty value, which is what it
+// says, rather than a line that vanished.
+const OPTION_RE = /^(\s+)([a-z_-]+):(.*)$/;
+
+/** The option keys a step actually has. An indented `word: rest` that is
+ *  NOT one of these is a line of the instruction — "Warning: do not
+ *  publish" is prose that happens to contain a colon, and it used to be
+ *  swallowed as an unknown option, silently, along with any typo of a real
+ *  key. The consistency suite reads this list against the docs. */
+const STEP_OPTION_KEYS = new Set([
+  "approve", "ask", "case", "delegate", "each", "effort", "else", "limits", "loop", "max", "max_turns", "model",
+  "on-fail", "onfail", "output", "parallel", "preview", "retry", "schema", "timeout", "until", "verify", "wait", "when",
+]);
+
+/** A line that opens a markdown block rather than continuing a sentence:
+ *  a heading, a bullet, a numbered item, a quote, a rule, or a paragraph
+ *  that opens in bold. Tested against the line already trimmed, so it says
+ *  "this is a document" whatever margin the list gave it. */
+const MARKDOWN_BLOCK_RE = /^(?:#{1,6}\s|[-*+]\s|>\s|\d+[.)]\s|\*\*|__|---|\|)/;
+
+/** The most fan-out instances `parallel:` may run at once — the fan-out's
+ *  own hard cap, since more slots than items is no cap. */
+export const PARALLEL_CAP = 20;
+/** The most turns `max_turns:` may allow. A turn is one model reply, tool
+ *  calls included; a step that needs more than this is not one step. */
+export const MAX_TURNS_CAP = 500;
 
 /** "90s", "30m", "4h", "3d" — or a bare number of seconds. Clamped to 30
  *  days: a wait is a pause in a flow, not a second scheduler. */
 export function parseWait(value: string): number | undefined {
+  const secs = parseDuration(value);
+  return secs === undefined ? undefined : Math.min(secs, 30 * 86400);
+}
+
+/** The one duration grammar every key shares — `wait:`, `timeout:`, the
+ *  flow's `throttle:`/`debounce:`/`sla:` — as whole seconds, at least 1.
+ *  Undefined for anything that is not one: the caller says what the key
+ *  was, because "not a duration" is only useful with the line it names. */
+export function parseDuration(value: string): number | undefined {
   const m = value.trim().match(/^(\d+(?:\.\d+)?)\s*([smhd]?)$/i);
   if (!m) return undefined;
   const mult = { "": 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2].toLowerCase() as "" | "s" | "m" | "h" | "d"];
   const secs = Math.round(Number(m[1]) * mult);
-  return secs > 0 ? Math.min(secs, 30 * 86400) : undefined;
+  return secs > 0 ? secs : undefined;
+}
+
+/** `timeout:` — the same units `wait:` takes, and no ceiling: the platform
+ *  sets no clock of its own, so the author's number stands as written.
+ *  `timeout: 15m` was `Math.max(1, Number("15m") || 0)` — one second — and
+ *  every step wearing it was cut off before its first tool call returned. */
+export function parseTimeout(value: string): number | undefined {
+  return parseDuration(value);
+}
+
+/** A whole number within [min, max], or undefined — for the counted
+ *  options (`retry:`, `loop:`, `max:`, `parallel:`). "abc" and "2.5" and "9"
+ *  on a key capped at 5 are all refused rather than silently rounded,
+ *  clamped, or read as zero. */
+function parseCount(value: string, min: number, max: number): number | undefined {
+  if (!/^\d+$/.test(value.trim())) return undefined;
+  const n = Number(value.trim());
+  return n >= min && n <= max ? n : undefined;
 }
 
 /** An ISO 8601 instant (YAML may already have parsed it into a Date), or
@@ -1234,7 +1613,7 @@ export function parseInstant(raw: unknown): string | null {
  * removed a leading OR a trailing quote independently, so a value that
  * merely *ended* with one lost it — and
  *
- *   verify: test "$(cat ../../storage/draft/published.run)" = "$FOLDRUN_RUN_ID"
+ *   verify: test "$(cat workspace/storage/draft/published.run)" = "$FOLDRUN_RUN_ID"
  *
  * reached bash unbalanced, which exited 2 with "unexpected EOF" on every
  * run. The step could never pass, whatever the agent did, and nothing said
@@ -1253,15 +1632,106 @@ export function unquote(raw: string): string {
   return inner.includes(q) ? value : inner;
 }
 
+/**
+ * Does this text carry the marker a `when:` is looking for?
+ *
+ * At the START OF A LINE, not anywhere in the prose. A plain substring
+ * search is the obvious implementation and it is wrong in a way that is
+ * very hard to see: an agent writing
+ *
+ *   There are no BLOCKED items this week.
+ *
+ * opened a `when: BLOCKED` gate, because the word is right there. Saying a
+ * marker is absent necessarily names it, so the more carefully an agent
+ * explains itself the more likely it is to trip its own condition. It bit
+ * one desk on its first run and sat latent in another.
+ *
+ * A verdict is written as a headline — the line leads with it — so leading
+ * position is what distinguishes "this is my verdict" from "here is a word
+ * I am using in a sentence". Markdown decoration in front of it is fine: a
+ * heading, a bullet or bold is still a line that leads with the marker.
+ *
+ * The marker must also END at a boundary, so BLOCKED does not match
+ * BLOCKEDBY.
+ */
+/**
+ * The path of a `when: rows of <path>` condition, or null when the condition
+ * is a marker. `rows of` is the phrase `each:` uses for the same file, so a
+ * flow reads a CSV one way in both. The whole phrase is required: a bare
+ * `when: ROWS` stays the marker it always was.
+ */
+export function whenRowsPath(when: string): string | null {
+  const m = when.trim().match(/^rows\s+of\s+(\S.*)$/i);
+  return m ? m[1].trim() : null;
+}
+
+export function markerPresent(text: string | null | undefined, marker: string): boolean {
+  const needle = marker.trim().toLowerCase();
+  if (!needle || !text) return false;
+  for (const raw of text.split("\n")) {
+    // Strip what markdown puts in front of a headline: heading hashes,
+    // quote marks, list bullets, emphasis, backticks.
+    // Heading hashes, quote marks, bullets, numbered-list markers, task
+    // checkboxes, a leading table pipe, emphasis, backticks.
+    const line = raw.replace(/^(?:[\s>#*_`\-+|]|\d+[.)](?=\s)|\[[ xX]\])*/, "").toLowerCase();
+    if (!line.startsWith(needle)) continue;
+    const after = line[needle.length];
+    // End of line, or a separator. A letter or digit means this is a longer
+    // word that merely begins the same way.
+    if (after === undefined || !/[a-z0-9]/.test(after)) return true;
+  }
+  return false;
+}
+
 export function parseFlow(file: string, raw: string): FlowInfo {
+  // A flow saved with CRLF (Windows, some editors) read as no steps at all:
+  // every line kept its "\r", which STEP_RE's `.` will not match. Read it as
+  // LF; the line count, and so every step's `line`, is the same.
+  raw = raw.replace(/\r\n/g, "\n");
   const { data, content } = matter(raw);
   const steps: FlowStep[] = [];
+  // Flow-level problems: a malformed step target (below) and unreadable
+  // frontmatter enums (before the return). Reported as errors by flow-lint.
+  const frontProblems: string[] = [];
   // Frontmatter is stripped by matter(), so add it back to keep line numbers
   // pointing at the real file rather than the body.
   const offset = raw.slice(0, raw.length - content.length).split("\n").length - 1;
   let lineNo = 0;
+  // A `schema:` with nothing after the colon takes the lines indented
+  // deeper than it as a YAML block — the one place the grammar allows a
+  // shape to be written out rather than named, because a schema is a
+  // document and a one-line one is unreadable past three fields.
+  let block: { step: FlowStep; indent: number; lines: string[] } | null = null;
+  // The step still accepting wrapped instruction lines, or null once
+  // anything has closed it. See the continuation rule below.
+  let open: FlowStep | null = null;
+  const endBlock = () => {
+    if (!block) return;
+    const { step, lines } = block;
+    block = null;
+    // Dedent by the block's own margin, not trim: the first line's indent
+    // is every line's indent, and YAML reads a mapping by its columns.
+    const margin = Math.min(...lines.filter((l) => l.trim()).map((l) => l.match(/^\s*/)![0].length));
+    const text = lines.map((l) => (l.trim() ? l.slice(margin) : "")).join("\n").trim();
+    if (!text) return void (step.problems ??= []).push("schema: — the block under it is empty");
+    const parsed = parseSchemaText(text);
+    if ("problem" in parsed) (step.problems ??= []).push(`schema: ${parsed.problem}`);
+    else step.schema = parsed.schema;
+  };
   for (const line of content.split("\n")) {
     lineNo++;
+    if (block) {
+      const indent = line.match(/^(\s*)\S/)?.[1].length;
+      if (indent === undefined) {
+        block.lines.push("");
+        continue;
+      }
+      if (indent > block.indent) {
+        block.lines.push(line.slice(block.indent + 1));
+        continue;
+      }
+      endBlock();
+    }
     const m = line.match(STEP_RE);
     if (m) {
       steps.push({
@@ -1275,48 +1745,160 @@ export function parseFlow(file: string, raw: string): FlowInfo {
         instruction: m[5].trim(),
         line: lineNo + offset,
       });
+      open = steps[steps.length - 1];
       continue;
     }
-    // Indented options belong to the step above them.
+    // A line shaped like a numbered step whose `[[target]]` STEP_RE would
+    // not accept — capitals or an underscore in the name — used to fall
+    // through and be swallowed as prose, so the step silently vanished.
+    // Name it instead: an agent is [a-z0-9-], and a real one that is merely
+    // missing is a separate, later error.
+    const shape = line.match(/^\s*\d+[?!]?\.?\s+\[\[(flow:)?([^\]]*)\]\]/);
+    if (shape && !STEP_RE.test(line)) {
+      frontProblems.push(`step \`[[${shape[1] ?? ""}${shape[2]}]]\` on line ${lineNo + offset}: a step targets an agent or flow named in lower case, digits and dashes — not \`${shape[2]}\`.`);
+    }
+    // An indented line that is not an option continues the instruction —
+    // but only while the step is still open.
+    //
+    // Both directions of this have been wrong in production. Dropping the
+    // continuation silently cut twenty-five live instructions off mid
+    // sentence. Taking every indented line instead read the *wrapped lines
+    // of a bullet list* three paragraphs below the last step as orders: the
+    // gbp-desk publisher was told to "publish Tuesday's five every way step
+    // 3 could fail was also a way Thursday's five silently never went out".
+    //
+    // So a step's instruction ends where the step ends. A continuation is
+    // an indented line that follows the step line, or a previous
+    // continuation, with nothing in between — no blank line, no unindented
+    // line, no option, no schema block. Once any of those closes the step
+    // the instruction is finished, and prose below the last step is prose.
+    //
+    // Indented markdown never continues an instruction either. A heading, a
+    // bullet, a quote, a numbered item or a paragraph opening in bold is a
+    // document, not a sentence somebody wrapped, and the indentation is a
+    // list's own margin.
     const opt = line.match(OPTION_RE);
+    const isOption = !!opt && STEP_OPTION_KEYS.has(opt[2]);
+    if (open && /^\s+\S/.test(line) && !isOption) {
+      if (MARKDOWN_BLOCK_RE.test(line.trim())) {
+        open = null;
+      } else {
+        open.instruction = `${open.instruction} ${line.trim()}`.trim();
+        open.wrapped = true;
+        continue;
+      }
+    }
+    // Anything that is not a continuation closes the step to further ones.
+    open = null;
+    // Indented options belong to the step above them.
     if (opt && steps.length) {
       const step = steps[steps.length - 1];
-      const [, key, rawValue] = opt;
+      const [, indentText, key, rawValue] = opt;
       const value = unquote(rawValue);
+      // A value the key cannot read is recorded, never guessed at. Every
+      // one of these used to be coerced — Number("abc") || 0, clamped —
+      // and the run went ahead with a number the author never wrote.
+      const problem = (text: string) => (step.problems ??= []).push(`${key}: ${value} — ${text}`);
       if (key === "approve") step.approve = value !== "false";
       else if (key === "when") step.when = value;
       else if (key === "case") step.case = value;
       else if (key === "else") step.else = value !== "false";
-      else if (key === "retry") step.retry = Math.min(5, Math.max(0, Number(value) || 0));
-      else if (key === "timeout") step.timeout = Math.max(1, Number(value) || 0);
+      else if (key === "retry") {
+        const n = parseCount(value, 0, 5);
+        if (n === undefined) problem("a whole number of extra attempts, at most 5");
+        // Over the cap still runs, capped: the check fails, the run does not.
+        step.retry = n ?? Math.min(5, Math.max(0, Math.floor(Number(value)) || 0));
+      }
+      else if (key === "timeout") {
+        const secs = parseTimeout(value);
+        if (secs === undefined) problem("not a duration; write seconds (900) or 15m, 4h, 3d");
+        else step.timeout = secs;
+      }
       else if (key === "verify") step.verify = value;
-      else if (key === "output") step.output = /^json$/i.test(value) ? "json" : undefined;
+      else if (key === "output") {
+        if (/^json$/i.test(value)) step.output = "json";
+        else problem("the only shape is json");
+      }
       else if (key === "model") step.model = value;
       else if (key === "effort") step.effort = value;
-      else if (key === "loop") step.loop = Math.min(5, Math.max(1, Number(value) || 0)) || undefined;
+      else if (key === "loop") {
+        const n = parseCount(value, 1, 5);
+        if (n === undefined) problem("a whole number of extra cycles, 1 to 5");
+        step.loop = n ?? (Math.min(5, Math.max(1, Math.floor(Number(value)) || 0)) || undefined);
+      }
       else if (key === "until") step.until = value;
       else if (key === "each") {
         if (value === "lines") step.each = "lines";
         else if (value === "items") step.each = "items";
         else if (/^rows\b/.test(value)) {
           step.each = "rows";
-          // "rows of ../../storage/leads.csv" — the path is the part after "of".
+          // "rows of workspace/storage/leads.csv" — the path is the part after "of".
           step.eachPath = value.replace(/^rows(\s+of)?\s*/, "").trim() || undefined;
+          if (!step.eachPath) problem("rows needs a file: each: rows of workspace/storage/leads.csv");
         }
+        else problem("lines, items, or rows of <path>");
       }
       else if (key === "on-fail" || key === "onfail") step.onFail = refNames(value)[0] ?? undefined;
       else if (key === "wait") {
         if (/^event$/i.test(value)) step.waitFor = "event";
-        else step.waitSecs = parseWait(value);
+        else {
+          step.waitSecs = parseWait(value);
+          if (step.waitSecs === undefined) problem("event, or a duration: 90s, 30m, 4h, 3d");
+        }
       }
       else if (key === "ask") { step.ask = value; }
       else if (key === "preview") {
-        step.preview = value.split(",").map((p) => p.trim().replace(/^(\.\.\/\.\.\/)?storage\//, "")).filter(Boolean);
+        step.preview = value.split(",").map((p) => p.trim().replace(/^(\.\.\/\.\.\/|workspace\/)?storage\//, "")).filter(Boolean);
       }
       else if (key === "delegate") step.delegate = refNames(value).slice(0, 5);
-      else if (key === "max") step.max = Math.min(20, Math.max(1, Number(value) || 0)) || undefined;
+      else if (key === "max") {
+        const n = parseCount(value, 1, 20);
+        if (n === undefined) problem("a whole number of items, 1 to 20");
+        step.max = n ?? (Math.min(20, Math.max(1, Math.floor(Number(value)) || 0)) || undefined);
+      }
+      else if (key === "parallel") {
+        const n = parseCount(value, 1, PARALLEL_CAP);
+        if (n === undefined) problem(`a whole number of instances to run at once, 1 to ${PARALLEL_CAP}`);
+        else step.parallel = n;
+      }
+      else if (key === "max_turns") {
+        const n = parseCount(value, 1, MAX_TURNS_CAP);
+        if (n === undefined) problem(`a whole number of turns, 1 to ${MAX_TURNS_CAP}`);
+        else step.maxTurns = n;
+      }
+      else if (key === "limits") {
+        const read = parseStepLimits(value);
+        for (const p of read.problems) problem(p);
+        if (Object.keys(read.limits).length) step.limits = read.limits;
+      }
+      else if (key === "schema") {
+        if (!value) block = { step, indent: indentText.length, lines: [] };
+        else if (/^[{[]/.test(value)) {
+          const parsed = parseSchemaText(value);
+          if ("problem" in parsed) problem(parsed.problem);
+          else step.schema = parsed.schema;
+        }
+        else if (!/\s/.test(value) && (/\.(json|ya?ml)$/i.test(value) || value.includes("/"))) step.schemaPath = value;
+        else problem("a JSON object, a path under the workspace (schemas/lead.json), or a YAML block on the lines below");
+      }
     }
   }
+  endBlock();
+  // A frontmatter enum written with a typo — `overlap: que` — read as null
+  // and ran with the silent default. flows.md promises otherwise ("a value
+  // the option cannot read is a check error, never a guess"); make it true
+  // for these too, not only for step options.
+  const badEnum = (key: string, val: unknown, allowed: string[]) => {
+    if (typeof val === "string" && val.trim() && !allowed.includes(val.trim())) {
+      frontProblems.push(`${key}: ${val} — the values are ${allowed.join(", ")}.`);
+    }
+  };
+  badEnum("overlap", data.overlap, ["skip", "queue"]);
+  badEnum("priority", data.priority, ["high", "normal", "low"]);
+  badEnum("catchup", data.catchup, ["none", "last"]);
+  badEnum("on", data.on, ["completed", "failed", "blocked", "any"]);
+  badEnum("signature", data.signature, ["github", "stripe", "slack", "hmac"]);
+
   steps.sort((a, b) => a.group - b.group);
   return {
     name: data.name ?? file.replace(/\.md$/, ""),
@@ -1327,12 +1909,14 @@ export function parseFlow(file: string, raw: string): FlowInfo {
     model: data.model ?? null,
     effort: data.effort ?? null,
     overlap: data.overlap === "skip" || data.overlap === "queue" ? data.overlap : null,
+    live: data.live === true,
     priority: data.priority === "high" || data.priority === "low" || data.priority === "normal" ? data.priority : null,
-    budget: Number(data.budget) > 0 ? Number(data.budget) : null,
+    budget: runBudget(data.budget),
+    budgetProblem: budgetProblem(data.budget, ["run"]),
     // `after: [[flow:publish]]` — a link or a bare name, read the same way
     // as every other file-naming field (refs.ts).
     after: (refNames(data.after)[0] ?? "").replace(/^flow:/, "").trim() || null,
-    on: data.on === "failed" || data.on === "any" ? data.on : "completed",
+    on: data.on === "failed" || data.on === "blocked" || data.on === "any" ? data.on : "completed",
     at: parseInstant(data.at),
     url: typeof data.url === "string" ? data.url.trim() : null,
     every: typeof data.every === "string" || typeof data.every === "number" ? (parseWait(String(data.every)) ?? null) : null,
@@ -1344,10 +1928,86 @@ export function parseFlow(file: string, raw: string): FlowInfo {
         ? data.signing_secret.trim().replace(/^\$\{|\}$/g, "")
         : null,
     path: typeof data.path === "string" ? data.path.trim().replace(/^\/+/, "") : null,
+    // A header name is case-insensitive on the wire; a JSON field is not.
+    // `body:eventId` lower-cased to `body:eventid` matched nothing, and a
+    // dedupe that matches nothing admits everything.
+    idempotency: typeof data.idempotency === "string" ? idempotencyName(data.idempotency) : null,
+    debounce: durationOf(data.debounce),
+    throttle: durationOf(data.throttle),
+    catchup: data.catchup === "none" || data.catchup === "last" ? data.catchup : null,
+    disableAfter: Number.isFinite(Number(data.disable_after)) && Number(data.disable_after) > 0
+      ? Math.min(100, Math.floor(Number(data.disable_after)))
+      : null,
+    pauseWhen: typeof data.pause_when === "string" && data.pause_when.trim() && data.pause_when.trim().length <= 60
+      ? data.pause_when.trim()
+      : null,
+    sla: durationOf(data.sla),
+    approvers: approverList(data.approvers),
+    approveWithin: durationOf(data.approve_within),
+    description: typeof data.description === "string" ? data.description.trim() || null : null,
+    frontProblems,
     steps,
   };
 }
 
+/** A schema written out: JSON, or YAML (parsed as frontmatter is, by the
+ *  same engine). The result must be an object — a schema is a document,
+ *  and `schema: 3` or `schema: [a, b]` describes nothing. */
+export function parseSchemaText(text: string): { schema: Record<string, unknown> | boolean } | { problem: string } {
+  let value: unknown;
+  try {
+    value = /^\s*[{[]/.test(text) ? JSON.parse(text) : matter(`---\n${text}\n---\n`).data;
+  } catch (err) {
+    return { problem: `cannot read the schema — ${err instanceof Error ? err.message.split("\n")[0] : String(err)}` };
+  }
+  if (typeof value === "boolean") return { schema: value };
+  if (typeof value !== "object" || value === null || Array.isArray(value) || Object.keys(value).length === 0) {
+    return { problem: "a schema is a JSON object (type, properties, required, …)" };
+  }
+  return { schema: value as Record<string, unknown> };
+}
+
+function idempotencyName(raw: string): string | null {
+  const v = raw.trim();
+  if (!v) return null;
+  return v.toLowerCase().startsWith("body:") ? `body:${v.slice(5).trim()}` : v.toLowerCase();
+}
+
+/** A duration frontmatter value — "30m", "2d", or bare seconds — or null.
+ *  Shares parseWait's units and its thirty-day ceiling, so every duration in
+ *  the format is written and bounded the same way. */
+function durationOf(raw: unknown): number | null {
+  if (typeof raw === "number") return raw > 0 ? Math.min(Math.round(raw), 30 * 86400) : null;
+  if (typeof raw !== "string") return null;
+  return parseWait(raw) ?? null;
+}
+
+/** `approvers:` — a YAML list, or one address, or "admins". Lower-cased,
+ *  because an email address that differs only in case is the same person and
+ *  a gate that refuses them is a support ticket. */
+function approverList(raw: unknown): string[] | null {
+  const items = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(",") : [];
+  const out = items.map((v) => String(v).trim().toLowerCase()).filter(Boolean);
+  return out.length ? [...new Set(out)] : null;
+}
+
+/** May this person decide a gate of this flow? `approvers:` is an allowlist
+ *  of addresses plus the word "admins"; an empty list defers to whatever
+ *  permission the caller already needed to reach the route.
+ *
+ *  Self-approval is refused separately (see approvals.ts): who STARTED a run
+ *  is a property of the run, not of the flow file. */
+export function mayApprove(
+  flow: Pick<FlowInfo, "approvers"> | null | undefined,
+  who: { email?: string | null; role?: string | null },
+): boolean {
+  const list = flow?.approvers;
+  if (!list || list.length === 0) return true;
+  const email = (who.email ?? "").trim().toLowerCase();
+  if (email && list.includes(email)) return true;
+  return list.includes("admins") && (who.role === "admin" || who.role === "owner");
+}
+
 /** A live run of this flow — the fact overlap: decisions are made on. */
 export function flowHasLiveRun(tenant: string, workspace: string, flowName: string): boolean {
   return listRuns(tenant, workspace).some(
@@ -1413,7 +2073,7 @@ function emitFlow(head: string, preamble: string[], groups: FlowBlock[][]): stri
  * and the diff is exactly the lines that changed. A flow with no
  * frontmatter gains the smallest one that can carry the trigger.
  */
-export function setFlowTrigger(
+function setFlowTriggerLF(
   raw: string,
   opts: { trigger: FlowTrigger; schedule?: string; timezone?: string },
 ): string {
@@ -1473,7 +2133,7 @@ export function setFlowTrigger(
  * the prefix is taken verbatim from the file and only the tail replaced. A
  * flow's markdown stays the author's.
  */
-export function updateFlowStepInstruction(raw: string, index: number, instruction: string): string {
+function updateFlowStepInstructionLF(raw: string, index: number, instruction: string): string {
   const { head, preamble, blocks } = splitFlowBlocks(raw);
   if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
     throw new Error(`no step ${index}`);
@@ -1483,9 +2143,9 @@ export function updateFlowStepInstruction(raw: string, index: number, instructio
   const m = line.match(STEP_RE);
   if (!m) throw new Error(`step ${index} is not a step line`);
   // Everything up to where the instruction starts, exactly as written.
-  const prefix = m[5] ? line.slice(0, line.length - m[5].length) : `${line.replace(/\s+$/, "")} — `;
+  const prefix = m[5] ? line.slice(0, line.length - m[5].length) : `${line.trimEnd()} — `;
   const next = instruction.trim().replace(/\s*\n\s*/g, " ");
-  block.lines = [`${prefix}${next}`.replace(/\s+$/, ""), ...block.lines.slice(1)];
+  block.lines = [`${prefix}${next}`.trimEnd(), ...block.lines.slice(1)];
   // Same regrouping as updateFlowStep: consecutive blocks sharing a number
   // are one parallel group, and emitFlow puts the file back together.
   const groups: FlowBlock[][] = [];
@@ -1497,10 +2157,10 @@ export function updateFlowStepInstruction(raw: string, index: number, instructio
   return emitFlow(head, preamble, groups);
 }
 
-export function updateFlowStep(
+function updateFlowStepLF(
   raw: string,
   index: number,
-  options: Partial<Record<"model" | "effort" | "retry" | "timeout" | "verify" | "when" | "case" | "else" | "loop" | "until" | "each" | "max", string | number | null>>,
+  options: Partial<Record<"model" | "effort" | "retry" | "timeout" | "verify" | "when" | "case" | "else" | "loop" | "until" | "each" | "max" | "limits", string | number | null>>,
 ): string {
   const { head, preamble, blocks } = splitFlowBlocks(raw);
   if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
@@ -1520,12 +2180,21 @@ export function updateFlowStep(
     loop: (v) => (Number(v) > 0 ? String(Math.min(5, Math.max(1, Math.floor(Number(v))))) : null),
     max: (v) => (Number(v) > 0 ? String(Math.min(20, Math.max(1, Math.floor(Number(v))))) : null),
     each: (v) => (v === "lines" ? "lines" : null),
+    // `{web.search: 10, calls: 300}` — one line, read the way parseFlow
+    // reads it; a value it would flag is refused rather than written.
+    limits: (v) => {
+      if (!v || v === "{}") return null;
+      const read = parseStepLimits(v);
+      if (read.problems.length) throw new Error(`limits: ${read.problems[0]}`);
+      const pairs = Object.entries(read.limits);
+      return pairs.length ? `{${pairs.map(([k, n]) => `${k}: ${n}`).join(", ")}}` : null;
+    },
   };
 
   const block = blocks[index];
   const managed = new Set(Object.keys(options));
   const kept = block.lines.slice(1).filter((line) => {
-    const key = line.match(OPTION_RE)?.[1];
+    const key = line.match(OPTION_RE)?.[2];
     return !(key && managed.has(key));
   });
   const added: string[] = [];
@@ -1547,7 +2216,7 @@ export function updateFlowStep(
   return emitFlow(head, preamble, groups);
 }
 
-export function reorderFlowSteps(raw: string, groups: number[][]): string {
+function reorderFlowStepsLF(raw: string, groups: number[][]): string {
   const { head, preamble, blocks: ordered } = splitFlowBlocks(raw);
 
   const seen = new Set<number>();
@@ -1567,7 +2236,7 @@ export function reorderFlowSteps(raw: string, groups: number[][]): string {
 }
 
 /** Append a step as its own group at the end of the flow. */
-export function addFlowStep(
+function addFlowStepLF(
   raw: string,
   step: { target: string; subflow?: boolean; instruction?: string },
 ): string {
@@ -1582,7 +2251,7 @@ export function addFlowStep(
 }
 
 /** Drop one step, by its index in the flow's parsed steps. */
-export function removeFlowStep(raw: string, index: number): string {
+function removeFlowStepLF(raw: string, index: number): string {
   const { head, preamble, blocks } = splitFlowBlocks(raw);
   if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
     throw new Error(`no step ${index}`);
@@ -1591,6 +2260,20 @@ export function removeFlowStep(raw: string, index: number): string {
   return emitFlow(head, preamble, groupBlocks(kept));
 }
 
+// The rewriters above work on LF (eol.ts); the web route calls these with
+// the file as saved, so a CRLF flow is read as LF and written back as CRLF.
+export const setFlowTrigger = (raw: string, opts: Parameters<typeof setFlowTriggerLF>[1]): string =>
+  asRaw(raw, setFlowTriggerLF(toLF(raw), opts));
+export const updateFlowStepInstruction = (raw: string, index: number, instruction: string): string =>
+  asRaw(raw, updateFlowStepInstructionLF(toLF(raw), index, instruction));
+export const updateFlowStep = (raw: string, index: number, options: Parameters<typeof updateFlowStepLF>[2]): string =>
+  asRaw(raw, updateFlowStepLF(toLF(raw), index, options));
+export const reorderFlowSteps = (raw: string, groups: number[][]): string =>
+  asRaw(raw, reorderFlowStepsLF(toLF(raw), groups));
+export const addFlowStep = (raw: string, step: Parameters<typeof addFlowStepLF>[1]): string =>
+  asRaw(raw, addFlowStepLF(toLF(raw), step));
+export const removeFlowStep = (raw: string, index: number): string => asRaw(raw, removeFlowStepLF(toLF(raw), index));
+
 /** Blocks → the group structure they currently describe. */
 function groupBlocks(blocks: FlowBlock[]): FlowBlock[][] {
   const map = new Map<number, FlowBlock[]>();
@@ -1608,6 +2291,19 @@ export function listFlows(tenant: string, workspace: string): FlowInfo[] {
     .map((f) => parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8")));
 }
 
+/** One flow of a workspace by name, or null. The same read listFlows makes,
+ *  named so callers that want a single flow — the approval rules, the
+ *  runner's budget stamp — do not each re-implement the directory walk. */
+export function readFlow(tenant: string, workspace: string, flowName: string): FlowInfo | null {
+  const dir = path.join(workspaceDir(tenant, workspace), "flows");
+  if (!fs.existsSync(dir)) return null;
+  for (const f of fs.readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+    const flow = parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8"));
+    if (flow.name === flowName) return flow;
+  }
+  return null;
+}
+
 export interface WorkspaceSummary {
   name: string;
   description: string;
@@ -1691,7 +2387,7 @@ export function listWorkspaces(tenant: string): WorkspaceSummary[] {
         agents: listAgents(tenant, name).length,
         flows: listFlows(tenant, name).length,
         deployedAt: fs.statSync(pDir).mtime.toISOString(),
-        runCount: fs.existsSync(runsDir) ? fs.readdirSync(runsDir).length : 0,
+        runCount: fs.existsSync(runsDir) ? fs.readdirSync(runsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).length : 0,
         ...(preview ? { preview } : {}),
       };
     })
@@ -1702,7 +2398,10 @@ export function listWorkspaces(tenant: string): WorkspaceSummary[] {
 
 // Editable paths: project.md, .md files under agents/ or flows/, and an
 // agent's own scripts (text source files it runs with bash).
-const SCRIPT_EXT = /\.(py|sh|[mc]?js|ts|rb|sql|txt|json|ya?ml|toml|env|md)$/i;
+// csv/tsv: a desk's registers and ledgers (who was emailed, what was
+// posted) are tables, and refusing them meant a register could be neither
+// seeded nor read through the door — only rewritten by a run (2026-09-15).
+const SCRIPT_EXT = /\.(py|sh|[mc]?js|ts|rb|sql|txt|json|ya?ml|toml|env|md|[ct]sv)$/i;
 
 /**
  * May this path be edited — and therefore, must it be listed?
@@ -1744,18 +2443,27 @@ function assertEditablePath(rel: string) {
  *  never be served. Listing them is honest — hiding them is what makes a file
  *  tree disagree with the filesystem it claims to show — but their contents
  *  are the vault and the money, so a reader gets the reason instead. */
-const ACCOUNT_SEALED = new Set(["secrets.json", "oauth-clients.json", "ledger.jsonl"]);
+// billing.json, oauth-connections.json and secret-health.json were listed and
+// served until 2026-09-24: any member of the account, a viewer included, could
+// open the Stripe customer id and billing email, and which connections exist.
+const ACCOUNT_SEALED: Record<string, string> = {
+  "secrets.json": "the vault — encrypted, and never served to a browser. Manage secrets in Settings.",
+  "oauth-clients.json": "OAuth client credentials — never served to a browser.",
+  "ledger.jsonl": "the billing ledger — append-only, read it through Usage and Wallet.",
+  "billing.json": "the account's billing settings — read and change them in Wallet.",
+  "oauth-connections.json": "connected apps and their health — see Settings → Connections.",
+  "secret-health.json": "secret usage bookkeeping — see Settings → Secrets.",
+};
 
 export function accountFileSealed(rel: string): string | null {
   const norm = rel.replaceAll("\\", "/");
-  if (ACCOUNT_SEALED.has(norm)) {
-    return norm === "secrets.json"
-      ? "the vault — encrypted, and never served to a browser. Manage secrets in Settings."
-      : norm === "oauth-clients.json"
-        ? "OAuth client credentials — never served to a browser."
-        : "the billing ledger — append-only, read it through Usage and Wallet.";
-  }
-  if (/^(billed|workspaces\/[^/]+\/runs)\//.test(norm)) {
+  if (/(^|\/)secrets\.json\.[^/]+$/.test(norm)) return "the vault's lock or a save in flight — never served.";
+  if (Object.hasOwn(ACCOUNT_SEALED, norm)) return ACCOUNT_SEALED[norm];
+  // What a move into the database leaves behind: billing.json.imported-<date>
+  // and the like, kept for a rollback — the same contents, so the same seal.
+  const moved = /^(.+\.json)\.imported-[\d-]+$/.exec(norm);
+  if (moved && Object.hasOwn(ACCOUNT_SEALED, moved[1])) return ACCOUNT_SEALED[moved[1]];
+  if (/^(billed|once|topups|workspaces\/[^/]+\/runs)\//.test(norm)) {
     return "generated bookkeeping, not an authored file.";
   }
   if (/^workspaces\/[^/]+\/secrets\.json$/.test(norm)) {
@@ -1770,7 +2478,7 @@ export function accountFileSealed(rel: string): string | null {
  *  honesty's clothes. `accountFileSealed` still refuses these if a path is
  *  constructed directly — the listing hides them, the reader guards them. */
 const ACCOUNT_BOOKKEEPING =
-  /^(billed\/|ledger\.jsonl$|oauth-clients\.json$)|(^|\/)runs\/|(^|\/)secrets\.json$/;
+  /^(billed\/|once\/|topups\/|ledger\.jsonl$|oauth-clients\.json$|billing\.json$|oauth-connections\.json$|secret-health\.json$|[^/]+\.json\.imported-[\d-]+$)|(^|\/)runs\/|(^|\/)secrets\.json(\.[^/]+)?$/;
 
 /**
  * The account directory as it actually is on disk.
@@ -1837,7 +2545,7 @@ export function listWorkspaceFiles(tenant: string, workspace: string): string[]
   const dir = workspaceDir(tenant, workspace);
   if (!fs.existsSync(dir)) return [];
   const out: string[] = [];
-  for (const entry of fs.readdirSync(dir, { recursive: true })) {
+  for (const entry of entriesNoFollow(dir)) {
     const rel = String(entry);
     if (/(^|\/)(runs|outputs)\//.test(rel)) continue;
     // Skip anything reached through a symlink — a stray link would otherwise
@@ -1883,7 +2591,9 @@ export function writeWorkspaceFile(
   content: string,
   meta: ChangeMeta = {},
 ) {
-  if (content.length > 256 * 1024) throw new Error("file too large");
+  // 512 KB: a folder tool's program is one file, and the gallery browser's is
+  // past 256 KB. Still a file a person edits, not a store for data.
+  if (content.length > MAX_EDITABLE_FILE) throw new Error("file too large");
   matter(content); // reject files whose frontmatter doesn't parse
   const p = path.join(workspaceDir(tenant, workspace), assertEditablePath(rel));
   const existed = fs.existsSync(p);
@@ -1897,7 +2607,7 @@ export function writeWorkspaceFile(
   // the editor's line gutter dutifully numbered all of it. Trailing blank
   // lines are not content in any format this holds (markdown, YAML
   // frontmatter, a script), and no author types thirty of them on purpose.
-  fs.writeFileSync(p, `${content.replace(/\s+$/, "")}\n`);
+  fs.writeFileSync(p, `${content.trimEnd()}\n`);
   // Code is executable wherever it lives: the scripts shelf, a skill's
   // bundled scripts/, or a folder tool's own directory. A run.mjs written
   // without the bit fails at exec, which reads as "the tool is broken".
@@ -2064,9 +2774,11 @@ export function deleteWorkspacePath(tenant: string, workspace: string, rel: stri
   }
   // Whole-folder units: an agent, a skill, a folder tool. Each is one thing
   // to its reader, so each is one thing to delete.
-  if (/^agents\/[a-z0-9-]+$/.test(norm) ||
-      /^(skills|tools)\/[a-z0-9-]+$/.test(norm) ||
-      /^agents\/[a-z0-9-]+\/skills\/[a-z0-9-]+$/.test(norm)) {
+  // An underscore is allowed in the folder's name: a tool called
+  // `my_tool` is one thing too, and its tool.md is refused alone above.
+  if (/^agents\/[a-z0-9_-]+$/.test(norm) ||
+      /^(skills|tools)\/[a-z0-9_-]+$/.test(norm) ||
+      /^agents\/[a-z0-9_-]+\/skills\/[a-z0-9_-]+$/.test(norm)) {
     const gone = deletionsUnder(dir, norm);
     fs.rmSync(path.join(dir, norm), { recursive: true, force: true });
     recordRevision(tenant, workspace, gone, { message: `deleted ${norm}/`, ...meta });
@@ -2243,11 +2955,94 @@ export interface RunEvent {
   call?: string;
   ms?: number;
   err?: boolean;
+  /** Set on a test run's event that reports what the platform did instead
+   *  of the real thing — a refused send, a redirected email, a diverted
+   *  state write, a withheld secret. The run page lists these; the text is
+   *  still the trace's line. See test-mode.ts. */
+  effect?: TestEffect;
+  /** Set when a person was involved mid-step: a question the agent asked
+   *  (ask_person), its answer, or a message a person sent in (operator.ts). */
+  operator?: OperatorEvent;
+  /** Set on a tool event a SUB-AGENT made (`subagents:`): its name. The
+   *  trace labels the call with it; cost stays the step's. */
+  subagent?: string;
+  /** Set on an error a failed check wrote — `verify:` (its headline and its
+   *  detail), `output: json`, a schema. What the runner reads to decline a
+   *  retry of an outward step whose tools already ran. */
+  check?: boolean;
+}
+
+/** A question an agent asked a person while its step ran (tools: [ask]). */
+export interface StepQuestion {
+  id: string;
+  question: string;
+  options?: string[];
+  askedAt: string;
+  answer?: string;
+  answeredAt?: string;
+  by?: string | null;
+  /** true when the wait ran out with no answer. */
+  unanswered?: boolean;
+}
+
+/** A message a person sent into a running step, and when the agent got it. */
+export interface StepMessage {
+  text: string;
+  by?: string | null;
+  at: string;
+  deliveredAt: string;
+}
+
+/** One attempt of a step — see StepRecord.tries. */
+export interface StepAttempt {
+  /** Which try, 1-based, in the order they ran: a retry is the next try,
+   *  and so is the full re-run after a slim go the browser pod was lost
+   *  under. Equal to the step's attempt (`attempts` at the time) unless
+   *  `attempt` says otherwise. */
+  n: number;
+  /** The step's attempt this try belongs to, written only when it is not
+   *  `n` — after a lost slim go, its full re-run is try 2 of attempt 1. */
+  attempt?: number;
+  /** `lost`: a slim go the account's browser pod went away under, which
+   *  the step ran again on the full image within the same attempt — a row
+   *  of its own (image slim), before the full go's. */
+  status: "completed" | "failed" | "lost";
+  costUsd: number | null;
+  tokens: { input: number; output: number } | null;
+  computeSecs: number | null;
+  startedAt: string;
+  finishedAt: string;
+  /** The last error event this attempt wrote, when it failed. */
+  error?: string;
+  /** The runner image this attempt ended on, and — when it browsed through
+   *  the account's pod from slim — what happened to the pod: reconnects,
+   *  the re-run on full, or why it was not re-run. */
+  image?: "full" | "slim";
+  browserPod?: string;
+}
+
+/** The step's totals across its attempts, from the rows. Null where no
+ *  attempt reported the figure — an in-process step rents no sandbox, and
+ *  billing reads null as zero, not as "unknown, charge something". */
+export function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs"> {
+  const costs = tries.map((t) => t.costUsd).filter((c): c is number => typeof c === "number");
+  const toks = tries.map((t) => t.tokens).filter((t): t is { input: number; output: number } => !!t);
+  const secs = tries.map((t) => t.computeSecs).filter((c): c is number => typeof c === "number");
+  return {
+    costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
+    tokens: toks.length ? toks.reduce((a, b) => ({ input: a.input + b.input, output: a.output + b.output }), { input: 0, output: 0 }) : null,
+    computeSecs: secs.length ? secs.reduce((a, b) => a + b, 0) : null,
+  };
 }
 
 export interface StepRecord {
   agent: string;
   instruction: string;
+  /** Questions the agent asked a person mid-step (tools: [ask]), newest
+   *  last. One without an answer (and not `unanswered`) is still open. */
+  questions?: StepQuestion[];
+  /** Messages a person sent into the running step, as delivered. */
+  messages?: StepMessage[];
   group: number;
   optional: boolean;
   /** Carried from the flow — see FlowStep. Both are resolved at run
@@ -2264,6 +3059,17 @@ export interface StepRecord {
   verify?: string;
   /** Attempts made so far, for the run trace. */
   attempts?: number;
+  /**
+   * One row per attempt, oldest first: what each cost and how it ended.
+   * `costUsd`, `tokens` and `computeSecs` on the step are the SUM of these
+   * rows — a retried step spent every attempt's money, and the run's spend,
+   * the flow's `budget:` and the platform's bill all read the step's
+   * figure, so the figure is the total. Before this the step carried only
+   * the last attempt's cost and a `retry: 2` step could spend three shares
+   * of the budget while reporting one. A loop cycle that re-runs the step
+   * appends here too, so its earlier cycles are not lost from the bill.
+   */
+  tries?: StepAttempt[];
   /** The sandbox this step is executing in, while it is: which executor,
    *  its handle (a pod name), and how many of its output lines the driver
    *  has already applied to this record. What a driver that inherits the
@@ -2274,6 +3080,20 @@ export interface StepRecord {
   /** A size class a retry moved the step up to (an evicted or OOM-killed
    *  attempt), overriding the agent's own `size:` for the attempts after. */
   sizeUp?: "large" | "heavy";
+  /** Which runner image the step's sandbox ran: `full` (browsers in it) or
+   *  `slim`, why, and `pod` when a browsing step ran slim and browsed
+   *  through the account's browser pod. The last attempt's; absent where
+   *  the executor has one image (docker, in-process). */
+  image?: { variant: "full" | "slim"; why?: string; pod?: boolean } | null;
+  /** Slim browsing through the account's pod (browser-pod.ts): reconnect
+   *  tries and how many got through; when the pod was lost, why and what
+   *  the step had written by then; and what happened — `fallback` (the
+   *  step had only read and ran again on the full image) or `failure` (it
+   *  had written, so it was not re-run). */
+  browserPod?: (BrowserPodOutcome & { fallback?: string; failure?: string }) | null;
+  /** The slim go a lost browser pod ended, set aside while the step re-runs
+   *  on full; recordAttempt makes it a `lost` row of `tries` and clears it. */
+  podLostTry?: Omit<StepAttempt, "n" | "attempt" | "startedAt"> | null;
   /** When the step actually started and finished executing — not when the
    *  run reached it. A step's events approximate this (first and last), but
    *  a model can think for minutes before its first tool call, and a step
@@ -2296,6 +3116,11 @@ export interface StepRecord {
   max?: number;
   /** Carried from the flow — see FlowStep. */
   output?: "json";
+  schema?: Record<string, unknown> | boolean;
+  schemaPath?: string;
+  parallel?: number;
+  maxTurns?: number;
+  limits?: Record<string, number>;
   /** The parsed JSON an `output: json` step returned. Kept beside the prose
    *  result rather than instead of it: the reply is still what a person
    *  reads on the run page, and the data is what the next step computes on. */
@@ -2422,6 +3247,20 @@ export interface RunRecord {
    * simply gets its first line — which is still better than a status.
    */
   summary?: string | null;
+  /**
+   * What the run's work concluded, when its summary leads with one of the
+   * four verdict words every desk ends on: GOOD, BAD, QUIET, BLOCKED.
+   *
+   * `status` says whether the machine ran — a step crashed, a budget ran
+   * out. The verdict says what the agents found when it did. They are
+   * different facts: a publisher that checks, sees the wrong change in
+   * front of it and refuses to push has run perfectly, and its run is
+   * `completed`. Until this field, that run was a green tick beside a line
+   * reading BLOCKED (run-mu4sdg8z-1otr, 2026-09-17) — the one outcome a
+   * person most needed to see, drawn as success. Null: the summary does
+   * not lead with a verdict, and the run reads exactly as it always did.
+   */
+  verdict?: Verdict | null;
   /** The flow's per-run `budget:` at the time this run started, so the cap
    *  a run was held to is on its record rather than read from a file that
    *  may since have changed. Null: none. */
@@ -2430,6 +3269,26 @@ export interface RunRecord {
    *  the agents decided was worth remembering, listed so a person can review
    *  the lesson without diffing the folder. */
   memoryWrites?: string[];
+  /** Who asked for this run, when a person did: their email address. A
+   *  schedule, a webhook and a chained flow have no one, and leave it unset.
+   *  Kept so a gate can refuse the one approval nobody should be able to
+   *  give — your own. */
+  startedBy?: string | null;
+  /** When this run's gate stops waiting, stamped the moment it parks from
+   *  the flow's `approve_within:`. A gate nobody answers by then is rejected
+   *  and the run fails, rather than holding a concurrency slot forever. */
+  approveBy?: string | null;
+  /** A test run: every step runs for real, against the real files and the
+   *  real read APIs, but nothing outward happens — sends are refused or
+   *  sunk at the egress proxy, send-capable secrets never enter the
+   *  sandbox, and state/ and storage/ writes land under this run's own
+   *  directory. On the record, not in an env var, so a script cannot turn
+   *  it off; carried onto every rerun of this run. See test-mode.ts. */
+  test?: boolean;
+  /** Digests of the emailed approval links that have already decided a
+   *  step of this run — never the tokens. A link is good once; the second
+   *  click is a 409, not a second approval. Written by approvals.ts. */
+  approvalLinksUsed?: string[];
   steps: StepRecord[];
 }
 
@@ -2461,6 +3320,7 @@ export function deleteRun(tenant: string, workspace: string, runId: string): boo
     recursive: true,
     force: true,
   });
+  noteRunDeleted(path.dirname(file), runId);
   onRunDeleted?.(tenant, workspace, runId);
   return true;
 }
@@ -2535,6 +3395,7 @@ export function writeRun(tenant: string, workspace: string, run: RunRecord) {
   const tmp = `${p}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify(run, null, 2));
   fs.renameSync(tmp, p);
+  noteRunWritten(path.dirname(p), run, p);
 }
 
 // Every run in an account, each tagged with the workspace it belongs to —
@@ -2543,9 +3404,277 @@ export interface RunWithWorkspace extends RunRecord {
   workspace: string;
 }
 
+/**
+ * Every run in the account, newest first, off the per-workspace index.
+ *
+ * A finished run comes back as the index knows it: id, flow, status,
+ * summary, times, and each step's agent, group, status, cost, tokens,
+ * seconds, skip reason and last error — with `instruction` empty, `events`
+ * holding only that error, and `result` null. That is what every list and
+ * every rollup reads (runCost, runFailure, runDurationSecs, the usage
+ * window, the graph's stats). A run that is still live — queued, running,
+ * or parked at a gate — is read whole, because the gate's question and its
+ * events are what the approvals list shows. Anything wanting a finished
+ * run's reply or trace opens it with readRun.
+ *
+ * This used to parse every run file of every workspace on every call, and
+ * the dashboard calls it every twenty seconds per open tab.
+ */
 export function listAllRuns(tenant: string): RunWithWorkspace[] {
   return listWorkspaces(tenant)
-    .flatMap((p) => listRuns(tenant, p.name).map((r) => ({ ...r, workspace: p.name })))
+    .flatMap((p) =>
+      listRunSummaries(tenant, p.name).map((s) => {
+        const whole = LIVE_STATUSES.has(s.status) ? readRun(tenant, p.name, s.id) : null;
+        return { ...(whole ?? runFromSummary(s)), workspace: p.name };
+      }),
+    )
+    .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+
+// ------------------------------------------------------------ the run index
+//
+// runs/.index.json: one row per run with what a list needs — never a reply,
+// never a trace — kept up to date by writeRun and deleteRun, and repaired
+// from the directory by any reader that finds it missing or stale. Stale is
+// decided per file: a row remembers the mtime of the record it was made
+// from, and a record whose mtime moved (another process wrote it, a copy
+// restored it) is re-read on its own. So the index is never trusted over the
+// directory, and never costs more than the files that actually changed.
+//
+// Writers of one run are one process; two processes writing different runs
+// of a workspace can each save a copy that lacks the other's newest row,
+// and the next reader mends it by mtime. No lock beyond the atomic rename.
+
+/** What a list knows about one step. */
+export interface RunSummaryStep {
+  agent: string;
+  group: number;
+  status: StepRecord["status"];
+  costUsd: number | null;
+  tokens?: { input: number; output: number } | null;
+  computeSecs?: number | null;
+  skipReason?: string;
+  /** The last error event, for a failed step — what runFailure reads. */
+  error?: string;
+  item?: string;
+  waitFor?: "event";
+  ask?: string;
+  /** The step's instruction, kept for a parked step so the approvals banner can show the question without the record. */
+  instruction?: string;
+  /** When a parked step last spoke — the moment the banner sorts by. */
+  waitingSince?: string;
+  startedAt?: string;
+  finishedAt?: string;
+}
+
+/** What a list knows about one run. */
+export interface RunSummary {
+  id: string;
+  flow: string;
+  status: RunRecord["status"];
+  summary: string | null;
+  startedAt: string;
+  finishedAt: string | null;
+  stopRequested?: boolean;
+  test?: boolean;
+  budgetUsd?: number | null;
+  tags?: string[];
+  startedBy?: string | null;
+  parkedAt?: string | null;
+  /** A step is parked for a person — what the approvals banner counts. */
+  awaitingApproval: boolean;
+  steps: RunSummaryStep[];
+}
+
+interface RunIndexRow extends RunSummary {
+  /** mtime of the record this row was made from; a moved mtime means re-read. */
+  mtimeMs: number;
+}
+interface RunIndex {
+  v: 1;
+  runs: Record<string, RunIndexRow>;
+}
+
+const RUN_INDEX = ".index.json";
+const LIVE_STATUSES = new Set<RunRecord["status"]>(["queued", "running", "awaiting-approval"]);
+
+/** One run's row. */
+export function summarizeRun(run: RunRecord): RunSummary {
+  return {
+    id: run.id,
+    flow: run.flow,
+    status: run.status,
+    summary: run.summary ?? null,
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt ?? null,
+    ...(run.stopRequested ? { stopRequested: true } : {}),
+    ...(run.test ? { test: true } : {}),
+    ...(run.budgetUsd !== undefined ? { budgetUsd: run.budgetUsd } : {}),
+    ...(run.tags?.length ? { tags: run.tags } : {}),
+    ...(run.startedBy ? { startedBy: run.startedBy } : {}),
+    ...(run.parkedAt ? { parkedAt: run.parkedAt } : {}),
+    awaitingApproval: run.steps.some((s) => s.status === "awaiting-approval" && s.waitFor !== "event"),
+    steps: run.steps.map((s) => {
+      const error = s.status === "failed" ? s.events.filter((e) => e.type === "error").at(-1)?.text : undefined;
+      return {
+        agent: s.agent,
+        group: s.group,
+        status: s.status,
+        costUsd: s.costUsd,
+        ...(s.tokens !== undefined ? { tokens: s.tokens } : {}),
+        ...(s.computeSecs !== undefined ? { computeSecs: s.computeSecs } : {}),
+        ...(s.skipReason ? { skipReason: s.skipReason } : {}),
+        ...(error ? { error: error.slice(0, 500) } : {}),
+        ...(s.item ? { item: s.item } : {}),
+        ...(s.waitFor ? { waitFor: s.waitFor } : {}),
+        ...(s.ask ? { ask: s.ask } : {}),
+        ...(s.status === "awaiting-approval" ? { instruction: s.instruction, waitingSince: s.events.at(-1)?.t ?? run.startedAt } : {}),
+        ...(s.startedAt ? { startedAt: s.startedAt } : {}),
+        ...(s.finishedAt ? { finishedAt: s.finishedAt } : {}),
+      };
+    }),
+  };
+}
+
+/** A RunRecord with the shape a list reads and nothing else — see listAllRuns. */
+export function runFromSummary(s: RunSummary): RunRecord {
+  const { awaitingApproval: _awaiting, ...run } = s;
+  return {
+    ...run,
+    steps: s.steps.map((st) => {
+      const { error, ...rest } = st;
+      return {
+        ...rest,
+        instruction: "",
+        optional: false,
+        events: error ? [{ t: st.finishedAt ?? s.finishedAt ?? s.startedAt, type: "error" as const, text: error }] : [],
+        result: null,
+      };
+    }),
+  };
+}
+
+const runIndexCache = new Map<string, { index: RunIndex; mtimeMs: number }>();
+
+function readRunIndex(dir: string): RunIndex | null {
+  const file = path.join(dir, RUN_INDEX);
+  let mtimeMs: number;
+  try {
+    mtimeMs = fs.statSync(file).mtimeMs;
+  } catch {
+    runIndexCache.delete(dir);
+    return null;
+  }
+  const cached = runIndexCache.get(dir);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.index;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as RunIndex;
+    if (parsed?.v !== 1 || typeof parsed.runs !== "object" || !parsed.runs) return null;
+    runIndexCache.set(dir, { index: parsed, mtimeMs });
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeRunIndex(dir: string, index: RunIndex) {
+  const file = path.join(dir, RUN_INDEX);
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(index));
+  fs.renameSync(tmp, file);
+  try {
+    runIndexCache.set(dir, { index, mtimeMs: fs.statSync(file).mtimeMs });
+  } catch {
+    runIndexCache.delete(dir);
+  }
+}
+
+const sameRow = (a: RunIndexRow | undefined, b: RunSummary) =>
+  !!a && JSON.stringify({ ...a, mtimeMs: 0 }) === JSON.stringify({ ...b, mtimeMs: 0 });
+
+/** writeRun just saved `run` at `file`: bring its row up to date. The file
+ *  is rewritten only when the row's content moved — a live step appends an
+ *  event several times a second, and the row does not change for that;
+ *  the mtime it remembers goes stale instead, and a reader re-reads that
+ *  one record, which is the cheap and correct thing. */
+function noteRunWritten(dir: string, run: RunRecord, file: string) {
+  try {
+    const index = readRunIndex(dir);
+    if (!index) return; // no index yet — the first reader builds it whole
+    const row = summarizeRun(run);
+    if (sameRow(index.runs[run.id], row)) return;
+    index.runs[run.id] = { ...row, mtimeMs: fs.statSync(file).mtimeMs };
+    writeRunIndex(dir, index);
+  } catch {
+    // the index is a cache; the record is the truth and it is already on disk
+  }
+}
+
+function noteRunDeleted(dir: string, runId: string) {
+  try {
+    const index = readRunIndex(dir);
+    if (!index || !(runId in index.runs)) return;
+    delete index.runs[runId];
+    writeRunIndex(dir, index);
+  } catch {
+    // ditto
+  }
+}
+
+/**
+ * The workspace's runs as the index knows them, newest first — the call a
+ * list makes. Reconciled against the directory on every read: rows for
+ * records that are gone are dropped, records with no row or a moved mtime
+ * are re-read, and the index is rewritten if anything changed. A missing
+ * or unreadable index is a full scan that leaves one behind.
+ */
+export function listRunSummaries(tenant: string, workspace: string): RunSummary[] {
+  const dir = path.join(workspaceDir(tenant, workspace), "runs");
+  if (!fs.existsSync(dir)) return [];
+  const index: RunIndex = readRunIndex(dir) ?? { v: 1, runs: {} };
+  const present = new Set<string>();
+  let changed = false;
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".json") || f.startsWith(".")) continue;
+    const id = f.slice(0, -".json".length);
+    present.add(id);
+    let mtimeMs: number;
+    try {
+      mtimeMs = fs.statSync(path.join(dir, f)).mtimeMs;
+    } catch {
+      continue; // pruned between the listing and the stat
+    }
+    const row = index.runs[id];
+    if (row && row.mtimeMs === mtimeMs) continue;
+    try {
+      const run = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")) as RunRecord;
+      index.runs[id] = { ...summarizeRun(run), mtimeMs };
+      changed = true;
+    } catch {
+      // a torn or foreign file is not a run; leave whatever row it had
+    }
+  }
+  for (const id of Object.keys(index.runs)) {
+    if (present.has(id)) continue;
+    delete index.runs[id];
+    changed = true;
+  }
+  if (changed) {
+    try {
+      writeRunIndex(dir, index);
+    } catch {
+      // a read-only or racing directory still gets its answer
+    }
+  }
+  return Object.values(index.runs)
+    .map(({ mtimeMs: _m, ...row }) => row)
+    .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+
+/** Every workspace's runs as summaries, tagged with the workspace. */
+export function listAllRunSummaries(tenant: string): (RunSummary & { workspace: string })[] {
+  return listWorkspaces(tenant)
+    .flatMap((p) => listRunSummaries(tenant, p.name).map((s) => ({ ...s, workspace: p.name })))
     .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }
 
@@ -2662,6 +3791,28 @@ export function runFailure(run: RunRecord): { agent: string; reason: string } |
  * runFailure, which puts the reason for a failure on the list for the same
  * reason — the sentence was in the record all along.
  */
+export const VERDICTS = ["GOOD", "BAD", "QUIET", "BLOCKED"] as const;
+export type Verdict = (typeof VERDICTS)[number];
+
+/**
+ * The verdict a headline leads with, or null. Leading, whole-word and
+ * upper-case only — "GOOD — 6 links applied", "**BLOCKED**: nothing
+ * pushed", "BAD: 3 pages dropped". A summary that merely contains the word
+ * ("no BLOCKED items") has no verdict, for the reason markerPresent gives.
+ */
+export function verdictOf(summary: string | null | undefined): Verdict | null {
+  if (!summary) return null;
+  const line = summary.replace(/^[\s#>*_`\-]+/, "");
+  const m = /^(GOOD|BAD|QUIET|BLOCKED)(?![A-Za-z0-9_])/.exec(line);
+  return m ? (m[1] as Verdict) : null;
+}
+
+/** A run's verdict: recorded when it finished, else read from its summary,
+ *  so runs from before the field existed show one too. */
+export function runVerdict(run: Pick<RunRecord, "verdict" | "summary">): Verdict | null {
+  return run.verdict !== undefined ? run.verdict : verdictOf(run.summary);
+}
+
 export function runSummary(run: RunRecord): string | null {
   for (let i = run.steps.length - 1; i >= 0; i--) {
     const line = stepHeadline(run.steps[i]);
@@ -2775,12 +3926,14 @@ export function listAgentSteps(tenant: string, workspace: string, agent: string)
   return out;
 }
 
+/** Every run of the workspace, whole, newest first. Parses every record;
+ *  a list that needs only what a list needs reads listRunSummaries. */
 export function listRuns(tenant: string, workspace: string): RunRecord[] {
   const dir = path.join(workspaceDir(tenant, workspace), "runs");
   if (!fs.existsSync(dir)) return [];
   return fs
     .readdirSync(dir)
-    .filter((f) => f.endsWith(".json"))
+    .filter((f) => f.endsWith(".json") && !f.startsWith("."))
     .map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")) as RunRecord)
     .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }