foldrun 2.3.0 → 2.5.0

package/bin/foldrun.mjs

@@ -135,7 +135,7 @@ const HELP = `foldrun — agents are just folders
   foldrun hook rm <name>    delete a hook folder — says which agents still turn it on, asks (--yes, --library)
   foldrun extract [dir]     move single-file script tools into folders (tool.md + run.*)
   foldrun run <target>      run an agent or flow HERE (target: name, or flow:name) — on the platform: flow run / invoke a flow, agent run one agent
-  foldrun eval [name]       run one eval, or all of them (--to <workspace>: the deployed evals, run on the platform)
+  foldrun eval [name]       run one eval, or all of them (--to <workspace>: the deployed evals, run on the platform; --last reads their latest results, --run <id> one run's verdict, running nothing)
   foldrun eval new <name>   a new eval in the deployed workspace, its agent the first one there — edit its cases, then eval <name> --to (--to)
   foldrun promote <run-id>  keep a finished run as a regression case in evals/ (--eval <name>, --expect "contains: …" repeatable, --case <name>); a run that went wrong takes --should "what it should have done"
   foldrun probe <model>     live check: can this model hold a tool loop here?
@@ -183,10 +183,12 @@ const HELP = `foldrun — agents are just folders
   foldrun billing card      Stripe's page for saving a card for auto top-up (owner only)
   foldrun billing credit <usd>  put credit on the balance by hand (--note "…") — only on an install without Stripe (self-hosted, dev); refused once billing is live
   foldrun gallery           the platform's built-in tools (web) and whether you keep your own copy — also pull (a copy for offline runs), upgrade <tool>
-  foldrun account           the account's defaults — also set <key> <value>, clear <key> (timezone, notify, budget, concurrency, deploy_block none|secrets|security, network_enforce on|off), pause [--reason] [--stop] / resume (the kill switch), telemetry [set <url> --header name=\${SECRET} | clear | test] (runs as OpenTelemetry traces), providers (--check) (singular; accounts lists logins)
+  foldrun identity          what your cloud must trust for keyless identities: the issuer and each agent's subject (--to <workspace>, --json)
+  foldrun jobs              the four jobs — governance, guardrail, observability, evaluation — and what each has set (--to <workspace>, --json)
+  foldrun account           the account's defaults — also set <key> <value>, clear <key> (timezone, notify, budget, concurrency, deploy_block none|secrets|security, network_enforce on|off, owner, alerts <threshold> <value>, judge model|effort <value>; or <job>.<field>, e.g. governance.owner), pause [--reason] [--stop] / resume (the kill switch), telemetry [set <url> --header name=\${SECRET} | clear | test] (runs as OpenTelemetry traces), providers (--check) (singular; accounts lists logins)
   foldrun account export    everything the platform holds about the account as one JSON file (owner only; --file <path>, --force)
   foldrun account model     the account's own model key — set <provider> --key <api key> (--key - reads stdin; custom --base-url --format), remove
-  foldrun workspace         one deployed workspace's settings (--to) — also set <name|description|timezone|budget|notify|network_enforce> <value>, clear <key>, pause [--reason] [--stop] / resume (the kill switch)
+  foldrun workspace         one deployed workspace's settings (--to) — also set <name|description|timezone|budget|notify|network_enforce|owner|alerts|judge> <value> (or <job>.<field>), clear <key>, pause [--reason] [--stop] / resume (the kill switch)
   foldrun workspace vocabulary  the names the dashboard's editor completes in a workspace: agents, flows, skills, tools, secrets, scripts, types, documents (--to, --json)
   foldrun notify test       send one test notification from a workspace and say what happened (--to <workspace>)
   foldrun webhooks deliveries  the notify: webhooks a workspace sent, newest first — status, attempts, last answer (--failed, --status <s>, --event <e>, --limit, --offset, --to)
@@ -276,7 +278,7 @@ Options
   --on-fail <agent>         flow add: who takes the step over when it fails
   --off                     flow add: take the pattern off the step instead (fan-out, loop, approval, ask, wait, rescue)
   --schedule "<cron>"       flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
-  --kind <k>                secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file or a prompted password), api (--base-url, --header "Name: value" repeatable), service-account (--file <key.json>, --scopes), m2m (--token-url, --client-id, --scopes; secret prompted)
+  --kind <k>                secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file or a prompted password), api (--base-url, --header "Name: value" repeatable, or --basic-user <u> with the password prompted or --basic-password), service-account (--file <key.json>, --scopes, --subject <user to act as>), client-cert (--cert-file, --key-file, --passphrase, --export to put it in the sandbox as files too), identity (--audience: keyless cloud access, no credential stored), m2m (--token-url, --client-id, --scopes; secret prompted)
   --client <name>           connect: run the consent from that OAuth client saved on the platform (secrets clients lists them)
   --subagent <name>         agent link, agent unlink: a worker it delegates to (subagents:)
   --consult <name>          agent link, agent unlink: a colleague it asks (agents:)
@@ -304,6 +306,7 @@ Options
   --step <n>                approve, reject: decide only that step; default is every step that is waiting
   --payload <json|text|@f>  approve: release a step waiting on wait: event with this body, recorded as you
   --note "<text>"           approve, reject: guidance the agent reads — or the reason for a refusal; billing credit: the ledger line's note
+  --run <id>                eval --to: that eval run's verdict, by the id the run printed; runs nothing
   --stale [days]            agent ls: only agents not run in that many days (never run included); bare, those past alerts: stale_days
   --reason "<text>"         account pause, workspace pause: why — shown to everyone who opens it
   --stop                    account pause, workspace pause: also stop every run going now (asks; --yes to mean it)
@@ -332,7 +335,9 @@ Options
   --from <n>                invoke, flow run, rerun: start at step n; earlier steps are recorded as skipped (a bulk rerun defaults to 1)
   --no-browser              login, connect, billing top-up/card/plan: print the address instead of opening it
   --provider <name>         connect: google, github, microsoft or linkedin (fills the URLs)
-  --scopes "<a b c>"        connect: space-separated scopes (default: the provider's example)
+  --no-pkce                 connect, secrets clients add: leave PKCE off (only for an app with a secret whose provider refuses it)
+  --issuer <url>            secrets clients add: the provider's issuer, checked against the iss it sends back (RFC 9207)
+  --scopes "<a b c>"        connect: space-separated scopes (default: the provider's example; with --client, the saved client's default — the connection keeps the ones asked for)
   --client-id / --client-secret  connect: the OAuth app (prompted if omitted; secret never echoed)
   --port <n>                connect: loopback port for the redirect (default 8642 — register http://localhost:8642/callback on the app)
   --authorize-url / --token-url  connect: a provider with no preset
@@ -379,7 +384,7 @@ if (!command || command === "--help" || command === "-h") {
 // `--value` as the account's argument and stored an empty secret; `--force
 // ./dir` swallowed the directory. A flag followed by another flag is also
 // boolean, so an unlisted switch at least does not eat its neighbour.
-const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop"]);
+const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export"]);
 // Flags said more than once collect into a list: `--tag a --tag b`.
 const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule"]);
 // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
@@ -491,7 +496,11 @@ function pinned() {
   return null;
 }
 
-const workspace = pinned() ?? here;
+// `init` makes a new account in the directory it is given. It never resolves
+// to a workspace above it: a home directory holding some unrelated `agents/`
+// (a git repo of that name) passes the workspace test, and `init` anywhere
+// under it used to scaffold into the home directory itself (2026-10-21).
+const workspace = (command === "init" ? null : pinned()) ?? here;
 if (!ACCOUNT_WIDE.has(command)) process.env.FOLDRUN_WORKSPACE = workspace;
 // The account scope, decided once here and honoured by the core's
 // singleAccountRoot — so `library/` beside `workspaces/` is what an agent's

package/docs/agents.md

@@ -43,6 +43,28 @@ by deleting its folder and redeploying.
 Only `name` and the body are required. Every other field widens or narrows
 what the agent can reach, and the default is narrow.
 
+### Grouped by job
+
+The fields that govern an agent or guard it may be grouped under the job
+they do. `governance:` holds `owner` and `budget`; `guardrail:` holds
+`limits`, `network`, `hooks`, `disallowedTools`, `permissionMode` and
+`secrets`:
+
+```yaml
+---
+name: researcher
+tools: [web, read]
+governance:
+  owner: ana@acme.io
+guardrail:
+  network: [api.example.com]
+  limits: {web.search: 40, repeat: 5}
+---
+```
+
+It reads exactly as the same fields at the top. A field written both ways is
+refused. See [The four jobs](four-jobs).
+
 ## Which model, and how hard it thinks
 
 | field | values | |

package/docs/api.md

@@ -179,7 +179,7 @@ history with each message.
 | `/api/workspaces/<ws>/export` | GET | this workspace, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the workspace tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the workspace |
 | `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A workspace package into a name that does not exist makes that workspace (`workspace:manage`, the plan's workspace count). 400 for anything not a package, or one holding memory/, state/ or outputs/. Idempotent |
 | `/api/workspaces/<ws>/evals` | GET, POST | list; create (`name`) |
-| `/api/workspaces/<ws>/evals/<eval>/run` | POST | run one eval |
+| `/api/workspaces/<ws>/evals/<eval>/run` | GET, POST | POST runs one eval and answers with its result; with `{ async: true }` it answers `202 { started, eval, runId, startedAt }` at once and the eval runs on — an eval of slow cases outlives a proxy's read timeout (Cloudflare's is 125 s by default). One run of an eval at a time: a second is `409` naming the run that holds it. `GET ?run=<runId>` is what to poll — that run alone, whatever else runs or writes the eval's latest result meanwhile: `{ runId, state, running }` where `state` is `running`, `done` (with its `result`), `failed` (with `error`), `lost` (it stopped reporting before saving a result, e.g. a restart) or `unavailable` (an id not on record — the last 20 runs are kept). Plain `GET` answers who holds the eval now (`running`, `runId`, `startedAt`) and the latest `result`. The dashboard and `foldrun eval --to` start async and poll by run id |
 | `/api/workspaces/<ws>/tools/<tool>/test` | POST | exercise one tool (`args`, `path`). An http tool with an `operations:` allowlist is probed only with a GET to one of its operations (no `path`: the first GET without parameters), and fails if the allowlist resolves nothing, as a run does |
 | `/api/workspaces/<ws>/hooks` | GET | the [hooks](hooks) this workspace can turn on — its own and the library's (shadowing marked), invalid ones with the reason, and who turns each on — plus `recent`: every deny, rewrite and failure hooks wrote in the last `?runs=` runs (1–500, default 50), newest first; `?all=1` includes notes and context |
 | `/api/workspaces/<ws>/hooks/<name>/test` | POST | run one [hook](hooks) on a sample event: body `{ event }`, answer the hook's own (`ok`, `decision`, `reason`, `input`, `context`, `reply`, `note`, `failure`, `ms`). Shares the `hooks/` path with flow webhooks below — `/test` is only ever a hook's. Answers `404` for no such hook, `422` for an invalid `hook.md`, `400` for an event that is not an object. On an isolated install hook code never runs in the platform's own process, so this answers with where to test it instead (`foldrun hook test` locally, or a test run) |
@@ -319,7 +319,7 @@ its header and requires a URL it can GET for itself.
 | `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
 
 `PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
-a cert), `oauth2`, `service_account`, `ssh`, or `api`. They go to the vault;
+a cert), `oauth2`, `service_account`, `ssh`, `api`, `client_cert` (`{ cert, key, passphrase?, export? }` — mutual TLS, presented by the egress proxy to the exact sites the secret is bound to), or `identity` (`{ audience }` — keyless cloud access). They go to the vault;
 agents name them in `secrets:` and never see them in a file.
 
 Reads return which secrets exist, never their values.
@@ -343,6 +343,7 @@ Reads return which secrets exist, never their values.
 | `/api/issues/<id>` | GET POST | one issue; POST acts on it: `{ action: "acknowledge" | "snooze" | "resolve" | "reopen", for?: "30m" | "4h" | "1d" | "1w", until?: ISO, times?: n, note? }` (editor or above), kept in its history with who did it, and answers `{ issue }` as it now stands. A snooze needs `for`, a future `until`, or `times` (until it happens that many more times; with a time too, whichever comes first). A platform issue is the account's: closing it needs access to every workspace. A run that goes wrong the same way after a resolve opens the issue again |
 | `/api/account/export` | GET | the owner's copy of what the platform holds about the account, as one JSON file (`foldrun-<account>-export.json`): `workspaces` (with their flows), `members` (email, role, scope, since), `runs` (an index — id, workspace, flow, status, times, headline) and the whole `ledger` (each line's charge; the platform's provider cost is left out). `billing:manage`, so the owner; audited as `account.exported`. The markdown itself comes from `foldrun pull` or the source API |
 | `/api/account/telemetry/test` | POST | send one made-up run as an OpenTelemetry trace to the collector `telemetry:` names — the account's, or `{ workspace }`'s — with its header secrets filled from the vault; `{ ok, status?, error?, spans?, endpoint }`. `409` when no `telemetry:` is set. Needs `workspace:manage` |
+| `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the workspace's when `workspace` is given (null: unset), as written with blocks folded; `combine` is how the two meet at run time (`workspace replaces`, `either turns it on`, `both apply`, `per key`, `per field`, `level nearest, sites from both`, `account only`); `writable` is whether that scope's settings PATCH (`/api/account`, or the workspace's) writes it — the rest are written in `AGENTS.md`. See [The four jobs](four-jobs) |
 | `/api/account/pause` | GET, POST, DELETE | the account's kill switch: the same as a workspace's `/pause`, for every workspace at once. GET `{ paused, account, workspaces }` (`workspaces`: those paused on their own). POST `{ reason?, stop?: true }`, DELETE resumes the account — a workspace paused on its own stays paused. Needs `workspace:manage` and access to every workspace |
 | `/api/account/close` | POST | the owner asks to close the account — in person, never a key, with `confirm` set to the account's name and an optional `reason`. Not a delete: the account is suspended at once (runs in flight finish, sign-in and the export still work), `closeRequested` is set on its admin state, and the super admin is mailed to settle the last invoice and any refund. Returns `{ ok, suspended, notified }`; 409 when already asked. Hosted installs only |
 | `/api/account/backups` | GET | what is backed up for this account: `policy` (`schedule`, `keepLocal`, `keepOffsiteDays`, `encrypted`, `covers`, `excludes`), `last`, `backups` (each nightly archive that holds this account, newest first: `id`, `at`, `bytes` (the encrypted object), `sha256` (the archive inside the encryption — what a decrypt must reproduce), `kinds` — files, database, keys — `verified`, `offsite`, `keepDays`, `encrypted` (sealed with age before it left the server; false for archives taken before October 2026), `recipient` (the key's fingerprint, `sha256:<16 hex>`, or null)), `requests` (earlier restore requests) and `workspaces` (`name`, `head`, `history`, `lastChange`) — what a restore can reach. See [Backups and restore](backups-and-restore.md) |
@@ -350,7 +351,7 @@ Reads return which secrets exist, never their values.
 | `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage`. See [api-usage](api-usage.md) |
 | `/api/account/flags` | GET | the feature flags as they stand for this account — `{ flags: [{ name, description, owner, default, on, source, rollout }] }`, `source` being what decided it: `account` (an override for this account), `global` (the install-wide setting), `rollout` (a percentage of accounts, by a stable hash of account and flag; `rollout` is the percentage) or `default`. Read-only, every role; only the super admin changes a flag. See [Feature flags](feature-flags.md) |
 | `/api/openapi.json` | GET | this API as an OpenAPI 3.1 document — every route and method, bearer auth, the rate-limit, version and Idempotency-Key headers, and request/response schemas for runs, flow runs, deploy, source, secrets, keys and billing. No key needed. Generated from the route files by `scripts/gen-openapi.mjs`; the dashboard renders it at Docs → API reference, `foldrun api spec` saves it |
-| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place |
+| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place |
 | `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some workspaces, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, workspace deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The super admin's own levers (`operator.*`) are the platform's record and not listed. Kept for the life of the account |
 | `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET is cached for a year — the URL's `?v=` changes with the picture |
 | `/api/search?q=` | GET | find anything in the account by name — workspaces, agents, flows, tools, skills, knowledge, memory, runs (by id, flow or headline); ranked, at most six per kind. The dashboard's Find palette reads it |
@@ -462,9 +463,11 @@ signed-in person, never by a key — mints an ordinary API key at their role.
 | Route | Methods | |
 |---|---|---|
 | `/api/oauth/clients` | GET, POST, DELETE | registered providers (`name`, `client`, `config`) |
-| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`) |
-| `/api/oauth/callback` | GET | where the provider returns |
-| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`) → `{ url }` |
+| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`, optional `scopes`). From a signed-in browser: `{ url }` is the provider's consent, bound to that browser by a cookie the callback checks, with PKCE. With an API key: `{ url, handoff: true }` is a dashboard page where a signed-in person accepts first (`foldrun connect --client` opens it). `scopes` (space-separated, as the provider spells them) is what this connection asks for instead of the client's default, and the connection keeps it for its reconnects — one saved app serves any number of connections at different scopes |
+| `/api/oauth/callback` | GET | where the provider returns — refuses a consent that comes back to another browser, and an `iss` that is not the app's issuer |
+| `/api/identity?workspace=` | GET | keyless cloud identity: `{ enabled, issuer, subject, tokenSeconds }` — the issuer a cloud must trust and the subject pattern each agent's tokens carry (`account:<a>:workspace:<w>:agent:<agent>`). Open (no key), outside `/api`: `/.well-known/openid-configuration` and `/.well-known/jwks.json`, 404 when the install does not issue tokens |
+| `/api/oauth/handoff/<id>` | POST | accept a connection started from a terminal: a signed-in person only, never a key; answers `{ url }`, the provider's consent bound to this browser. Used once, ten minutes |
+| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`, optional `scopes`) → `{ url }`; it asks for `scopes` when given, else the scopes the secret was connected with, else the client's default |
 | `/api/oauth/connections` | GET | each oauth2 secret's grant: saved client, `status` (ok, expiring, expired, failed, no-client), days left, last error |
 
 ## Triggers

package/docs/budgets-and-billing.md

@@ -25,7 +25,7 @@ mistake the editor names rather than a cap it quietly keeps.
 When an agent's cap and the flow's both apply to one step, the tighter one
 wins, and the step's error says which line set it: `budget: in the flow
 file` or `budget: on the writer agent`.
-| **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Defaults | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`) or plan number (`FOLDRUN_PLAN_CONCURRENCY`, which applies only where billing is on), or no cap. Your own number can lower that, never raise it; a higher number comes with a plan |
+| **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Governance | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`) or plan number (`FOLDRUN_PLAN_CONCURRENCY`, which applies only where billing is on), or no cap. Your own number can lower that, never raise it; a higher number comes with a plan |
 | **the queue lane** | the plan's lane (`high` \| `normal` \| `low`); `priority: low` in the account's `AGENTS.md` lowers it, and `high` there counts only with a plan that gives it | when slots are short, accounts take turns, weighted by lane — high 3, normal 2, low 1: every account's first run goes before anyone's second, a fast lane takes three turns to a slow lane's one and never all of them, an account with runs going waits behind one with none, and a run that has waited ten minutes moves up a turn. A flow's own `priority:` orders runs within that. The cap above still holds |
 | **room to start** | the install's `FOLDRUN_RUN_MEMORY_GIB` and `FOLDRUN_ACCOUNT_PODS` | a step whose sandbox would not fit, or whose account already has its most sandboxes running, waits to start — `room: waiting to start — …` on its trail — instead of failing. The wait is not billed; the run page's start-up chip shows it as `room`. A step still waiting after 30 minutes (`FOLDRUN_ROOM_WAIT_SEC`) fails, saying why |
 

package/docs/checks.md

@@ -81,7 +81,7 @@ listed with it. `deploy_block:` in `AGENTS.md` turns them into refusals:
 | `security` | any security finding: `secret/*`, `content/*`, `security/*`, `supply-chain/*`, and `flow/outward-ungated` (a step that acts outside with no check or approval) |
 
 Set it in the account's `AGENTS.md` for every workspace, or in one
-workspace's `AGENTS.md`, which wins. Settings → Defaults → **Refuse a
+workspace's `AGENTS.md`, which wins. Settings → Governance → **Refuse a
 deploy on**, or `foldrun account set deploy_block secrets`. A refused
 deploy names each finding and its rule; a `foldrun-ignore` with a reason
 (below) still accepts one.
@@ -351,6 +351,21 @@ place in `@foldrun/core` (`frontmatter-fields.ts`). The editor's completions
 come from the same list, so what the editor suggests and what `check`
 accepts cannot drift apart.
 
+### config/conflict
+
+*error.* A field written twice: at the top of the frontmatter and inside its
+job block (`limits:` and `guardrail: {limits: …}`). Only the top one would be
+read, so the file is refused until one is removed. See
+[The four jobs](four-jobs).
+
+### config/misplaced
+
+*error.* A setting inside the wrong job's block — `network:` under
+`governance:` — is not read, so a protection you wrote would not apply; the
+file is refused until it moves. The message names the block it belongs in, or
+says to write it at the top when it does none of the four jobs. A key foldrun
+does not read at all, inside a block, is only a note.
+
 ### config/invalid-frontmatter
 
 *warn.* Frontmatter that YAML cannot read. The commonest cause is a value
@@ -381,10 +396,10 @@ filtered, ignored and baselined. Each problem keeps its own level.
 | Rule | Covers |
 |---|---|
 | `agent/config` | frontmatter that cannot be read; a tool, skill, colleague, sub-agent or hook that does not exist; retired tool names |
-| `flow/config` | a step naming nothing, an option the parser cannot read, `verify:` written as prose, an arrangement that cannot have what its instruction asks for |
+| `flow/config` | a step naming nothing, an option the parser cannot read, `verify:` written as prose, a `verify: matches:` that is not a valid JavaScript regular expression, an arrangement that cannot have what its instruction asks for |
 | `tool/config` | a `run:` program that is missing, an import nothing declares, a leftover `type:` |
 | `skill/config` | a `SKILL.md` without a usable name or description |
-| `eval/config` | an eval that names nothing, or has no cases |
+| `eval/config` | an eval that names nothing, has no cases, or has a `matches:` that is not a valid JavaScript regular expression |
 | `hook/config` | a hook folder that is not a valid hook; a `hooks:` name that resolves to nothing |
 | `knowledge/okf` | a knowledge or memory document that is not a conformant bundle entry, an unreadable date, a stale document |
 | `workspace/config` | an `AGENTS.md` setting that cannot be read; a path a deploy refuses |

package/docs/cli.md

@@ -70,7 +70,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun hook test <name>` | run one hook HERE on one event, exactly as a step runs it (the event on stdin, a stripped environment, its `timeout:`), and print its answer — decision, reason, a rewritten input, context, reply or note — and how long it took. `--event '<json>'` or `--event @file`; without it, a sample event for the hook's `on:`. A deny is an answer (exit 0); a hook that crashes, times out or answers in the wrong shape is a failure (exit 1) — which, on a gate, refuses the call. `--to <workspace>` runs the DEPLOYED hook on the platform instead (`POST …/hooks/<name>/test { event }`) |
 | `foldrun hook rm <name>` | delete a hook folder (`--library` for the account's). Says which agents and AGENTS.md files still turn it on — their steps are refused until it goes from their `hooks:` — and asks; `--yes` on a pipe |
 | `foldrun run <target>` | run an agent or a flow HERE, on this machine (`name`, or `flow:name`) — `--test` for a [test run](runs#test-runs). On a platform: `flow run`/`invoke` for a flow, `agent run` for one agent |
-| `foldrun eval [name]` | one eval, or all of them. `--to <workspace>` runs the DEPLOYED workspace's evals on the platform (`POST …/evals/<name>/run`), waiting for each verdict, and prints the same lines; exits 1 when a case fails |
+| `foldrun eval [name]` | one eval, or all of them. `--to <workspace>` runs the DEPLOYED workspace's evals on the platform (`POST …/evals/<name>/run` with `async: true`, then polling `GET …/run?run=<id>` — an eval longer than a proxy's timeout still gets its own verdict), waiting for each (`--timeout <s>`, default 900; past it, the run id to read it with). `--run <id>` prints that run's verdict and runs nothing — a run that was lost or is unknown exits 1; `--last` prints each eval's latest result and runs nothing, and prints the same lines; exits 1 when a case fails |
 | `foldrun eval new <name>` | the Evals page's New, on the deployed workspace (`POST …/evals { name }`): an eval whose `agent:` is the workspace's first agent and whose case is a placeholder — edit it (`source cat`/`put`), then `foldrun eval <name> --to <workspace>` runs it. `--to <workspace>` |
 | `foldrun promote <run-id>` | keep a finished run as a regression case: its task and what the next run must still say go into `evals/<target>-regressions.md` (or `--eval <name>`), appended when the file exists. `--expect "contains: $34"` — repeatable, eval syntax — replaces the default judge line that holds the next run to the recorded conclusion; `--case <name>` names the case. A run that went wrong (failed, BLOCKED, BAD) takes `--should "what it should have done"` — the judge's claim — or `--expect` |
 | `foldrun probe <model>` | can this model hold a tool loop here? A live check |
@@ -96,10 +96,10 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
 | `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `--site <domain>` (repeatable, or `a,b`) binds it as it is stored |
 | `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
-| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable), `service-account` (`--file <key.json>`, `--scopes`), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
+| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `secrets sites`), `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
 | `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --provider google\|github\|microsoft\|linkedin` (or `--authorize-url` / `--token-url`) `--client-id … --scopes …` saves one (secret prompted), `clients rm <name>` removes it |
-| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--provider google\|github\|microsoft\|linkedin`; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
-| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
+| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--provider google\|github\|microsoft\|linkedin`; PKCE is on (`--no-pkce` only for an app with a secret whose provider refuses it), and an app with no client secret is a public app; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
+| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform (`--scopes "<a b>"` asks for this connection's own scopes instead of the client's default; the connection keeps them). It opens a page in the dashboard where you, signed in, accept the connection before the provider is asked, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
 | `foldrun deploy [dir]` | push this account into an installation — every workspace and the shared library. `foldrun deploy <workspace>` pushes one. Never removes a workspace the platform has and the folder does not. It first prints where it is going and as whom (`deploying to <url> as <profile> (<email>)`); a deploy that would delete files the folder no longer has lists them and asks — what runs wrote (`storage/`, `state/`, the trigger log) is never deleted, so never listed. The confirmed list goes with the deploy; if the platform would now remove anything else it refuses and the CLI asks again. With no terminal (a script, a CI job, a coding agent) it refuses unless `--yes`. A deploy that only adds or changes files asks nothing |
 | `foldrun help <command>` | that command's usage and options. `foldrun <command> --help` and `-h` print the same and never run the command |
 | `foldrun pull [workspace]` | bring the platform's account down into this folder — refuses to overwrite a locally edited file, and names every one it would have taken (`--force` takes them) |
@@ -142,8 +142,10 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun billing top-up <usd>` | the Payment page's top-up: Stripe's checkout page for that amount, opened in the browser (`--no-browser`, or no terminal, prints it). The credit lands when Stripe confirms the payment. `billing card` is the same for saving a card for auto top-up. Both need `billing:manage` |
 | `foldrun billing credit <usd>` | put credit on the balance by hand (`POST /api/billing { usd, note }`, `--note "…"` on the ledger line) — only on an install without Stripe, a self-hosted or dev platform; once billing is live the platform refuses it and top-ups go through `billing top-up`. The dashboard's Billing → Add credit does the same while billing is off. Needs `billing:manage` |
 | `foldrun gallery` | the tools the platform ships to every account (`web`), and for each whether this account keeps its own copy and whether that copy still matches. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <tool>` replaces the account's copy with the current gallery version, the old one a revision back |
-| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is the account's own model key, what every step runs on unless a `provider:` block names another: `foldrun account model` shows it (never the key, only its last four; exit 1 when there is none and runs are refused), `model set <provider> --key <api key>` sets it — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it; a Claude login token is refused for any account not allowed the platform's own credential. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
-| `foldrun workspace` | one deployed workspace's own settings (`--to <workspace>`): description, timezone, budget and notify, read from its `AGENTS.md` — unset means the account's. `set timezone <tz>`, `set budget 20/week`, `set notify email <address>` / `set notify url <https://…>` (`--events`; merged with what the file says), `set network_enforce on` (refuse a site off an agent's `network:` list here; `off` or `clear` goes back to the account's), `pause` (`--reason`, `--stop`) and `resume` — this workspace's kill switch, `set description "…"`, `set name <new>` — a rename changes every webhook URL, so it asks first and names the flows whose URLs changed — and `clear <key>`. Singular — `workspaces` is the list |
+| `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the workspace in, `--json` |
+| `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the workspace's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |
+| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is the account's own model key, what every step runs on unless a `provider:` block names another: `foldrun account model` shows it (never the key, only its last four; exit 1 when there is none and runs are refused), `model set <provider> --key <api key>` sets it — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it; a Claude login token is refused for any account not allowed the platform's own credential. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
+| `foldrun workspace` | one deployed workspace's own settings (`--to <workspace>`): description, timezone, budget and notify, read from its `AGENTS.md` — unset means the account's. `set timezone <tz>`, `set budget 20/week`, `set notify email <address>` / `set notify url <https://…>` (`--events`; merged with what the file says), `set network_enforce on` (refuse a site off an agent's `network:` list here; `off` or `clear` goes back to the account's), `set owner`, `set alerts <threshold> <value>`, `set judge model|effort <value>`, and `<job>.<field>` as on `account`, `pause` (`--reason`, `--stop`) and `resume` — this workspace's kill switch, `set description "…"`, `set name <new>` — a rename changes every webhook URL, so it asks first and names the flows whose URLs changed — and `clear <key>`. Singular — `workspaces` is the list |
 | `foldrun workspace vocabulary` | what the dashboard's editor completes as you type in a workspace (`--to`): agents, flows, skills, tools, secrets (names only), scripts, document types and linkable documents (`GET …/vocabulary`; `--json`) |
 | `foldrun notify test` | send one test notification to whatever the workspace's `notify:` resolves to, and print what happened — the provider's own words when it failed ("domain not verified"). Exits 1 when it did not go. `--to <workspace>` |
 | `foldrun webhooks deliveries` | the `notify:` webhooks a workspace sent, newest first: event, status (`delivered`, `retrying`, `failed`, `skipped`), attempts, the last answer and the delivery id — and a switched-off endpoint first, with the way back. `--failed` for the ones that gave up, `--status <s>`, `--event <e>`, `--limit`, `--offset`, `--json`. `--to <workspace>` |

package/docs/evals.md

@@ -33,7 +33,7 @@ satisfy. The heading is the case's name, so make it the thing being checked.
 |---|---|
 | `name` | the eval's identity |
 | `agent` **or** `flow` | what runs. A flow eval runs the whole flow per case |
-| `model` | the **judge's** tier, not the subject's — cases run the agent on its own model |
+| `model` | the **judge's** tier, not the subject's — cases run the agent on its own model. Unset, the workspace's `judge:` in `AGENTS.md` (see [The four jobs](four-jobs#judge--the-evaluation-default)), else the fast tier |
 | `effort` | the judge's effort. PASS/FAIL against one sentence is not deep work |
 | `trigger` | `deploy` (default) or `manual` |
 | `inputs` | `true` makes the file a flow's saved inputs, not a test: its cases are named tasks for [Run with…](flows#run-with-saved-inputs) and `foldrun invoke --inputs`, and nothing runs them as an eval |
@@ -45,7 +45,7 @@ satisfy. The heading is the case's name, so make it the thing being checked.
 |---|---|
 | `contains:` | the text must appear |
 | `not-contains:` | the text must not appear |
-| `matches:` | a regular expression over the reply |
+| `matches:` | a JavaScript regular expression over the reply, case-insensitive. No inline flags such as `(?m)`: write `(^\|\n)` for the start of a line. `foldrun check` reports one that does not compile |
 | `file:` | the path exists and is non-empty |
 | `run:` | a shell command that must exit 0 |
 | `judge:` | a model grades the reply against this sentence |

package/docs/flows.md

@@ -291,7 +291,7 @@ decided by a number belongs in a command that can be tested:
    verify: judge: quotes the real price
 ```
 
-`contains:`, `not-contains:` and `matches:` test the step's **conclusion** —
+`contains:`, `not-contains:` and `matches:` (a JavaScript regular expression, case-insensitive; no inline `(?m)`, write `(^|\n)` for a line start) test the step's **conclusion** —
 its final reply, the same text the run's headline is read from — so a step
 that narrated between tool calls and then opened its answer with `BAD — …`
 passes `matches: ^BAD\b`. `judge:` grades the same conclusion as "the reply", with everything the step wrote before it shown alongside as context, so a claim about the work can still be checked.
@@ -492,6 +492,15 @@ before `low`. It adds to the account's lane, so a high flow on a low account
 is normal. The account's `concurrency:` still bounds how many of its runs are
 live at once.
 
+## Grouped by job
+
+A flow's frontmatter may group its fields by the job they do:
+`governance:` (`owner`, `approvers`, `approve_within`, `budget`, `priority`),
+`guardrail:` (`throttle`, `debounce`, `overlap`, `disable_after`, `live`) and
+`observability:` (`issues`, `sla`). It reads exactly as the same fields at
+the top; a field written both ways is refused. Step options stay under their
+step. See [The four jobs](four-jobs).
+
 ## Model resolution
 
 Nearest wins: the step, then the flow, then the agent's own frontmatter. The

package/docs/four-jobs.md

@@ -0,0 +1,95 @@
+# The four jobs
+
+Running agents is four jobs, and every setting that controls them does one:
+
+| Job | What it decides |
+|---|---|
+| **Governance** | who answers for it, and what it may spend, decide and ship |
+| **Guardrail** | what it may reach and call, and what stops it mid-run |
+| **Observability** | what is recorded, and who is told |
+| **Evaluation** | how its work is judged |
+
+These are the same settings foldrun has always had. You can write each one at
+the top of the file, as before, or group them under the job they do:
+
+```yaml
+---
+name: blog-desk
+governance:
+  owner: ops@acme.io
+  budget: 60/month
+  deploy_block: secrets
+guardrail:
+  limits: {calls: 300, repeat: 5}
+  network: trusted
+observability:
+  notify: {email: ops@acme.io, events: [failed]}
+  alerts: {failure_rate: 30%, new_host: true}
+evaluation:
+  judge: {model: fast}
+---
+```
+
+reads exactly as `owner:`, `budget:`, `limits:` and the rest written at the
+top. Either way works, and the two can be mixed in one file.
+
+## Which field belongs to which job
+
+| File | `governance:` | `guardrail:` | `observability:` | `evaluation:` |
+|---|---|---|---|---|
+| `AGENTS.md` | `owner`, `budget`, `priority`, `concurrency`, `deploy_block` | `limits`, `network`, `network_enforce`, `hooks` | `alerts`, `telemetry`, `notify`, `capture` | `judge` |
+| an agent | `owner`, `budget` | `limits`, `network`, `hooks`, `disallowedTools`, `permissionMode`, `secrets` | — | — |
+| a flow | `owner`, `approvers`, `approve_within`, `budget`, `priority` | `throttle`, `debounce`, `overlap`, `disable_after`, `live` | `issues`, `sla` | — |
+
+A field that does none of the four, such as `name`, `model`, `tools`,
+`trigger` or `schedule`, is written at the top. Step options in a flow, such
+as `verify:` and `limits:` under a step, stay where they are.
+
+## The rules
+
+- **One place, not both.** A field written at the top *and* inside its block
+  is refused: `foldrun check` and a deploy stop on
+  [`config/conflict`](checks#config-conflict) until one is removed.
+- **The right block.** A setting inside another job's block is not read —
+  a guardrail under `governance:` would guard nothing — so check refuses it
+  and says which block it belongs in
+  ([`config/misplaced`](checks#config-misplaced)).
+- **Editing keeps the form.** Settings, the CLI and the flow canvas edit a
+  field where it is written, inside its block or at the top, and add a new
+  one at the top. A block written on one line (`guardrail: {network: [a.com]}`)
+  is not rewritten for you: the edit is refused (`409`) and asks for the block
+  one key per line.
+- **Only the three settings files.** Blocks are read in an agent's
+  `agent.md`, a flow and `AGENTS.md`. In knowledge, memory, skills and every
+  other document, `governance:` and the rest are that document's own words
+  and are left as written.
+- **The cascade is unchanged.** The account's `AGENTS.md`, then the
+  workspace's, then the agent, then the step: a block at one level and a flat
+  key at another combine exactly as two flat keys would.
+
+## `judge:` — the evaluation default
+
+`judge: {model, effort}` in `AGENTS.md` is the model, and how hard it
+thinks, for every grader in the workspace: each eval's `judge:` checks and
+every flow step's `verify: judge:`. An eval that names its own `model:` keeps
+it. Unset, judges run on the fast tier. Field by field, the workspace's wins:
+a workspace that sets only `effort` keeps the account's `model`.
+
+## Where each job shows
+
+| Job | In the dashboard | In the CLI |
+|---|---|---|
+| Governance | Settings → Governance: owner, budget, deploy rules, pause, team, API | `foldrun jobs`, `foldrun account set governance.<field>` |
+| Guardrail | Settings → Guardrail: network enforcement; each agent's page | `foldrun check --security`, `foldrun agent network` |
+| Observability | Settings → Observability: notify, alerts, telemetry; Observe, Issues | `foldrun issues`, `foldrun account telemetry` |
+| Evaluation | Settings → Evaluation: the judge; the Evals page | `foldrun eval --to <workspace>` |
+
+`foldrun jobs` prints all four; with `--to <workspace>`, each field's value
+there, the account's, and how the two combine. They do not all simply
+override: `network_enforce` is on when either turns it on, a workspace's
+`budget` and the account's both apply, `hooks` run from both, `network`
+takes its level from the nearest setting and its sites from every level, `limits` merge key by key, `judge`
+field by field, and `priority` and `concurrency` are read from the account
+alone. The rest — `owner`, `notify`, `alerts`, `telemetry` and others — the
+workspace's replaces the account's whole. Fields the CLI cannot set (`limits`,
+`network`, `hooks`, `capture`, …) are written in `AGENTS.md`.

package/docs/network.md

@@ -144,7 +144,7 @@ The list is refused when any one of three says so:
 
 Each only switches it on. A workspace cannot turn off what its account
 turned on, and nothing in an account turns off the install's. Settings →
-Defaults (account) and a workspace's Settings have the switch, and so does
+Guardrail, on the account's and a workspace's Settings, has the switch, and so does
 `foldrun account set network_enforce on` / `foldrun workspace set
 network_enforce on --to <workspace>`.
 

package/docs/notifications.md

@@ -112,6 +112,11 @@ alerts:
   new_host: true      # an agent reached a site it never reached before
 ```
 
+A workspace's `alerts:` replaces the account's whole: once it has its own,
+the account's thresholds no longer apply there, and `alerts: {}` means none
+for that workspace (`new_host: false` turns off one the account has on).
+Without an `alerts:` of its own it takes the account's.
+
 Each comes to `notify:` as event `alert` — like the three above it follows
 `failed`, or name `alert` in `events:` — at most once a day per rule, and once
 per slow run: "⚠ blog-desk: 6 of its last 15 runs failed", "⚠ blog-desk was
@@ -135,7 +140,7 @@ Three watch for behaviour that is out of character rather than broken:
   usual".
 - `runs_per_hour` — one flow started that many times in the last hour: a
   loop, a webhook sender retrying, a schedule written wrong. At most once a
-  day per flow. `throttle:` caps it for good; Settings → Pause stops it now.
+  day per flow. `throttle:` caps it for good; Settings → Governance → Pause stops it now.
 - `new_host` — after each run, the sites every agent reached (from the
   egress lines on its trail) are compared with what it reached before, and a
   new one is told: "blog-desk: agent researcher reached a site it never

package/docs/runs.md

@@ -153,7 +153,7 @@ telemetry:
     authorization: ${OTEL_TOKEN}             # a vault secret, by name
 ```
 
-In the account's `AGENTS.md` (Settings → API → *Send runs to your
+In the account's `AGENTS.md` (Settings → Observability → *Send runs to your
 tracing*, or `foldrun account telemetry set <url> --header
 authorization='${OTEL_TOKEN}'`), or a workspace's, which replaces the
 account's whole. Every run that finishes is sent as one trace: a span for

package/docs/secrets.md

@@ -30,9 +30,36 @@ PUT /api/secrets   { "name": "STRIPE_KEY", "value": "sk_live_…" }
 | `file` | a PEM, a certificate, a service-account JSON |
 | `oauth2` | a connected third-party account (see below) |
 | `service_account`, `ssh`, `api` | structured credentials the platform knows how to present |
+| `client_cert` | a certificate and key for mutual TLS, presented by the egress proxy |
+| `identity` | keyless cloud access: an audience, and tokens the platform signs (below) |
 
 Reads return which secrets exist, never their values.
 
+A **service account** is a key file that signs its own token request. It
+acts as itself, or — with **Act as** (`subject`) — as a user the provider
+lets it act for (RFC 7523's grant subject; for Google, domain-wide
+delegation, which a Workspace admin grants in their own console). Each
+subject gets its own token.
+
+An **`api`** connection is a base URL and the headers that go with it. For
+an old system that wants **HTTP Basic**, give a username and password
+instead of an `Authorization` header: the platform builds the header (RFC
+7617, UTF-8), refuses a colon in the username, needs an https base URL, and
+masks the password and the encoded header in every trace — as it does every
+header value of an `api` connection.
+
+A **client certificate** (mutual TLS) is a PEM certificate, its key and an
+optional passphrase; the key must belong to the certificate or it is
+refused. Bind it to the **exact hosts** it is for (`foldrun secrets sites
+NAME api.bank.example` — no wildcards): the egress proxy presents it on its
+own connection to those hosts, and the sandbox never holds the key. Two
+certificates bound to one host is refused, not guessed. A redirect to
+another site never carries it. Unbound, it stays out of the sandbox; save it
+with **export** only for a step that runs without the egress proxy, and it
+arrives as files (`$NAME_CERT`, `$NAME_KEY`, `$NAME_PASSPHRASE_FILE`). This
+is client authentication with a certificate — not OAuth's certificate-bound
+tokens (RFC 8705), which foldrun does not do.
+
 ## Scopes
 
 A secret lives at the **account** or in one **workspace**. An agent looks in
@@ -173,6 +200,78 @@ anything OAuth. Settings → Connections walks the consent flow once and stores
 the result as an `oauth2` secret; the platform refreshes it. An agent names
 it in `secrets:` like any other.
 
+You bring the OAuth app: register it once with the provider (its client id
+and secret, and the redirect URL the form shows), save it, and connect. Every
+later connection can use the same saved app — choose it under **App** and
+type the scopes this connection needs, as the provider spells them. Each
+connection keeps its own scopes, so one app serves any number of APIs from
+the same provider (an ads API in one secret, a search API in another), and
+**Reconnect** asks for that connection's scopes again. The provider decides
+what the app may ask for; foldrun only carries the words. From a terminal:
+`foldrun connect NAME --client <saved app> --scopes "<scopes>" --to <workspace>`.
+
+How a connection is kept safe, whatever the provider:
+
+- **PKCE** (S256) is on for every connection: a code stolen on its way back
+  is useless without the verifier only foldrun holds. An app with no client
+  secret (a *public* app) is allowed — PKCE is then what protects it, and
+  its refreshes send no secret. Turn PKCE off only for an app with a secret
+  whose provider refuses the parameters.
+- **The browser that starts a connection is the one it must come back to.**
+  The consent link carries a cookie the callback checks; a link opened in
+  someone else's browser connects nothing.
+- **From a terminal**, `foldrun connect --client` opens a page in the
+  dashboard where you, signed in, see the secret, the app, the scopes and
+  where it will be stored, and accept before the provider is asked.
+- **Issuer.** Give a saved app its provider's issuer and the `iss` the
+  provider sends back (RFC 9207) must match it; without one, a returned
+  `iss` must at least be the authorize URL's own site.
+- The flow's own parameters (`client_id`, `redirect_uri`, `scope`, `state`,
+  the PKCE pair) cannot be overridden by extra parameters or by a query
+  string in the authorize URL.
+- A provider that **rotates refresh tokens** sends a new one with each
+  refresh; it replaces the old one in the vault, where that secret is kept.
+
+## Keyless cloud identity
+
+The safest credential is none at all. A cloud that supports workload
+identity federation — AWS (`AssumeRoleWithWebIdentity`), Google Cloud
+(Workload Identity Federation), Microsoft Entra (federated credentials) —
+can trust **foldrun's signature** instead of a key you store: a step proves
+which account, workspace and agent it is, and the cloud gives it a
+short-lived credential of its own.
+
+1. In your cloud, trust this install as an OIDC provider: its issuer is
+   shown by `foldrun identity` (and in the Connections form). Pin the
+   subject — `account:<account>:workspace:<workspace>:agent:<agent>` — at
+   least to your account, and the audience you choose.
+2. `foldrun secrets set AWS_ID --kind identity --audience sts.amazonaws.com`
+   (or Connections → Identity). Nothing secret is stored: only the audience.
+3. Name it in an agent's `secrets:`. The step gets **`$AWS_ID_FILE`**: a
+   token signed RS256, valid ten minutes, renewed while the step runs. Point
+   your cloud's SDK at it — for AWS, `AWS_ROLE_ARN` and
+   `AWS_WEB_IDENTITY_TOKEN_FILE=$AWS_ID_FILE`; for Google, an
+   `external_account` credential file whose `credential_source.file` is it;
+   for Entra, the token as the client assertion.
+
+What it is and is not:
+
+- A **workload-federation issuer**, not a sign-in provider: discovery
+  publishes what federation reads (issuer, JWKS, RS256, public subjects),
+  and nothing more.
+- The subject and claims come from the platform's own record of the run,
+  never from the sandbox. A token is issued only to the step the identity
+  was granted to, only while its driver checks in, and never after the step
+  stops or ends.
+- Stopping a step stops renewal; it cannot recall a token already issued,
+  which expires within ten minutes on its own.
+- Within an account, a workspace or agent recreated under the same name
+  is the same subject: pin your trust policy to the account at least.
+- Who may run or edit an agent that names the identity may use it — as
+  with every secret.
+- Not on a laptop: only a sandboxed step on a platform whose operator set
+  `FOLDRUN_OIDC_ISSUER` gets a token.
+
 ## How they are kept
 
 Every account has its own encryption key. Secrets are sealed under it, and

package/docs/workspaces.md

@@ -163,6 +163,11 @@ workspace's, and a workspace that does not takes the account's.
 trace; a workspace's block replaces the account's whole. See
 [Runs](runs#sending-the-trace-to-your-own-tracing).
 
+The frontmatter may also group these defaults by the job they do —
+`governance:`, `guardrail:`, `observability:` and `evaluation:` (where
+`judge:` sets the model every grader here uses). A block reads exactly as the
+same keys at the top. See [The four jobs](four-jobs) for which key goes where.
+
 `network_enforce: true` refuses a site off a step's [`network:`](network)
 list instead of only naming it in the trace. The account's `true` holds for
 every workspace; a workspace can add it for itself but not drop the
@@ -210,7 +215,7 @@ to the next level with one line in the trace rather than failing the step.
 
 When something is going wrong — an agent posting what it should not, a
 loop spending money — pause the workspace, or the whole account, from its
-Settings → Pause, `foldrun workspace pause` / `foldrun account pause`, or
+Settings → Governance → Pause, `foldrun workspace pause` / `foldrun account pause`, or
 the API (`POST /api/workspaces/<ws>/pause`, `POST /api/account/pause`).
 
 While paused, nothing new starts: a schedule's fire, a webhook delivery, a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^2.5.0"
+    "@foldrun/core": "^2.7.0"
   },
   "files": [
     "bin",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts",
     "release": "node scripts/release.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "docs:sync": "node scripts/sync-docs.mjs",

package/src/commands.mjs

@@ -3674,8 +3674,11 @@ async function connect(positional, flags) {
   }
 
   const clientId = flags["client-id"] ?? env("OAUTH_CLIENT_ID") ?? (await promptVisible("  client_id: "));
-  const clientSecret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden("  client_secret: "));
-  if (!clientId || !clientSecret) throw new Error("client_id and client_secret are required");
+  const pkce = flags["no-pkce"] !== true;
+  const clientSecret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden(`  client_secret${pkce ? " (empty for a public app)" : ""}: `));
+  if (!clientId) throw new Error("client_id is required");
+  // No secret is a public app, which PKCE alone protects (RFC 9700 §2.1.1).
+  if (!clientSecret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
   const scopes = flags.scopes ?? preset?.scopes_example ?? "";
 
   // One fixed loopback address, the same on every developer's machine, so an
@@ -3691,13 +3694,21 @@ async function connect(positional, flags) {
   const crypto = await import("node:crypto");
   const http = await import("node:http");
   const state = crypto.randomBytes(24).toString("hex");
+  // PKCE (RFC 7636, S256): 32 random bytes as the verifier, its hash as the challenge.
+  const verifier = pkce ? crypto.randomBytes(32).toString("base64url") : null;
   const authorize = new URL(authorizeUrl);
+  // Extras first: the flow's own parameters are set after, and win.
+  for (const [k, v] of Object.entries(preset?.authorize_extra ?? {})) authorize.searchParams.set(k, v);
+  for (const k of ["client_id", "redirect_uri", "response_type", "scope", "state", "code_challenge", "code_challenge_method"]) authorize.searchParams.delete(k);
   authorize.searchParams.set("response_type", "code");
   authorize.searchParams.set("client_id", clientId);
   authorize.searchParams.set("redirect_uri", redirectUri);
   authorize.searchParams.set("state", state);
   if (scopes) authorize.searchParams.set("scope", scopes);
-  for (const [k, v] of Object.entries(preset?.authorize_extra ?? {})) authorize.searchParams.set(k, v);
+  if (verifier) {
+    authorize.searchParams.set("code_challenge", crypto.createHash("sha256").update(verifier).digest("base64url"));
+    authorize.searchParams.set("code_challenge_method", "S256");
+  }
 
   // One request, then the listener closes. The state is the whole authority:
   // a callback with any other value is answered and ignored.
@@ -3733,7 +3744,11 @@ async function connect(positional, flags) {
   const exchange = await fetch(tokenUrl, {
     method: "POST",
     headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
-    body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId, client_secret: clientSecret }).toString(),
+    body: new URLSearchParams({
+      grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId,
+      ...(clientSecret ? { client_secret: clientSecret } : {}),
+      ...(verifier ? { code_verifier: verifier } : {}),
+    }).toString(),
   });
   const payload = /** @type {any} */ (await exchange.json().catch(() => ({})));
   if (!exchange.ok || (!payload.refresh_token && !payload.access_token)) {
@@ -3743,7 +3758,7 @@ async function connect(positional, flags) {
   // Store: the refresh recipe when there is one, the bare token otherwise.
   /** @type {any} */
   const body = payload.refresh_token
-    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, client_secret: clientSecret, refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
+    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}), refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
     : { name, value: payload.access_token, workspace: workspaceName };
   if (url) {
     // The same PUT `secrets set` makes. A store that fails here has spent the
@@ -5656,6 +5671,145 @@ async function telemetryCmd(url, args, flags) {
   return 0;
 }
 
+// ---------------------------------------------------------- the four jobs
+//
+// governance, guardrail, observability, evaluation — what each AGENTS.md
+// field does, as the platform maps it (GET /api/account/jobs). The CLI reads
+// the map from the platform rather than from @foldrun/core, so it always
+// matches the platform it is talking to.
+
+/** GET /api/account/jobs, for the account or one workspace. */
+function jobsOf(url, flags, workspace) {
+  return remoteCall(url, flags, `/api/account/jobs${workspace ? `?workspace=${enc(workspace)}` : ""}`);
+}
+
+/**
+ * `governance.deploy_block` → `deploy_block`, checked against the map: a
+ * field written under the wrong job is refused with the right one named.
+ * A bare key comes back as it was, with no request.
+ */
+async function jobKey(url, flags, key, workspace) {
+  if (typeof key !== "string" || !key.includes(".")) return { key, view: null };
+  const job = key.slice(0, key.indexOf("."));
+  const field = key.slice(key.indexOf(".") + 1);
+  const view = await jobsOf(url, flags, workspace);
+  const j = view.jobs.find((x) => x.name === job);
+  if (!j) throw new Error(`"${job}" is not one of the four jobs — governance, guardrail, observability, evaluation`);
+  const f = j.fields.find((x) => x.key === field);
+  if (!f) {
+    const right = view.jobs.find((x) => x.fields.some((y) => y.key === field));
+    throw new Error(right ? `${field} is a ${right.name} setting, not a ${job} one — \`${right.name}.${field}\`` : `${job} has no setting "${field}" — it holds ${j.fields.map((y) => y.key).join(", ")}`);
+  }
+  // `writable` says what this scope's settings can write; the rest live in
+  // AGENTS.md itself. A server too old to say leaves it to the PATCH.
+  if (f.writable === false) {
+    throw new Error(`${job}.${field} is not set from here — write \`${field}:\` in ${workspace ? `workspaces/${workspace}/AGENTS.md` : "the account's AGENTS.md"} (under \`${job}:\` or at the top) and deploy`);
+  }
+  return { key: field, view };
+}
+
+/** The value a field has at one level (the account's, or the workspace's). */
+async function jobValue(url, flags, key, workspace, view) {
+  const v = view ?? (await jobsOf(url, flags, workspace));
+  for (const j of v.jobs) {
+    const f = j.fields.find((x) => x.key === key);
+    if (f) return workspace ? f.workspace : f.account;
+  }
+  return null;
+}
+
+/**
+ * `set alerts <threshold> <value>` and `set judge model|effort <value>` —
+ * one entry merged into the block as it stands (the platform replaces a
+ * block whole). `off` removes the entry. A workspace's alerts, once its own,
+ * stay its own: the last threshold removed leaves `{}` ("none here"), and
+ * `new_host off` is written as false so the account's `on` does not apply;
+ * `clear alerts` goes back to the account's.
+ */
+async function mergedEntry(url, flags, key, args, workspace, view, how) {
+  const [entry, ...words] = args;
+  const raw = words.join(" ").trim();
+  const allowed = key === "alerts"
+    ? ["failure_rate", "min_runs", "credits_day", "run_minutes", "stale_days", "cost_spike", "runs_per_hour", "new_host"]
+    : ["model", "effort"];
+  if (!allowed.includes(entry)) throw new Error(`${how} <${allowed.join("|")}> <value> — not "${entry ?? ""}"`);
+  if (!raw) throw new Error(`${how} ${entry} <value> — or \`${entry} off\` to remove it`);
+  const current = { ...((await jobValue(url, flags, key, workspace, view)) ?? {}) };
+  if (raw === "off") delete current[entry];
+  else if (entry === "new_host") current.new_host = onOff("new_host", raw, `${how} new_host on`);
+  else current[entry] = key === "alerts" && entry !== "failure_rate" && /^\d+(\.\d+)?$/.test(raw) ? Number(raw) : raw;
+  const own = key === "alerts" && workspace;
+  // A workspace's `new_host: false` is an opt-out from the account's on —
+  // kept whatever else is edited; at the account false is just unset.
+  if (own && entry === "new_host" && raw === "off") current.new_host = false;
+  else if (!own && current.new_host === false) delete current.new_host;
+  if (own) return current;
+  return Object.keys(current).length ? current : null;
+}
+
+/** A setting's value as one short line. */
+function shortValue(v) {
+  if (v === null || v === undefined) return null;
+  return typeof v === "object" ? JSON.stringify(v).replace(/"([a-z_]+)":/g, "$1: ").replace(/,/g, ", ") : String(v);
+}
+
+/**
+ * `foldrun identity [--to <workspace>]` — what a cloud must trust to accept
+ * this account's keyless identities: the issuer, and each agent's subject.
+ */
+async function identityCmd(flags) {
+  const url = platformFor(flags, "identity");
+  const ws = typeof flags.to === "string" ? flags.to : null;
+  const info = await remoteCall(url, flags, `/api/identity${ws ? `?workspace=${enc(ws)}` : ""}`);
+  if (flags.json === true) {
+    console.log(JSON.stringify(info, null, 2));
+    return 0;
+  }
+  if (!info.enabled) {
+    console.log(`\n  ${c.yellow("This install does not issue identity tokens")} ${c.dim("— its operator sets FOLDRUN_OIDC_ISSUER")}\n`);
+    return 1;
+  }
+  console.log(`\n  ${c.bold("Keyless cloud identity")}\n`);
+  console.log(`  issuer   ${info.issuer}`);
+  console.log(`  subject  ${info.subject}`);
+  console.log(`  tokens   ${Math.round(info.tokenSeconds / 60)} minutes, renewed while a step runs`);
+  console.log(`\n  ${c.dim("Trust the issuer in your cloud and pin at least the account in the subject; then `foldrun secrets set NAME --kind identity --audience <aud>` and name it in an agent's secrets:")}\n`);
+  return 0;
+}
+
+/**
+ * `foldrun jobs [--to <workspace>]` — the four jobs and every AGENTS.md
+ * field of each: the account's value, the workspace's, and how the two
+ * combine (they do not all simply override — network_enforce is on if
+ * either turns it on, both budgets apply).
+ */
+async function jobsCmd(flags, layout) {
+  const url = platformFor(flags, "jobs");
+  const ws = typeof flags.to === "string" ? flags.to : null;
+  const view = await jobsOf(url, flags, ws);
+  if (flags.json === true) {
+    console.log(JSON.stringify(view, null, 2));
+    return 0;
+  }
+  console.log(`\n  ${c.bold("The four jobs")}  ${c.dim(ws ? `workspace ${ws}, over the account's` : "the account — every workspace inherits these")}`);
+  for (const j of view.jobs) {
+    console.log(`\n  ${c.bold(j.title)}  ${c.dim(j.what)}`);
+    const w = Math.max(...j.fields.map((f) => f.key.length));
+    for (const f of j.fields) {
+      const account = shortValue(f.account);
+      if (!ws) {
+        console.log(`    ${pad(f.key, w)}  ${account ?? c.dim("unset")}`);
+        continue;
+      }
+      const here = shortValue(f.workspace);
+      const how = f.combine ? c.dim(`  · ${f.combine}`) : "";
+      console.log(`    ${pad(f.key, w)}  ${here ?? c.dim("unset")}${c.dim(`  account: ${account ?? "unset"}`)}${how}`);
+    }
+  }
+  console.log(`\n  ${c.dim(`set one: foldrun ${ws ? `workspace set <job>.<field> … --to ${ws}` : "account set <job>.<field> …"} — e.g. governance.deploy_block secrets`)}\n`);
+  return 0;
+}
+
 /** A GET …/pause, or null from a platform older than the kill switch —
  *  the settings still print, without the line. */
 async function pauseState(request) {
@@ -5748,15 +5902,23 @@ async function accountCmd(positional, flags) {
     throw new Error(`unknown account verb "${verb}" — \`foldrun account\` shows them, \`set\` and \`clear\` change one, \`model\` is the account's own model key, \`providers\` checks the model keys, \`export\` downloads everything, \`pause\`/\`resume\` the kill switch`);
   }
 
-  const key = positional[1];
-  const KEYS = ["timezone", "notify", "budget", "concurrency", "deploy_block", "network_enforce"];
+  // `governance.deploy_block` names the job; checked, then sent as the field.
+  const { key, view } = await jobKey(url, flags, positional[1], null);
+  // telemetry: is set with its own verb (an endpoint and headers, not one
+  // value); `clear` works here as for any other key.
+  if (key === "telemetry" && verb === "set") {
+    throw new Error("telemetry has its own verb — `foldrun account telemetry set <otlp-url> [--header name=value]`; `foldrun account clear telemetry` turns it off");
+  }
+  const KEYS = ["timezone", "notify", "budget", "concurrency", "deploy_block", "network_enforce", "owner", "alerts", "judge", ...(verb === "clear" ? ["telemetry"] : [])];
   if (!KEYS.includes(key)) {
-    throw new Error(`which setting? \`foldrun account ${verb} <${KEYS.join("|")}> …\``);
+    throw new Error(`which setting? \`foldrun account ${verb} <${KEYS.join("|")}> …\` — or <job>.<field>, e.g. governance.owner (\`foldrun jobs\` lists them)`);
   }
 
   let patch;
   if (verb === "clear") {
     patch = { [key]: null };
+  } else if (key === "alerts" || key === "judge") {
+    patch = { [key]: await mergedEntry(url, flags, key, positional.slice(2), null, view, `foldrun account set ${key}`) };
   } else if (key === "notify") {
     // `set notify email you@example.com` / `set notify url https://…`, and
     // --events to change what is notified on.
@@ -8440,9 +8602,50 @@ function printEvalResult(result) {
  * run there. Each run waits for its verdict: an eval is something you wait
  * for, and the platform answers when every case has.
  */
+/**
+ * One eval on the platform, started and polled (POST …/run { async: true },
+ * then GET …/run) — a long eval outlives the proxy in front of the platform,
+ * which cut the old waiting request at 100 s. A platform that answers the
+ * POST with the result itself (older ones) is read as before.
+ */
+async function remoteEvalRun(url, flags, ws, name) {
+  const path = `/api/workspaces/${enc(ws)}/evals/${enc(name)}/run`;
+  const started = await remoteCall(url, flags, path, { method: "POST", body: JSON.stringify({ async: true }) }, { seconds: explicitTimeout(flags) ?? 900 });
+  if (!started?.started) return started;
+  console.log(`  ${c.dim(`run ${started.runId}`)}`);
+  const deadline = Date.now() + (explicitTimeout(flags) ?? 900) * 1000;
+  for (;;) {
+    if (Date.now() > deadline) {
+      throw new Error(`${name} is still running after ${explicitTimeout(flags) ?? 900}s — \`foldrun eval ${name} --to ${ws} --run ${started.runId}\` reads this run's verdict when it is done, without running it again`);
+    }
+    await new Promise((r) => setTimeout(r, Number(process.env.FOLDRUN_EVAL_POLL_MS) || 4000));
+    const view = await remoteEvalRunView(url, flags, path, started.runId);
+    if (view.state === "running") continue;
+    return evalRunVerdict(name, view);
+  }
+}
+
+/** GET …/run?run=<id> — that one run's state, and nothing else's. */
+function remoteEvalRunView(url, flags, path, runId) {
+  return remoteCall(url, flags, `${path}?run=${encodeURIComponent(runId)}`);
+}
+
+/** A run's view as the result printEvalResult reads — a failure, a lost
+ *  lease or an unknown id are an error, never a pass. */
+function evalRunVerdict(name, view) {
+  if (view.state === "done" && view.result) return view.result;
+  return { eval: name, passed: 0, failed: 0, cases: [], error: view.error ?? `the run ended as ${view.state ?? "unknown"}, with no result` };
+}
+
 async function remoteEvalsCmd(name, flags, layout) {
   const url = platformFor(flags, "eval --to <workspace>");
   const ws = platformWorkspace(flags, layout, "eval");
+  // --run reads one run of one eval: a bare --run, or one with no eval
+  // named, would otherwise start runs or read the id against every eval.
+  if (flags.run !== undefined) {
+    if (typeof flags.run !== "string" || !flags.run.trim()) throw new Error("--run takes the run id the eval printed — `foldrun eval <name> --to <ws> --run <id>`");
+    if (!name) throw new Error("--run reads one eval's run — name it: `foldrun eval <name> --to <ws> --run <id>`");
+  }
   const { evals = [] } = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals`);
   const all = evals.filter((e) => !name || e.name === name);
   if (!all.length) {
@@ -8451,7 +8654,36 @@ async function remoteEvalsCmd(name, flags, layout) {
   let failed = 0;
   for (const info of all) {
     console.log(`\n  ${c.bold(info.name)} ${c.dim(`${info.cases?.length ?? "?"} cases · ${ws}`)}`);
-    const result = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(info.name)}/run`, { method: "POST" }, { seconds: explicitTimeout(flags) ?? 900 });
+    // --run <id>: that run's verdict, run nothing (GET …/run?run=).
+    if (typeof flags.run === "string") {
+      const view = await remoteEvalRunView(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(info.name)}/run`, flags.run);
+      if (view.state === "running") {
+        console.log(`  ${c.dim(`run ${flags.run} is still running, since ${view.startedAt}`)}`);
+        failed++;
+        continue;
+      }
+      const result = evalRunVerdict(info.name, view);
+      printEvalResult(result);
+      failed += Number(result.failed ?? 0) + (result.error ? 1 : 0);
+      continue;
+    }
+    // --last: what the platform has, run nothing (GET …/run).
+    if (flags.last === true) {
+      const state = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(info.name)}/run`);
+      if (state.running) console.log(`  ${c.dim(`running since ${state.startedAt} — no result yet`)}`);
+      if (state.error) {
+        console.log(`  ${c.red("✗")} the last run could not finish — ${state.error}`);
+        failed++;
+      }
+      if (!state.result) {
+        if (!state.running && !state.error) console.log(`  ${c.dim("never run")}`);
+        continue;
+      }
+      printEvalResult(state.result);
+      failed += Number(state.result.failed ?? 0) + (state.result.error ? 1 : 0);
+      continue;
+    }
+    const result = await remoteEvalRun(url, flags, ws, info.name);
     printEvalResult(result);
     failed += Number(result.failed ?? 0) + (result.error ? 1 : 0);
   }
@@ -9065,8 +9297,10 @@ async function workspaceDefaults(url, flags, ws) {
 async function workspaceCmd(positional, flags, layout) {
   const url = platformFor(flags, "workspace");
   const ws = platformWorkspace(flags, layout, "workspace");
-  const [verb, key, ...rest] = positional;
-  const KEYS = ["name", "description", "timezone", "budget", "notify", "network_enforce"];
+  const [verb, written, ...rest] = positional;
+  // `observability.notify` names the job; checked, then sent as the field.
+  const { key, view } = verb === "set" || verb === "clear" ? await jobKey(url, flags, written, ws) : { key: written, view: null };
+  const KEYS = ["name", "description", "timezone", "budget", "notify", "network_enforce", "owner", "alerts", "judge"];
   const show = (d, title) => {
     const notify = d.notify ? [d.notify.email, d.notify.url].filter(Boolean).join(", ") + c.dim(` on ${(d.notify.events ?? []).join(", ") || "nothing"}`) : c.dim("the account's");
     const budget = d.budget == null ? c.dim("the account's") : typeof d.budget === "object" ? `$${d.budget.usd} per ${d.budget.period}` : String(d.budget).includes("/") ? `$${String(d.budget).replace("/", " per ")}` : `$${d.budget} per month`;
@@ -9100,7 +9334,9 @@ async function workspaceCmd(positional, flags, layout) {
   /** @type {Record<string, any>} */
   let patch;
   if (verb === "clear") patch = { [key]: key === "description" ? "" : null };
-  else if (key === "notify") {
+  else if (key === "alerts" || key === "judge") {
+    patch = { [key]: await mergedEntry(url, flags, key, rest, ws, view, `foldrun workspace set ${key}`) };
+  } else if (key === "notify") {
     const [channel, value] = rest;
     if (channel !== "email" && channel !== "url") throw new Error("`foldrun workspace set notify email <address>` or `set notify url <https://…>` — and --events failed,awaiting-approval,completed");
     if (!value && flags.events === undefined) throw new Error(`\`foldrun workspace set notify ${channel} <value>\` — or --events alone to change only what is notified on`);
@@ -10296,9 +10532,17 @@ async function oauthClientsCmd(positional, flags) {
     const token_url = flags["token-url"] ?? preset?.token_url;
     if (!authorize_url || !token_url) throw new Error("--provider, or both --authorize-url and --token-url");
     const client_id = flags["client-id"] ?? env("OAUTH_CLIENT_ID") ?? (await promptVisible("  client_id: "));
-    const client_secret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden("  client_secret: "));
-    if (!client_id || !client_secret) throw new Error("client_id and client_secret are required");
-    const config = { authorize_url, token_url, client_id, client_secret, scopes: flags.scopes ?? preset?.scopes_example ?? "", ...(preset?.authorize_extra ? { authorize_extra: preset.authorize_extra } : {}) };
+    const pkce = flags["no-pkce"] !== true;
+    const client_secret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden(`  client_secret${pkce ? " (empty for a public app)" : ""}: `));
+    if (!client_id) throw new Error("client_id is required");
+    if (!client_secret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
+    if (flags.issuer !== undefined && (typeof flags.issuer !== "string" || !/^https:\/\/[^?#]+$/.test(flags.issuer))) throw new Error("--issuer is the provider's https issuer URL, no query or fragment");
+    const config = {
+      authorize_url, token_url, client_id, client_secret: client_secret ?? "", scopes: flags.scopes ?? preset?.scopes_example ?? "",
+      ...(preset?.authorize_extra ? { authorize_extra: preset.authorize_extra } : {}),
+      ...(pkce ? {} : { pkce: false }),
+      ...(typeof flags.issuer === "string" ? { issuer: flags.issuer } : {}),
+    };
     await remoteCall(url, flags, "/api/oauth/clients", { method: "POST", body: JSON.stringify({ name, config }) });
     console.log(`\n  ${c.green("✓")} saved ${name} ${c.dim(`— \`foldrun connect NAME --client ${name}\` runs a consent from it`)}\n`);
     return 0;
@@ -10315,9 +10559,15 @@ async function connectFromClient(name, flags) {
   const url = platformFor(flags, "connect --client");
   const workspace = typeof flags.to === "string" ? flags.to : undefined;
   const before = (await remoteCall(url, flags, "/api/oauth/connections")).connections?.find((s) => s.name === name && (s.workspace ?? undefined) === workspace)?.connectedAt ?? null;
-  const started = await remoteCall(url, flags, "/api/oauth/start", { method: "POST", body: JSON.stringify({ client: flags.client, secret: name, ...(workspace ? { workspace } : {}) }) });
+  // --scopes: this connection's own, instead of the saved client's default;
+  // the platform keeps them with the connection for its reconnects.
+  const scopes = typeof flags.scopes === "string" && flags.scopes.trim() ? { scopes: flags.scopes } : {};
+  const started = await remoteCall(url, flags, "/api/oauth/start", { method: "POST", body: JSON.stringify({ client: flags.client, secret: name, ...(workspace ? { workspace } : {}), ...scopes }) });
   const opened = flags["no-browser"] === true || !process.stdout.isTTY ? false : await openInBrowser(started.url);
-  console.log(opened ? `\n  Opened your browser to consent with the saved ${c.bold(flags.client)} client.\n` : `\n  Open this address in your browser:\n\n    ${started.url}\n`);
+  // The platform answers a hand-off page: a signed-in person accepts the
+  // connection there, then the provider's consent runs in that browser.
+  const what = started.handoff ? "accept the connection, then consent" : "consent";
+  console.log(opened ? `\n  Opened your browser to ${what} with the saved ${c.bold(flags.client)} app.\n` : `\n  Open this address in your browser to ${what}:\n\n    ${started.url}\n`);
   console.log(`  ${c.dim("Waiting for the platform to store it…")}`);
   const deadline = Date.now() + 10 * 60 * 1000;
   while (Date.now() < deadline) {
@@ -10352,7 +10602,11 @@ async function secretOfKind(kind, flags) {
     }
     case "api": {
       const lines = [].concat(flags.header ?? []);
-      if (!lines.length) lines.push(await promptHidden("  header (Name: value): "));
+      // --basic-user: HTTP Basic from a username and password (prompted, or
+      // --basic-password); the platform builds the Authorization header.
+      const basicUser = typeof flags["basic-user"] === "string" ? flags["basic-user"] : null;
+      const basic = basicUser ? { basic: { username: basicUser, password: typeof flags["basic-password"] === "string" ? flags["basic-password"] : await promptHidden("  password: ") } } : {};
+      if (!lines.length && !basicUser) lines.push(await promptHidden("  header (Name: value): "));
       const headers = Object.fromEntries(
         lines.filter(Boolean).map((l) => {
           const i = String(l).indexOf(":");
@@ -10361,7 +10615,23 @@ async function secretOfKind(kind, flags) {
         }),
       );
       const base = typeof flags["base-url"] === "string" ? { base_url: flags["base-url"] } : {};
-      return { body: { api: { ...base, headers } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
+      return { body: { api: { ...base, headers, ...basic } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
+    }
+    case "identity": {
+      // A keyless cloud identity: only the audience; the platform signs the
+      // tokens (`foldrun identity` prints what the cloud must trust).
+      if (typeof flags.audience !== "string" || !flags.audience.trim()) throw new Error("--kind identity needs --audience <value your cloud's trust expects in aud>");
+      return { body: { identity: { audience: flags.audience } }, local: (k, n, b, s) => k.setIdentitySecret("default", n, b.identity, s) };
+    }
+    case "client-cert": {
+      // A client certificate for mutual TLS. Bind it to the exact hosts it is
+      // for with `foldrun secrets sites NAME host`; the egress proxy presents
+      // it there. --export also puts it in the sandbox as files.
+      const cert = read(flags["cert-file"], "--cert-file <cert.pem> — the certificate, chain included");
+      const key = read(flags["key-file"], "--key-file <key.pem> — its private key");
+      const passphrase = typeof flags.passphrase === "string" ? flags.passphrase : undefined;
+      const client_cert = { cert, key, ...(passphrase ? { passphrase } : {}), ...(flags.export === true ? { export: true } : {}) };
+      return { body: { client_cert }, local: (k, n, b, s) => k.setClientCertSecret("default", n, b.client_cert, s) };
     }
     case "service-account": {
       let j;
@@ -10371,7 +10641,9 @@ async function secretOfKind(kind, flags) {
         if (err instanceof SyntaxError) throw new Error(`${flags.file} is not JSON — the key file Google gives you`);
         throw err;
       }
-      const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "" };
+      // --subject: the user it acts as (domain-wide delegation, granted by the
+      // provider's admin); without it the account acts as itself.
+      const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "", ...(typeof flags.subject === "string" ? { subject: flags.subject } : {}) };
       return { body: { service_account: sa }, local: (k, n, b, s) => k.setServiceAccountSecret("default", n, b.service_account, s) };
     }
     case "m2m": {
@@ -10382,7 +10654,7 @@ async function secretOfKind(kind, flags) {
       return { body: { oauth2 }, local: (k, n, b, s) => k.setOAuth2Secret("default", n, b.oauth2, s) };
     }
     default:
-      throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account or m2m (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
+      throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account, m2m, client-cert or identity (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
   }
 }
 
@@ -10948,6 +11220,9 @@ export async function run(command, positional, flags, workspace, layout) {
       if (positional[0] === "new" && positional[1]) return evalNewCmd(positional[1], flags, layout);
       // --to names a deployed workspace: its evals run there.
       if (typeof flags.to === "string") return remoteEvalsCmd(positional[0], flags, layout);
+      // --last reads the platform's results; a local eval has none to read,
+      // and running the cases instead would break its promise to run nothing.
+      if (flags.last === true || flags.run !== undefined) throw new Error("--last and --run read a deployed workspace's results — add --to <workspace>");
       needsOne(layout, "eval");
       return runEvals(positional[0], flags);
     case "promote":
@@ -11035,6 +11310,10 @@ export async function run(command, positional, flags, workspace, layout) {
       return rerunCmd(positional[0], flags, layout);
     case "account":
       return accountCmd(positional, flags);
+    case "identity":
+      return identityCmd(flags);
+    case "jobs":
+      return jobsCmd(flags, layout);
     case "schedule":
       if (positional[0] === "tick") return scheduleTickCmd(flags);
       return scheduleCmd(flags);