@foldrun/core 0.4.0 → 0.6.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,14 +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 } from "./paths.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.
 /**
@@ -177,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);
 }
@@ -277,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. */
@@ -336,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();
@@ -361,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 {
@@ -460,7 +483,7 @@ export function buildMemoryIndex(dir, prefix = "") {
 // Workspace-scoped shared assets: skills/, memory/, tools/ sit beside agents/
 // and are available to every agent in that workspace.
 export function workspaceMemoryIndex(tenant, workspace) {
-    return buildMemoryIndex(path.join(workspaceDir(tenant, workspace), "memory"), "../../memory/");
+    return buildMemoryIndex(path.join(workspaceDir(tenant, workspace), "memory"), "workspace/memory/");
 }
 // Knowledge is what you *gave* an agent — stable reference material an agent
 // reads and never rewrites. Memory is what it *learned* and authors itself.
@@ -470,7 +493,7 @@ export function knowledgeIndex(dir, prefix = "") {
     return buildMemoryIndex(dir, prefix);
 }
 export function workspaceKnowledgeIndex(tenant, workspace) {
-    return knowledgeIndex(path.join(workspaceDir(tenant, workspace), "knowledge"), "../../knowledge/");
+    return knowledgeIndex(path.join(workspaceDir(tenant, workspace), "knowledge"), "workspace/knowledge/");
 }
 // One noun for capability. A tools/<name>.md file declares either an HTTP
 // endpoint or a script — `type:` says which, and it's inferred when omitted
@@ -515,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
@@ -582,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 {};
@@ -608,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`);
         }
@@ -890,12 +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))
@@ -916,11 +1061,22 @@ 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),
         };
     });
 }
@@ -941,9 +1097,14 @@ const OPTION_RE = /^(\s+)([a-z_-]+):(.*)$/;
  *  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",
+    "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;
@@ -1002,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
@@ -1043,6 +1204,16 @@ export function unquote(raw) {
  * 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)
@@ -1064,8 +1235,15 @@ export function markerPresent(text, marker) {
     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;
@@ -1075,6 +1253,9 @@ export function parseFlow(file, raw) {
     // 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;
@@ -1119,26 +1300,52 @@ export function parseFlow(file, raw) {
                 instruction: m[5].trim(),
                 line: lineNo + offset,
             });
+            open = steps[steps.length - 1];
             continue;
         }
-        // An indented line that is not an option continues the instruction.
+        // 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".
         //
-        // 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.
+        // 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.
         //
-        // 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.
+        // 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);
-        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;
+        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];
@@ -1197,10 +1404,10 @@ 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 ../../storage/leads.csv");
+                        problem("rows needs a file: each: rows of workspace/storage/leads.csv");
                 }
                 else
                     problem("lines, items, or rows of <path>");
@@ -1220,7 +1427,7 @@ export function parseFlow(file, raw) {
                 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);
@@ -1244,6 +1451,13 @@ export function parseFlow(file, raw) {
                 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: [] };
@@ -1262,6 +1476,20 @@ export function parseFlow(file, raw) {
         }
     }
     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$/, ""),
@@ -1279,7 +1507,7 @@ export function parseFlow(file, raw) {
         // `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,
@@ -1300,9 +1528,14 @@ export function parseFlow(file, raw) {
         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,
     };
 }
@@ -1414,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(", ")}`);
     }
@@ -1470,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}`);
@@ -1496,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}`);
@@ -1514,6 +1747,17 @@ 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));
@@ -1542,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) {
@@ -1562,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();
@@ -1574,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}`);
@@ -1582,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();
@@ -1748,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)) {
@@ -1771,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.
  *
@@ -1849,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;
@@ -1888,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));
@@ -2067,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 });
@@ -2639,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]);