@foldrun/core 0.2.0 → 0.4.0

package/src/store.ts

@@ -24,6 +24,8 @@ 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 { platform } from "./platform.ts";
+import type { TestEffect } from "./test-mode.ts";
 import matter from "gray-matter";
 
 /**
@@ -40,12 +42,14 @@ export function readFrontmatter(file: string): Record<string, unknown> {
 }
 import { ownToolNames, legacyUseNames } from "./tool-names.ts";
 import { refNames } from "./refs.ts";
+import { parseBudget, budgetProblem } from "./budget.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 } 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.
@@ -452,6 +456,13 @@ export function saveWorkspace(
   // deploy writes straight to disk, so nothing else would generate them.
   syncWorkspaceBundles(dir);
 
+  // Here, not in deployWorkspace: a workspace CREATED with files (the API's
+  // create, the CLI's first deploy, a template) comes through this function
+  // without going through deployWorkspace, and the first live check found
+  // exactly that — a new desk's cron was seen on the five-minute rescan, not
+  // the next tick.
+  workspaceChanged(tenant, workspace, "deploy");
+
   return { preserved: preserved.length };
 }
 
@@ -781,6 +792,12 @@ export interface AgentInfo {
    *  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;
 }
 
 // Recognised HTTP verbs a tool may declare. Deliberately NOT named
@@ -966,7 +983,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),
@@ -995,11 +1012,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. */
@@ -1061,9 +1081,29 @@ 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;
   /** 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 {
@@ -1083,12 +1123,20 @@ export interface FlowInfo {
    *  overlap) — a default that changed underfoot would surprise every flow
    *  that legitimately runs in parallel. */
   overlap: "skip" | "queue" | null;
+  /** Where this flow's runs stand in the queue against everyone else's:
+   *  "high" is claimed before the round-robin, "low" after it. Adds to the
+   *  account's own priority; the account's cap still bounds how many run
+   *  at once, so a high lane never starves the rest outright. Unset is
+   *  normal — first come, fair across accounts. */
+  priority: "high" | "normal" | "low" | null;
   /** The most one run of this flow may spend, in USD. A literal, never an
    *  expression — the cap is readable off the file, which is the property
    *  the whole grammar exists to keep. Checked between groups: the group
    *  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. */
@@ -1111,6 +1159,67 @@ 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;
+  /** `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;
+
   steps: FlowStep[];
 }
 
@@ -1161,6 +1270,13 @@ export function agentAssets(tenant: string, workspace: string, agent: string): A
   return { skills, memory };
 }
 
+/** 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;
+}
+
 export function listAgents(tenant: string, workspace: string): AgentInfo[] {
   const dir = path.join(workspaceDir(tenant, workspace), "agents");
   if (!fs.existsSync(dir)) return [];
@@ -1183,24 +1299,77 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
         consults: refNames(data.agents),
         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"]),
       };
     });
 }
 
 // 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", "loop", "max", "max_turns", "model",
+  "on-fail", "onfail", "output", "parallel", "preview", "retry", "schema", "timeout", "until", "verify", "wait", "when",
+]);
+
+/** 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
@@ -1239,6 +1408,46 @@ 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.
+ */
+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 {
   const { data, content } = matter(raw);
   const steps: FlowStep[] = [];
@@ -1246,8 +1455,38 @@ export function parseFlow(file: string, raw: string): FlowInfo {
   // 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;
+  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({
@@ -1263,23 +1502,60 @@ export function parseFlow(file: string, raw: string): FlowInfo {
       });
       continue;
     }
-    // Indented options belong to the step above them.
+    // An indented line that is not an option continues the instruction.
+    //
+    // Without this it was silently DROPPED. An instruction wrapped over
+    // three lines kept the first and discarded the rest, the run went
+    // green, and the agent worked from an instruction its author had not
+    // written — the worst failure this parser can have, because nothing
+    // anywhere reports it. Twenty-five live instructions across eight desks
+    // were being cut this way.
+    //
+    // Indentation is what makes it a continuation, exactly as it is for an
+    // option. Unindented prose between steps is still prose and still
+    // ignored, so a flow file's commentary is undisturbed.
     const opt = line.match(OPTION_RE);
+    if (steps.length && /^\s+\S/.test(line) && !(opt && STEP_OPTION_KEYS.has(opt[2]))) {
+      const step = steps[steps.length - 1];
+      step.instruction = `${step.instruction} ${line.trim()}`.trim();
+      continue;
+    }
+    // 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";
@@ -1288,21 +1564,51 @@ export function parseFlow(file: string, raw: string): FlowInfo {
           step.each = "rows";
           // "rows of ../../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 ../../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);
       }
       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 === "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();
   steps.sort((a, b) => a.group - b.group);
   return {
     name: data.name ?? file.replace(/\.md$/, ""),
@@ -1313,7 +1619,10 @@ 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,
-    budget: Number(data.budget) > 0 ? Number(data.budget) : null,
+    live: data.live === true,
+    priority: data.priority === "high" || data.priority === "low" || data.priority === "normal" ? data.priority : 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,
@@ -1329,10 +1638,81 @@ 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,
+    sla: durationOf(data.sla),
+    approvers: approverList(data.approvers),
+    approveWithin: durationOf(data.approve_within),
     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(
@@ -1468,9 +1848,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[][] = [];
@@ -1510,7 +1890,7 @@ export function updateFlowStep(
   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[] = [];
@@ -1593,6 +1973,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;
@@ -1676,7 +2069,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 } : {}),
       };
     })
@@ -1687,7 +2080,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?
@@ -1882,7 +2278,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".
@@ -1895,8 +2291,19 @@ export function writeWorkspaceFile(
   // The revision: what it was, what it is now. Identical content records
   // nothing — see history.ts.
   recordRevision(tenant, workspace, [{ path: norm, before, after: fs.readFileSync(p, "utf8") }], meta);
+  workspaceChanged(tenant, workspace, "write");
 }
 
+/** Tell the platform, and never let its listener fail a write. */
+function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete") {
+  try {
+    platform.workspaceChanged(tenant, workspace, why);
+  } catch {
+    // a scheduler that could not be told will find out on its next rescan
+  }
+}
+export { workspaceChanged as notifyWorkspaceChanged };
+
 // memory/ and knowledge/ are OKF bundles, so index.md has to stay current —
 // a generated index that drifts is the same class of bug as a memory index
 // naming files that don't exist.
@@ -1990,6 +2397,7 @@ export function renameWorkspaceFile(tenant: string, workspace: string, from: str
   );
   syncBundleFor(src);
   syncBundleFor(dst, "Update");
+  workspaceChanged(tenant, workspace, "write");
 }
 
 /** Every text file under a path, as revision entries recording deletion. */
@@ -2051,12 +2459,14 @@ export function deleteWorkspacePath(tenant: string, workspace: string, rel: stri
   recordRevision(tenant, workspace, gone, meta);
   // A bundle's index must stop naming what is gone.
   syncBundleFor(p);
+  workspaceChanged(tenant, workspace, "write");
 }
 
 export function deleteWorkspace(tenant: string, workspace: string) {
   const dir = workspaceDir(tenant, workspace);
   if (!fs.existsSync(dir)) throw new Error(`workspace ${workspace} not found`);
   fs.rmSync(dir, { recursive: true, force: true });
+  workspaceChanged(tenant, workspace, "delete");
 }
 
 /**
@@ -2214,6 +2624,39 @@ 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;
+}
+
+/** One attempt of a step — see StepRecord.tries. */
+export interface StepAttempt {
+  /** Which attempt, 1-based: `attempts` on the step at the time. */
+  n: number;
+  status: "completed" | "failed";
+  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 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 {
@@ -2235,6 +2678,27 @@ 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
+   *  run — after a deploy rolled the last one, or it crashed — needs to
+   *  re-attach and carry on rather than run the step again. Cleared when
+   *  the step settles. */
+  sandbox?: { kind: string; ref: string; consumed: number; since: string } | null;
+  /** 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";
   /** 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
@@ -2257,6 +2721,10 @@ export interface StepRecord {
   max?: number;
   /** Carried from the flow — see FlowStep. */
   output?: "json";
+  schema?: Record<string, unknown> | boolean;
+  schemaPath?: string;
+  parallel?: number;
+  maxTurns?: 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. */
@@ -2391,6 +2859,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[];
 }
 
@@ -2422,6 +2910,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;
 }
@@ -2496,6 +2985,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 —
@@ -2504,9 +2994,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));
 }
 
@@ -2736,12 +3494,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));
 }