@foldrun/core 0.3.0 → 0.5.0

package/dist/src/secrets.js

@@ -22,21 +22,47 @@ import fs from "node:fs";
 import path from "node:path";
 import { dataRoot } from "./paths.js";
 import { platform } from "./platform.js";
+import { fetchUntrusted } from "./untrusted-fetch.js";
+/**
+ * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
+ * `authTagLength`, Node accepts whatever length `setAuthTag` is handed — 4, 8,
+ * 12, 13, 14, 15 or 16 bytes — so a stored record whose tag had been cut to
+ * four bytes would still "verify" on 32 bits of authentication instead of
+ * 128. The tag comes from the record on disk; the record is the thing an
+ * attacker with file access would edit. One option makes a short tag an
+ * error rather than a weaker check.
+ */
+const GCM = { authTagLength: 16 };
 // The account's own data key, when the platform holds one; the install key
 // otherwise. See platform.ts — locally there is no account key.
 const tenantKey = (tenant) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.js";
+import { trimSlashes } from "./paths.js";
 const keyFile = () => path.join(dataRoot(), ".secret-key");
-function masterKey() {
+/**
+ * The install's root secret, as text: FOLDRUN_SECRET_KEY when set, else the
+ * contents of `.secret-key` under the data root — created here, the first
+ * time anything asks, so there is never a moment when a derived token has
+ * nothing real to hang off. The vault, hook tokens, approval links and git
+ * push secrets all derive from this one value; rotating it invalidates every
+ * one of them together. Exported for webhook.ts, which used to fall back to
+ * a fixed dev string until the vault happened to create this file — so hook
+ * URLs were computable by anyone who read the source, and then changed the
+ * first time a secret was stored.
+ */
+export function installKeyMaterial() {
     const fromEnv = process.env.FOLDRUN_SECRET_KEY;
     if (fromEnv)
-        return crypto.createHash("sha256").update(fromEnv).digest();
+        return fromEnv;
     fs.mkdirSync(dataRoot(), { recursive: true });
     if (!fs.existsSync(keyFile())) {
         fs.writeFileSync(keyFile(), crypto.randomBytes(32).toString("hex"), { mode: 0o600 });
     }
-    return crypto.createHash("sha256").update(fs.readFileSync(keyFile(), "utf8")).digest();
+    return fs.readFileSync(keyFile(), "utf8");
+}
+function masterKey() {
+    return crypto.createHash("sha256").update(installKeyMaterial()).digest();
 }
 // `workspace` undefined means the account store.
 function secretsFile(tenant, workspace) {
@@ -50,20 +76,83 @@ function secretsFile(tenant, workspace) {
     return path.join(base, "secrets.json");
 }
 function read(tenant, workspace) {
-    const f = secretsFile(tenant, workspace);
-    if (!fs.existsSync(f))
+    return readFile(secretsFile(tenant, workspace));
+}
+// ------------------------------------------------------------ safe writes
+//
+// A vault file is read, changed and written back. It was written in place,
+// with no lock: two saves at once kept one; a crash mid-write left half a
+// file, which is an account that cannot authenticate anything; and the boot
+// re-wrap ran in every pod at once through ONE shared temp name, so two pods
+// could interleave into it and rename a corrupt file into place.
+//
+// Now every change goes through mutateVaultFile: an exclusive lock file
+// (O_EXCL, which NFS 4.1 and EFS honour, so it holds across pods), the read
+// and the change under it, a temp file unique to this writer, and a rename —
+// atomic on the same filesystem, so a reader sees the old file or the new
+// one, never half. A lock older than LOCK_STALE_MS is a crashed holder.
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 10_000;
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function readFile(file) {
+    if (!fs.existsSync(file))
         return {};
     try {
-        return JSON.parse(fs.readFileSync(f, "utf8"));
+        return JSON.parse(fs.readFileSync(file, "utf8"));
     }
     catch {
         return {};
     }
 }
-function write(tenant, workspace, data) {
-    const f = secretsFile(tenant, workspace);
-    fs.mkdirSync(path.dirname(f), { recursive: true });
-    fs.writeFileSync(f, JSON.stringify(data, null, 2), { mode: 0o600 });
+function lockVault(file) {
+    const lock = `${file}.lock`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            const fd = fs.openSync(lock, "wx", 0o600);
+            fs.writeSync(fd, `${process.pid}@${new Date().toISOString()}`);
+            fs.closeSync(fd);
+            return () => fs.rmSync(lock, { force: true });
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+                    fs.rmSync(lock, { force: true }); // a holder that died; take it over
+                    continue;
+                }
+            }
+            catch {
+                continue; // released between the open and the stat
+            }
+            if (Date.now() > deadline)
+                throw new Error("the vault is busy — another change is being saved; try again");
+            sleep(25);
+        }
+    }
+}
+/**
+ * Change one vault file safely: `change` gets what is stored now and returns
+ * the new contents, or null to leave the file untouched. Returns what is
+ * stored after.
+ */
+export function mutateVaultFile(file, change) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const release = lockVault(file);
+    try {
+        const current = readFile(file);
+        const next = change(structuredClone(current));
+        if (next === null)
+            return current;
+        const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return next;
+    }
+    finally {
+        release();
+    }
 }
 export const SECRET_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
 export function setSecret(tenant, name, value, workspace, kind) {
@@ -73,13 +162,14 @@ export function setSecret(tenant, name, value, workspace, kind) {
     if (value.length > 8192)
         throw new Error("secret too long");
     const sealed = encryptValue(tenant, value);
-    const all = read(tenant, workspace);
-    all[name] = {
-        ...sealed,
-        updatedAt: new Date().toISOString(),
-        ...(kind ? { kind } : {}),
-    };
-    write(tenant, workspace, all);
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        all[name] = {
+            ...sealed,
+            updatedAt: new Date().toISOString(),
+            ...(kind ? { kind } : {}),
+        };
+        return all;
+    });
 }
 /**
  * Which key writes this account's records.
@@ -98,7 +188,7 @@ function keyFor(tenant) {
 export function encryptValue(tenant, value) {
     const { key, mark } = keyFor(tenant);
     const iv = crypto.randomBytes(12);
-    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv, GCM);
     const enc = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
     return {
         iv: iv.toString("base64"),
@@ -134,7 +224,7 @@ function decrypt(tenant, rec) {
         else {
             key = masterKey();
         }
-        const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(rec.iv, "base64"));
+        const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(rec.iv, "base64"), GCM);
         decipher.setAuthTag(Buffer.from(rec.tag, "base64"));
         return Buffer.concat([
             decipher.update(Buffer.from(rec.data, "base64")),
@@ -165,9 +255,12 @@ export function getSecret(tenant, name, workspace) {
     return shared === null ? null : { value: shared, scope: "account" };
 }
 export function deleteSecret(tenant, name, workspace) {
-    const all = read(tenant, workspace);
-    delete all[name];
-    write(tenant, workspace, all);
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        if (!(name in all))
+            return null;
+        delete all[name];
+        return all;
+    });
 }
 // Metadata only — never values. Without a workspace this lists the account
 // store; with one it lists what that workspace actually resolves, marking
@@ -263,47 +356,47 @@ export function rotateMasterKey(tenant, from, to) {
     const rewritten = [];
     const unreadable = [];
     for (const { file } of secretFiles(tenant)) {
-        const all = JSON.parse(fs.readFileSync(file, "utf8"));
-        const next = {};
         let count = 0;
-        for (const [name, rec] of Object.entries(all)) {
-            // A record under the ACCOUNT's key is not under the install key, so
-            // rotating the install key must not touch it — re-encrypting it here
-            // with a key it was never sealed with is how a rotation would destroy a
-            // vault it was meant to protect. Rotating the install key now re-wraps
-            // the account keys instead, which is a handful of small values rather
-            // than every secret on the box.
-            if (rec.k === "tenant") {
-                next[name] = rec;
-                continue;
-            }
-            let plain;
-            try {
-                const d = crypto.createDecipheriv("aes-256-gcm", oldKey, Buffer.from(rec.iv, "base64"));
-                d.setAuthTag(Buffer.from(rec.tag, "base64"));
-                plain = Buffer.concat([d.update(Buffer.from(rec.data, "base64")), d.final()]).toString("utf8");
-            }
-            catch {
-                unreadable.push(name);
-                next[name] = rec; // untouched
-                continue;
+        mutateVaultFile(file, (all) => {
+            const next = {};
+            for (const [name, rec] of Object.entries(all)) {
+                // A record under the ACCOUNT's key is not under the install key, so
+                // rotating the install key must not touch it — re-encrypting it here
+                // with a key it was never sealed with is how a rotation would destroy a
+                // vault it was meant to protect. Rotating the install key now re-wraps
+                // the account keys instead, which is a handful of small values rather
+                // than every secret on the box.
+                if (rec.k === "tenant") {
+                    next[name] = rec;
+                    continue;
+                }
+                let plain;
+                try {
+                    const d = crypto.createDecipheriv("aes-256-gcm", oldKey, Buffer.from(rec.iv, "base64"), GCM);
+                    d.setAuthTag(Buffer.from(rec.tag, "base64"));
+                    plain = Buffer.concat([d.update(Buffer.from(rec.data, "base64")), d.final()]).toString("utf8");
+                }
+                catch {
+                    unreadable.push(name);
+                    next[name] = rec; // untouched
+                    continue;
+                }
+                const iv = crypto.randomBytes(12);
+                const c = crypto.createCipheriv("aes-256-gcm", newKey, iv, GCM);
+                const enc = Buffer.concat([c.update(plain, "utf8"), c.final()]);
+                next[name] = {
+                    iv: iv.toString("base64"),
+                    tag: c.getAuthTag().toString("base64"),
+                    data: enc.toString("base64"),
+                    updatedAt: rec.updatedAt, // rotation is not an edit
+                    // Kept: without it an oauth2 secret stops being refreshed after a
+                    // rotation, and a file/ssh/api secret stops being materialised.
+                    ...(rec.kind ? { kind: rec.kind } : {}),
+                };
+                count++;
             }
-            const iv = crypto.randomBytes(12);
-            const c = crypto.createCipheriv("aes-256-gcm", newKey, iv);
-            const enc = Buffer.concat([c.update(plain, "utf8"), c.final()]);
-            next[name] = {
-                iv: iv.toString("base64"),
-                tag: c.getAuthTag().toString("base64"),
-                data: enc.toString("base64"),
-                updatedAt: rec.updatedAt, // rotation is not an edit
-            };
-            count++;
-        }
-        // Write via a temp file in the same directory: a half-written secrets.json
-        // is an account that cannot authenticate anything.
-        const tmp = `${file}.rotating`;
-        fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
-        fs.renameSync(tmp, file);
+            return next;
+        });
         rewritten.push({ file, secrets: count });
     }
     return { rewritten, unreadable };
@@ -347,12 +440,12 @@ async function exchange(config, cacheKey) {
             client_secret: config.client_secret,
             ...(config.extra ?? {}),
         });
-        const res = await fetch(config.token_url, {
+        const res = await fetchUntrusted(config.token_url, {
             method: "POST",
             headers: { "content-type": "application/x-www-form-urlencoded" },
             body: body.toString(),
             signal: AbortSignal.timeout(15_000),
-        });
+        }, { sameOrigin: true });
         const payload = (await res.json().catch(() => ({})));
         if (!res.ok || !payload.access_token) {
             throw new Error(`token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
@@ -376,7 +469,10 @@ async function exchange(config, cacheKey) {
  * refresh throws with the secret's name and the provider's reason — a run
  * should fail saying "GOOGLE_ADS_TOKEN: invalid_grant", not 401 somewhere.
  */
-export async function materializeSecrets(env) {
+export async function materializeSecrets(env, 
+/** Whose secrets these are, when the caller knows: lets the platform keep
+ *  each OAuth connection's health and quote a reconnect link on failure. */
+ctx) {
     const out = { ...env };
     for (const [name, value] of Object.entries(env)) {
         if (typeof value !== "string")
@@ -399,8 +495,12 @@ export async function materializeSecrets(env) {
                 out[name] = await exchange(config, `${name}:${config.client_id}:${fp}`);
             }
             catch (err) {
-                throw new Error(`secret ${name}: ${err instanceof Error ? err.message : String(err)}`);
+                const message = err instanceof Error ? err.message : String(err);
+                const link = ctx ? await platform.noteOAuthRefresh(ctx, name, message).catch(() => undefined) : undefined;
+                throw new Error(`secret ${name}: ${message}${link ? ` — reconnect it in one click: ${link}` : ""}`);
             }
+            if (ctx)
+                await platform.noteOAuthRefresh(ctx, name, null).catch(() => undefined);
         }
         else if (value.startsWith(SERVICE_ACCOUNT_PREFIX)) {
             let config;
@@ -437,7 +537,7 @@ export function setServiceAccountSecret(tenant, name, config, workspace) {
         if (!config[field]?.trim())
             throw new Error(`service account secret needs ${field}`);
     }
-    if (!/BEGIN [A-Z ]*PRIVATE KEY/.test(config.private_key)) {
+    if (!/BEGIN [A-Z ]{0,40}PRIVATE KEY/.test(config.private_key)) {
         throw new Error("private_key must be a PEM key (from the service account JSON)");
     }
     setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(config), workspace, "service-account");
@@ -467,7 +567,7 @@ async function exchangeServiceAccount(config, cacheKey) {
         signer.update(`${header}.${claim}`);
         const signature = base64url(signer.sign(config.private_key));
         const jwt = `${header}.${claim}.${signature}`;
-        const res = await fetch(config.token_url, {
+        const res = await fetchUntrusted(config.token_url, {
             method: "POST",
             headers: { "content-type": "application/x-www-form-urlencoded" },
             body: new URLSearchParams({
@@ -475,7 +575,7 @@ async function exchangeServiceAccount(config, cacheKey) {
                 assertion: jwt,
             }).toString(),
             signal: AbortSignal.timeout(15_000),
-        });
+        }, { sameOrigin: true });
         const payload = (await res.json().catch(() => ({})));
         if (!res.ok || !payload.access_token) {
             throw new Error(`service account exchange failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token"}`);
@@ -534,7 +634,7 @@ export function setSshSecret(tenant, name, config, workspace) {
     const hasPassword = Boolean(config.password);
     if (hasKey === hasPassword)
         throw new Error("ssh secret needs a private key or a password (not both)");
-    if (hasKey && !/BEGIN [A-Z ]*PRIVATE KEY/.test(config.private_key)) {
+    if (hasKey && !/BEGIN [A-Z ]{0,40}PRIVATE KEY/.test(config.private_key)) {
         throw new Error("private_key must be a PEM/OpenSSH private key");
     }
     if (hasPassword && /[\n\r]/.test(config.password))
@@ -571,7 +671,7 @@ export function setApiSecret(tenant, name, config, workspace) {
     const base = config.base_url?.trim();
     if (base && !/^https?:\/\//.test(base))
         throw new Error("base_url must be http(s)");
-    setSecret(tenant, name, API_PREFIX + JSON.stringify({ ...(base ? { base_url: base.replace(/\/+$/, "") } : {}), headers: config.headers }), workspace, "api");
+    setSecret(tenant, name, API_PREFIX + JSON.stringify({ ...(base ? { base_url: trimSlashes(base) } : {}), headers: config.headers }), workspace, "api");
 }
 export function isApiValue(value) {
     return value.startsWith(API_PREFIX);
@@ -594,33 +694,34 @@ export function rewrapTenantSecrets(tenant) {
     let moved = 0;
     const unreadable = [];
     for (const { file } of secretFiles(tenant)) {
-        const all = JSON.parse(fs.readFileSync(file, "utf8"));
-        const plain = new Map();
-        let pending = 0;
-        for (const [name, rec] of Object.entries(all)) {
-            if (rec.k === "tenant")
-                continue; // already moved
-            const value = decrypt(tenant, rec);
-            if (value === null) {
-                unreadable.push(name);
-                continue;
+        // Under the vault's lock: every pod runs this at boot, and a save made
+        // between our read and our write must not be lost.
+        mutateVaultFile(file, (all) => {
+            const plain = new Map();
+            const unreadableHere = [];
+            for (const [name, rec] of Object.entries(all)) {
+                if (rec.k === "tenant")
+                    continue; // already moved
+                const value = decrypt(tenant, rec);
+                if (value === null) {
+                    unreadableHere.push(name);
+                    continue;
+                }
+                plain.set(name, value);
             }
-            plain.set(name, value);
-            pending += 1;
-        }
-        // Nothing to do, or something could not be read — leave the file alone.
-        // A partial conversion is worse than none, because the half that moved is
-        // no longer openable by the key the other half still needs.
-        if (pending === 0 || unreadable.length)
-            continue;
-        const next = { ...all };
-        for (const [name, value] of plain) {
-            next[name] = { ...encryptValue(tenant, value), updatedAt: all[name].updatedAt, ...(all[name].kind ? { kind: all[name].kind } : {}) };
-        }
-        const tmp = `${file}.rewrap`;
-        fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
-        fs.renameSync(tmp, file);
-        moved += pending;
+            unreadable.push(...unreadableHere);
+            // Nothing to do, or something in THIS file could not be read — leave it
+            // alone. A partial conversion is worse than none, because the half that
+            // moved is no longer openable by the key the other half still needs.
+            if (plain.size === 0 || unreadableHere.length)
+                return null;
+            const next = { ...all };
+            for (const [name, value] of plain) {
+                next[name] = { ...encryptValue(tenant, value), updatedAt: all[name].updatedAt, ...(all[name].kind ? { kind: all[name].kind } : {}) };
+            }
+            moved += plain.size;
+            return next;
+        });
     }
     return { moved, unreadable };
 }

package/dist/src/starter.d.ts

@@ -18,4 +18,13 @@ export interface StarterFile {
  * workspace somewhere would be worse than no starter.
  */
 export declare function accountFiles(account: string): StarterFile[];
+/**
+ * What an account folder ignores, at its own root.
+ *
+ * The workspace scaffold has always shipped one of these; an account folder is
+ * the thing that gets committed now, and the key that decrypts its secrets
+ * lives at ITS root — `<account>/.foldrun/` — so the guard has to be here too
+ * or the first `git add .` commits the vault key.
+ */
+export declare function accountGitignore(): StarterFile;
 export declare function starterFiles(workspace: string): StarterFile[];

package/dist/src/starter.js

@@ -64,6 +64,36 @@ dropped further down.
         },
     ];
 }
+/**
+ * What an account folder ignores, at its own root.
+ *
+ * The workspace scaffold has always shipped one of these; an account folder is
+ * the thing that gets committed now, and the key that decrypts its secrets
+ * lives at ITS root — `<account>/.foldrun/` — so the guard has to be here too
+ * or the first `git add .` commits the vault key.
+ */
+export function accountGitignore() {
+    return {
+        path: ".gitignore",
+        content: `# The key that decrypts every secret in this account, plus the local run
+# store. Never commit these.
+.foldrun/
+
+# Written by runs, not by you.
+workspaces/*/runs/
+workspaces/*/outputs/
+state/
+storage/
+# The link a running step keeps in its agent folder (workspace/ for the
+# shell); removed when the step ends, ignored in case one is left behind.
+workspaces/*/agents/*/workspace
+
+.env
+.env.local
+.DS_Store
+`,
+    };
+}
 export function starterFiles(workspace) {
     return [
         {
@@ -98,6 +128,9 @@ Context every agent here shares. Prices, rules, anything they should all know.
 # Written by runs, not by you.
 runs/
 outputs/
+# The link a running step keeps in its agent folder (workspace/ for the
+# shell); removed when the step ends, ignored in case one is left behind.
+agents/*/workspace
 
 .env
 .env.local
@@ -114,6 +147,8 @@ effort: high
 tools:
   - web
   - read
+web:
+  actions: [search, fetch]
 ---
 
 Pick exactly one topic, in a short paragraph, and say who it helps and why now.
@@ -126,7 +161,7 @@ Do not write the article.
 name: writer
 description: Turns a brief into a short draft.
 tools:
-  - files
+  - write
 ---
 
 Write a short draft from the brief you were given. Save it to outputs/draft.md.
@@ -209,6 +244,10 @@ foldrun deploy --url <server> --token $FOLDRUN_TOKEN
 \`check\` is cheap and catches a broken flow before a schedule fires it at 3am.
 Run it after edits, the way you would run a typecheck.
 
+A deploy that would delete files this folder no longer has lists them and
+stops: with no terminal it is refused. Tell the person what it would delete; add \`--yes\`
+only when they asked for exactly that deletion.
+
 ## Where things go
 
 | Path | What |
@@ -231,10 +270,23 @@ Regenerated every run means a file; accumulated across runs means \`state/\`.
 That last row is worth knowing: a subagent you write in Claude Code is imported
 as \`agents/<name>/agent.md\` at deploy, no conversion. Write it either way.
 
+## Paths inside a workspace
+
+An agent's working directory is \`agents/<name>/\`. Write every path to the
+workspace's own folders as \`workspace/…\` — \`workspace/storage/report.csv\`,
+\`workspace/state/cursor.json\` — in an agent's prose, in flow options
+(\`each: rows of\`, \`when: rows of\`, \`verify:\`, \`preview:\`, \`schema:\`) and in
+script arguments. It resolves the same in the file tools, the shell, scripts
+and checks. The older \`../../storage/…\` reaches the same place and still
+works; \`foldrun check\` suggests the new spelling where it sees it.
+A Node script started as \`node workspace/tools/x/run.mjs\` is its own main
+module there, so its \`import.meta.url\` entry check runs (it did not before
+2 Oct 2026 and exited 0 doing nothing).
+
 ## What a deploy does NOT touch
 
-\`runs/\`, \`state/\`, \`secrets.json\`, and any memory an agent wrote that your
-push does not mention. Those belong to the platform, not to git — a deploy that
+\`runs/\`, \`state/\`, \`storage/\`, \`secrets.json\`, the trigger log, and any
+memory an agent wrote that your push does not mention. Those belong to the platform, not to git — a deploy that
 reverted what an agent learned would make every run a little dumber.
 
 Secrets never go in these files. \`foldrun secrets\` puts them in the vault, and
@@ -270,19 +322,32 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/runs/<id>/stop\` | POST | kill it — destroys the sandbox too |
 | \`/runs/<id>/rerun\` | POST | again, or from a chosen step |
 | \`/runs/<id>/approve\` | POST | release a run waiting on a human |
+| \`/runs/<id>/answer\` | POST | answer a question an agent is asking mid-step (\`tools: [ask]\`) |
+| \`/runs/<id>/message\` | POST | tell a running step something; \`step\` picks one of a parallel group |
 | \`/flows\` · \`/flows/<f>\` | GET POST · POST DELETE PATCH | list, create, edit |
 | \`/flows/<f>/run\` | POST | start a flow |
 | \`/agents\` · \`/agents/<a>/run\` | GET POST · POST | list agents, run one |
 | \`/evals\` · \`/evals/<e>/run\` | GET POST · POST | list evals, run one |
 | \`/tools/<t>/test\` | POST | exercise one tool alone |
-| \`/storage\` · \`/storage/download\` · \`/storage/upload-url\` | GET POST PUT DELETE · GET · POST | workspace files |
+| \`/storage\` · \`/storage/download\` · \`/storage/upload-url\` · \`/storage/preview\` | GET POST PUT DELETE · GET · POST · GET | workspace files, any type; \`preview\` returns one parsed for reading |
 | \`/assets\` | POST | upload an asset |
 | \`/hooks/<f>/rotate\` | POST | new webhook token for a flow |
+| \`/notify/deliveries\` · \`/notify/deliveries/<id>/redeliver\` | GET · POST | every notify: webhook sent and each attempt; send one again |
+| \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
 
 Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/schedule\`,
 \`/api/approvals\`, \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
-\`/api/healthz\` (open) and \`/api/metrics\` (Prometheus).
+\`/api/me/notifications\` (what mail you get; a key acts for whoever minted it),
+\`/api/account/backups\` (snapshots, restore requests), \`/api/me/onboarding\` (getting started),
+\`/api/healthz\` and \`/api/version\` (open), \`/api/changelog\` (release notes)
+and \`/api/metrics\` (Prometheus).
+
+Every call answers — and the CLI sends — \`Foldrun-Version: YYYY-MM-DD\` (dated API
+versions; an account pin in Settings → API), \`X-RateLimit-*\` headers (a \`429\`
+carries \`Retry-After\`), and writes that start work take an \`Idempotency-Key\`
+(a retry with the same key replays the first answer). The whole surface as
+OpenAPI 3.1: \`/api/openapi.json\` (open), or \`foldrun api spec --out openapi.json\`.
 
 Debugging a failed run is usually: \`runs\` to find it, \`runs/<id>\` to read which
 step failed and what it cost, fix the markdown, \`deploy\`, then \`rerun\`.
@@ -295,6 +360,11 @@ git push endpoint.
 
 A numbered list of steps. The number is the GROUP: same number means those
 steps run in parallel, and the flow waits for all of them before the next.
+The dashboard's canvas and the CLI edit the same file: \`foldrun flow show
+<flow>\` draws it, \`foldrun flow add <flow> <pattern>\` inserts a pattern
+(chain, parallel, router, fan-out, loop, approval, ask, wait, rescue,
+subflow), \`foldrun flow rm-step\` removes a step, and \`foldrun agent link
+<agent> --subagent|--consult|--can-ask\` wires agents together.
 
 \`\`\`markdown
 ---
@@ -310,7 +380,7 @@ priority: normal         # high | normal | low — where its runs stand in the q
 1. [[researcher]] — Find three sources on {{topic}}.
 2. [[writer]] — Draft from what the researcher found.
    model: max
-   verify: the draft cites every source
+   verify: judge: the draft cites every source
 3?. [[editor]] — Tighten it.
 4!. [[publisher]] — Publish it.
 \`\`\`
@@ -323,11 +393,14 @@ Indented under a step, any of:
 | | |
 |---|---|
 | \`approve: true\` | stop for a human (\`!\` is shorthand for this) |
-| \`when: <condition>\` | run only if it holds |
+| \`when: <MARKER>\` | run only if a line of the previous result begins with it |
+| \`when: rows of <path>\` | run only if that CSV has a data row — for the steps after an \`each:\` |
 | \`case: <value>\` / \`else: true\` | branch on the previous step's result |
 | \`retry: 2\` | re-run on failure, up to 5 |
 | \`timeout: 900\` | seconds before the step is cut off |
-| \`verify: <claim>\` | the step fails unless this is true of its output |
+| \`verify: <shell>\` | the step fails unless the command exits 0; the reply is in \`$FOLDRUN_REPLY_FILE\` |
+| \`verify: judge: <claim>\` | a model grades the claim against the output |
+| \`verify: contains:\` / \`not-contains:\` / \`matches:\` / \`file:\` | the cheap checks, no shell |
 | \`model:\` / \`effort:\` | override the flow's default for this step |
 | \`loop: 3\` / \`until: <condition>\` | repeat until it holds, at most 5 |
 | \`each: lines\` | run once per line of the previous result |
@@ -340,7 +413,11 @@ Indented under a step, any of:
 | \`preview: draft/*.mdx\` | what the approval box shows — paths under \`storage/\`, globs allowed |
 | \`delegate: [[a]], [[b]]\` | hand the step to whichever fits, up to 5 |
 | \`output: json\` | the reply ends with one JSON value; the next step gets it as data, \`each: items\` fans out over it |
+| \`schema: {...}\` | with \`output: json\` — the JSON Schema the value must satisfy; inline, a YAML block under the key, or a file path |
 | \`each: items\` | run once per element of the previous step's JSON array |
+| \`parallel: 3\` | how many \`each:\` instances run at once — default all |
+| \`max_turns: 20\` | the most model turns before the step is stopped, beside \`budget:\` and \`timeout:\` |
+| \`limits: {web.search: 10}\` | this step's call limits, over the agent's key by key |
 
 ## Writing an agent
 
@@ -354,14 +431,17 @@ description: Finds and summarises sources.
 model: default              # fast | default | max
 effort: low                 # how hard to think about it
 size: large                 # small | large | heavy — the sandbox it rents
-tools: [WebSearch, Read, my-folder-tool]  # built-ins and your own tools/, one list
+tools: [web, read, ask, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step
 disallowedTools: [Bash]     # subtract from what it would otherwise have
 skills: [house-style]       # from skills/
 scripts: [summarise.py]     # from scripts/, each becomes a callable tool
 apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
-agents: [writer]            # colleagues this one may consult
-secrets: [CRM_TOKEN]        # from the vault — never written in these files
+agents: [writer]            # colleagues this one may consult (an answer, no tools)
+subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
+secrets: [CRM_TOKEN]        # keys the agent uses itself; a tool's own come with the tool
+limits: {web.search: 40, crm: 20, calls: 300}  # per step; a call past a limit is refused, never run
+timezone: Australia/Sydney  # the calendar it works to — IANA name or UTC+10
 provider: {}                # BYOK: your own model credential
 permissionMode: plan        # plan first, act once approved
 runtime:                    # only if scripts need packages
@@ -374,6 +454,10 @@ You research a topic and report what you found...
 Only \`name\` and the prose are required. Every other field widens or narrows
 what the agent can reach, and the default is narrow.
 
+\`timezone:\` is nearest-wins all the way down: the agent's own, else its
+flow's, else the workspace's AGENTS.md, else the account's, else UTC. It sets
+\`TZ\` and the date the agent is told, so a Sydney desk stamps the Sydney date.
+
 \`runtime:\` installs pip/npm packages in the sandbox each agent runs in. Pin
 versions the normal way (\`pandas>=2\`, \`lodash@^4\`). Python and Node are
 supported; anything else should ship as a committed binary.