@foldrun/core 0.3.0 → 0.5.0

package/src/secrets.ts

@@ -23,26 +23,54 @@ import fs from "node:fs";
 import path from "node:path";
 import { dataRoot } from "./paths.ts";
 import { platform } from "./platform.ts";
+import { fetchUntrusted } from "./untrusted-fetch.ts";
+
+/**
+ * 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 } as const;
 
 // 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: string) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.ts";
+import { trimSlashes } from "./paths.ts";
 
 const keyFile = () => path.join(dataRoot(), ".secret-key");
 
 /** Which store a secret came from. */
 export type SecretScope = "account" | "workspace";
 
-function masterKey(): Buffer {
+/**
+ * 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(): string {
   const fromEnv = process.env.FOLDRUN_SECRET_KEY;
-  if (fromEnv) return crypto.createHash("sha256").update(fromEnv).digest();
+  if (fromEnv) 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(): Buffer {
+  return crypto.createHash("sha256").update(installKeyMaterial()).digest();
 }
 
 // `workspace` undefined means the account store.
@@ -76,19 +104,80 @@ interface StoredSecret {
 type SecretsFile = Record<string, StoredSecret>;
 
 function read(tenant: string, workspace?: string): SecretsFile {
-  const f = secretsFile(tenant, workspace);
-  if (!fs.existsSync(f)) return {};
+  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: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function readFile(file: string): SecretsFile {
+  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: string, workspace: string | undefined, data: SecretsFile) {
-  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: string): () => void {
+  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 as NodeJS.ErrnoException).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: string, change: (all: SecretsFile) => SecretsFile | null): SecretsFile {
+  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}$/;
@@ -105,13 +194,14 @@ export function setSecret(
   }
   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;
+  });
 }
 
 /**
@@ -135,7 +225,7 @@ export function encryptValue(
 ): { iv: string; tag: string; data: string; k?: "tenant" } {
   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"),
@@ -180,6 +270,7 @@ function decrypt(tenant: string, rec: StoredSecret | undefined): string | null {
       "aes-256-gcm",
       key,
       Buffer.from(rec.iv, "base64"),
+      GCM,
     );
     decipher.setAuthTag(Buffer.from(rec.tag, "base64"));
     return Buffer.concat([
@@ -214,9 +305,11 @@ export function getSecret(
 }
 
 export function deleteSecret(tenant: string, name: string, workspace?: string) {
-  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;
+  });
 }
 
 export interface SecretEntry {
@@ -340,48 +433,46 @@ export function rotateMasterKey(
   const unreadable: string[] = [];
 
   for (const { file } of secretFiles(tenant)) {
-    const all: SecretsFile = JSON.parse(fs.readFileSync(file, "utf8"));
-    const next: SecretsFile = {};
     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;
+    mutateVaultFile(file, (all) => {
+      const next: SecretsFile = {};
+      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: string;
+        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++;
       }
-      let plain: string;
-      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;
-      }
-      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 });
   }
 
@@ -459,12 +550,12 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
       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(() => ({}))) as {
       access_token?: string;
       expires_in?: number;
@@ -498,6 +589,9 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<string>
  */
 export async function materializeSecrets(
   env: Record<string, string>,
+  /** 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?: { tenant: string; workspace?: string },
 ): Promise<Record<string, string>> {
   const out: Record<string, string> = { ...env };
   for (const [name, value] of Object.entries(env)) {
@@ -518,8 +612,11 @@ export async function materializeSecrets(
         const fp = crypto.createHash("sha256").update(grantMaterial).digest("hex").slice(0, 16);
         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: ServiceAccountConfig;
       try {
@@ -570,7 +667,7 @@ export function setServiceAccountSecret(
   for (const field of ["token_url", "issuer", "private_key", "scope"] as const) {
     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");
@@ -604,7 +701,7 @@ async function exchangeServiceAccount(config: ServiceAccountConfig, cacheKey: st
     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({
@@ -612,7 +709,7 @@ async function exchangeServiceAccount(config: ServiceAccountConfig, cacheKey: st
         assertion: jwt,
       }).toString(),
       signal: AbortSignal.timeout(15_000),
-    });
+    }, { sameOrigin: true });
     const payload = (await res.json().catch(() => ({}))) as {
       access_token?: string;
       expires_in?: number;
@@ -692,7 +789,7 @@ export function setSshSecret(tenant: string, name: string, config: SshConfig, wo
   const hasKey = Boolean(config.private_key?.trim());
   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!)) throw new Error("ssh password cannot contain newlines");
@@ -737,7 +834,7 @@ export function setApiSecret(tenant: string, name: string, config: ApiConfig, wo
   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 }),
+    API_PREFIX + JSON.stringify({ ...(base ? { base_url: trimSlashes(base) } : {}), headers: config.headers }),
     workspace, "api",
   );
 }
@@ -767,33 +864,32 @@ export function rewrapTenantSecrets(tenant: string): { moved: number; unreadable
   const unreadable: string[] = [];
 
   for (const { file } of secretFiles(tenant)) {
-    const all: SecretsFile = JSON.parse(fs.readFileSync(file, "utf8"));
-    const plain = new Map<string, string>();
-    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<string, string>();
+      const unreadableHere: string[] = [];
+      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: SecretsFile = { ...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: SecretsFile = { ...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/src/starter.ts

@@ -72,6 +72,37 @@ 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(): StarterFile {
+  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: string): StarterFile[] {
   return [
     {
@@ -107,6 +138,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
@@ -124,6 +158,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.
@@ -137,7 +173,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.
@@ -224,6 +260,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 |
@@ -246,10 +286,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
@@ -285,19 +338,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\`.
@@ -310,6 +376,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
 ---
@@ -325,7 +396,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.
 \`\`\`
@@ -338,11 +409,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 |
@@ -355,7 +429,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
 
@@ -369,14 +447,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
@@ -389,6 +470,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.