@foldrun/core 0.2.0

package/dist/src/store.js

@@ -0,0 +1,2378 @@
+// Filesystem storage. Three real directories, one per scope — the nesting IS
+// the scope model, so "nearest wins" is literally walking up the tree:
+//
+//   data/<account>/                        the company: one bill, one identity
+//   ├── secrets.json                       account credentials
+//   ├── library/                           shared by every workspace
+//   │   └── {skills,memory,knowledge,tools,scripts}/
+//   ├── .runtimes/                         generated: container images, venvs
+//   └── workspaces/<workspace>/            a trust boundary
+//       ├── AGENTS.md                      shared context for this workspace
+//       ├── agents/<agent>/                one role
+//       │   └── {agent.md,skills,memory,knowledge,scripts,outputs}/
+//       ├── {flows,evals,skills,memory,knowledge,tools,scripts,state}/
+//       ├── secrets.json                   workspace credentials
+//       └── runs/                          generated: the audit trail
+//
+// Anything generated is either dot-prefixed (.runtimes, .results) or named for
+// what produced it (runs/, outputs/). Everything else is authored by a person
+// or an agent, and belongs in git.
+//
+// An account is a named directory (per OKF: tenancy is a hosting concern).
+import fs from "node:fs";
+import path from "node:path";
+import { recordRevision, registerTreeReader } from "./history.js";
+import { dataRoot, singleWorkspace } from "./paths.js";
+import matter from "gray-matter";
+/**
+ * The frontmatter of one markdown file, as the runtime reads it. Exported
+ * for the CLI: `foldrun probe` used to import gray-matter itself, which is
+ * this package's dependency, not the CLI's — on an installed CLI the import
+ * failed, the catch swallowed it, and the workspace's provider block was
+ * silently ignored, so the probe went to Anthropic and reported a model
+ * that "may not exist". Reading through here, the CLI cannot drift from
+ * the runtime, and there is nothing to fail to import.
+ */
+export function readFrontmatter(file) {
+    return matter(fs.readFileSync(file, "utf8")).data;
+}
+import { ownToolNames, legacyUseNames } from "./tool-names.js";
+import { refNames } from "./refs.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";
+// 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.
+/**
+ * Single-workspace mode. When set, the workspace IS this directory — no
+ * tenant, no projects/ nesting. That's the difference between a framework you
+ * run on a folder and a platform that hosts many, and it's the only thing the
+ * core needs to know about which one it's in.
+ */
+export { singleWorkspace };
+// The directories a workspace is made of. Declared once: this list had drifted
+// into four separate copies, and the file tree quietly stopped showing
+// knowledge/, evals/ and state/ because one of them was never updated.
+export const WORKSPACE_DIRS = [
+    "agents",
+    "flows",
+    "evals",
+    "skills",
+    "memory",
+    "knowledge",
+    "tools",
+    "scripts",
+    "state",
+];
+const IN_WORKSPACE_DIR = new RegExp(`^(${WORKSPACE_DIRS.join("|")})/`);
+// Where the file store mirrors its bytes for a run to read. Deliberately not
+// in WORKSPACE_DIRS: that list is the workspace's *source*, and everything
+// derived from it — the file tree, the git export, what a deploy may carry —
+// treats membership as "this is reviewable text". Blobs are not. Declared
+// here rather than in files.ts because saveWorkspace has to know the name to
+// preserve it, and store.ts is the module files.ts depends on, not the
+// reverse. See files.ts for the whole argument.
+export const STORAGE_DIR = "storage";
+/** What this directory was called before. Read-only: nothing writes here any
+ *  more, but installs created before the rename have bytes under it, and a
+ *  workspace whose files vanished on upgrade is a data-loss bug however
+ *  cosmetic the cause. `adoptLegacyFilesDir` moves one across, once. */
+export const LEGACY_FILES_DIR = "files";
+/**
+ * Move a pre-rename `files/` directory to `storage/`, once, in place.
+ *
+ * Called on the paths that resolve the store and the run mirror, so an
+ * existing install upgrades the first time either is touched rather than
+ * needing a migration step someone has to remember to run. A no-op when
+ * `storage/` already exists (the normal case after the first call) or when
+ * there is nothing to move (a fresh install).
+ */
+export function adoptLegacyFilesDir(parent) {
+    const current = path.join(parent, STORAGE_DIR);
+    const legacy = path.join(parent, LEGACY_FILES_DIR);
+    if (fs.existsSync(current) || !fs.existsSync(legacy))
+        return;
+    try {
+        fs.renameSync(legacy, current);
+    }
+    catch {
+        // A rename across devices, or a permission we do not have: copy instead,
+        // and leave the original alone rather than risk losing it.
+        try {
+            fs.cpSync(legacy, current, { recursive: true });
+        }
+        catch {
+            /* the caller sees an absent directory, which is the pre-rename state */
+        }
+    }
+}
+/**
+ * Rewrite a pre-rename `mdagent_version:` in an AGENTS.md to `foldrun_version:`,
+ * once, in place.
+ *
+ * The reader used to accept both spellings, which meant the old name lived on
+ * forever in files nobody would ever edit. Migrating on touch retires it: the
+ * first read of an account or workspace converts the file, and after that
+ * there is one name in the codebase and one name on disk.
+ *
+ * Only the key is touched — same line, same value, same everything else — so
+ * a file with comments or unusual formatting comes through unchanged.
+ */
+export function adoptLegacyVersionKey(dir) {
+    for (const name of ["AGENTS.md", "project.md"]) {
+        const file = path.join(dir, name);
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!/^mdagent_version:/m.test(raw))
+            continue;
+        try {
+            fs.writeFileSync(file, raw.replace(/^mdagent_version:/m, "foldrun_version:"));
+        }
+        catch {
+            /* read-only checkout, or a source tree we do not own: the caller reads
+               the file either way, and a missing version is a warning, not a stop. */
+        }
+    }
+}
+// Where an account keeps its workspaces. Renamed from "projects" once the
+// concept settled on *workspace* everywhere else; the old directory is still
+// read so an existing install keeps working without a migration step.
+const WORKSPACES = "workspaces";
+const LEGACY_WORKSPACES = "projects";
+function workspacesRoot(tenant) {
+    const current = path.join(dataRoot(), tenant, WORKSPACES);
+    if (fs.existsSync(current))
+        return current;
+    const legacy = path.join(dataRoot(), tenant, LEGACY_WORKSPACES);
+    return fs.existsSync(legacy) ? legacy : current;
+}
+const SAFE_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function assertSafeName(name, kind) {
+    if (!SAFE_NAME.test(name))
+        throw new Error(`invalid ${kind} "${name}" — kebab-case only`);
+}
+export function workspaceDir(tenant, workspace) {
+    const single = singleWorkspace();
+    if (single)
+        return path.resolve(single);
+    assertSafeName(tenant, "tenant");
+    assertSafeName(workspace, "workspace");
+    // An existing workspace keeps its current home; a new one is created under
+    // the canonical name.
+    const legacy = path.join(dataRoot(), tenant, LEGACY_WORKSPACES, workspace);
+    if (fs.existsSync(legacy))
+        return legacy;
+    return path.join(dataRoot(), tenant, WORKSPACES, 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.
+ */
+export function accountDir(tenant) {
+    const single = singleWorkspace();
+    if (single)
+        return path.resolve(single, "..");
+    assertSafeName(tenant, "tenant");
+    return path.join(dataRoot(), tenant);
+}
+/**
+ * Create the account's AGENTS.md if it is missing. Returns what it wrote.
+ *
+ * Called from every path that brings a workspace into being, because there is
+ * no separate "create an account" step — the account root accumulates
+ * (`library/`, `secrets.json`) as things need it, and its AGENTS.md is one
+ * more of those things.
+ *
+ * Never overwrites, and treats the legacy `project.md` as already-present: the
+ * whole file is hand-authored config, and a deploy is not permission to touch
+ * a scope the deploy did not ship. `dir` is explicit for `foldrun init`, which
+ * writes a workspace to an arbitrary path before anything is pinned to it and
+ * so cannot ask accountDir where "up" is.
+ */
+export function ensureAccountFiles(tenant, dir = accountDir(tenant)) {
+    const written = [];
+    for (const f of accountFiles(path.basename(path.resolve(dir)))) {
+        if (fs.existsSync(path.join(dir, f.path)))
+            continue;
+        if (f.path === "AGENTS.md" && fs.existsSync(path.join(dir, "project.md")))
+            continue;
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, f.path), f.content);
+        written.push(f.path);
+    }
+    return written;
+}
+// Files whose names are part of a standard, and must be spelled exactly.
+// AGENTS.md is the Linux Foundation convention; SKILL.md is the Agent Skills
+// standard. Case-insensitive filesystems (macOS, Windows)
+// happily accept `Skill.md` locally and then it vanishes on a Linux runtime —
+// so the wrong case is rejected here, loudly, with the right spelling.
+const CANONICAL = ["AGENTS.md", "SKILL.md"];
+/**
+ * The format version this build understands.
+ *
+ * A workspace declares what it targets with `foldrun_version` in AGENTS.md.
+ * Without it, the first breaking change to the flow grammar or frontmatter
+ * silently changes what everyone's existing files mean — the one failure a
+ * format cannot recover from, because there is no error to notice.
+ *
+ * Missing is treated as "current": nobody's existing workspace breaks by
+ * having been written before this existed.
+ */
+export const FORMAT_VERSION = "0.1";
+export function checkFormatVersion(declared) {
+    const value = typeof declared === "string" ? declared.trim() : null;
+    if (!value)
+        return { declared: null, supported: FORMAT_VERSION, warning: null };
+    const [major, minor = "0"] = value.split(".");
+    const [okMajor, okMinor] = FORMAT_VERSION.split(".");
+    if (major !== okMajor) {
+        return {
+            declared: value,
+            supported: FORMAT_VERSION,
+            warning: `this workspace targets foldrun format ${value}, and this build understands ` +
+                `${FORMAT_VERSION}. A different major version may mean different behaviour — ` +
+                `read it as best-effort rather than correct.`,
+        };
+    }
+    if (Number(minor) > Number(okMinor)) {
+        return {
+            declared: value,
+            supported: FORMAT_VERSION,
+            warning: `this workspace targets foldrun format ${value}; this build understands ` +
+                `${FORMAT_VERSION}. Newer fields will be ignored rather than rejected.`,
+        };
+    }
+    return { declared: value, supported: FORMAT_VERSION, warning: null };
+}
+export function assertCanonicalCase(rel) {
+    const base = rel.split("/").pop() ?? rel;
+    for (const want of CANONICAL) {
+        if (base !== want && base.toLowerCase() === want.toLowerCase()) {
+            throw new Error(`"${base}" must be spelled exactly "${want}" — it is a standard filename and the case is ` +
+                `part of it. Rename it and try again.`);
+        }
+    }
+}
+/**
+ * What the platform owns inside a workspace directory, in one place.
+ *
+ * Three separate mechanisms need this exact list and drifted apart while it
+ * lived in each of them: deploys must preserve these files, and the run
+ * executors (docker and k8s) must not copy them into a sandbox. A platform
+ * file added to one list and not the others is either silently wiped by the
+ * 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"];
+/** 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;
+    return norm === "runs" || norm.startsWith("runs/") || norm === ".foldrun" || norm.startsWith(".foldrun/");
+}
+export function saveWorkspace(tenant, workspace, files, 
+/** Attribution for the revision this save records. A deploy passes the
+ *  commit, which becomes the revision's id. */
+meta = {}) {
+    if (files.length > 500)
+        throw new Error("too many files");
+    for (const f of files) {
+        const norm = path.normalize(f.path);
+        if (norm.startsWith("..") || path.isAbsolute(norm) || norm.startsWith("runs")) {
+            throw new Error(`illegal file path: ${f.path}`);
+        }
+        assertCanonicalCase(norm);
+        if (!IN_WORKSPACE_DIR.test(norm) && norm !== "project.md" && norm !== "AGENTS.md") {
+            throw new Error(`unexpected file: ${f.path} — a workspace holds AGENTS.md plus ` +
+                `${WORKSPACE_DIRS.map((d) => `${d}/`).join(", ")}`);
+        }
+    }
+    // Executable: an agent's own scripts/, or the workspace-level shared scripts/.
+    const isScript = (rel) => {
+        const norm = path.normalize(rel);
+        return (/^agents\/[^/]+\/scripts\//.test(norm) || // an agent's own scripts
+            /^agents\/[^/]+\/skills\/[^/]+\/scripts\//.test(norm) || // scripts bundled in a skill
+            /^scripts\//.test(norm) // workspace-wide shared scripts
+        );
+    };
+    const dir = workspaceDir(tenant, workspace);
+    // The scope above has to exist before anything under it runs, and this is
+    // the only chokepoint every hosted workspace passes through — the dashboard's
+    // New button, the API, and `git push` deploys all land here.
+    ensureAccountFiles(tenant);
+    // A deploy replaces the workspace, but it must not destroy what it never
+    // owned. Git is authoritative for the files it ships; the platform owns
+    // everything an agent produced at run time. So:
+    //
+    //   runs/            always kept — the audit trail
+    //   state/           always kept — what an agent carries between runs
+    //   storage/         always kept — the file store's run mirror, which no
+    //                    deploy can ship (a deploy carries source, and bytes
+    //                    are not source) and every run expects to find. Note
+    //                    the pre-rename `files/` is NOT protected here: a
+    //                    workspace still holding one loses it on deploy, which
+    //                    is why adoptLegacyFilesDir runs on the read paths.
+    //   memory/*.md      kept when the deploy doesn't ship that file
+    //
+    // That last rule is the subtle one. Memory is written from both sides: a
+    // human commits a fact, and an agent learns one. Keeping only the files the
+    // deploy *didn't* mention means deleting a memory in git deletes it on the
+    // server, while a memory an agent wrote survives a push that never knew
+    // 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));
+    // What is there now, for the revision: every editable file's content
+    // before this save replaces the tree.
+    const before = new Map();
+    if (fs.existsSync(dir)) {
+        for (const rel of listWorkspaceFiles(tenant, workspace)) {
+            try {
+                before.set(rel, fs.readFileSync(path.join(dir, rel), "utf8"));
+            }
+            catch {
+                // vanished mid-read; not part of the revision
+            }
+        }
+    }
+    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 })) {
+            const rel = String(entry).split(path.sep).join("/");
+            const from = path.join(dir, rel);
+            try {
+                if (!fs.statSync(from).isFile() || !isAgentOwned(rel))
+                    continue;
+            }
+            catch {
+                continue; // a broken link or a file that vanished mid-deploy
+            }
+            const to = path.join(snapshot, rel);
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.copyFileSync(from, to);
+            preserved.push(rel);
+        }
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    for (const f of files) {
+        const target = path.join(dir, path.normalize(f.path));
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, f.content);
+        // Anything under an agent's scripts/ is meant to be run.
+        if (isScript(f.path))
+            fs.chmodSync(target, 0o755);
+    }
+    // Restore after writing, so a deploy never overwrites preserved state.
+    if (snapshot) {
+        for (const rel of preserved) {
+            const to = path.join(dir, rel);
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.copyFileSync(path.join(snapshot, rel), to);
+        }
+        fs.rmSync(snapshot, { recursive: true, force: true });
+    }
+    // The revision: shipped files against what they replaced, plus anything
+    // that was there and is not any more (and was not preserved).
+    const keep = new Set(preserved);
+    const changes = files.map((f) => {
+        const rel = path.normalize(f.path).split(path.sep).join("/");
+        return { path: rel, before: before.get(rel) ?? null, after: f.content };
+    });
+    for (const [rel, content] of before) {
+        if (!shipped.has(rel) && !keep.has(rel))
+            changes.push({ path: rel, before: content, after: null });
+    }
+    recordRevision(tenant, workspace, changes, {
+        by: meta.by ?? (meta.commit ? "deploy" : "system"),
+        message: meta.message ?? (meta.commit ? `deployed ${meta.commit.slice(0, 7)}` : undefined),
+        commit: meta.commit ?? null,
+    });
+    // The files are conformant concepts the moment they land; the bundles around
+    // 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);
+    return { preserved: preserved.length };
+}
+// The prompt-facing index for an OKF bundle (memory/ or knowledge/).
+//
+// The on-disk artifact is index.md, written by syncIndex and conformant with
+// the spec. This builds the same listing with paths the agent can actually
+// open, plus the v0.2 signals that change how a fact should be treated: a
+// stale price list or an unverified claim should not read like a confirmed
+// one.
+//
+// There is no curated preamble. A hand-written MEMORY.md used to be read in
+// ahead of this listing, and it was a reserved name we invented inside someone
+// else's format — a consumer applying OKF's rules saw an untyped concept and
+// rejected the bundle. Shared prose belongs in AGENTS.md, which is already the
+// place for context every agent here gets.
+export function buildMemoryIndex(dir, prefix = "") {
+    if (!fs.existsSync(dir))
+        return null;
+    const lines = [];
+    for (const doc of readBundle(dir)) {
+        const marks = [
+            doc.type && doc.type !== "Memory" ? doc.type : null,
+            doc.status !== "stable" ? doc.status : null,
+            doc.stale ? `STALE since ${doc.staleAfter} — confirm before relying on it` : null,
+            // Same signals as the on-disk index, one definition — see provenanceMarks.
+            // This is the copy a model reads mid-run, so it is the one that decides
+            // whether it treats its own earlier guess as a fact.
+            ...provenanceMarks(doc),
+        ].filter(Boolean);
+        lines.push(`- [${doc.title}](${prefix}${doc.file})` +
+            (doc.description ? ` — ${doc.description}` : "") +
+            (marks.length ? ` _(${marks.join(", ")})_` : ""));
+    }
+    return lines.length ? lines.join("\n") : null;
+}
+// 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/");
+}
+// Knowledge is what you *gave* an agent — stable reference material an agent
+// reads and never rewrites. Memory is what it *learned* and authors itself.
+// Keeping them apart matters: a price list an agent silently edits is a bug,
+// and a fact it discovered that you have to maintain by hand is a chore.
+export function knowledgeIndex(dir, prefix = "") {
+    return buildMemoryIndex(dir, prefix);
+}
+export function workspaceKnowledgeIndex(tenant, workspace) {
+    return knowledgeIndex(path.join(workspaceDir(tenant, workspace), "knowledge"), "../../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
+// (a `base:` means http, a `run:` means script). Both are granted the same
+// way, with `tools: [name]`, so "what can this agent do?" has one answer in one
+// place instead of three (`tools:`, `scripts:`, `apis:`).
+// An MCP server an agent can connect to. MCP is the cross-vendor standard for
+// tools (Anthropic, OpenAI, Google), so accepting a server here is what lets
+// someone reuse the ecosystem instead of re-describing an integration we
+// already have a format for. Both transports the SDK supports are allowed:
+// a local process (`command`) or a remote endpoint (`url`).
+const asRecord = (v) => v && typeof v === "object" && !Array.isArray(v)
+    ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, String(x)]))
+    : {};
+/**
+ * The program inside a single-file script tool: the first fenced block whose
+ * language tag names a runnable language. By tag, not by position — a body
+ * legitimately opens with a \`\`\`yaml example of the tools: line, and running
+ * the documentation would be a memorable bug. Untagged fences never qualify:
+ * "which block is the program" must be answerable by reading, not guessing.
+ */
+export function fencedCode(body) {
+    const block = fencedCodeBlock(body);
+    return block ? { code: block.code, ext: block.ext } : null;
+}
+/**
+ * The same block, with where it sits — for the migration that lifts a
+ * single-file tool's program out into a file beside it. Extracting the code
+ * and then removing it from the body are the same question asked twice, and
+ * a second copy of the language table is how they would come to disagree.
+ */
+export function fencedCodeBlock(body) {
+    const EXT = {
+        js: ".mjs", mjs: ".mjs", javascript: ".mjs", ts: ".mjs",
+        python: ".py", py: ".py", bash: ".sh", sh: ".sh", ruby: ".rb", rb: ".rb",
+    };
+    for (const m of body.matchAll(/```([a-zA-Z0-9]+)\r?\n([\s\S]*?)```/g)) {
+        const ext = EXT[m[1].toLowerCase()];
+        if (ext && m[2].trim()) {
+            return { code: m[2], ext, start: m.index, end: m.index + m[0].length };
+        }
+    }
+    return null;
+}
+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
+    // the document. `type: Tool` says what the file is and deliberately says
+    // nothing about how it connects, so it falls through to inference below.
+    const declared = readTransport(data);
+    // Inferred when neither is present, so simple files stay simple.
+    const kind = declared ??
+        (typeof data.command === "string" || typeof data.url === "string"
+            ? "mcp"
+            : typeof data.run === "string"
+                ? "script"
+                : "http");
+    if (kind === "mcp") {
+        const command = typeof data.command === "string" ? data.command : undefined;
+        const url = typeof data.url === "string" ? data.url : undefined;
+        if (!command && !url)
+            return null;
+        return {
+            kind: "mcp",
+            name,
+            spec: {
+                name,
+                description: typeof data.description === "string" ? data.description : "",
+                command,
+                args: Array.isArray(data.args) ? data.args.map(String) : [],
+                env: asRecord(data.env),
+                url,
+                headers: asRecord(data.headers),
+            },
+        };
+    }
+    if (kind === "script") {
+        // The program is a run: path, or the file's own fenced code block — the
+        // single-file form, which is what lets a script tool read and edit like
+        // every other markdown document.
+        if (typeof data.run === "string")
+            return { kind: "script", name, spec: { ...data, name } };
+        const inline = body ? fencedCode(body) : null;
+        if (!inline)
+            return null;
+        return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext } };
+    }
+    const [spec] = parseApis([{ ...data, name }]);
+    return spec ? { kind: "http", name, spec } : null;
+}
+/**
+ * Tools in a directory, in both shapes.
+ *
+ *   tools/email.md            flat — a definition and nothing else
+ *   tools/bounce-verify/      folder — tool.md plus the code it runs
+ *     tool.md
+ *     run.mjs
+ *
+ * The folder is the shape to write. A script tool is a definition and an
+ * executable that cannot be separated — point `run:` at the wrong scope and
+ * the tool silently resolves to nothing — so keeping them in one directory
+ * is what stops the two from ever disagreeing. It is also how skills already
+ * work, which is the pattern people have seen.
+ *
+ * A folder tool's `run:` is relative to its own folder, and rewritten here
+ * to the scope-qualified path the runner resolves. That is the point of the
+ * shape: the definition never names the scope it lives in, so the same
+ * folder works copied into a workspace or installed at the account.
+ *
+ * Flat files keep working unchanged — the shape is a migration, not a break.
+ */
+function readToolDir(dir, scope = "workspace") {
+    if (!fs.existsSync(dir))
+        return {};
+    const out = {};
+    const broken = [];
+    const add = (raw, fallbackName, folder) => {
+        try {
+            const { data, content } = matter(raw);
+            // A COPY, because the qualification below is a mutation and the object
+            // is not ours: gray-matter caches its result by the input string, so two
+            // byte-identical definitions at different scopes are handed the same
+            // `data` object. Mutating it in place stamped the first reader's scope
+            // onto the second — an account tool whose `run:` came back
+            // `workspace/tools/…`, resolving to a path in whichever workspace was
+            // read first, and therefore to nothing. Silent, and dependent on read
+            // order, which is the worst pair of properties a bug can have.
+            //
+            // Real case: the same `browser` tool installed at the account and in a
+            // workspace, which is exactly what installing one gallery tool twice
+            // produces.
+            const d = { ...data };
+            // A folder tool's code sits beside its definition; qualify the path so
+            // the runner can find it from an agent directory two levels down.
+            if (folder && typeof d.run === "string" && !/^(workspace|account|shared|library)\//.test(d.run)) {
+                d.run = `${scope}/tools/${folder}/${d.run.replace(/^\.\//, "")}`;
+            }
+            const def = parseToolDef(d, fallbackName, content);
+            if (def)
+                out[def.name] = def;
+            else
+                broken.push(`${fallbackName}: no base, run, command or fenced code block — nothing to call`);
+        }
+        catch (err) {
+            // A malformed definition must not fail every run in the workspace. But
+            // it must not vanish either: dropped silently, a tool with a YAML typo
+            // is indistinguishable from one that was never created, and the agent
+            // that opted into it is told the tool "is not in the workspace" —
+            // which sends its author looking in the wrong place entirely.
+            broken.push(`${fallbackName}: ${err instanceof Error ? err.message.split("\n")[0] : "unreadable"}`);
+        }
+    };
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            const manifest = path.join(dir, entry.name, "tool.md");
+            if (fs.existsSync(manifest))
+                add(fs.readFileSync(manifest, "utf8"), entry.name, entry.name);
+            continue;
+        }
+        if (!entry.name.endsWith(".md"))
+            continue;
+        add(fs.readFileSync(path.join(dir, entry.name), "utf8"), entry.name.replace(/\.md$/, ""), null);
+    }
+    // Reported through the definitions map so a caller that only wants tools
+    // can ignore it, and the runner can say what is actually wrong.
+    brokenTools.set(dir, broken);
+    return out;
+}
+/** Why a tool in this directory failed to load, keyed by directory. */
+const brokenTools = new Map();
+/** Definitions that exist on disk but could not be read, for the scopes an
+ *  agent draws on. Empty when everything parsed. */
+export function brokenToolReport(tenant, workspace) {
+    const dirs = [
+        path.join(workspaceDir(tenant, workspace), "tools"),
+        path.join(dataRoot(), tenant, "library", "tools"),
+    ];
+    return dirs.flatMap((d) => brokenTools.get(d) ?? []);
+}
+export function workspaceTools(tenant, workspace) {
+    return readToolDir(path.join(workspaceDir(tenant, workspace), "tools"), "workspace");
+}
+export { readToolDir };
+// Files under agents/<name>/scripts/ — the agent's own tooling, runnable
+// with the bash tool.
+export function agentScripts(tenant, workspace, agent) {
+    const dir = path.join(workspaceDir(tenant, workspace), "agents", agent, "scripts");
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { recursive: true })) {
+        const rel = String(entry);
+        if (fs.statSync(path.join(dir, rel)).isFile())
+            out.push(rel);
+    }
+    return out.sort();
+}
+// Recognised HTTP verbs a tool may declare. Deliberately NOT named
+// "safe methods" — in HTTP that term means "no side effects" (GET, HEAD), and
+// DELETE is the opposite. This is an allowlist: unknown or exotic verbs are
+// dropped rather than passed to fetch, and a tool that declares none is
+// read-only, because the least dangerous thing should happen when a file says
+// nothing.
+const ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+// Model selection. Tiers are the portable default — they keep working as
+// models are renamed. An explicit alias or full model id is passed straight
+// through for callers who want to pin one.
+export const MODEL_TIERS = {
+    fast: "haiku",
+    default: "sonnet",
+    max: "opus",
+};
+// The same three tiers under every name someone reasonably reaches for.
+// Nobody should have to learn our vocabulary to pick a model, and the
+// alternative to accepting `small` is worse than pedantic: an unrecognised
+// word is passed through as a model id, so `model: small` would reach the
+// provider as a model called "small" and fail the step at run time, on a
+// file that reads perfectly. A synonym table is cheaper than that error.
+const MODEL_ALIASES = {
+    fast: "fast",
+    small: "fast",
+    cheap: "fast",
+    mini: "fast",
+    light: "fast",
+    low: "fast",
+    haiku: "fast",
+    default: "default",
+    standard: "default",
+    base: "default",
+    balanced: "default",
+    mid: "default",
+    medium: "default",
+    normal: "default",
+    sonnet: "default",
+    max: "max",
+    large: "max",
+    big: "max",
+    best: "max",
+    smart: "max",
+    high: "max",
+    deep: "max",
+    opus: "max",
+};
+/** Which tier a word names, or null if it names none. Exported because the
+ *  provider block keys a remap table by tier and should accept every word
+ *  `model:` does — one vocabulary, not two. */
+export function resolveTier(value) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    return MODEL_ALIASES[value.trim().toLowerCase()] ?? null;
+}
+export function resolveModel(value) {
+    const raw = typeof value === "string" && value.trim() ? value.trim() : "default";
+    const tier = resolveTier(raw);
+    if (tier)
+        return MODEL_TIERS[tier];
+    return raw; // "claude-opus-5" | a provider's own id | …
+}
+// Effort is the other half of model selection, and the orthogonal one: the
+// model is which brain, effort is how long it thinks before answering. The
+// five levels are the SDK's own union — we neither invent our own scale nor
+// narrow theirs, so a level added upstream is one line here.
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+const EFFORT_ALIASES = {
+    low: "low",
+    min: "low",
+    minimal: "low",
+    lowest: "low",
+    fast: "low",
+    quick: "low",
+    medium: "medium",
+    med: "medium",
+    mid: "medium",
+    moderate: "medium",
+    normal: "medium",
+    balanced: "medium",
+    high: "high",
+    default: "high", // the SDK's default, said out loud
+    deep: "high",
+    xhigh: "xhigh",
+    "x-high": "xhigh",
+    "extra-high": "xhigh",
+    extrahigh: "xhigh",
+    "very-high": "xhigh",
+    veryhigh: "xhigh",
+    higher: "xhigh",
+    max: "max",
+    maximum: "max",
+    highest: "max",
+    full: "max",
+};
+/**
+ * `null` for both "not set" and "not a level we know" — unlike a model, the
+ * set is closed, so passing an unrecognised word through would be a 400 from
+ * the API rather than someone's pinned choice. Callers that can report say
+ * which it was with `isEffortWord`.
+ */
+export function resolveEffort(value) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    return EFFORT_ALIASES[value.trim().toLowerCase()] ?? null;
+}
+/** True when a non-empty `effort:` was written but names no level — the
+ *  one case worth a line in the run trace, because silence there looks
+ *  exactly like the setting having been applied. */
+export function isEffortWord(value) {
+    return typeof value === "string" && value.trim().length > 0 && resolveEffort(value) === null;
+}
+const RATE_UNIT_SECONDS = {
+    s: 1, sec: 1, second: 1,
+    m: 60, min: 60, minute: 60,
+    h: 3600, hr: 3600, hour: 3600,
+};
+/** `"5/s"`, `"100/m"`, `"1000/h"` → a bucket size and refill rate. Null for
+ *  anything else: an unreadable limit is ignored rather than guessed. */
+export function parseRate(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        return { count: value, perSec: value };
+    }
+    if (typeof value !== "string")
+        return null;
+    const m = /^\s*(\d+(?:\.\d+)?)\s*\/\s*([a-z]+)\s*$/i.exec(value);
+    if (!m)
+        return null;
+    const count = Number(m[1]);
+    const unit = RATE_UNIT_SECONDS[m[2].toLowerCase()];
+    if (!(count > 0) || !unit)
+        return null;
+    return { count, perSec: count / unit };
+}
+// apis: frontmatter:
+//   apis:
+//     - name: google_ads
+//       base: https://googleads.googleapis.com/v18
+//       description: Google Ads REST API. Use searchStream for metrics.
+//       methods: [GET, POST]
+//       headers:
+//         Authorization: Bearer ${GOOGLE_ADS_TOKEN}
+//         developer-token: ${GOOGLE_ADS_DEV_TOKEN}
+//       openapi: tools/google_ads/openapi.yaml   # optional: typed tools
+//       operations: [searchStream, "GET /customers/{id}"]
+//       rate: 10/s                               # or 100/m, 1000/h
+export function parseApis(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        const name = typeof e.name === "string" ? e.name : null;
+        const base = typeof e.base === "string" ? e.base : null;
+        if (!name || !base)
+            continue;
+        const asRecordLocal = (v) => v && typeof v === "object" && !Array.isArray(v)
+            ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, String(x)]))
+            : {};
+        const methods = Array.isArray(e.methods)
+            ? e.methods.map((m) => String(m).toUpperCase()).filter((m) => ALLOWED_METHODS.includes(m))
+            : ["GET"];
+        const rate = parseRate(e.rate);
+        const operations = Array.isArray(e.operations)
+            ? e.operations.map((o) => String(o).trim()).filter(Boolean)
+            : null;
+        out.push({
+            name: name.replace(/[^a-zA-Z0-9_]/g, "_"),
+            ...(Number(e.timeout) > 0 ? { timeout: Number(e.timeout) } : {}),
+            base: base.replace(/\/+$/, ""),
+            description: typeof e.description === "string" ? e.description : "",
+            headers: asRecordLocal(e.headers),
+            query: asRecordLocal(e.query),
+            methods: methods.length ? methods : ["GET"],
+            ...(typeof e.openapi === "string" && e.openapi.trim() ? { openapi: e.openapi.trim() } : {}),
+            // An explicit list, even an empty one, means "only these" — the
+            // generic tool is withheld. Absent means "everything, plus call_<api>".
+            ...(operations ? { operations } : {}),
+            ...(rate ? { rate } : {}),
+        });
+    }
+    return out;
+}
+export const FLOW_TRIGGERS = ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+export function agentAssets(tenant, workspace, agent) {
+    const base = path.join(workspaceDir(tenant, workspace), "agents", agent);
+    const nameOf = (file, fallback) => {
+        try {
+            return matter(fs.readFileSync(file, "utf8")).data.name ?? fallback;
+        }
+        catch {
+            return fallback;
+        }
+    };
+    // Skills: folders with SKILL.md (Agent Skills standard) plus flat .md files.
+    const skills = [];
+    const skillsDir = path.join(base, "skills");
+    if (fs.existsSync(skillsDir)) {
+        for (const entry of fs.readdirSync(skillsDir).sort()) {
+            const full = path.join(skillsDir, entry);
+            if (fs.statSync(full).isDirectory()) {
+                const skillMd = path.join(full, "SKILL.md");
+                if (fs.existsSync(skillMd))
+                    skills.push(nameOf(skillMd, entry));
+            }
+            else if (entry.endsWith(".md")) {
+                skills.push(nameOf(full, entry.replace(/\.md$/, "")));
+            }
+        }
+    }
+    const memory = [];
+    const memoryDir = path.join(base, "memory");
+    if (fs.existsSync(memoryDir)) {
+        for (const f of fs.readdirSync(memoryDir).sort()) {
+            if (f.endsWith(".md") && !["index.md", "log.md"].includes(f)) {
+                memory.push(nameOf(path.join(memoryDir, f), f.replace(/\.md$/, "")));
+            }
+        }
+    }
+    return { skills, memory };
+}
+export function listAgents(tenant, workspace) {
+    const dir = path.join(workspaceDir(tenant, workspace), "agents");
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((n) => fs.existsSync(path.join(dir, n, "agent.md")))
+        .sort()
+        .map((name) => {
+        const { data } = matter(fs.readFileSync(path.join(dir, name, "agent.md"), "utf8"));
+        const tools = refNames(data.tools);
+        return {
+            name,
+            description: data.description ?? "",
+            model: data.model ?? "default",
+            effort: data.effort ?? null,
+            tools,
+            apis: parseApis(data.apis),
+            ownTools: ownToolNames(data),
+            legacyUse: legacyUseNames(data),
+            consults: refNames(data.agents),
+            skills: data.skills === undefined ? null : refNames(data.skills),
+            secrets: Array.isArray(data.secrets) ? data.secrets.map(String) : [],
+        };
+    });
+}
+// 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*(.+)$/;
+/** "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 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;
+}
+/** 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
+ *  `at:` never fires, and `foldrun check` says so. */
+export function parseInstant(raw) {
+    if (!(typeof raw === "string" || raw instanceof Date))
+        return null;
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+/**
+ * Strip the quotes a person wrapped a whole value in, and only those.
+ *
+ * `schedule: "0 8 * * *"` is quoted so YAML-minded readers are comfortable,
+ * and the cron parser must not see the quotes. But the rule that did this
+ * 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"
+ *
+ * reached bash unbalanced, which exited 2 with "unexpected EOF" on every
+ * run. The step could never pass, whatever the agent did, and nothing said
+ * why: the trace printed the command the parser had already broken.
+ *
+ * So a pair is only stripped when the value opens and closes with the same
+ * quote AND contains no other instance of it — which is what "the whole
+ * value is quoted" actually means. `"a" = "b"` keeps its quotes, because
+ * they are two pairs, not one wrapper.
+ */
+export function unquote(raw) {
+    const value = raw.trim();
+    const q = value[0];
+    if ((q !== '"' && q !== "'") || value.length < 2 || !value.endsWith(q))
+        return value;
+    const inner = value.slice(1, -1);
+    return inner.includes(q) ? value : inner;
+}
+export function parseFlow(file, raw) {
+    const { data, content } = matter(raw);
+    const steps = [];
+    // 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;
+    for (const line of content.split("\n")) {
+        lineNo++;
+        const m = line.match(STEP_RE);
+        if (m) {
+            steps.push({
+                group: Number(m[1]),
+                // Both "2? [[x]]" and an `approve: true` option are accepted; "!"
+                // is shorthand for the common case of needing a human.
+                optional: m[2] === "?",
+                approve: m[2] === "!" || undefined,
+                agent: m[4],
+                subflow: m[3] ? m[4] : undefined,
+                instruction: m[5].trim(),
+                line: lineNo + offset,
+            });
+            continue;
+        }
+        // Indented options belong to the step above them.
+        const opt = line.match(OPTION_RE);
+        if (opt && steps.length) {
+            const step = steps[steps.length - 1];
+            const [, key, rawValue] = opt;
+            const value = unquote(rawValue);
+            if (key === "approve")
+                step.approve = value !== "false";
+            else if (key === "when")
+                step.when = value;
+            else if (key === "case")
+                step.case = value;
+            else if (key === "else")
+                step.else = value !== "false";
+            else if (key === "retry")
+                step.retry = Math.min(5, Math.max(0, Number(value) || 0));
+            else if (key === "timeout")
+                step.timeout = Math.max(1, Number(value) || 0);
+            else if (key === "verify")
+                step.verify = value;
+            else if (key === "output")
+                step.output = /^json$/i.test(value) ? "json" : undefined;
+            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 === "until")
+                step.until = value;
+            else if (key === "each") {
+                if (value === "lines")
+                    step.each = "lines";
+                else if (value === "items")
+                    step.each = "items";
+                else if (/^rows\b/.test(value)) {
+                    step.each = "rows";
+                    // "rows of ../../storage/leads.csv" — the path is the part after "of".
+                    step.eachPath = value.replace(/^rows(\s+of)?\s*/, "").trim() || undefined;
+                }
+            }
+            else if (key === "on-fail" || key === "onfail")
+                step.onFail = refNames(value)[0] ?? undefined;
+            else if (key === "wait") {
+                if (/^event$/i.test(value))
+                    step.waitFor = "event";
+                else
+                    step.waitSecs = parseWait(value);
+            }
+            else if (key === "ask") {
+                step.ask = value;
+            }
+            else if (key === "preview") {
+                step.preview = value.split(",").map((p) => p.trim().replace(/^(\.\.\/\.\.\/)?storage\//, "")).filter(Boolean);
+            }
+            else if (key === "delegate")
+                step.delegate = refNames(value).slice(0, 5);
+            else if (key === "max")
+                step.max = Math.min(20, Math.max(1, Number(value) || 0)) || undefined;
+        }
+    }
+    steps.sort((a, b) => a.group - b.group);
+    return {
+        name: data.name ?? file.replace(/\.md$/, ""),
+        file,
+        trigger: data.trigger ?? "manual",
+        schedule: data.schedule ?? null,
+        timezone: data.timezone ?? null,
+        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,
+        // `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",
+        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,
+        signature: ["github", "stripe", "slack", "hmac"].includes(String(data.signature))
+            ? String(data.signature)
+            : null,
+        signingSecret: typeof data.signing_secret === "string"
+            ? data.signing_secret.trim().replace(/^\$\{|\}$/g, "")
+            : null,
+        path: typeof data.path === "string" ? data.path.trim().replace(/^\/+/, "") : null,
+        steps,
+    };
+}
+/** 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"));
+}
+// Split a flow file into its frontmatter, any prose before the first step,
+// and one block per step. Blocks come back in the same order as parseFlow's
+// steps, so a block index and a step index mean the same thing.
+function splitFlowBlocks(raw) {
+    const head = raw.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n?)/)?.[1] ?? "";
+    const preamble = [];
+    const blocks = [];
+    for (const line of raw.slice(head.length).split("\n")) {
+        if (STEP_RE.test(line))
+            blocks.push({ group: Number(line.match(STEP_RE)[1]), lines: [line] });
+        else if (blocks.length)
+            blocks[blocks.length - 1].lines.push(line);
+        else
+            preamble.push(line);
+    }
+    // parseFlow sorts by group, and Array.prototype.sort is stable, so the same
+    // sort here keeps block i aligned with steps[i].
+    const ordered = blocks.map((b, i) => ({ ...b, i })).sort((a, b) => a.group - b.group || a.i - b.i);
+    while (preamble.length && preamble[preamble.length - 1].trim() === "")
+        preamble.pop();
+    return { head, preamble, blocks: ordered };
+}
+function emitFlow(head, preamble, groups) {
+    const out = [];
+    groups.forEach((group, g) => {
+        for (const block of group) {
+            const [stepLine, ...rest] = block.lines;
+            const m = stepLine.match(STEP_RE);
+            const [, , marker = "", flowPrefix = "", target, instruction] = m;
+            out.push(`${g + 1}${marker}. [[${flowPrefix}${target}]]${instruction.trim() ? ` — ${instruction.trim()}` : ""}`);
+            while (rest.length && rest[rest.length - 1].trim() === "")
+                rest.pop();
+            out.push(...rest);
+        }
+    });
+    // Keep the blank line that conventionally follows frontmatter.
+    const gap = preamble.length ? `${preamble.join("\n")}\n\n` : head ? "\n" : "";
+    return `${head}${gap}${out.join("\n")}\n`;
+}
+/**
+ * Rewrite a flow's trigger in place — the dashboard's trigger picker.
+ *
+ * Line-level surgery on the frontmatter, not a YAML round-trip: everything
+ * the author wrote (comments, key order, unrelated keys) survives verbatim,
+ * 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) {
+    if (!FLOW_TRIGGERS.includes(opts.trigger)) {
+        throw new Error(`unknown trigger "${opts.trigger}" — one of ${FLOW_TRIGGERS.join(", ")}`);
+    }
+    const wanted = new Map();
+    wanted.set("trigger", opts.trigger === "manual" ? null : opts.trigger); // manual is the default — say nothing
+    if (opts.trigger === "schedule") {
+        const cron = (opts.schedule ?? "").trim();
+        // Shape only — the scheduler's parseCron is the authority, and the API
+        // route runs it; importing it here would cycle store ↔ scheduler.
+        const shaped = /^@\w+$/.test(cron) || cron.split(/\s+/).length === 5;
+        if (!cron || !shaped) {
+            throw new Error(`"${cron}" is not a cron expression (5 fields, or @daily-style)`);
+        }
+        wanted.set("schedule", `"${cron}"`);
+        wanted.set("timezone", opts.timezone?.trim() ? opts.timezone.trim() : null);
+    }
+    else {
+        wanted.set("schedule", null);
+        wanted.set("timezone", null);
+    }
+    const lines = raw.split("\n");
+    const hasFront = lines[0]?.trim() === "---";
+    const close = hasFront ? lines.indexOf("---", 1) : -1;
+    const front = hasFront && close > 0 ? lines.slice(1, close) : [];
+    const body = hasFront && close > 0 ? lines.slice(close + 1) : lines;
+    const kept = front.filter((line) => {
+        const key = line.match(/^(\w+):/)?.[1];
+        return !(key && wanted.has(key));
+    });
+    for (const [key, value] of wanted) {
+        if (value !== null)
+            kept.push(`${key}: ${value}`);
+    }
+    if (kept.length === 0)
+        return body.join("\n").replace(/^\n+/, "");
+    return ["---", ...kept, "---", ...body].join("\n");
+}
+/**
+ * Rewrite one step's option lines — the board's step editor. Surgical, like
+ * every flow rewrite: only the managed option lines of block `index` change;
+ * the step line, its unmanaged options (approve stays the `!` marker's
+ * business), other steps, comments and frontmatter survive verbatim.
+ * `null` clears an option; values are clamped exactly as parseFlow reads
+ * them, so what the editor writes is what the runner will do.
+ */
+/**
+ * Rewrite one step's instruction, and nothing else.
+ *
+ * The step line carries four things — the group number, the optional/approve
+ * marker, the wikilink, and the instruction — and only the last is being
+ * edited. Rebuilding the line from the parsed step would silently normalise
+ * the other three (a "2?" becoming "2.", an en dash becoming an em dash), so
+ * 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) {
+    const { head, preamble, blocks } = splitFlowBlocks(raw);
+    if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
+        throw new Error(`no step ${index}`);
+    }
+    const block = blocks[index];
+    const line = block.lines[0];
+    const m = line.match(STEP_RE);
+    if (!m)
+        throw new Error(`step ${index} is not a step line`);
+    // Everything up to where the instruction starts, exactly as written.
+    const prefix = m[5] ? line.slice(0, line.length - m[5].length) : `${line.replace(/\s+$/, "")} — `;
+    const next = instruction.trim().replace(/\s*\n\s*/g, " ");
+    block.lines = [`${prefix}${next}`.replace(/\s+$/, ""), ...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 = [];
+    for (const b of blocks) {
+        const last = groups[groups.length - 1];
+        if (last && last[0].group === b.group)
+            last.push(b);
+        else
+            groups.push([b]);
+    }
+    return emitFlow(head, preamble, groups);
+}
+export function updateFlowStep(raw, index, options) {
+    const { head, preamble, blocks } = splitFlowBlocks(raw);
+    if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
+        throw new Error(`no step ${index}`);
+    }
+    const clamp = {
+        model: (v) => v || null,
+        effort: (v) => resolveEffort(v) ?? null,
+        verify: (v) => v || null,
+        when: (v) => v || null,
+        case: (v) => v || null,
+        else: (v) => (v === "true" || v === "1" ? "true" : null),
+        until: (v) => v || null,
+        retry: (v) => String(Math.min(5, Math.max(0, Number(v) || 0))),
+        timeout: (v) => (Number(v) > 0 ? String(Math.max(1, Math.floor(Number(v)))) : null),
+        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),
+    };
+    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];
+        return !(key && managed.has(key));
+    });
+    const added = [];
+    for (const [key, value] of Object.entries(options)) {
+        if (value === null || value === undefined || !(key in clamp))
+            continue;
+        const cleaned = clamp[key](String(value).trim());
+        if (cleaned === null)
+            continue;
+        added.push(`   ${key}: ${cleaned}`);
+    }
+    block.lines = [block.lines[0], ...added, ...kept];
+    // Reassemble the original grouping: consecutive blocks sharing a group.
+    const groups = [];
+    for (const b of blocks) {
+        const last = groups[groups.length - 1];
+        if (last && last[0].group === b.group)
+            last.push(b);
+        else
+            groups.push([b]);
+    }
+    return emitFlow(head, preamble, groups);
+}
+export function reorderFlowSteps(raw, groups) {
+    const { head, preamble, blocks: ordered } = splitFlowBlocks(raw);
+    const seen = new Set();
+    for (const group of groups) {
+        if (group.length === 0)
+            throw new Error("a group must contain at least one step");
+        for (const i of group) {
+            if (!Number.isInteger(i) || i < 0 || i >= ordered.length)
+                throw new Error(`no step ${i}`);
+            if (seen.has(i))
+                throw new Error(`step ${i} appears twice`);
+            seen.add(i);
+        }
+    }
+    if (seen.size !== ordered.length) {
+        throw new Error(`expected all ${ordered.length} steps, got ${seen.size}`);
+    }
+    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) {
+    assertSafeName(step.target, "step target");
+    const { head, preamble, blocks } = splitFlowBlocks(raw);
+    const instruction = (step.instruction ?? "").replace(/[\r\n]+/g, " ").trim();
+    const line = `0. [[${step.subflow ? "flow:" : ""}${step.target}]]${instruction ? ` — ${instruction}` : ""}`;
+    if (!STEP_RE.test(line))
+        throw new Error("could not build a valid step line");
+    const groups = groupBlocks(blocks);
+    groups.push([{ group: 0, lines: [line] }]);
+    return emitFlow(head, preamble, groups);
+}
+/** Drop one step, by its index in the flow's parsed steps. */
+export function removeFlowStep(raw, index) {
+    const { head, preamble, blocks } = splitFlowBlocks(raw);
+    if (!Number.isInteger(index) || index < 0 || index >= blocks.length) {
+        throw new Error(`no step ${index}`);
+    }
+    const kept = blocks.filter((_, i) => i !== index);
+    return emitFlow(head, preamble, groupBlocks(kept));
+}
+/** Blocks → the group structure they currently describe. */
+function groupBlocks(blocks) {
+    const map = new Map();
+    for (const b of blocks)
+        map.set(b.group, [...(map.get(b.group) ?? []), b]);
+    return [...map.entries()].sort((a, b) => a[0] - b[0]).map(([, v]) => v);
+}
+export function listFlows(tenant, workspace) {
+    const dir = path.join(workspaceDir(tenant, workspace), "flows");
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .map((f) => parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8")));
+}
+/**
+ * Every account this installation holds.
+ *
+ * A tenant is a directory under the data root, but not every directory there
+ * is one — `.runtimes/` sits beside them, and so do keys.json and the secret
+ * key. What makes a tenant is that it holds workspaces, so that is the test.
+ *
+ * Single-workspace mode has no accounts at all: the workspace *is* the whole
+ * installation, and there is nothing above it to enumerate.
+ */
+export function listTenants() {
+    if (singleWorkspace())
+        return [];
+    const root = dataRoot();
+    if (!fs.existsSync(root))
+        return [];
+    return fs
+        .readdirSync(root)
+        .filter((name) => SAFE_NAME.test(name))
+        .filter((name) => {
+        const dir = path.join(root, name);
+        try {
+            if (!fs.statSync(dir).isDirectory())
+                return false;
+        }
+        catch {
+            return false;
+        }
+        return [WORKSPACES, LEGACY_WORKSPACES].some((w) => fs.existsSync(path.join(dir, w)));
+    })
+        .sort();
+}
+export function listWorkspaces(tenant) {
+    assertSafeName(tenant, "tenant");
+    const dir = workspacesRoot(tenant);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((n) => fs.statSync(path.join(dir, n)).isDirectory())
+        .map((name) => {
+        const pDir = path.join(dir, name);
+        // AGENTS.md is the workspace's config file; project.md is the name it
+        // had before. Take the first NON-EMPTY description across both — not the
+        // first file that merely exists. A workspace with both files but a
+        // description only in project.md (AGENTS.md carrying just `notify:`, say)
+        // otherwise shows blank, because the old code broke on file-exists.
+        let description = "";
+        for (const file of ["AGENTS.md", "project.md"]) {
+            const p = path.join(pDir, file);
+            if (!fs.existsSync(p))
+                continue;
+            try {
+                const d = matter(fs.readFileSync(p, "utf8")).data.description ?? "";
+                if (d) {
+                    description = d;
+                    break;
+                }
+            }
+            catch {
+                // an unreadable file is not a description; try the next
+            }
+        }
+        const runsDir = path.join(pDir, "runs");
+        let preview;
+        try {
+            preview = JSON.parse(fs.readFileSync(path.join(dir, `.${name}.preview.json`), "utf8"));
+        }
+        catch {
+            // not a preview
+        }
+        return {
+            name,
+            description,
+            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,
+            ...(preview ? { preview } : {}),
+        };
+    })
+        .sort((a, b) => b.deployedAt.localeCompare(a.deployedAt));
+}
+// ---------- 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;
+/**
+ * May this path be edited — and therefore, must it be listed?
+ *
+ * The listing and the writer used to answer this separately, and drifted
+ * twice. First `state/notes.md` could be written and never appeared; that was
+ * fixed by adding a state rule to the listing. Then folder tools arrived and
+ * `tools/x/run.mjs` — the program half of every script tool — was writable,
+ * readable, and invisible in the file tree, so the code you were told to edit
+ * could not be found.
+ *
+ * Writable and invisible is the worst of both. One rule decides now: the
+ * listing asks the writer, so a path that can be saved is a path that shows.
+ */
+export function isEditablePath(rel) {
+    try {
+        assertEditablePath(rel);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertEditablePath(rel) {
+    const norm = path.normalize(rel);
+    if (norm.startsWith("..") || path.isAbsolute(norm))
+        throw new Error(`illegal path: ${rel}`);
+    assertCanonicalCase(norm);
+    if (norm === "project.md" || norm === "AGENTS.md")
+        return norm;
+    if (norm.includes("outputs/"))
+        throw new Error(`not an editable path: ${rel}`);
+    if (/scripts\//.test(norm) && SCRIPT_EXT.test(norm))
+        return norm;
+    if (/^agents\/[^/]+\/skills\/[^/]+\//.test(norm) && SCRIPT_EXT.test(norm))
+        return norm;
+    if (/^(skills|memory|knowledge|tools|state)\//.test(norm) && SCRIPT_EXT.test(norm))
+        return norm;
+    if (/^(agents|flows|evals)\//.test(norm) && norm.endsWith(".md"))
+        return norm;
+    throw new Error(`not an editable path: ${rel}`);
+}
+/** Files under the account directory that exist, are worth showing, and must
+ *  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"]);
+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)) {
+        return "generated bookkeeping, not an authored file.";
+    }
+    if (/^workspaces\/[^/]+\/secrets\.json$/.test(norm)) {
+        return "the workspace vault — encrypted, and never served to a browser.";
+    }
+    return null;
+}
+/** Generated bookkeeping: nobody authored it, no agent reads it, and each has
+ *  a page that presents it properly. Listing it would add rows whose only
+ *  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$/;
+/**
+ * The account directory as it actually is on disk.
+ *
+ * A faithful walk, with one rule for what it leaves out: show what a person
+ * authors or an agent reads. That keeps the path you see the path an agent
+ * types, which is the whole point of the tree — while sparing you rows that
+ * exist only to be refused.
+ *
+ * The vault is not an exception to that rule. Secrets are authored in Settings
+ * and reach an agent as environment variables — never as a file, deliberately,
+ * so that no single read can carry them all off. `secrets.json` is therefore
+ * neither authored here nor read by an agent, and a row that can only refuse
+ * the person who clicks it teaches nothing. The reader still guards it.
+ */
+export function listAccountFiles(tenant, cap = 4000) {
+    const root = accountDir(tenant);
+    if (!fs.existsSync(root))
+        return [];
+    const out = [];
+    const walk = (abs, rel, depth) => {
+        if (out.length >= cap || depth > 8)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (out.length >= cap)
+                return;
+            const next = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isSymbolicLink())
+                continue;
+            // Content-addressed blobs and a run's copied outputs are bytes under a
+            // hash — thousands of names that mean nothing to a reader. The
+            // revision store (.history), the runtime cache (.runtimes, with npm's
+            // _cacache under it) and the file-store indexes (storage/) are the
+            // platform's own bookkeeping: real paths, but not files anyone reads
+            // here, and between them most of what the page used to list.
+            if (/(^|\/)(blobs|outputs|\.results|node_modules|\.git|\.history|\.runtimes|\.npm-cache|_cacache|storage|previews|avatars)$/.test(next))
+                continue;
+            if (ACCOUNT_BOOKKEEPING.test(next))
+                continue;
+            if (e.isDirectory())
+                walk(path.join(abs, e.name), next, depth + 1);
+            else
+                out.push(next);
+        }
+    };
+    walk(root, "", 0);
+    return out;
+}
+/** One file under the account directory, or the reason it will not be served. */
+export function readAccountFile(tenant, rel) {
+    const sealed = accountFileSealed(rel);
+    if (sealed)
+        return { sealed };
+    const norm = rel.replaceAll("\\", "/");
+    if (norm.includes(".."))
+        return { sealed: "path escapes the account directory." };
+    const file = path.join(accountDir(tenant), norm);
+    try {
+        if (fs.statSync(file).size > 512 * 1024)
+            return { sealed: "too large to show here — download it instead." };
+        return { content: fs.readFileSync(file, "utf8") };
+    }
+    catch {
+        return { sealed: "could not be read." };
+    }
+}
+export function listWorkspaceFiles(tenant, workspace) {
+    const dir = workspaceDir(tenant, workspace);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { recursive: true })) {
+        const rel = String(entry);
+        if (/(^|\/)(runs|outputs)\//.test(rel))
+            continue;
+        // Skip anything reached through a symlink — a stray link would otherwise
+        // pull another workspace (or the whole library) into this listing.
+        try {
+            if (fs.lstatSync(path.join(dir, rel)).isSymbolicLink())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        // Generated, not authored — the same reason runs/ is hidden above.
+        if (/(^|\/)\.results\//.test(rel))
+            continue;
+        // Directories are entries too, and a directory is not an editable file.
+        try {
+            if (!fs.statSync(path.join(dir, rel)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        // One rule, asked of the writer — see isEditablePath. The four separate
+        // predicates that used to live here disagreed with it twice, and both
+        // times the symptom was a file you could save and could not see.
+        if (isEditablePath(rel))
+            out.push(rel);
+    }
+    return out.sort();
+}
+export function readWorkspaceFile(tenant, workspace, rel) {
+    const p = path.join(workspaceDir(tenant, workspace), assertEditablePath(rel));
+    if (!fs.existsSync(p))
+        throw new Error(`file not found: ${rel}`);
+    return fs.readFileSync(p, "utf8");
+}
+export function writeWorkspaceFile(tenant, workspace, rel, content, meta = {}) {
+    if (content.length > 256 * 1024)
+        throw new Error("file too large");
+    matter(content); // reject files whose frontmatter doesn't parse
+    const p = path.join(workspaceDir(tenant, workspace), assertEditablePath(rel));
+    const existed = fs.existsSync(p);
+    const before = existed ? fs.readFileSync(p, "utf8") : null;
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    // One trailing newline, never a run of them.
+    //
+    // Models end a document with blank lines — several, sometimes dozens — and
+    // nothing trimmed them, so every save kept whatever the last writer left.
+    // A reader sees it as a file that scrolls for a page after the text stops;
+    // 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`);
+    // 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".
+    const norm = rel.replaceAll("\\", "/");
+    if (/^scripts\//.test(norm) || /(^|\/)scripts\//.test(norm) ||
+        (/^tools\//.test(norm) && !norm.endsWith(".md"))) {
+        fs.chmodSync(p, 0o755);
+    }
+    syncBundleFor(p, existed ? "Update" : "Creation");
+    // 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);
+}
+// 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.
+export function syncBundleFor(file, change) {
+    // Walk up to the bundle root — a concept may sit in a nested section.
+    let dir = path.dirname(file);
+    let hops = 0;
+    while (hops < 6) {
+        const base = path.basename(dir);
+        if (base === "memory" || base === "knowledge")
+            break;
+        dir = path.dirname(dir);
+        hops++;
+    }
+    const kind = path.basename(dir);
+    if (kind !== "memory" && kind !== "knowledge")
+        return;
+    // A workspace- or account-level bundle is a root; an agent's own is nested
+    // inside one, and the spec permits okf_version only at a bundle root.
+    const isRoot = path.basename(path.resolve(dir, "..", "..")) !== "agents";
+    syncIndex(dir, kind === "memory" ? "Memory" : "Knowledge", isRoot);
+    if (change) {
+        appendLog(dir, path.relative(dir, file).split(path.sep).join("/"), change);
+    }
+}
+/**
+ * Rename one editable file. Both ends pass the same gate as a write — a
+ * rename must not be able to move a file somewhere a write couldn't create
+ * it — and an existing target refuses rather than silently replacing
+ * someone's work. Bundle indexes on both sides are re-synced, because a
+ * memory file leaving a bundle is as much a change to its index as one
+ * arriving.
+ */
+/**
+ * Why a path can never be moved or renamed, in a sentence — or null when it
+ * can. One vocabulary for the tree, the API and the tests, because "not an
+ * editable path" told the person *that* they were refused and made them
+ * guess at *why*, when the why is the whole lesson: in this format,
+ * location is meaning.
+ */
+export function anchoredReason(rel) {
+    const norm = rel.replaceAll("\\", "/");
+    const base = norm.split("/").pop();
+    if (norm === "AGENTS.md" || norm === "project.md") {
+        return `${base} is the workspace's own identity — it cannot move; rename or delete the workspace instead`;
+    }
+    if (base === "agent.md") {
+        return "agent.md is the agent because of where it sits — to rename the agent, rename its folder";
+    }
+    if (base === "SKILL.md") {
+        return "SKILL.md names its skill — to rename the skill, rename its folder";
+    }
+    if (base === "tool.md") {
+        return "tool.md names its tool — to rename the tool, rename its folder";
+    }
+    if (/(^|\/)(knowledge|memory)\/(.*\/)?(index|log)\.md$/.test(norm)) {
+        return `${base} is generated from the files around it — it is rebuilt in place on the next write`;
+    }
+    return null;
+}
+export function renameWorkspaceFile(tenant, workspace, from, to, meta = {}) {
+    // Refuse with the reason before any path validation: "not an editable
+    // path" is true of AGENTS.md too, and the generic sentence buries the
+    // specific one worth reading.
+    const why = anchoredReason(from) ?? anchoredReason(to);
+    if (why)
+        throw new Error(why);
+    const dir = workspaceDir(tenant, workspace);
+    const src = path.join(dir, assertEditablePath(from));
+    const dst = path.join(dir, assertEditablePath(to));
+    if (!fs.existsSync(src))
+        throw new Error(`${from} does not exist`);
+    if (fs.existsSync(dst))
+        throw new Error(`${to} already exists`);
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    const moved = deletionsUnder(workspaceDir(tenant, workspace), path.normalize(from).replaceAll("\\", "/"));
+    fs.renameSync(src, dst);
+    // A rename is a deletion and a creation with the same bytes, which is
+    // exactly how git records one and what lets "where did this go" be answered.
+    const toNorm = path.normalize(to).replaceAll("\\", "/");
+    recordRevision(tenant, workspace, [
+        ...moved,
+        ...moved.map((f) => ({
+            path: f.path === path.normalize(from).replaceAll("\\", "/") ? toNorm : f.path.replace(path.normalize(from).replaceAll("\\", "/"), toNorm),
+            before: null,
+            after: f.before,
+        })),
+    ], { message: `renamed ${from} → ${to}`, ...meta });
+    syncBundleFor(src);
+    syncBundleFor(dst, "Update");
+}
+/** Every text file under a path, as revision entries recording deletion. */
+function deletionsUnder(dir, norm) {
+    const abs = path.join(dir, norm);
+    if (!fs.existsSync(abs))
+        return [];
+    if (fs.statSync(abs).isFile()) {
+        return [{ path: norm, before: fs.readFileSync(abs, "utf8"), after: null }];
+    }
+    return fs
+        .readdirSync(abs, { recursive: true })
+        .map(String)
+        .filter((e) => {
+        try {
+            return fs.statSync(path.join(abs, e)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((e) => ({
+        path: `${norm}/${e.split(path.sep).join("/")}`,
+        before: fs.readFileSync(path.join(abs, e), "utf8"),
+        after: null,
+    }));
+}
+export function deleteWorkspacePath(tenant, workspace, rel, meta = {}) {
+    const norm = path.normalize(rel).replaceAll("\\", "/");
+    if (norm.startsWith("..") || path.isAbsolute(norm))
+        throw new Error(`illegal path: ${rel}`);
+    const dir = workspaceDir(tenant, workspace);
+    // The two files a workspace cannot exist without. assertEditablePath lets
+    // them through — they are editable — but editable and deletable are
+    // different claims, and deleting AGENTS.md is deleting the workspace's
+    // own name.
+    // The same sentences the tree and the rename path use — one vocabulary
+    // for "this file is structure, not content". An identity file is only
+    // deletable as its whole folder: agent.md alone leaves a folder that is
+    // no longer an agent but still shadows the name.
+    const anchored = anchoredReason(norm);
+    if (anchored) {
+        if (/(agent|SKILL|tool)\.md$/.test(norm)) {
+            throw new Error(`${norm.split("/").pop()} is its folder's identity — delete the whole folder instead`);
+        }
+        throw new Error(anchored);
+    }
+    // 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)) {
+        const gone = deletionsUnder(dir, norm);
+        fs.rmSync(path.join(dir, norm), { recursive: true, force: true });
+        recordRevision(tenant, workspace, gone, { message: `deleted ${norm}/`, ...meta });
+        return;
+    }
+    const p = path.join(dir, assertEditablePath(norm));
+    const gone = deletionsUnder(dir, norm);
+    fs.rmSync(p, { force: true });
+    recordRevision(tenant, workspace, gone, meta);
+    // A bundle's index must stop naming what is gone.
+    syncBundleFor(p);
+}
+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 });
+}
+/**
+ * What a rename would break, so the caller can say so before doing it.
+ *
+ * The workspace name is not just a directory: it is in every webhook URL *and*
+ * in the token those URLs carry, which is derived from `tenant/workspace/flow`.
+ * So a rename invalidates both halves — an old hook doesn't 404, it fails the
+ * signature check, which reads like an attack rather than a rename. Anything
+ * calling those URLs has to be re-pointed by hand.
+ */
+export function renameImpact(tenant, workspace) {
+    return {
+        webhookFlows: listFlows(tenant, workspace)
+            .filter((f) => f.trigger === "webhook")
+            .map((f) => f.name),
+    };
+}
+/**
+ * Rename a workspace: move the directory, then update the `name:` in AGENTS.md
+ * so the file and its folder don't disagree.
+ *
+ * Runs, state and secrets travel with it — they live inside the directory, so
+ * there is nothing to migrate and nothing to lose.
+ */
+export function renameWorkspace(tenant, from, to) {
+    assertSafeName(to, "workspace");
+    if (from === to)
+        return;
+    const src = workspaceDir(tenant, from);
+    if (!fs.existsSync(src))
+        throw new Error(`workspace ${from} not found`);
+    // Deliberately not workspaceDir(): that returns the *legacy* path when one
+    // exists, and renaming into `projects/` would resurrect the old layout.
+    const dest = singleWorkspace()
+        ? (() => { throw new Error("cannot rename in single-workspace mode"); })()
+        : path.join(dataRoot(), tenant, WORKSPACES, to);
+    if (fs.existsSync(dest))
+        throw new Error(`workspace ${to} already exists`);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.renameSync(src, dest);
+    const agentsMd = path.join(dest, "AGENTS.md");
+    if (fs.existsSync(agentsMd)) {
+        const raw = fs.readFileSync(agentsMd, "utf8");
+        fs.writeFileSync(agentsMd, raw.replace(/^name:.*$/m, `name: ${to}`));
+    }
+}
+/** Set a workspace's description, in AGENTS.md, without touching anything else. */
+export function setWorkspaceDescription(tenant, workspace, description) {
+    const file = path.join(workspaceDir(tenant, workspace), "AGENTS.md");
+    if (!fs.existsSync(file))
+        throw new Error("this workspace has no AGENTS.md");
+    const raw = fs.readFileSync(file, "utf8");
+    const block = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/);
+    if (!block)
+        throw new Error("AGENTS.md has no frontmatter");
+    const [, open, body, close] = block;
+    const lines = body.split("\n");
+    const at = lines.findIndex((l) => /^description:/.test(l));
+    const line = `description: ${description}`;
+    if (at === -1)
+        lines.push(line);
+    else
+        lines[at] = line;
+    fs.writeFileSync(file, raw.replace(open + body + close, open + lines.join("\n") + close));
+}
+/**
+ * Starter files for "+ New workspace" in the dashboard.
+ *
+ * Kept as a name because the API route and its callers use it; the content
+ * lives in starter.ts so this and `foldrun init` cannot drift. They did:
+ * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
+ * so every workspace made from the dashboard was born in the old format.
+ */
+export function templateFiles(workspace) {
+    // The starter minus what only matters on a laptop's disk: .gitignore
+    // guards a local clone's secrets, but the hosted store never keeps
+    // secrets in the tree and saveWorkspace rightly refuses files outside
+    // the workspace's own vocabulary.
+    return starterFiles(workspace).filter((f) => f.path === "AGENTS.md" || IN_WORKSPACE_DIR.test(f.path));
+}
+// Kept as names because routes import them; the content lives in KINDS, which
+// is the single table every creation path reads.
+export const AGENT_TEMPLATE = (name) => KINDS.agents.template(name);
+export const FLOW_TEMPLATE = (name, firstAgent) => KINDS.flows.template(name, { firstAgent });
+// The orchestration patterns a new flow can start from. Each template ships
+// the pattern's syntax filled in with real agent names, because a working
+// example in your own workspace teaches loop:/until:/each: better than any
+// reference page — you rename the instructions, not learn the shape.
+export const FLOW_PATTERNS = ["pipeline", "review-loop", "fan-out", "debate", "router"];
+export function flowPatternTemplate(pattern, name, agents) {
+    // Real agents where they exist, honest placeholders where they don't —
+    // `foldrun check` will point at any placeholder left unrenamed.
+    const a = (i, fallback) => agents[i] ?? agents[0] ?? fallback;
+    const head = `---\nname: ${name}\n---\n\n`;
+    switch (pattern) {
+        case "review-loop":
+            return (head +
+                `1. [[${a(0, "writer")}]] — draft the deliverable\n` +
+                `2. [[${a(1, "reviewer")}]] — review it against the brief; end your reply with APPROVED when it is ready\n` +
+                `   loop: 3\n` +
+                `   until: APPROVED\n`);
+        case "fan-out":
+            return (head +
+                `1. [[${a(0, "lister")}]] — list the items to process, one per line\n` +
+                `2. [[${a(1, "worker")}]] — handle this one item\n` +
+                `   each: lines\n` +
+                `   max: 10\n` +
+                `3. [[${a(2, "summariser")}]] — pull every result into one summary\n`);
+        case "router":
+            return (head +
+                `1. [[${a(0, "classifier")}]] — classify the request: reply with exactly one word, BUG or QUESTION\n` +
+                `2. [[${a(1, "debugger")}]] — investigate and fix the bug\n` +
+                `   case: BUG\n` +
+                `2. [[${a(2, "writer")}]] — answer the question clearly\n` +
+                `   case: QUESTION\n` +
+                `2. [[${a(3, "triager")}]] — neither label fit; say what is missing\n` +
+                `   else: true\n`);
+        case "debate":
+            return (head +
+                `1. [[${a(0, "researcher")}]] — gather the facts\n` +
+                `2. [[${a(1, "advocate")}]] — argue the strongest case for, from the facts\n` +
+                `2. [[${a(2, "skeptic")}]] — argue the strongest case against, from the facts\n` +
+                `3. [[${a(3, "judge")}]] — weigh both cases and give a verdict\n`);
+        default:
+            return FLOW_TEMPLATE(name, a(0, "my-agent"));
+    }
+}
+export function runFilePath(tenant, workspace, runId) {
+    assertSafeName(runId, "run id");
+    return path.join(workspaceDir(tenant, workspace), "runs", `${runId}.json`);
+}
+/**
+ * Erase a run from history: its record and the outputs archived under its
+ * id.
+ *
+ * The ledger line stays, and that is settled rather than provisional: if
+ * deleting a run voided its charge, deletion would be a refund button — run
+ * the expensive extraction, read the result, delete, never pay. Money is
+ * not deleted because a trace was.
+ *
+ * What deletion *does* owe the books is an explanation. A charge pointing
+ * at a run that no longer exists reads as unexplained forever, so the
+ * deletion writes itself down: a zero-value adjustment naming the run, on
+ * the same append-only file the charge lives in. The balance is untouched;
+ * the story is complete.
+ */
+export function deleteRun(tenant, workspace, runId) {
+    const file = runFilePath(tenant, workspace, runId);
+    if (!fs.existsSync(file))
+        return false;
+    fs.rmSync(file, { force: true });
+    fs.rmSync(path.join(workspaceDir(tenant, workspace), "runs", runId), {
+        recursive: true,
+        force: true,
+    });
+    onRunDeleted?.(tenant, workspace, runId);
+    return true;
+}
+/** ledger.ts registers here — store cannot import it without a cycle, and
+ *  money must not depend on one. */
+let onRunDeleted;
+export function registerRunDeletionListener(fn) {
+    onRunDeleted = fn;
+}
+/**
+ * What a run archived: every file its agents left in outputs/, copied under
+ * runs/<id>/outputs/<agent>/ when the run finished (runner.ts, archive()).
+ *
+ * Per agent, not per step — the archive is a copy of each agent's folder,
+ * and the record cannot say which step wrote which file. An agent that
+ * steps twice in one run shows the same files against both steps.
+ */
+export function listRunOutputs(tenant, workspace, runId) {
+    const root = path.join(workspaceDir(tenant, workspace), "runs", runId, "outputs");
+    if (!fs.existsSync(root))
+        return [];
+    const out = [];
+    const walk = (agent, dir, rel) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, e.name);
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory())
+                walk(agent, full, r);
+            else if (e.isFile())
+                out.push({ agent, path: r, bytes: fs.statSync(full).size });
+        }
+    };
+    for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+        if (e.isDirectory())
+            walk(e.name, path.join(root, e.name), "");
+    }
+    return out.sort((a, b) => a.agent.localeCompare(b.agent) || a.path.localeCompare(b.path));
+}
+/** The absolute path of one archived output, or null when the name escapes
+ *  the archive or names nothing — the API serves only what this returns. */
+export function runOutputPath(tenant, workspace, runId, agent, rel) {
+    if (!agent || !rel || agent.includes("/") || agent.includes("\\") || agent.startsWith("."))
+        return null;
+    const root = path.resolve(workspaceDir(tenant, workspace), "runs", runId, "outputs", agent);
+    const full = path.resolve(root, rel);
+    if (full !== root && !full.startsWith(root + path.sep))
+        return null;
+    if (!fs.existsSync(full) || !fs.statSync(full).isFile())
+        return null;
+    return full;
+}
+export function readRun(tenant, workspace, runId) {
+    const p = runFilePath(tenant, workspace, runId);
+    return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+}
+export function writeRun(tenant, workspace, run) {
+    const p = runFilePath(tenant, workspace, run.id);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    // Atomic write — runs are re-read while running (dashboard polls, CLI
+    // tails), and a plain writeFileSync can be caught half-written.
+    const tmp = `${p}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(run, null, 2));
+    fs.renameSync(tmp, p);
+}
+export function listAllRuns(tenant) {
+    return listWorkspaces(tenant)
+        .flatMap((p) => listRuns(tenant, p.name).map((r) => ({ ...r, workspace: p.name })))
+        .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+/**
+ * The status a person should see. "failed" and "someone stopped it" are
+ * different facts — the record keeps them apart (stopRequested), and the
+ * display must too: a run a person chose to end is not a run that broke,
+ * and showing it red teaches people that stopping things is dangerous.
+ */
+export function runDisplayStatus(run) {
+    return run.status === "failed" && run.stopRequested ? "stopped" : run.status;
+}
+export function runCost(run) {
+    return run.steps.reduce((sum, s) => sum + (s.costUsd ?? 0), 0);
+}
+/**
+ * What a finished run consumed, in the units the format itself has — the
+ * shape ledger.ts prices. Structural, not an import, because ledger.ts
+ * imports this module and money must not depend on a cycle.
+ *
+ * Only steps that actually ran count. A pending step never happened, a
+ * skipped one was skipped by the flow's own `when`, and an `expanded`
+ * fan-out template is a row in the trace rather than work — billing any of
+ * them would charge for steps the customer can see never executed, which is
+ * the fastest way to lose an argument about an invoice.
+ */
+export function runMeter(run) {
+    let steps = 0;
+    let computeSecs = 0;
+    let smallSecs = 0;
+    let netBytes = 0;
+    for (const s of run.steps) {
+        if (s.status !== "completed" && s.status !== "failed")
+            continue;
+        // A carried step ran — and was billed — in the run it was carried from.
+        if (s.carriedFrom)
+            continue;
+        steps += 1;
+        const secs = s.computeSecs ?? 0;
+        computeSecs += secs;
+        if (s.size === "small")
+            smallSecs += secs;
+        netBytes += (s.actual?.rxBytes ?? 0) + (s.actual?.txBytes ?? 0);
+    }
+    return { tokenCostUsd: runCost(run), steps, computeSecs, smallSecs, netBytes };
+}
+/**
+ * The compute meter for hold+work pricing: core-seconds and GiB-seconds
+ * actually reserved (from each step's own recorded reservation), and CPU
+ * seconds actually burned (from the sandbox's cgroup, where readable).
+ * Steps with no recorded reservation contribute plain seconds only — the
+ * flat-rate fallback prices those.
+ */
+export function runComputeMeter(run) {
+    let coreSecs = 0, gibSecs = 0, busyCpuSecs = 0, flatSecs = 0;
+    for (const s of run.steps) {
+        if (s.status !== "completed" && s.status !== "failed")
+            continue;
+        if (s.carriedFrom)
+            continue;
+        const secs = s.computeSecs ?? 0;
+        if (secs <= 0)
+            continue;
+        if (s.reserved) {
+            coreSecs += secs * s.reserved.cpus;
+            gibSecs += secs * s.reserved.memGiB;
+        }
+        else {
+            flatSecs += secs;
+        }
+        busyCpuSecs += s.actual?.busyCpuSecs ?? 0;
+    }
+    return { coreSecs, gibSecs, busyCpuSecs, flatSecs };
+}
+export function runDurationSecs(run) {
+    if (!run.finishedAt)
+        return null;
+    return (new Date(run.finishedAt).getTime() - new Date(run.startedAt).getTime()) / 1000;
+}
+/**
+ * Why a failed run failed, said in one line: the failing step and its last
+ * error event. The journal has the whole story; a runs *list* needs the
+ * sentence — "failed" with no reason makes every diagnosis start by opening
+ * the run, and the answer was sitting in the record all along.
+ */
+export function runFailure(run) {
+    if (run.status !== "failed")
+        return null;
+    const step = run.steps.find((s) => s.status === "failed");
+    if (!step)
+        return null;
+    const errors = step.events.filter((e) => e.type === "error");
+    const last = errors[errors.length - 1];
+    return { agent: step.agent, reason: last?.text ?? "failed without an error event" };
+}
+/**
+ * The one-line outcome, pulled out of the reply that already says it.
+ *
+ * The last step with a result, because that is the one that concluded —
+ * a reporter at the end of a flow, or on a failed run whatever got furthest,
+ * which is the most informative line available either way.
+ *
+ * Markdown decoration is stripped rather than rendered: this lands in an
+ * email subject and a table cell, where `## ` and `**` are noise. Sibling of
+ * runFailure, which puts the reason for a failure on the list for the same
+ * reason — the sentence was in the record all along.
+ */
+export function runSummary(run) {
+    for (let i = run.steps.length - 1; i >= 0; i--) {
+        const line = stepHeadline(run.steps[i]);
+        if (line)
+            return line;
+    }
+    return null;
+}
+/**
+ * What one step concluded, in a line.
+ *
+ * The model's ANSWER first, falling back to the whole reply. `result` is every
+ * text block joined, and a model that narrates before calling a tool puts
+ * "Now let me read the outputs…" at the top of it — so reading the joined
+ * text reported the plan of every step that used a tool, which is most of
+ * them. Steps recorded before `conclusion` existed have only `result`, and
+ * for those this is exactly what it always was.
+ */
+export function stepHeadline(step) {
+    return headlineOf(step.conclusion) ?? headlineOf(step.result);
+}
+/**
+ * The first line of a reply that a person would recognise as its point.
+ *
+ * Markdown decoration is stripped rather than skipped, so a reply that opens
+ * with `## Done: 4 findings` still has a headline. A line that is only
+ * punctuation — a bare `#`, a rule, a row of asterisks — is decoration, and a
+ * code fence is the shape of an `output: json` reply, not its headline.
+ *
+ * Exported because a run's summary and one agent's step both want it, and two
+ * copies would be two answers to the same question.
+ */
+export function headlineOf(result) {
+    if (!result)
+        return null;
+    for (const raw of result.split("\n")) {
+        const line = raw
+            .replace(/^\s*#{1,6}\s+/, "") // heading
+            .replace(/^\s*[-*+]\s+/, "") // bullet
+            .replace(/^\s*>\s?/, "") // quote
+            .replace(/\*\*/g, "")
+            .replace(/\s+/g, " ")
+            .trim();
+        // A line that is only markdown punctuation — a bare `#`, a `---` rule,
+        // a row of asterisks — is decoration, not a headline. Checked after the
+        // strips above rather than folded into them, because `#{1,6}\s*` would
+        // also eat the hash in a line that legitimately opens "#1 priority".
+        // A code fence, or a line that is only brackets, is the shape of an
+        // `output: json` reply, not its headline either.
+        if (!line || /^[#>\-*_=\s`{}\[\],]*$/.test(line) || line.startsWith("```"))
+            continue;
+        return line.length > 200 ? `${line.slice(0, 197)}…` : line;
+    }
+    return null;
+}
+/**
+ * Everything one agent has done, newest first.
+ *
+ * The runs list answers "what ran"; it is keyed by flow, so an agent that
+ * appears in four flows has its work scattered across four filters and an
+ * agent used by none is invisible unless someone remembers the `adhoc:`
+ * prefix. This is the other axis, and the one you want when the question is
+ * "is this agent any good" rather than "did Monday's flow finish".
+ */
+/** Path refusals in a step — see deniedPaths in the dashboard's
+ *  step-io-model, which is the pure copy the client can import. */
+export function deniedPaths(step) {
+    return (step.events ?? []).filter((e) => / was denied: /.test(e.text ?? "")).length;
+}
+export function listAgentSteps(tenant, workspace, agent) {
+    const out = [];
+    for (const run of listRuns(tenant, workspace)) {
+        for (const step of run.steps) {
+            if (step.agent !== agent)
+                continue;
+            // A fan-out template expands into instances and produces nothing
+            // itself; listing it would be a row that never has a result.
+            if (step.status === "expanded")
+                continue;
+            out.push({
+                runId: run.id,
+                flow: run.flow,
+                status: run.status,
+                startedAt: run.startedAt,
+                headline: stepHeadline(step),
+                instruction: step.instruction,
+                stepStatus: step.status,
+                costUsd: step.costUsd,
+                item: step.item,
+                denied: deniedPaths(step),
+            });
+        }
+    }
+    return out;
+}
+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"))
+        .map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")))
+        .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+// RFC 9110 field-name characters. Anything else is not a header, and a
+// gateway would reject it — better to say so here than to have the run fail
+// with someone else's error message.
+const HEADER_NAME_RE = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+export function parseProvider(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const block = raw;
+    const warnings = [];
+    // A name resolves to defaults; anything spelled out beside it wins. An
+    // unknown name is a warning and the block reads as if it were absent,
+    // because guessing a URL from a name is how a key ends up at a stranger.
+    const preset = providerPreset(block.name);
+    if (block.name !== undefined && !preset) {
+        warnings.push(`provider.name: "${String(block.name)}" is not a provider this runtime knows — spell out base_url, format and auth instead`);
+    }
+    const baseUrl = (typeof block.base_url === "string" ? block.base_url.trim() : "") || preset?.baseUrl || "";
+    const token = typeof block.token === "string" ? block.token.trim() : "";
+    const formatRaw = typeof block.format === "string" ? block.format.trim().toLowerCase() : "";
+    let format = preset?.format ?? "anthropic";
+    if (formatRaw === "anthropic" || formatRaw === "openai" || formatRaw === "responses")
+        format = formatRaw;
+    else if (formatRaw)
+        warnings.push(`provider.format: "${formatRaw}" is not anthropic, openai or responses — using ${format}`);
+    const authRaw = typeof block.auth === "string" ? block.auth.trim().toLowerCase() : "";
+    let auth = preset?.auth ?? "bearer";
+    if (authRaw === "bearer" || authRaw === "x-api-key")
+        auth = authRaw;
+    else if (authRaw === "api-key" || authRaw === "key" || authRaw === "header")
+        auth = "x-api-key";
+    else if (authRaw)
+        warnings.push(`provider.auth: "${authRaw}" is not bearer or x-api-key — using ${auth}`);
+    if (preset && !baseUrl) {
+        warnings.push(`provider.name: ${preset.name} needs a base_url — ${preset.note ?? "its address is per account"}`);
+    }
+    // A pasted Chat-Completions URL with no format: the runtime would speak
+    // Anthropic at it and get a 404 from the wrong path. Said here, at the
+    // file, not there.
+    if (format === "anthropic" && !preset && baseUrl && looksOpenAiShaped(baseUrl)) {
+        warnings.push(`provider.base_url looks like a Chat-Completions endpoint — add \`format: openai\` to reach it through the translator`);
+    }
+    const models = {};
+    if (block.models && typeof block.models === "object" && !Array.isArray(block.models)) {
+        for (const [key, value] of Object.entries(block.models)) {
+            const tier = resolveTier(key);
+            if (!tier) {
+                warnings.push(`provider.models: "${key}" is not a tier — use ${Object.keys(MODEL_TIERS).join(", ")}. Ignored.`);
+                continue;
+            }
+            const id = typeof value === "string" ? value.trim() : "";
+            if (!id) {
+                warnings.push(`provider.models.${key}: empty — ignored`);
+                continue;
+            }
+            models[tier] = id;
+        }
+    }
+    else if (block.models !== undefined) {
+        warnings.push("provider.models: expected a map of tier → model id — ignored");
+    }
+    // `params:` — the provider's own request fields, passed through as
+    // written. Not validated against any vendor's schema: the endpoint is the
+    // authority on what it accepts, and a list here would be stale in a month.
+    const params = {};
+    if (block.params && typeof block.params === "object" && !Array.isArray(block.params)) {
+        for (const [key, value] of Object.entries(block.params)) {
+            const name = key.trim();
+            if (!name)
+                continue;
+            if (PROTECTED_PARAMS.includes(name)) {
+                warnings.push(`provider.params.${name}: that is the conversation, not a setting — ignored`);
+                continue;
+            }
+            params[name] = value;
+        }
+    }
+    else if (block.params !== undefined) {
+        warnings.push("provider.params: expected a map of field → value — ignored");
+    }
+    if (Object.keys(params).length && format === "anthropic") {
+        warnings.push("provider.params only reaches a `format: openai` or `format: responses` endpoint — an Anthropic-shaped one is spoken to directly, so set its knobs at the provider (an OpenRouter preset, say) instead");
+    }
+    const headers = {};
+    if (block.headers && typeof block.headers === "object" && !Array.isArray(block.headers)) {
+        for (const [name, value] of Object.entries(block.headers)) {
+            const key = name.trim();
+            if (!HEADER_NAME_RE.test(key)) {
+                warnings.push(`provider.headers: "${name}" is not a valid header name — ignored`);
+                continue;
+            }
+            const text = value == null ? "" : String(value);
+            // A newline in a value would end the header and start another one —
+            // the whole point of a separator-delimited blob is that nothing in it
+            // may contain the separator.
+            if (/[\r\n]/.test(text)) {
+                warnings.push(`provider.headers.${key}: value contains a line break — ignored`);
+                continue;
+            }
+            headers[key] = text.trim();
+        }
+    }
+    else if (block.headers !== undefined) {
+        warnings.push("provider.headers: expected a map of name → value — ignored");
+    }
+    // One level only: the nested block's own `fallback:` is dropped, with a
+    // word about it, rather than followed.
+    let fallback = null;
+    if (block.fallback !== undefined) {
+        const inner = parseProvider(block.fallback);
+        if (!inner || !inner.baseUrl)
+            warnings.push("provider.fallback: needs a base_url — ignored");
+        else {
+            if (inner.fallback)
+                warnings.push("provider.fallback.fallback: only one level of fallback is followed — ignored");
+            fallback = { ...inner, fallback: null };
+            warnings.push(...inner.warnings.map((w) => `fallback: ${w}`));
+        }
+    }
+    return { name: preset?.name ?? null, format, auth, baseUrl, token, models, headers, params, warnings, fallback };
+}
+/** The env the SDK reads for a tier remap. Our tier names are ours; these
+ *  are the SDK's, and this function is the only place the two meet. */
+const TIER_ENV = {
+    fast: "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    default: "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    max: "ANTHROPIC_DEFAULT_OPUS_MODEL",
+};
+/**
+ * The whole of a provider block as the env the Agent SDK reads. The one
+ * place our format meets the SDK's, so the mapping is testable without a
+ * vault: the caller resolves `${SECRET}` first and passes values.
+ *
+ * The token goes to ANTHROPIC_AUTH_TOKEN (a bearer credential) and
+ * ANTHROPIC_API_KEY is explicitly blanked. Both matter. A key left in the
+ * environment is sent as `x-api-key` and treated as a direct-Anthropic
+ * credential, so a gateway that wants `Authorization: Bearer` gets the
+ * wrong header — and worse, an *unset* key lets the SDK fall back to
+ * authenticating against Anthropic directly, which fails somewhere far from
+ * the file that caused it. A gateway that genuinely wants the key header
+ * asks for it by name: `headers: { x-api-key: ${TOKEN} }`.
+ */
+export function providerEnvFor(spec) {
+    const env = {};
+    if (spec.baseUrl)
+        env.ANTHROPIC_BASE_URL = spec.baseUrl;
+    if (spec.token) {
+        if (spec.auth === "x-api-key") {
+            env.ANTHROPIC_API_KEY = spec.token;
+            env.ANTHROPIC_AUTH_TOKEN = "";
+        }
+        else {
+            env.ANTHROPIC_AUTH_TOKEN = spec.token;
+            env.ANTHROPIC_API_KEY = "";
+        }
+    }
+    for (const [tier, id] of Object.entries(spec.models)) {
+        if (id)
+            env[TIER_ENV[tier]] = id;
+    }
+    const lines = Object.entries(spec.headers).map(([k, v]) => `${k}: ${v}`);
+    if (lines.length)
+        env.ANTHROPIC_CUSTOM_HEADERS = lines.join("\n");
+    return env;
+}
+// The workspace tree, for history's first commit — see registerTreeReader.
+registerTreeReader((tenant, scope) => {
+    if (scope === "@library" || !fs.existsSync(workspaceDir(tenant, scope)))
+        return null;
+    const dir = workspaceDir(tenant, scope);
+    return listWorkspaceFiles(tenant, scope).flatMap((rel) => {
+        try {
+            return [{ path: rel, before: null, after: fs.readFileSync(path.join(dir, rel), "utf8") }];
+        }
+        catch {
+            return [];
+        }
+    });
+});