@foldrun/core 0.2.0 → 0.4.0

package/dist/src/store.js

@@ -23,6 +23,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
 import { dataRoot, singleWorkspace } from "./paths.js";
+import { platform } from "./platform.js";
 import matter from "gray-matter";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
@@ -38,10 +39,12 @@ export function readFrontmatter(file) {
 }
 import { ownToolNames, legacyUseNames } from "./tool-names.js";
 import { refNames } from "./refs.js";
+import { parseBudget, budgetProblem } from "./budget.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 } 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.
 /**
@@ -413,6 +416,12 @@ meta = {}) {
     // them are not bundles until their index.md exists to carry okf_version. A
     // 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 };
 }
 // The prompt-facing index for an OKF bundle (memory/ or knowledge/).
@@ -829,7 +838,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),
@@ -881,6 +890,12 @@ export function agentAssets(tenant, workspace, agent) {
     }
     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) {
+    const b = parseBudget(raw, "run");
+    return b && b.period === "run" ? b.usd : null;
+}
 export function listAgents(tenant, workspace) {
     const dir = path.join(workspaceDir(tenant, workspace), "agents");
     if (!fs.existsSync(dir))
@@ -904,22 +919,71 @@ export function listAgents(tenant, workspace) {
             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) {
+    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
@@ -957,6 +1021,48 @@ 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.
+ */
+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) {
     const { data, content } = matter(raw);
     const steps = [];
@@ -964,8 +1070,42 @@ export function parseFlow(file, raw) {
     // 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;
+    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({
@@ -981,12 +1121,33 @@ export function parseFlow(file, raw) {
             });
             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) => (step.problems ??= []).push(`${key}: ${value} — ${text}`);
             if (key === "approve")
                 step.approve = value !== "false";
             else if (key === "when")
@@ -995,20 +1156,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") {
@@ -1020,15 +1199,22 @@ export function parseFlow(file, raw) {
                     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
+                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;
@@ -1038,10 +1224,44 @@ export function parseFlow(file, raw) {
             }
             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$/, ""),
@@ -1052,7 +1272,10 @@ export function parseFlow(file, raw) {
         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,
@@ -1067,9 +1290,79 @@ 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,
+        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) {
+    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"));
@@ -1188,9 +1481,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 = [];
@@ -1225,7 +1518,7 @@ export function updateFlowStep(raw, index, options) {
     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 = [];
@@ -1306,6 +1599,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.
  *
@@ -1383,7 +1690,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 } : {}),
         };
     })
@@ -1392,7 +1699,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?
  *
@@ -1593,7 +1903,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".
@@ -1606,7 +1916,18 @@ export function writeWorkspaceFile(tenant, workspace, rel, content, meta = {}) {
     // 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, workspace, why) {
+    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.
@@ -1697,6 +2018,7 @@ export function renameWorkspaceFile(tenant, workspace, from, to, meta = {}) {
     ], { message: `renamed ${from} → ${to}`, ...meta });
     syncBundleFor(src);
     syncBundleFor(dst, "Update");
+    workspaceChanged(tenant, workspace, "write");
 }
 /** Every text file under a path, as revision entries recording deletion. */
 function deletionsUnder(dir, norm) {
@@ -1759,12 +2081,14 @@ export function deleteWorkspacePath(tenant, workspace, rel, meta = {}) {
     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, workspace) {
     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");
 }
 /**
  * What a rename would break, so the caller can say so before doing it.
@@ -1892,6 +2216,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`);
@@ -1920,6 +2257,7 @@ export function deleteRun(tenant, workspace, runId) {
         recursive: true,
         force: true,
     });
+    noteRunDeleted(path.dirname(file), runId);
     onRunDeleted?.(tenant, workspace, runId);
     return true;
 }
@@ -1983,10 +2321,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));
 }
 /**
@@ -2188,13 +2734,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));
 }