@foldrun/core 0.3.0 → 0.5.0

package/dist/src/store.js

@@ -22,8 +22,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
-import { dataRoot, singleWorkspace } from "./paths.js";
+import { dataRoot, singleWorkspace, singleAccountRoot, entriesNoFollow } from "./paths.js";
 import { platform } from "./platform.js";
+import { toLF, asRaw } from "./eol.js";
 import matter from "gray-matter";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
@@ -37,12 +38,20 @@ import matter from "gray-matter";
 export function readFrontmatter(file) {
     return matter(fs.readFileSync(file, "utf8")).data;
 }
-import { ownToolNames, legacyUseNames } from "./tool-names.js";
+import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.js";
 import { refNames } from "./refs.js";
+import { parseBudget, budgetProblem } from "./budget.js";
+import { timezoneProblem } from "./clock.js";
+import { parseStepLimits, readLimits } from "./limits.js";
+import { webProblems, webWarnings, runnerEngines } from "./providers.js";
+import { actionProblems } from "./web-actions.js";
+import { languageProblem } from "./language.js";
+import { localeProblems } from "./locale.js";
 import { readBundle, syncIndex, appendLog, provenanceMarks, syncWorkspaceBundles, } from "./okf.js";
 import { readTransport, KINDS } from "./kinds.js";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS } from "./providers.js";
 import { starterFiles, accountFiles } from "./starter.js";
+import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.js";
 // 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.
 /**
@@ -175,14 +184,15 @@ export function workspaceDir(tenant, workspace) {
  * 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) {
     const single = singleWorkspace();
     if (single)
-        return path.resolve(single, "..");
+        return singleAccountRoot();
     assertSafeName(tenant, "tenant");
     return path.join(dataRoot(), tenant);
 }
@@ -275,14 +285,37 @@ export function assertCanonicalCase(rel) {
  * 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) {
     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, shipped) {
+    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, workspace, files, 
 /** Attribution for the revision this save records. A deploy passes the
  *  commit, which becomes the revision's id. */
@@ -334,15 +367,7 @@ meta = {}) {
     // 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) => 
-    // 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) => keptOnDeploy(rel, shipped);
     // What is there now, for the revision: every editable file's content
     // before this save replaces the tree.
     const before = new Map();
@@ -359,7 +384,7 @@ meta = {}) {
     const snapshot = fs.existsSync(dir) ? fs.mkdtempSync(path.join(dataRoot(), ".keep-")) : null;
     const preserved = [];
     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 {
@@ -513,6 +538,15 @@ export function fencedCodeBlock(body) {
     }
     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) {
+    return data.outward === true;
+}
 export function parseToolDef(data, fallbackName, body) {
     const name = typeof data.name === "string" ? data.name : fallbackName;
     // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -580,6 +614,81 @@ export function parseToolDef(data, fallbackName, body) {
  *
  * 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) {
+    const out = {};
+    const req = path.join(folder, "requirements.txt");
+    if (fs.existsSync(req)) {
+        const packages = [];
+        const ignored = new Set();
+        // 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")).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, extra) {
+    const base = own && typeof own === "object" && !Array.isArray(own) ? { ...own } : {};
+    const list = (v) => (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, scope = "workspace") {
     if (!fs.existsSync(dir))
         return {};
@@ -606,9 +715,19 @@ function readToolDir(dir, scope = "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);
+            // `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] = 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`);
         }
@@ -836,7 +955,7 @@ export function parseApis(raw) {
         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),
@@ -888,6 +1007,40 @@ export function agentAssets(tenant, workspace, agent) {
     }
     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) {
+    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) {
+    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) {
+    const out = [];
+    if (Array.isArray(data.apis)) {
+        for (const a of data.apis)
+            if (a && typeof a === "object" && typeof a.name === "string")
+                out.push(a.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.name === "string")
+                out.push(sc.name);
+        }
+    }
+    if (data.mcpServers && typeof data.mcpServers === "object")
+        out.push(...Object.keys(data.mcpServers));
+    return out;
+}
 export function listAgents(tenant, workspace) {
     const dir = path.join(workspaceDir(tenant, workspace), "agents");
     if (!fs.existsSync(dir))
@@ -908,25 +1061,90 @@ export function listAgents(tenant, workspace) {
             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) {
+    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) {
     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()];
     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) {
+    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, min, max) {
+    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
  *  null for anything that is not one — a `once` flow with an unreadable
@@ -945,7 +1163,7 @@ export function parseInstant(raw) {
  * 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
@@ -964,15 +1182,111 @@ export function unquote(raw) {
     const inner = value.slice(1, -1);
     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) {
+    const m = when.trim().match(/^rows\s+of\s+(\S.*)$/i);
+    return m ? m[1].trim() : null;
+}
+export function markerPresent(text, marker) {
+    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, raw) {
+    // 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 = [];
+    // Flow-level problems: a malformed step target (below) and unreadable
+    // frontmatter enums (before the return). Reported as errors by flow-lint.
+    const frontProblems = [];
     // 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 = null;
+    // The step still accepting wrapped instruction lines, or null once
+    // anything has closed it. See the continuation rule below.
+    let open = 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({
@@ -986,14 +1300,61 @@ export function parseFlow(file, raw) {
                 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) => (step.problems ??= []).push(`${key}: ${value} — ${text}`);
             if (key === "approve")
                 step.approve = value !== "false";
             else if (key === "when")
@@ -1002,20 +1363,38 @@ export function parseFlow(file, raw) {
                 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") {
@@ -1025,30 +1404,92 @@ export function parseFlow(file, raw) {
                     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
+                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, val, allowed) => {
+        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$/, ""),
@@ -1059,12 +1500,14 @@ export function parseFlow(file, raw) {
         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,
@@ -1075,9 +1518,84 @@ export function parseFlow(file, raw) {
             ? 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) {
+    let value;
+    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 };
+}
+function idempotencyName(raw) {
+    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) {
+    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) {
+    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, who) {
+    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, workspace, flowName) {
     return listRuns(tenant, workspace).some((r) => r.flow === flowName && (r.status === "running" || r.status === "queued" || r.status === "awaiting-approval"));
@@ -1129,7 +1647,7 @@ function emitFlow(head, preamble, groups) {
  * 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(raw, opts) {
+function setFlowTriggerLF(raw, opts) {
     if (!FLOW_TRIGGERS.includes(opts.trigger)) {
         throw new Error(`unknown trigger "${opts.trigger}" — one of ${FLOW_TRIGGERS.join(", ")}`);
     }
@@ -1185,7 +1703,7 @@ export function setFlowTrigger(raw, opts) {
  * 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, index, instruction) {
+function updateFlowStepInstructionLF(raw, index, instruction) {
     const { head, preamble, blocks } = splitFlowBlocks(raw);
     if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
         throw new Error(`no step ${index}`);
@@ -1196,9 +1714,9 @@ export function updateFlowStepInstruction(raw, index, instruction) {
     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 = [];
@@ -1211,7 +1729,7 @@ export function updateFlowStepInstruction(raw, index, instruction) {
     }
     return emitFlow(head, preamble, groups);
 }
-export function updateFlowStep(raw, index, options) {
+function updateFlowStepLF(raw, index, options) {
     const { head, preamble, blocks } = splitFlowBlocks(raw);
     if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
         throw new Error(`no step ${index}`);
@@ -1229,11 +1747,22 @@ export function updateFlowStep(raw, index, options) {
         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 = [];
@@ -1257,7 +1786,7 @@ export function updateFlowStep(raw, index, options) {
     }
     return emitFlow(head, preamble, groups);
 }
-export function reorderFlowSteps(raw, groups) {
+function reorderFlowStepsLF(raw, groups) {
     const { head, preamble, blocks: ordered } = splitFlowBlocks(raw);
     const seen = new Set();
     for (const group of groups) {
@@ -1277,7 +1806,7 @@ export function reorderFlowSteps(raw, groups) {
     return emitFlow(head, preamble, groups.map((g) => g.map((i) => ordered[i])));
 }
 /** Append a step as its own group at the end of the flow. */
-export function addFlowStep(raw, step) {
+function addFlowStepLF(raw, step) {
     assertSafeName(step.target, "step target");
     const { head, preamble, blocks } = splitFlowBlocks(raw);
     const instruction = (step.instruction ?? "").replace(/[\r\n]+/g, " ").trim();
@@ -1289,7 +1818,7 @@ export function addFlowStep(raw, step) {
     return emitFlow(head, preamble, groups);
 }
 /** Drop one step, by its index in the flow's parsed steps. */
-export function removeFlowStep(raw, index) {
+function removeFlowStepLF(raw, index) {
     const { head, preamble, blocks } = splitFlowBlocks(raw);
     if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
         throw new Error(`no step ${index}`);
@@ -1297,6 +1826,14 @@ export function removeFlowStep(raw, index) {
     const kept = blocks.filter((_, i) => i !== index);
     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, opts) => asRaw(raw, setFlowTriggerLF(toLF(raw), opts));
+export const updateFlowStepInstruction = (raw, index, instruction) => asRaw(raw, updateFlowStepInstructionLF(toLF(raw), index, instruction));
+export const updateFlowStep = (raw, index, options) => asRaw(raw, updateFlowStepLF(toLF(raw), index, options));
+export const reorderFlowSteps = (raw, groups) => asRaw(raw, reorderFlowStepsLF(toLF(raw), groups));
+export const addFlowStep = (raw, step) => asRaw(raw, addFlowStepLF(toLF(raw), step));
+export const removeFlowStep = (raw, index) => asRaw(raw, removeFlowStepLF(toLF(raw), index));
 /** Blocks → the group structure they currently describe. */
 function groupBlocks(blocks) {
     const map = new Map();
@@ -1314,6 +1851,20 @@ export function listFlows(tenant, workspace) {
         .sort()
         .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, workspace, flowName) {
+    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;
+}
 /**
  * Every account this installation holds.
  *
@@ -1391,7 +1942,7 @@ export function listWorkspaces(tenant) {
             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 } : {}),
         };
     })
@@ -1400,7 +1951,10 @@ export function listWorkspaces(tenant) {
 // ---------- file management (dashboard editing) ----------
 // 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?
  *
@@ -1446,17 +2000,29 @@ function assertEditablePath(rel) {
  *  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 = {
+    "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) {
     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)) {
@@ -1469,7 +2035,7 @@ export function accountFileSealed(rel) {
  *  function is to refuse the person who clicked them, which is noise wearing
  *  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$/;
+const ACCOUNT_BOOKKEEPING = /^(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.
  *
@@ -1547,7 +2113,7 @@ export function listWorkspaceFiles(tenant, workspace) {
     if (!fs.existsSync(dir))
         return [];
     const out = [];
-    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;
@@ -1586,7 +2152,9 @@ export function readWorkspaceFile(tenant, workspace, rel) {
     return fs.readFileSync(p, "utf8");
 }
 export function writeWorkspaceFile(tenant, workspace, rel, content, meta = {}) {
-    if (content.length > 256 * 1024)
+    // 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));
@@ -1601,7 +2169,7 @@ export function writeWorkspaceFile(tenant, workspace, rel, content, meta = {}) {
     // 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".
@@ -1765,9 +2333,11 @@ export function deleteWorkspacePath(tenant, workspace, rel, meta = {}) {
     }
     // 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 });
@@ -1914,6 +2484,19 @@ export function flowPatternTemplate(pattern, name, agents) {
             return FLOW_TEMPLATE(name, a(0, "my-agent"));
     }
 }
+/** 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) {
+    const costs = tries.map((t) => t.costUsd).filter((c) => typeof c === "number");
+    const toks = tries.map((t) => t.tokens).filter((t) => !!t);
+    const secs = tries.map((t) => t.computeSecs).filter((c) => 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 function runFilePath(tenant, workspace, runId) {
     assertSafeName(runId, "run id");
     return path.join(workspaceDir(tenant, workspace), "runs", `${runId}.json`);
@@ -1942,6 +2525,7 @@ export function deleteRun(tenant, workspace, runId) {
         recursive: true,
         force: true,
     });
+    noteRunDeleted(path.dirname(file), runId);
     onRunDeleted?.(tenant, workspace, runId);
     return true;
 }
@@ -2005,10 +2589,218 @@ export function writeRun(tenant, workspace, run) {
     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 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) {
     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));
+}
+const RUN_INDEX = ".index.json";
+const LIVE_STATUSES = new Set(["queued", "running", "awaiting-approval"]);
+/** One run's row. */
+export function summarizeRun(run) {
+    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) {
+    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", text: error }] : [],
+                result: null,
+            };
+        }),
+    };
+}
+const runIndexCache = new Map();
+function readRunIndex(dir) {
+    const file = path.join(dir, RUN_INDEX);
+    let mtimeMs;
+    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"));
+        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, index) {
+    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, b) => !!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, run, file) {
+    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, runId) {
+    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, workspace) {
+    const dir = path.join(workspaceDir(tenant, workspace), "runs");
+    if (!fs.existsSync(dir))
+        return [];
+    const index = readRunIndex(dir) ?? { v: 1, runs: {} };
+    const present = new Set();
+    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;
+        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"));
+            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) {
+    return listWorkspaces(tenant)
+        .flatMap((p) => listRunSummaries(tenant, p.name).map((s) => ({ ...s, workspace: p.name })))
         .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }
 /**
@@ -2115,6 +2907,25 @@ export function runFailure(run) {
  * 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"];
+/**
+ * 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) {
+    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] : 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) {
+    return run.verdict !== undefined ? run.verdict : verdictOf(run.summary);
+}
 export function runSummary(run) {
     for (let i = run.steps.length - 1; i >= 0; i--) {
         const line = stepHeadline(run.steps[i]);
@@ -2210,13 +3021,15 @@ export function listAgentSteps(tenant, workspace, agent) {
     }
     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, workspace) {
     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")))
         .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }