foldrun 0.5.0 → 0.7.2

package/docs/runs.md

@@ -0,0 +1,238 @@
+# Runs
+
+A run is the record of a flow being driven from its first step to its last:
+every step's reply, every tool call, every cost, and one line at the top that
+says what happened. It is the unit of the debug loop and the thing a person
+reads when they were not there.
+
+## The record
+
+Each run holds its steps in group order. A step carries:
+
+| field | what it is |
+|---|---|
+| `status` | `pending`, `running`, `awaiting-approval`, `completed`, `failed`, `skipped` |
+| `result` | everything the agent wrote, every turn joined |
+| `conclusion` | the final turn alone — what it concluded |
+| `data` | the parsed value, for a step with `output: json` |
+| `events` | tool calls, script runs with their timing, verify verdicts, refusals |
+| `costUsd`, `tokens`, `computeSecs`, `startupSecs` | what it cost and how long the sandbox lived — **summed across its attempts** |
+| `image` | which runner image the step's sandbox ran (isolated runs on a cluster): `variant` `full` or `slim`, `why`, and `pod: true` when a browsing step ran slim and browsed through the account's browser pod ([slim steps and a lost pod](tools#slim-steps-and-a-lost-pod)) |
+| `browserPod` | on a step that browsed through the pod from slim: `reconnects` (tries), `reconnected` (how many got through: the call went on after it) and `closedAgain` (how many reached the pod only for the call to drop again at once, when any did); when the pod was lost, `lost` (`cause` `lost` or `needs-full`, and `detail`) and `writes` (what the step had written by then, worded); then `fallback: "browser pod lost; re-ran on full"` when it had only read and ran again on the full image, or `failure` — `browser pod died after the step had written <what>` — when it had written and was not re-run |
+| `tries` | one row per attempt, oldest first (and a `status: "lost"` row, `image: "slim"`, before the full re-run when the browser pod was lost under a slim step that had only read — see [tools](tools#slim-steps-and-a-lost-pod)): `n` (the try, numbered in the order they ran), `attempt` (the step's attempt it belongs to, only when that is not `n` — the full re-run after a lost slim try 1 is `n: 2, attempt: 1`), `status`, `costUsd`, `tokens`, `computeSecs`, `startedAt`, `finishedAt`, the attempt's `image` and its `browserPod` line when it had one, and the attempt's last `error` when it failed. A `retry: 2` step that failed twice and then passed has three rows, and its `costUsd` is all three — the run's spend, the flow's `budget:` and the bill read the step's figure, so the figure is the total. A retry is handed what is left of the budget after the failed attempt spent, and nothing left means no retry, said on the record |
+| `item` | for a fan-out instance, which item this one handled |
+
+The run's `summary` is the **first meaningful line of the last step's
+conclusion** — heading marks and bullets stripped. It is the row in the runs
+list, the subject of the notification, and what a later run sees through
+`recall_runs()`. Nothing declares it; the runtime asks every agent to open its
+reply with one sentence saying what it concluded, and reads the line it wrote.
+An agent that opens with "I'll start by…" makes all three useless.
+
+## The run page
+
+Every run has a page of its own, `/dashboard/<workspace>/runs/<run>`, and
+every list, card, alert and search result that names a run opens it; the
+old `?run=` links still land there. It opens on the answer: how the run
+ended — status and the agent's verdict read together, so a run that
+completed and reported BLOCKED shows **blocked**, not green — what it was,
+its headline, when it started, how long it took, its steps and cost. If a
+step failed, its reason sits right under that, one click from the step
+(`#step-3` in the address opens and shows any step). A strip of the same
+flow's recent runs, this one ringed, says whether this was a one-off. **←**
+and **→** move to the older and newer run, **u** back to the list.
+
+Below that, the step list, the trace and a timeline —
+one bar per step with its tool calls marked in milliseconds, so a slow run
+says which step was slow. Every step shows its instruction, what it was
+handed from earlier groups, what it returned, its cost, and how many times it
+reached for a path it was not allowed and was refused (see [Security](security)).
+
+The page follows the run as it moves, gates included, without a reload: a
+**live** dot beside the status says the stream is connected (amber while it
+reconnects), and the browser tab reads the state and the step — `● running ·
+step 3/7` — so you can switch away and still see where it is. Only the step
+that is happening is open; a finished step folds to one line with its
+headline, duration, tokens and cost, and the next step opens as it starts.
+Click a step to pin it open or shut, or use **expand all** / **collapse
+all** above the column. A **json** link opens the run record exactly as the
+runner wrote it.
+
+A step's trace marks each line for what it is — the agent's words, a tool
+call (its name, then what it was called with, a click from whole), a verify
+result as **verified** or **verify failed**, an error, or the runner's own
+plumbing (egress, timings, resources), which is dimmed. Chips above it show
+only one kind, errors included; **full height** shows all of it at once. A
+step that drove a browser shows it live, then plays its recordings — see
+[Tools](tools#watching-it-live-and-the-recording).
+
+The account's home opens on **mission control**: what is **running now**
+(each run's step and agent, and anything running over an hour flagged), what
+**needs attention** (the newest failed, BAD or BLOCKED run of each flow in
+the last day with why, and anything waiting for an approval), and every
+desk's **last 24 runs** as a strip of cells beside its success rate, runs
+today and a week's spend. Every row and every cell opens its run.
+
+Each agent also has an **Activity** page: every step it has ever run, across
+flows and direct runs, with that step's own headline. It is where "how has
+this agent been going" is answered without opening runs one at a time.
+
+## Gates
+
+A step marked `2!` or carrying `approve: true` / `ask: <question>` parks the
+run until a person decides. Three doors open it, and the trace says which:
+
+- **the dashboard** — Approve or Reject on the run page, with a note that is
+  kept on the record;
+- **the emailed link** — the notification carries approve and reject links
+  when the install has a public URL;
+- **an external event** — a `wait: event` step is released by a POST to the
+  run's event URL, and what was posted reaches the next step.
+
+The answer typed at an `ask:` gate reaches the next step's prompt, so "GO,
+but skip the third one" is an instruction the publisher reads.
+
+**Who may answer.** A flow's `approvers:` names the addresses that may decide
+its gates, or `admins` for anyone at admin or above; unset, anyone who can
+run the workspace can answer. On top of that, and whatever the list says,
+**nobody approves a run they started themselves** — a gate exists so a second
+person looks. Rejecting your own run is always allowed. An API key carries a
+role but no address, so a key is not caught by the self-approval rule and
+only an `approvers:` list constrains it.
+
+**How long it waits.** By default, forever — which also means the run holds
+its place in the account's concurrency for as long as nobody looks. A flow's
+`approve_within:` stamps a deadline when the gate opens; past it the gate is
+**rejected**, the run fails, and the destination hears why. Rejection is the
+only safe way for a clock to answer a question a person was asked.
+
+## Test runs
+
+A test run is a real run of the flow that changes nothing outside it. Every
+step runs — the same agents, the same files, the same read APIs, the same
+gates — and the platform, not the desk's own script, makes sure nothing goes
+out and nothing real is written. It exists because every desk that sends had
+grown its own test switch inside its own code, and a switch a script can
+reach is a switch a script can move: on one occasion a send step edited its
+own gate file to get past its guard. The guard now lives where the step
+cannot reach it.
+
+Start one with the **Test run** checkbox on the Run button, `foldrun run
+<flow> --test` locally, `foldrun invoke <flow> --test` on a platform, or
+`POST .../flows/<flow>/run` with `{ "test": true }`. An eval's runs are test
+runs, and so is every run in a preview workspace (`<ws>-preview-<branch>`),
+unless the eval or the flow says `live: true` in its frontmatter — the safe
+default is opted out of, never into. A re-run of a test run, or a run started
+from one of its steps, stays a test.
+
+What the platform does on a test run, in the order a step meets it:
+
+| where | what |
+|---|---|
+| the egress proxy | any `POST`, `PUT`, `PATCH` or `DELETE` to a host that is not a model provider or a read-only service is **refused** with `403` and a JSON body `{ "test_mode": true, "would_have": { method, host, path, to, body } }`. A Resend `POST /emails` is instead **redirected**: the recipients become `delivered@resend.dev` (Resend's sink), the subject is prefixed `[TEST] `, and the call goes through — so a desk still gets a real message id. Reads (`GET`, `HEAD`, `OPTIONS`) pass. A host with no granted secret is refused as always |
+| the sandbox | secrets whose name says they can send — `RESEND_API_KEY`, `TWILIO_*`, `GETREACH_API_KEY`, `GITHUB_TOKEN`, `MONDAY_API_TOKEN`, `OI_CRM_API_KEY`, `CLOUDFLARE_*`, `LINKEDIN_*`, `MEDIUM_COOKIES`, `TIKTOK_*` — are **withheld**: the env var reads `TEST_MODE_WITHHELD`, so a script that never checked fails at the provider with an auth error rather than sending. A step granting a script tool marked `outward: true` gets no real secret at all; one granting a tool marked `test_mode: allow` gets them all. The sandbox also has `FOLDRUN_TEST_MODE=1` and `FOLDRUN_RUN_TEST=1`, for scripts that branch on it. The http tools still go through the proxy, where the table above applies |
+| the browser | the step is handed no account [browser pod](tools#where-the-browser-runs): the tool launches Chromium inside the run pod, which the run namespace's policy denies the internet, so a `web action=browse` call fails closed rather than fetching the world through a pod the policy does not select |
+| the write-back | `state/` and `storage/` go into the sandbox as they are; what the step wrote there comes out under `runs/<id>/test-writes/state/…` and `…/storage/…`, and the workspace's copies are untouched. Nothing is harvested to the file store and nothing under `storage/public/` is published |
+| the record | `test: true`; the summary opens with `[test]`; a **TEST** badge beside the status in the runs list and on the run page; every refusal, redirect, diversion and withheld secret is an event carrying an `effect`, and the run page's **Test run** panel lists them — "would have written state/sends.md, +3 lines" |
+| the rest | gates still park, and the approve page says it is a test run; notifications go out only for `failed`; a `trigger: flow` chained on a test run starts as a test run |
+
+Locally (`foldrun run --test`) there is no egress proxy, so the first row does
+not apply: a script that ignores `FOLDRUN_TEST_MODE` and has its own way to a
+provider is stopped only by the withheld secret. The other rows hold.
+
+The list of hosts an outward write may reach, the secret-name patterns and
+the Resend rewrite live in one table in core (`src/test-mode.ts`), with unit
+tests, so "what does a test run refuse" is a file and not a search.
+
+## Stopping, re-running, promoting
+
+**Stop** ends the run and destroys its sandbox, not just the record. A
+stopped run is recorded as stopped; it never quietly completes.
+
+**Stop and re-run in bulk.** `POST /api/workspaces/<ws>/runs/bulk` applies
+one of those two actions to every run a small filter names — statuses, a
+flow, a time window, or an explicit list of ids. It is the tool for the
+morning when one broken thing failed seventy runs. A call naming no filter is
+refused rather than treated as everything, `dryRun: true` shows what would be
+touched, and each run is its own outcome so one that cannot be stopped does
+not abort the rest.
+
+**Re-run from a group** (`from: N`) starts a new run at group N with the
+earlier groups recorded as skipped, not invented — the step reads what earlier
+steps wrote to `storage/` and `state/`, which is the durable handoff. Use it
+to redo the interesting half after a fix.
+
+**Promote** turns a run that worked into an eval case: its task and the
+result it should reproduce. The eval runs on every push from then on.
+
+## Why nothing happened
+
+The hardest question this platform gets is not about a run — it is about a
+run that does not exist. Every honest answer to it is a thing that
+deliberately did not happen: a duplicate delivery, a burst still being
+waited out, a throttled trigger, a flow switched off after a bad week, an
+`overlap: skip`, a fire missed while nothing was running.
+
+The Triggers page on each workspace records all of it: one row per flow
+saying how often its trigger fired, how often that became a run, and what
+the difference was, with the key in the flow file that decided each one. Its
+last section is the delivery log, which answers the separate and earlier
+question of whether a request arrived at all and was authentic — a bad token
+never reaches a flow rule, so it appears there and nowhere else.
+
+`GET /api/workspaces/<ws>/triggers` is the same thing as JSON.
+
+## Handoffs
+
+A step is handed the replies of **every earlier group**, oldest first, capped
+at about 30,000 characters with the newest kept. For a list that a later step
+must get exactly, or a report a person should also read, have the step write
+it to `storage/` — a tool that takes an `out=` path and tees its own output
+is the reliable way, because a model asked to copy a long report by hand
+shortens it.
+
+## What a run costs, and what stops it
+
+Every step records what it cost. A flow's `budget:` is checked between
+groups: the group that crosses it is the last that runs, and the run fails
+saying so. The workspace's and the account's `budget:` over time sit above
+that. See [Budgets and billing](budgets-and-billing).
+
+Finished runs older than the install's retention are pruned. Their headline
+survives in the eval history and in what agents can recall.
+
+## The runs list
+
+Beside the records sits `runs/.index.json`: one row per run with what a
+list needs — id, flow, status, summary, times, and each step's agent,
+status, cost, tokens, seconds and last error — never a reply or a trace. It
+is written with the record and repaired from the directory by any reader
+that finds a row missing, stale, or orphaned, so it is never trusted over
+the files. The runs pages and the account-wide list read it; a run still
+live is read whole; a finished run's reply and trace are opened by id.
+
+## What survives the platform
+
+A step is a sandbox that keeps its own log and files until the platform
+has read them back. On a cluster, the record carries which sandbox a
+running step is in and how much of its output has been applied — so when
+the worker that started it goes away, a deploy rolling it or a crash, the
+next worker **re-attaches** to the same sandbox and carries on from that
+line. Finished steps stay finished; the interrupted one is neither re-run
+nor lost, and the trace says `driver changed mid-step — re-attaching`. A
+deploy no longer costs a run; a step that was quiet for an hour inside a
+long tool call is still the same step afterwards.
+
+Only a sandbox that has actually ended — the cluster killed it, or nobody
+came back for it within forty minutes — is reported as such, in the
+cluster's own words (`OOMKilled`, `Evicted`), and handed to the step's
+`retry:` policy. Locally, with steps in containers rather than pods, an
+interrupted step is run again from its start, as before.
+
+A step whose program exits without reporting a result — it crashed after
+its last tool call — no longer waits out those forty minutes. The platform
+notices the exit within about half a minute, reads the whole log once more
+in case only the stream missed the result, and otherwise fails the step
+with `the step's program exited (code N) without reporting a result`
+followed by the last lines the program printed on stderr. The sandbox is
+still held at that point, so the files the step wrote are kept.

package/docs/scheduling.md

@@ -0,0 +1,103 @@
+# Scheduling and triggers
+
+A flow starts when its trigger fires. The default is a person — a button, an
+API call, `foldrun invoke` — and everything else is a line in the flow's
+frontmatter.
+
+## Triggers
+
+| `trigger` | starts when | the first step is handed |
+|---|---|---|
+| `manual` (default) | a person clicks Run, `foldrun invoke`, or an API call | an optional task |
+| `schedule` | the cron matches | nothing |
+| `once` | the instant in `at:` passes — fires once | nothing |
+| `webhook` | an HTTP POST reaches the flow's hook URL | the request body |
+| `email` | a message arrives at the flow's inbox URL | from, to, subject, text |
+| `flow` | the flow in `after:` settles the way `on:` says | that run's id, status, summary, result |
+| `storage` | a file lands under `path:` in this workspace's storage | the paths and who wrote them |
+| `watch` | the content at `url:` changes (polled every `every:`, default 15m) | the new content |
+
+A flow may not chain on itself. `watch` records its first sighting without
+firing. A `once` more than six hours gone at first sighting is recorded and
+never fired, so a flow deployed late does not run yesterday's job today.
+
+## Schedules
+
+```yaml
+---
+name: rankings
+trigger: schedule
+schedule: "0 5 * * 3"          # five-field cron
+timezone: Australia/Sydney     # IANA zone; UTC if unset
+overlap: skip                  # or queue; unset, runs may overlap
+catchup: last                  # or none — what a fire missed while down becomes
+budget: 5
+---
+```
+
+`overlap:` decides what a new fire does while a run of the same flow is
+live: `skip` consumes the occurrence — a cron re-firing over yesterday's
+long run almost never means "run two" — and `queue` starts it and holds it
+until the live one finishes.
+
+`catchup:` decides what a missed fire becomes. Nothing runs while the
+platform is down, and when it comes back the default — `catchup: last` — makes
+**one** make-up run, however many fires were missed. `catchup: none` skips it
+and waits for the next real occurrence, which is what a 07:00 report wants
+when it is noticed at 11:00. A fire a minute or so late is never treated as a
+make-up run: that is a tick running slightly behind.
+
+`throttle:`, `debounce:`, `idempotency:` and `disable_after:` shape how often
+a trigger becomes a run at all, and are described in
+[the flow reference](flows.md).
+
+**The cron trap worth knowing.** When both day-of-month and day-of-week are
+restricted, they are OR'd, not AND'd — by this scheduler and by cron itself.
+`0 5 1-7 * 5` looks like "the first Friday" and fires every Friday *and*
+every day of the first week: about eleven runs a month. For a monthly job,
+use a plain day of month (`0 5 3 * *`) and let the weekday go.
+
+**Daylight saving.** The schedule is read in `timezone:`, and when the clocks
+change it behaves as Vixie cron does. A job at a fixed time — neither minute
+nor hour a `*` — fires once in an hour that happens twice, the first time
+round, and a time the clocks skip fires once, at the first instant after the
+gap. Sydney's `30 2 * * *` runs once on 5 April and at 03:00 on 4 October. A
+`*` in the minute or the hour follows the clock as it is: an hourly job runs
+in both copies of a repeated hour and not in a skipped one.
+
+## One desk per day
+
+A pattern that has held up: give each scheduled flow its own morning, so a
+day's spend and a day's failure are one thing to read about. Put the flow
+that writes to a shared repository on the day nothing else does — two flows
+committing to the same `main` in one morning is a merge conflict at best.
+Run the cheap measurement before the expensive action, so the action reads a
+fresh measurement.
+
+## Webhooks and inboxes
+
+A `webhook` flow has a hook URL —
+`/api/hooks/<account>/<workspace>/<flow>?token=…` — and an `email` flow an
+inbox URL of the same shape. The token is derived, not stored; rotating it
+(`POST …/hooks/<flow>/rotate`) stops every old URL at once. A flow with
+`signature: github | stripe | slack | hmac` and a `signing_secret:` also has
+the provider's signature checked, and a Slack `url_verification` body is
+answered with its challenge and starts nothing.
+
+## Chaining
+
+```yaml
+trigger: flow
+after: rankings
+on: completed        # or failed, or any
+```
+
+The chained flow's first step is handed the finishing run's id, status and
+summary — and its result, so a flow that reports on another flow reads what
+it concluded rather than re-deriving it.
+
+## Composition
+
+A step may name a flow instead of an agent — `1. [[flow:weekly]] — …` — and
+that flow's steps run in place, keeping their own parallelism. Cycles, and
+nesting past three levels, are errors `foldrun check` reports.

package/docs/secrets.md

@@ -0,0 +1,163 @@
+# Secrets
+
+A secret is a value an agent may use and must never see written down. It is
+stored in the platform's vault, named in an agent's `secrets:` list, and
+handed to that agent's scripts as an environment variable at run time. It is
+never written into the workspace, never printed into a prompt, and never in
+git — which is what makes a workspace safe to commit.
+
+
+## Setting one
+
+```sh
+foldrun secrets set STRIPE_KEY               # this workspace's; prompted, never echoed
+foldrun secrets set STRIPE_KEY --account     # the account's, shared by every workspace
+foldrun secrets ls
+```
+
+Or in the dashboard under Settings → Secrets, or over the API:
+
+```sh
+PUT /api/secrets   { "name": "STRIPE_KEY", "value": "sk_live_…" }
+```
+
+`PUT` takes a name plus exactly one shape:
+
+| shape | for |
+|---|---|
+| `value` | a string — an API key, a password |
+| `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 |
+
+Reads return which secrets exist, never their values.
+
+## Scopes
+
+A secret lives at the **account** or in one **workspace**. An agent looks in
+its workspace first, then the account; a workspace secret shadows an account
+one of the same name. The run trace says which scope each secret came from
+(`secret DATAFORSEO_LOGIN ← workspace scope`), so a workspace quietly falling
+back to a shared credential is visible rather than silent.
+
+Put a credential at the account when every workspace should use the same one
+— your model provider, your email sender. Put it in a workspace when it is
+that job's — a customer's Search Console, a CRM key.
+
+## How an agent gets it
+
+```yaml
+---
+name: enricher
+tools: [crm_lookup]
+secrets: [OI_CRM_API_KEY]
+---
+```
+
+The agent's scripts see `OI_CRM_API_KEY` in their environment and nothing
+else. The model never sees the value: it sees that a tool exists, calls it,
+and the script reads the variable. The assembled prompt names which secrets
+are available and says, in as many words, never to print or write them.
+
+A `verify:` command on a step runs with the same environment, so a check can
+call the same API the step did.
+
+A value with a line break in it — a PEM key, a service-account JSON — cannot
+travel as an environment variable. It arrives as a file instead: a
+private file in the step's copy of the workspace, with the variable holding
+its path, and the run log names the secret that was handed over that way.
+
+## Where the value actually is
+
+On a cluster, the value is usually not in the sandbox at all. The worker
+holds it and hands the step a per-step address — the **egress proxy** —
+and every `http` tool and the model call itself send their requests through
+it with `${NAME}` still in the header. The proxy fills the placeholder on
+the way out, for the one host that secret was granted to, and forwards.
+The value exists in the worker's memory and on the wire to the provider; a
+program in the sandbox that reads its environment finds `RESEND_API_KEY`
+set to the literal text `${RESEND_API_KEY}`. An oauth2 or service-account
+secret is exchanged for a live token at the proxy too, so the recipe never
+crosses either.
+
+Script tools are the exception, because a script may need the value in
+process — the browser seeding a site's cookies, an ssh key. A step that
+grants such a script gets its declared secrets **materialised** into the
+sandbox as real values, and the run trace says so:
+
+```
+secrets: MEDIUM_COOKIES, RESEND_API_KEY materialised in the sandbox for browser; api tools and the model key go through the egress proxy
+```
+
+A script that sends through the proxy itself declares it, and then gets the
+placeholders like everything else:
+
+```yaml
+---
+transport: script
+name: crm_sync
+run: sync.py
+secrets: proxied      # reads FOLDRUN_EGRESS, sends ${NAME} in its headers
+---
+```
+
+The proxy is an allowlist, not a door: a step may send only to the hosts
+its declared tools and provider name, and `${STRIPE_API_KEY}` in a request
+to api.resend.com stays literal. Every request through it is one line in
+the trace — `egress: POST api.resend.com/emails → 200 (312ms)
+[RESEND_API_KEY]` — and the model's own calls are grouped, `× 34`. Leases
+live in the worker's memory, or in Redis when the install has one — as
+ciphertext under the account's key, six-hour expiry — so a request may
+land on any worker behind the Service and still find its lease. Without
+a proxy configured (the CLI, a compose install without
+`FOLDRUN_EGRESS_URL`) a step materialises everything, as it always did.
+
+## Connected accounts
+
+Some third parties are connected rather than pasted — Google, GitHub,
+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.
+
+## How they are kept
+
+Every account has its own encryption key. Secrets are sealed under it, and
+the account keys are wrapped by one root key the platform holds. A stolen
+copy of one account's secrets file opens nothing without the root key, and
+the root key is not in any backup — every backup file, the platform's own
+configuration included, is encrypted to a key the platform does not hold. See
+[Security](security) and, for the CLI on your machine, [Running it yourself](self-hosting).
+
+Rotating a secret is setting it again. The next run reads the new value; runs
+in flight keep the one they started with.
+
+## Whether a credential still works
+
+The vault knows a secret's name, its scope and its shape. Whether the thing
+on the other end still accepts it is a different question, and until it is
+answered a dead key, an untouched key and a working key all render the same
+way.
+
+Two facts are recorded, at the places that already know them and nowhere
+else. The egress proxy sees every http tool call and every model call,
+because filling the credential is its job; notifications and the provider
+check report their own. Nothing is instrumented for this.
+
+| shown | means |
+|---|---|
+| accepted by *host* on *date* | the far end took it, that recently |
+| refused by *host* on *date* | 401, 402 or 403 — the credential itself was rejected, with the date it last worked |
+| *host* failed | a 5xx at their end, which says nothing about the key |
+| not used yet | nothing has tried it, which is not the same as working |
+
+Only 401, 402 and 403 count against a key. A provider failing at its own end
+is not a reason to rotate anything, and counting it would send people to fix
+the wrong thing.
+
+A secret materialised into a sandbox reports nothing: the call happens inside
+the pod, where the platform cannot see the answer. The page says so rather
+than guessing.
+
+Rotating or deleting a secret forgets what the old one did. A fresh key
+showing its predecessor's refusals is the moment someone stops believing the
+indicator.

package/docs/security.md

@@ -0,0 +1,167 @@
+# Security
+
+The platform runs code it did not write, on behalf of people who may be
+wrong about what it will do, next to other people's data. Everything in its
+design follows from taking that seriously. This page is what an agent can
+and cannot do, and why.
+
+## Where a step runs
+
+Every step executes in its own sandbox, created for it and destroyed after
+it: a hardened container on a single box, a **gVisor** pod on a cluster.
+The sandbox holds a copy of the agent's folder and nothing else — not the
+platform's filesystem, not the vault, not another workspace. When the step
+ends, its files copy back through a filter, and the sandbox is gone.
+
+Startup is under a second warm, so this is not the latency it sounds like;
+it is the boundary that lets one account's agent and another's share a
+machine.
+
+## What the network allows
+
+A run pod may reach the public internet, DNS, the egress proxy where its
+credentials are filled in, and its own account's search and browser pods —
+and nothing else. The policy denies every private range (RFC1918) and the
+cloud metadata endpoint — the address that, on a cloud host, hands out the
+machine's own credentials. It cannot reach the platform's API, its
+database, its object store, or another account's pods. Workspace files
+come and go through presigned URLs, so no bucket credential is ever in a
+pod. A [test run](runs#test-runs) is denied the internet and the browser
+pod as well, at the network, so an outward call from a script fails closed
+whatever the script does.
+
+The CNI that enforces this is Cilium. Two things follow
+from that for anyone writing a rule: a pod is matched by its identity —
+its labels — never by an address range, so an `ipBlock` on the pod CIDR
+admits nothing and every in-cluster rule is a selector; and a deny beats
+every allow, which is how a test run keeps every ordinary allow and loses
+the internet. Hubble records every flow and every drop, which is where a
+"why can't this step reach X" question is answered.
+
+What a run reaches on the internet, it reaches as itself. A tool that calls
+a third party does so with the secret the agent was granted, and nothing
+about the platform.
+
+## What the file tools allow
+
+An agent's built-in Read, Write, Edit, Glob and Grep are confined to its
+workspace: its own folder, the workspace's shared directories, and the
+account library read-only. A path outside — an invented `/tmp/…`, an
+absolute path, a directory a tool cloned outside the workspace — is refused
+with a message naming the path the agent probably meant. Three more things
+stay off limits inside the workspace: the secrets file, the run journal,
+and the generated index of a knowledge bundle.
+
+Refusals are counted per step and shown on the run page. Each one is a
+wasted turn; a prompt that names the exact path brings the count to zero.
+
+## Secrets
+
+An agent names a secret in `secrets:`; the model never sees the value — it
+sees that a tool exists and calls it. Secrets are never written into a
+workspace, never in git, and reads of the vault return names, not values.
+
+On a cluster the value does not enter the sandbox either. The worker keeps
+it and the step sends its API and model requests through a per-step
+**egress proxy** with `${NAME}` placeholders; the proxy fills each one for
+the host it was granted to and forwards. A compromised script in the pod
+reads its environment and finds the name, not the key. The one exception
+is a script tool that needs the value in process (a browser seeding
+cookies), which materialises the step's secrets into the sandbox and says
+so in the trace — see [Secrets](secrets).
+
+At rest, each account has its own encryption key; the account keys are
+wrapped by one root key the platform holds. A stolen copy of an account's
+secrets opens nothing without it.
+
+Backups are encrypted before they leave the server. The nightly archive —
+every workspace, run record and the database — and the server's key file
+are encrypted with age to a public key whose private half is not on the
+server, so a copy of the backup bucket opens nothing; the job refuses to run
+rather than ship anything unencrypted. See [Backups and restore](backups-and-restore).
+
+Wherever a step's children run on the host itself rather than in a sandbox
+— a script tool, a `verify:` shell, the model's own Bash tool on a laptop
+or the host executor, a tool test in the dashboard — they start from an
+allowlisted environment, never the platform's own: `PATH`, `HOME`, the
+locale, the clock, proxy settings, `NODE_*`, the run's `FOLDRUN_RUN_*`
+identifiers, and the secrets the agent declared, by name. The root key,
+the datastore and mail credentials are not in it. A run container needs
+none of this: its environment is the boundary, assembled from the same
+rule before it starts.
+
+A run's record is scrubbed the same way its events are: a secret quoted in
+a step's reply, its conclusion or an `output: json` value is written as
+`[redacted:NAME]`. Every hook and approval token derives from the vault's
+own key, created the first time anything asks — never from a constant.
+
+## Capability is structural
+
+A step can do only what its agent's file grants: the tools it names, the
+secrets it names, the colleagues it may consult. An agent with no tool that
+writes cannot write, whatever it is told or tricked into. This is the
+platform's answer to prompt injection: not a paragraph asking the model to
+be careful, but a file in which the dangerous thing is absent.
+
+The pattern that follows from it, and that the reference desks use: the
+tool that *proposes* a change and the tool that *applies* it are two tools,
+and only the step after a human gate holds the second.
+
+## Gates and the record
+
+A `!` on a step parks the run for a person, and the run cannot proceed
+without a decision that is recorded — by whom, through which door, with
+what note. An emailed approve link decides **one step, once**: its token
+is bound to that step, expires (the flow's `approve_within:`, else a week),
+and — when the mail went to a named approver — decides as that person, so
+a forwarded link cannot walk past `approvers:`. Only a digest of a used
+token is kept, and a key rotation kills every old link. Share links are 24 random
+bytes; every failed fetch is the same 404.
+
+Every write to a workspace is a revision with an author; every sign-in, key
+use and role change is in the audit log; every step's tool calls, script
+runs and refusals are in the run's events. A run can be reconstructed from
+its record.
+
+## People
+
+Four roles, least privilege by route, one owner. See
+[Team and access](team-and-access). Sessions are revocable; API keys carry a
+role, can be given an end and rotated, show when they were last used, and
+cannot act as a named person. The account's
+[audit log](team-and-access#audit-log) records who did what — secrets by
+name only — for the owner and admins to read or export. Support can view an
+account only [read-only, for thirty minutes, with a reason the customer
+reads](team-and-access#support-access).
+
+## What is still yours to think about
+
+- A model reading a web page reads whatever is on it. Give the agent the
+  narrowest tools its job needs, and put a gate before anything irreversible.
+- A tool with write access to a third party — your repository, your CRM —
+  is a write. Scope the credential to what the tool must do.
+- Bring-your-own-key credentials are yours; the platform stores them sealed
+  and hands them to your steps, and never sees the bill.
+- The CLI on your machine runs steps as you, in your workspace, unless
+  `FOLDRUN_RUN_ISOLATION=container` is set. That is your laptop and your
+  call. See [Running it yourself](self-hosting).
+
+## Reporting a vulnerability
+
+Write to **hello@foldrun.io** with "security" in the subject. Do not open a
+public issue. The same address is in `/.well-known/security.txt` on
+foldrun.io and on the platform. Scope, what we will not pursue you for, and
+the response targets are on the
+[security page](https://foldrun.io/security/#report).
+
+## Subprocessors and the DPA
+
+The vendors that process customer data for the hosted platform — and the
+integrations that only run when *you* configure them with your own key —
+are listed at [foldrun.io/subprocessors](https://foldrun.io/subprocessors/).
+A data processing agreement is drafted at
+[foldrun.io/dpa](https://foldrun.io/dpa/); it is under legal review and not
+yet offered for signature.
+
+Whether the platform is up, and any incident, is on the status page — see
+[Status and incidents](status).