seisin 0.4.2 → 0.6.0

package/README.md

@@ -1,57 +1,65 @@
 # seisin
 
-[![test](https://github.com/carlostapiacl/seisin/actions/workflows/test.yml/badge.svg)](https://github.com/carlostapiacl/seisin/actions/workflows/test.yml)
+[![test](https://github.com/carlostapiacl/seisin/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/carlostapiacl/seisin/actions/workflows/test.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/carlostapiacl/seisin/badge)](https://scorecard.dev/viewer/?uri=github.com/carlostapiacl/seisin)
 [![npm](https://img.shields.io/npm/v/seisin?color=222)](https://www.npmjs.com/package/seisin)
-[![license](https://img.shields.io/badge/license-MIT-222)](LICENSE)
-[![node](https://img.shields.io/badge/node-%E2%89%A518-222)](package.json)
-[![no dependencies](https://img.shields.io/badge/dependencies-1-222)](package.json)
-
-**[The short version, with the demos playing →](https://carlostapiacl.github.io/seisin/)** · this page is the long one.
+[![license](https://img.shields.io/badge/license-MIT-222)](https://github.com/carlostapiacl/seisin/blob/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A518-222)](https://github.com/carlostapiacl/seisin/blob/main/package.json)
+[![one dependency: the sandbox runtime](https://img.shields.io/badge/dependencies-1-222)](https://github.com/carlostapiacl/seisin/blob/main/package.json)
 
 > **seisin** *(n.)* — the legal possession of a piece of land. Not who owns it on paper: who holds it now.
 
-**Give each AI agent its own folders and its own keys.** The kernel enforces it, and when it blocks something it tells you *whose* file it was.
+**Give each AI agent its own folders and its own keys.** The kernel enforces it, and when it denies something, seisin tells you *whose* file it was.
 
-A **permission layer**, not a sandbox — it sits on top of one. The isolation comes from the OS; what seisin adds is the part an OS cannot know: which role a path belongs to, and therefore who to ask next.
+![seisin denying a write outside a role's territory, then naming the owner](https://raw.githubusercontent.com/carlostapiacl/seisin/main/docs/img/demo.gif)
 
-*Two outside reviews went looking for ways past the boundary. [What they found, what broke, and what is still open →](docs/what-it-has-been-put-through.md)*
+```bash
+npm install -g seisin                  # on Linux, three system packages first: see Install
+seisin init && seisin check            # propose a policy from the repo, then read it
+seisin run <role> -- claude -p "…"     # the roles are the ones seisin check lists
+```
 
-*And what running four cells of agents behind it actually cost — including the numbers that did not survive a re-check. [Field notes →](docs/field-notes.md)*
+**Is it for me?** If two or more agents work in one repository, yes — that is what it is for.
+With one agent, its own sandbox covers most of this ([what is left over](#what-it-is-not)).
 
-**Three ways in, and they say the same thing.** The **CLI** is what a person types and what
-every agent runs under. The **console** (`seisin ui`) is for a person deciding something. The
-**MCP server** is for an agent asking about its own situation. A change to what any of them
-says lands in all three — [CONTRIBUTING](CONTRIBUTING.md#three-surfaces-and-a-change-lands-in-all-of-them)
-says why, and a test holds one half of it.
+**[The short version, with the demos playing →](https://carlostapiacl.github.io/seisin/)** · this page is the long one.
 
 <details>
 <summary><b>Contents</b></summary>
 
-**Start here** · [Sixty seconds](#sixty-seconds) · [Why this exists](#why-this-exists) · [What it is for, and what it is not for](#what-it-is-for-and-what-it-is-not-for) · [Install](#install) · [Use](#use) · [Configure](#configure)
+**Start here** · [What it does](#what-it-does) · [Sixty seconds](#sixty-seconds) · [Why this exists](#why-this-exists) · [What it is for, and what it is not for](#what-it-is-for-and-what-it-is-not-for) · [Install](#install) · [Use](#use) · [Configure](#configure)
 
 **Living with it** · [Day one](#what-will-look-like-a-bug-on-the-first-day) · [Which agents it has been run with](#which-agents-it-has-been-run-with) · [Where the first policy comes from](#where-the-first-policy-comes-from) · [When it says no, it leaves a request behind](#when-it-says-no-it-leaves-a-request-behind) · [When the boundary is right and the agent cannot hear it](#when-the-boundary-is-right-and-the-agent-cannot-hear-it) · [Scratch space, and what it costs](#scratch-space-and-what-it-costs)
 
-**Secrets** · [How it protects secrets](#how-it-protects-secrets) · [Keys in full](docs/keys.md)
+**Secrets** · [How it protects secrets](#how-it-protects-secrets) · [Keys in full](https://github.com/carlostapiacl/seisin/blob/main/docs/keys.md)
 
 **Looking at it** · [What the log says about the policy](#what-the-log-says-about-the-policy) · [Seeing what happened](#seeing-what-happened) · [Ask your own assistant](#ask-your-own-assistant)
 
 **The honest parts** · [How it holds](#how-it-holds) · [What it is not](#what-it-is-not) · [Why not a container](#why-not-a-container) · [Prior art](#prior-art) · [Status](#status)
 
-**Deeper** · [Keys](docs/keys.md) · [Agents](docs/agents.md) · [Day one](docs/first-day.md) · [Scratch](docs/scratch.md) · [Glossary](docs/glossary.md) · [What it has been put through](docs/what-it-has-been-put-through.md) · [Field notes](docs/field-notes.md) · [OpenShell compatibility](docs/openshell.md) · [Decisions](docs/decisions.md) · [nono backend contract](docs/nono-backend.md) · [Permission requests](docs/permission-requests.md) · [Contributing](CONTRIBUTING.md)
+**Deeper** · [Keys](https://github.com/carlostapiacl/seisin/blob/main/docs/keys.md) · [Agents](https://github.com/carlostapiacl/seisin/blob/main/docs/agents.md) · [Day one](https://github.com/carlostapiacl/seisin/blob/main/docs/first-day.md) · [Scratch](https://github.com/carlostapiacl/seisin/blob/main/docs/scratch.md) · [Glossary](https://github.com/carlostapiacl/seisin/blob/main/docs/glossary.md) · [What it has been put through](https://github.com/carlostapiacl/seisin/blob/main/docs/what-it-has-been-put-through.md) · [Field notes](https://github.com/carlostapiacl/seisin/blob/main/docs/field-notes.md) · [OpenShell compatibility](https://github.com/carlostapiacl/seisin/blob/main/docs/openshell.md) · [Decisions](https://github.com/carlostapiacl/seisin/blob/main/docs/decisions.md) · [nono backend contract](https://github.com/carlostapiacl/seisin/blob/main/docs/nono-backend.md) · [Requests](https://github.com/carlostapiacl/seisin/blob/main/docs/requests.md) · [Contributing](https://github.com/carlostapiacl/seisin/blob/main/CONTRIBUTING.md)
 
 </details>
 
+## What it does
+
+A **permission layer**, not a sandbox — it sits on top of one. The isolation comes from the OS; what seisin adds is the part an OS cannot know: which role a path belongs to, and therefore who to ask next.
+
+*Outside reviews went looking for ways past the boundary. [What they found, what broke, and what is still open →](https://github.com/carlostapiacl/seisin/blob/main/docs/what-it-has-been-put-through.md)*
+
+*And what running four teams of agents behind it actually cost — including the numbers that did not survive a re-check. [Field notes →](https://github.com/carlostapiacl/seisin/blob/main/docs/field-notes.md)*
+
 ```mermaid
 flowchart LR
     A["agent<br/>running as a role"] -->|writes src/api/orders.ts| K{{"the kernel<br/>Seatbelt · bubblewrap"}}
     K -->|not this role's| D["denied"]
-    D --> S["seisin reads the refusal<br/>and looks up the policy"]
+    D --> S["seisin reads the denial<br/>and looks up the policy"]
     S --> W["<b>whose it was</b><br/>belongs to backend"]
     S --> Q["a request, queued"]
-    Q --> H(["a person<br/>grants or declines"])
-    H -->|edits seisin.toml| P[("seisin.toml")]
-    P -.->|settings| K
+    S --> L[(".seisin/log.jsonl<br/>one hash-chained entry")]
+    Q --> H(["a person grants or declines<br/>in a terminal or the console"])
+    H -->|edits, with provenance| P[("seisin.toml")]
+    P -.->|"seisin run turns it into<br/>the sandbox settings"| K
 
     style D fill:#fde,stroke:#c66
     style W fill:#dfd,stroke:#6a6
@@ -60,35 +68,58 @@ flowchart LR
 
 **The kernel says no. seisin says whose.** That second half is the whole thing: other
 permission layers in this space answer *yes* or *no*, or at best *which rule* said no — and a
-refusal that also names an owner turns a dead end into a handoff.
-
-![seisin denying a write outside a role's territory, then naming the owner](docs/img/demo.gif)
+denial that also names an owner turns a dead end into a handoff.
 
 ```
 $ seisin run frontend -- sh -c 'echo // fix >> src/api/orders.ts'
-  sh: src/api/orders.ts: Operation not permitted
-  seisin: 1 kernel denial(s) recorded
-
-  1 pending request(s)
+seisin: frontend · writes src/web/** public/** (+6 scratch) · keys netlify-token.txt · runs no agent seisin knows · env 20 kept, 58 dropped · read all
+sh: src/api/orders.ts: Operation not permitted
+seisin: 1 kernel denial(s) recorded
 
     #1  frontend wants write on src/api/** (owned by backend)
         first asked over src/api/orders.ts
+        id frontend:write:src/api
+        handed to backend
 
-    seisin grant <n> [--reason "…"]   ·   seisin decline <n> [--reason "…"]
+  this run: 1 new request(s) — seisin requests
 ```
 
-**Whose it was, at the moment it was denied.** Other permission layers answer *yes* or *no*, and the good ones say which rule it was and how to widen it. Answering **"no, and it belongs to `backend`"** turns a block into a handoff — and one a person can approve in a command, rather than a line somebody has to remember to go and read.
+The first line is the run's own header: what this role may write, which keys it holds, and how
+much of your environment it did not inherit. The last lists only what this run filed; the
+rest of the queue is one count, and `seisin requests`.
+
+The line under the request is where it goes, decided from the policy as it stands: *handed to
+backend*, or *a person decides* when nobody or several roles own it. seisin does not start
+backend. Whatever does reads that decision (`seisin requests --json`, `seisin_requests`) and runs
+`seisin run backend --handoff frontend:write:src/api`, which starts only if the policy hands that
+request to backend — and anything backend is then denied joins the same handoff chain, so work
+cannot bounce back to frontend ([where a request goes](https://github.com/carlostapiacl/seisin/blob/main/docs/requests.md#where-a-request-goes)).
+A role that is a pipeline phase rather than a worker says `handoff = false`: it keeps its
+territory and is never handed work — what it owns goes to another owner, or to a person.
+
+A caller that probes the sandbox with a write it expects to be denied — its own canary — names
+that path with `--expect-denied <path>` (repeatable). The denial is logged as expected and asked
+of nobody: no request, no notification, no handoff. Only that exact path; any other is a request
+as usual ([expected denials](https://github.com/carlostapiacl/seisin/blob/main/docs/requests.md#a-denial-the-caller-expects)).
+
+**Whose it was, at the moment it was denied.** Other permission layers answer *yes* or *no*, and the good ones say which rule it was and how to widen it. Answering **"no, and it belongs to `backend`"** turns a denial into a handoff — and one a person can grant in a command, rather than a line somebody has to remember to go and read.
 
-The kernel is what denies; the name comes from the policy. That first line is all the boundary itself can say — no path, no reason, nothing to read afterwards — so seisin reads the refusal out of the kernel's own log and answers the question it leaves open. On Linux only the hook can do that; [the ask is upstream](docs/upstream/cli-violations.md) as [issue #582](https://github.com/anthropics/sandbox-runtime/issues/582).
+The kernel is what denies; the name comes from the policy. That first line is all the boundary itself can say — no path, no reason, nothing to read afterwards — so seisin reads the denial out of the kernel's own log and answers the question it leaves open. On Linux only the hook can do that; [the ask is upstream](https://github.com/carlostapiacl/seisin/blob/main/docs/upstream/cli-violations.md) as [issue #582](https://github.com/anthropics/sandbox-runtime/issues/582).
 
-The agent can ask directly too, from inside the box:
+The agent can ask directly too, from inside the sandbox:
 
 ```
 $ seisin run frontend -- seisin whose src/api/orders.ts
+seisin: frontend · writes src/web/** public/** (+6 scratch) · keys netlify-token.txt · runs no agent seisin knows · env 20 kept, 58 dropped · read all
+
   src/api/orders.ts belongs to backend
-  you are frontend. Hand it over rather than working around it.
+  you are frontend. It is handed to backend: hand it over rather than working around it.
 ```
 
+The second line is the same handoff decision the queue shows: with two owners it says a person
+decides and not to pick one, and in a run started with `--handoff` it says when handing the work
+back would be a cycle. The hook's denial and the note after a failed command say it the same way.
+
 ## Sixty seconds
 
 ```bash
@@ -97,7 +128,7 @@ cd your-repo
 seisin init                            # proposes a policy from what the repo already says
 seisin check                           # read it before you trust it
 seisin wire                            # let the agent record what it does
-seisin run frontend -- claude -p "…"   # run an agent inside its own territory
+seisin run <role> -- claude -p "…"     # a role from seisin check, inside its own territory
 ```
 
 On Linux, [three system packages first](#install). Everything below is why it works and where it does not.
@@ -106,7 +137,7 @@ On Linux, [three system packages first](#install). Everything below is why it wo
 
 ## Why this exists
 
-Two things are true about agent permissions today, and both are in the official docs.
+Two things are true about how agents are kept in bounds today, and both are in the official docs.
 
 **1. Permission rules match text, not behaviour.** From the Claude Code documentation:
 
@@ -131,12 +162,11 @@ A rule is a string comparison against a command someone might not spell that way
 
 ## What it is for, and what it is not for
 
-> **It turns an agent's mistake into a contained mistake. It does not turn a hostile
-> agent into a harmless one.**
+> **It turns an agent's mistake into a contained mistake. Against a hostile agent, the
+> guarantee is the one of the sandbox you run it under.**
 >
-> Two outside reviews have gone through it looking for ways past the boundary and
-> found eleven things between them. [What it has been put
-> through](docs/what-it-has-been-put-through.md) lists all of them — what was
+> Two outside reviews, plus three follow-ups, have gone through it looking for ways past the boundary.
+> [What they found and what remains open](https://github.com/carlostapiacl/seisin/blob/main/docs/what-it-has-been-put-through.md) lists all of them — what was
 > fixed, what was measured, and what is still open.
 
 That distinction is the whole threat model, and it is worth reading before you install
@@ -148,28 +178,33 @@ denies, and it does not care how the command was spelled — verified against a
 process, an absolute path, a symlink, a `python -c`, and a shell redirect the agent fell
 back to when its own file API was denied.
 
-**It is not built to hold against an agent that is trying.** Measured, in this repo's own
-fixtures:
+**Against an agent that is trying, the line is drawn by the sandbox.** seisin writes the
+policy and checks that the sandbox can hold it; [the sandbox you choose](https://github.com/carlostapiacl/seisin/blob/main/docs/sandboxes.md)
+enforces it. Some limits are the policy's and hold under any sandbox, measured in this repo's
+own fixtures:
 
 | | |
 |---|---|
-| it can read everything except the declared keys | by design — an agent that cannot read the repo cannot work. `seisin scan` exists because secrets live elsewhere too |
-| it can write anything inside its own territory | including staging an exfiltration, or destroying its own uncommitted work with `rm` |
+| with the default read mode (`read = "all"`) it can read everything except the declared key directories — **including `~/.ssh`, `~/.aws`, `~/.npmrc` and `~/.config`** | by design — an agent that cannot read the repo cannot work. `read = "territory"` closes those homes (as does `[runtime] isolate = "credentials"`); `seisin scan` finds secrets stored elsewhere |
+| it can write anything inside its own territory | including staging an exfiltration |
 | `base64` defeats the redaction | only the literal value is masked, and only on stdout and stderr |
-| an allowed domain is an allowed channel | if the agent's own API is reachable, so is everything that goes through it |
-| the hook is text-based and evadable | on purpose — what escapes it goes **unblocked by nothing**: the kernel still refuses. On macOS it is no longer unexplained either, because [the kernel's own refusals are recorded](#seeing-what-happened); on Linux it is. Either way, attribution is not a control |
+| an allowed domain is an allowed channel | if the agent's own API is reachable, so is everything that goes through it. [`[network] deny_addresses`](#configure) keeps an allowed name from resolving into your LAN |
+| the hook is text-based and evadable | on purpose — what escapes it goes **past the hook, not past the kernel**: the kernel still denies. On macOS it is no longer unexplained either, because [the kernel's own denials are recorded](#seeing-what-happened); on Linux it is. Either way, attribution is not a control |
+
+Others are the sandbox's, and differ between the two built in:
 
-And three things that outweigh all of the above:
+| | `srt` (the default) | `tartaros` |
+|---|---|---|
+| a process the agent leaves running | **macOS:** it outlives the run, whether it double-forks, ignores signals under `nohup` or calls `setsid` (measured 2026-10-16). **Linux:** the PID namespace ends with the run (read from its source) | **macOS:** the run's process group is killed; one that calls `setsid` outlives it (measured 2026-10-16). **Linux:** the run's cgroup is killed whole (read from its source) |
+| deleting inside the territory | write includes delete; the ask is upstream as [issue #545](https://github.com/anthropics/sandbox-runtime/issues/545) | not measured here |
+| `[network] deny_addresses` | enforced | not yet: a role that has it runs under `srt`, and `check` says why |
+| what it is | Anthropic's, described by its authors as a research preview | by the author of seisin, alpha |
 
-1. **It is young and has one author.** The first public release was September 2026, and the
-   implementation is still moving quickly. "Secure" is not a word earned by size or test count.
-2. **The enforcement is someone else's beta.** `sandbox-runtime` describes itself as a
-   research preview with an evolving API. A hole there is a hole here.
-3. **Two platforms tested, by one person, on one machine each.**
+`seisin check` says which sandbox each role gets before anything runs.
 
-For several of your own agents, on your own machine, getting in each other's way — that is
-what this is for, and it is a great deal better than nothing. For putting an agent you do
-not control in front of data you care about, it is not.
+For several of your own agents, on your own machine, getting in each other's way, this is
+what it is for. For an agent you do not control, choose the sandbox for that threat: seisin
+will not make its guarantee stronger than it is.
 
 ## Install
 
@@ -177,7 +212,7 @@ not control in front of data you care about, it is not.
 npm install -g seisin
 ```
 
-That pulls in [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime), which does the enforcing: Seatbelt on macOS, bubblewrap on Linux. No containers, no VMs, no daemon. seisin has **no other dependencies**.
+That pulls in [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime), the default sandbox: Seatbelt on macOS, bubblewrap on Linux. No containers, no VMs, no daemon. seisin has **no other dependencies**. [tartaros](https://github.com/carlostapiacl/tartaros), or a sandbox of your own, can enforce instead ([docs/sandboxes.md](https://github.com/carlostapiacl/seisin/blob/main/docs/sandboxes.md)).
 
 **On Linux you also need three system packages** — the runtime refuses to start without
 them rather than running unconfined, which is the right failure and an unhelpful message:
@@ -203,18 +238,75 @@ default Docker container forbids. `--cap-add SYS_ADMIN --security-opt seccomp=un
 gets namespaces; mounting `/proc` needs `--privileged`. If you cannot grant that, run
 seisin on the host and let the container be what it sandboxes.
 
+## JavaScript API
+
+The package is ESM. Import policy decisions from `seisin`; the same functions
+back the CLI. TypeScript declarations ship with the package. Install it in the project that
+imports it — a global install puts the CLI on your PATH, not the package where `import` looks:
+
+```bash
+npm install seisin
+```
+
+```js
+import { loadConfig, explain, ownersOf } from "seisin";
+
+const config = loadConfig("seisin.toml");
+console.log(ownersOf(config, "src/api/server.js"));
+console.log(explain(config, "frontend", "write", "src/api/server.js"));
+```
+
+The stable surface covers policy loading (`findConfig`, `loadConfig`,
+`parseToml`) and where it lives (`CONFIG_NAME`, `STATE_DIR`, `LOG_NAME`), ownership and
+explanations (`covers`, `ownersOf`, `keyHolders`, `explain`, `explainFileRead`, `readTarget`),
+resolved sandbox settings (`settingsFor`), key references (`parseKey`, `defaultName`,
+`entriesOf`, `MODES`), inspection and scanning (`inspect`, `sharedPaths`, `scan`), activity
+and requests (`readLog`, `logPath`, `observed`, `pendingRequests`, `requestQueue`,
+`requestsPath`, `grantFor`, `generalise`), handoffs (`decideHandoff`, `MAX_DEPTH`,
+`recordHandoff`), walls (`walls`, `wasted`), and hook decisions (`targetsOf`, `decide`).
+Granting is not in it: a grant is a person's, through the CLI or the console.
+Sandbox tuning constants, environment construction and output masking remain
+internal; they may change without an API compatibility promise.
+
 ## Use
 
 ```bash
 seisin init                              # proposes a seisin.toml for this repo
 seisin check                             # print the map, run nothing
+seisin check --system-log                # macOS: is the system log dropping denials right now?
+seisin help limits                       # what seisin cannot do, in any repo
 seisin run frontend -- claude -p "…"     # run an agent as that role
 seisin explain frontend write src/api/x  # ask one question, exit 0 or 1
-seisin review                            # what the log says about the policy
+seisin review --since 7d                 # what the log says about the policy, this week
 seisin wire                              # install the PreToolUse hook in this repo
-seisin ui                                # a console for editing the map
+seisin ui                                # a console for deciding what is waiting
 ```
 
+**Three ways in, and they say the same thing.** The **CLI** is what a person types and what
+every agent runs under. The **console** (`seisin ui`) is for a person deciding something. The
+**MCP server** is for an agent asking about its own situation. A change to what any of them
+says lands in all three — [CONTRIBUTING](https://github.com/carlostapiacl/seisin/blob/main/CONTRIBUTING.md#three-surfaces-and-a-change-lands-in-all-of-them)
+says why, and a test holds one half of it.
+
+`seisin <command> --help` lists a command's flags, examples and exit codes. The exit codes, so
+the commands compose in a script, a pre-commit hook or CI:
+
+| command | 0 | 1 | other |
+|---|---|---|---|
+| `run` | — | — | the command's own status; 86 if the canary proves the boundary does not hold; 127 if it is not on the role's PATH; 128+n when killed by signal n (130 for ctrl-c) |
+| `check` | the policy can be enforced (warnings included) | a role cannot be enforced as written, `--verify` failed, or `--system-log` measured messages dropped | |
+| `explain` | allowed | denied | |
+| `scan` | no certain credential | a certain credential outside the key dirs | |
+| `review` | no role denied repeatedly | a role denied repeatedly | |
+| `walls` | no walls | walls listed | |
+| `requests` | nothing pending | requests pending | |
+| `log verify` | the hash chain holds | the hash chain is broken | |
+| `whose`, `grant`, `decline`, `log`, `init`, `wire`, `ui`, `watch`, `mcp` | done | — | |
+| `hook` | always | — | |
+
+Every command exits **2** on a usage error — an unknown command, flag, role or action — and every
+command that reads the policy exits 2 when there is no `seisin.toml` here or above.
+
 ## Configure
 
 One file at the root of your repo. Anything not listed is denied — there is no permissive default.
@@ -236,19 +328,59 @@ keys     = ["database-url.txt", "sentry-dsn.txt"]
 network  = ["api.stripe.com"]   # this role only — it replaces [network] rather than adding
 ```
 
+An allowed name is only as safe as its DNS: one whose records somebody else controls can be
+pointed at a host on your network. The sandbox already denies loopback, link-local and
+cloud-metadata addresses. Private ranges are left to you, because allowing an intranet name is
+legitimate; to close them, list them:
+
+```toml
+[network]
+allow          = ["github.com", "*.github.com"]
+deny_addresses = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10", "fc00::/7"]
+```
+
+`[runtime] read = "all"` is the default. The opt-in `"territory"` mode keeps homes,
+temporary directories and mounted data roots shut, while retaining the repository and the
+paths each role names:
+
+```toml
+[runtime]
+read = "territory"
+
+[roles.backend]
+writes    = ["src/api/**"]
+reads     = ["../shared-schemas/**"]  # data needed read-only
+toolchain = ["~/.venvs/api"]          # program stack under a data root; bin/ goes first on PATH
+verify    = ["python", "-m", "pytest"] # run by seisin check --verify inside this role
+```
+
+`seisin check --verify --parallel` is an experimental speed option: role checks run at the same
+time. Use it only when those commands do not share mutable build outputs, caches, ports, or other
+resources; concurrent checks can race and produce misleading failures. Plain `--verify` remains
+serial and is the recommended default. `--parallel` requires `--verify`.
+
+`reads` and `toolchain` take literal paths or a subtree ending in `/**`; interior globs,
+`*` and `?` are refused. `verify` is an argv array and may not be empty. Each data root is
+denied whole and what the role keeps is allowed back, so what appears there during the run is
+shut as well. On Linux a kept directory holding a write path is allowed back entry by entry;
+one with more than 1,000 entries is refused, and the error names whether the repo or a `reads`
+path must move or narrow. Details and platform costs are in [Scratch and read territory](https://github.com/carlostapiacl/seisin/blob/main/docs/scratch.md).
+
 `[network] allow` is the fallback for roles that do not name their own. A role that needs one
 extra host should say so on its own line: a domain in the global list is reachable by every
 role, including the ones whose whole job is to have nothing to reach.
 
-> ⚠️ **HTTP(S) works; SSH does not.** The allow list is enforced by proxies the runtime
-> starts, and although one of them is a SOCKS5 proxy that could carry SSH, the chain breaks
-> at its last link: it requires authentication and the `ProxyCommand` the runtime wires up
-> cannot send any. Measured — `curl https://github.com` returns `200`, `ssh -T git@github.com`
-> cannot resolve the hostname, and `git ls-remote git@github.com:…` reaches the proxy and
-> dies at the handshake.
+> ⚠️ **HTTP(S) works on both platforms. SSH does not work on macOS.** The allow list is
+> enforced by proxies the runtime starts, and although one of them is a SOCKS5 proxy that could
+> carry SSH, on macOS the chain breaks at its last link: it requires authentication and the
+> `ProxyCommand` the runtime wires up cannot send any. Measured on macOS — `curl
+> https://github.com` returns `200`, `ssh -T git@github.com` cannot resolve the hostname, and
+> `git ls-remote git@github.com:…` reaches the proxy and dies at the handshake. **On Linux** the
+> runtime routes git's SSH through its HTTP proxy with credentials instead, so it is expected to
+> pass — read from the runtime's source, not measured here.
 >
-> **Use an HTTPS remote for git**, and run SSH deploys outside the confined turn.
-> [Why, exactly, and whose gap it is →](docs/decisions.md#ssh-does-not-work-and-it-is-not-seisin-that-decided-that)
+> **Use an HTTPS remote for git**, and on macOS run SSH deploys outside the confined run.
+> [Why, exactly, and whose gap it is →](https://github.com/carlostapiacl/seisin/blob/main/docs/decisions.md#ssh-does-not-work-and-it-is-not-seisin-that-decided-that)
 
 A role can also give something back. `never_writes` subtracts from its own `writes`, and it
 wins however wide the grant is:
@@ -260,25 +392,49 @@ never_writes = ["services/api/.git/index.lock"]   # works in a worktree; the can
 ```
 
 It is per role on purpose — there is no global version, because a global deny on a lock file
-breaks every role that legitimately commits there. A refusal it causes says so by name and
-leaves **no request** in the queue: approving one would undo a subtraction somebody wrote. An
+breaks every role that legitimately commits there. A denial it causes says so by name and
+leaves **no request** in the queue: granting one would undo a subtraction somebody wrote. An
 entry that no `writes` of the same role covers, or a misspelling like `never_write`, is named
 by `seisin check` instead of being ignored.
 
+A folder only one role may see is `private`. The role reads and writes it; every other role is
+denied both, whatever its `writes` say, in either read mode and under `isolate`:
+
+```toml
+[roles.legal]
+writes  = ["contracts/drafts/**"]
+private = ["contracts/signed/**"]     # part of legal's territory, and no other role reads it
+
+[roles.dev]
+writes = ["**"]                       # still cannot read or write contracts/signed
+```
+
+An entry is one folder inside the repo, `dir` or `dir/**`: no patterns, no absolute path, no
+`..`, not the repo itself. Two roles naming the same folder, or one inside the other, is refused
+at load, because each would be denied its own. `seisin check` shows it under the role and says
+when it sits inside another role's territory, since that role loses it. `seisin explain dev read
+contracts/signed/x` answers denied and names the owner, and a denial there leaves **no request**:
+no grant opens it. On Linux a missing private folder is created empty by `seisin run` (never by `check`), because
+bubblewrap cannot deny a path that does not exist without placing something there; and another
+role sees an empty folder in its place, where a write succeeds into memory that is discarded with
+the run and never reaches the real one. On macOS the write is denied.
+
 A role that starts a server — a dev server, the backend an end-to-end test drives — needs
 `local_binding = true`. Listening is off by default and per role: most roles never start one.
 It is wider than the name: the role can also listen on every interface and **connect to every
 port on localhost**, so anything listening there without authentication is within its reach.
 `seisin check` says this next to the role. That is macOS: on Linux each role already has a
 private loopback, serves without the key, and reaches nothing on the host either way.
+The canary therefore omits its loopback probe for a role with `local_binding = true`: reaching
+the decoy is allowed by that policy, not evidence that confinement failed.
 
 If a role only needs to *reach* a local service, name the ports instead:
 `local_ports = [8001, 8081]`. The role reaches those and nothing else on localhost, on macOS
-and Linux. The sandbox's proxy enforces the list, so the client has to use the proxy. curl,
-Node's `fetch` and Python's `urllib` do. A database driver or a raw socket don't, and get
-refused. For Chromium, pass Playwright's `proxy` option from `HTTP_PROXY`; on macOS it also
-needs `--single-process` to start. A listed port is open to anything that speaks `CONNECT`, not
-just HTTP, so list the service, not the protocol.
+and Linux. Under srt the sandbox's proxy enforces the list, so the client has to use the proxy.
+curl, Node's `fetch` and Python's `urllib` do. A database driver or a raw socket don't, and are
+denied. Under tartaros the kernel profile holds the list itself, so any client reaches a listed
+port directly, and loopback stays off its proxy. For a headless browser, see `browsers` below. A listed port is open to anything that
+speaks `CONNECT`, not just HTTP, so list the service, not the protocol.
 
 `mcp = ["playwright"]` lists the MCP servers a role may load; `mcp = []` means none, and no
 key means the policy doesn't say. seisin declares this and `explain` answers it
@@ -286,35 +442,96 @@ key means the policy doesn't say. seisin declares this and `explain` answers it
 launcher has to apply it. With Claude Code: `--mcp-config` holding only those servers, plus
 `--strict-mcp-config`.
 
-Refused connections are logged too: `connect tcp:<port>` (the kernel gives the port, not the
+A role that drives a headless Chromium — Playwright, `@playwright/mcp` — needs
+`browsers = ["chromium"]` on macOS. Without it the browser exits as it starts: its first act
+is to register a Mach service (`org.chromium.Chromium.MachPortRendezvousServer.<pid>`) that its
+own child processes look up, and the sandbox denies both. The preset allows exactly those two,
+by that prefix, and nothing else; every other role keeps the profile it had. The network is
+still `[network] allow`, through the sandbox's proxy, which takes credentials Playwright has to
+be handed apart from the URL:
+
+```js
+const u = new URL(process.env.HTTP_PROXY);   // http://<user>:<token>@localhost:<port>
+const browser = await chromium.launch({ proxy: {
+  server: `${u.protocol}//${u.host}`,
+  username: decodeURIComponent(u.username),
+  password: decodeURIComponent(u.password),
+} });
+```
+
+Passing `HTTP_PROXY` as `server` alone does not work: Playwright gives Chromium the address
+without the credentials and the proxy answers `407`. The token is the run's own, so the traffic
+stays tied to the run. `@playwright/mcp` runs under `[sandbox] provider = "tartaros"`, which
+gives the role a temp directory of its own for the unix socket the server always opens; under
+srt it does not yet. [docs/browsers.md](https://github.com/carlostapiacl/seisin/blob/main/docs/browsers.md) has the measurements, the MCP config,
+and what Chrome and Chrome for Testing still lack.
+
+Some files are not code but still make something happen outside the sandbox, and no territory
+reaches them: git hooks and config, a project's `.claude/`, `.mcp.json`, `.envrc`. Two softer
+families sit beside those, and a policy can hand them to one role:
+
+```toml
+[roles.frontend]
+writes        = ["apps/web/**"]
+control_files = ["ide"]           # keeps apps/web/.vscode/launch.json current
+
+[protect]
+instructions = true               # CLAUDE.md, AGENTS.md… only for roles handed "instructions"
+```
+
+- **`ide`** — `.vscode/`, `.cursor/`, `.windsurf/`. Your editor applies them as soon as they
+  change, which is how an injected agent turns on tool auto-approval. **Protected by default.**
+- **`instructions`** — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, Cursor and Windsurf rules, Copilot
+  instructions. Nothing runs them; the next agent session reads them as its instructions, so
+  one role writing them reaches another role's context. **Off unless `[protect]` turns it on**:
+  keeping them current is ordinary work for most teams.
+
+A role handed a family writes it only inside its own `writes`, and `seisin check` names it on
+every run. A denial says which setting would change it, and leaves no request: it is a decision
+about the policy, not a grant. Inside `node_modules` neither family is touched, so npm still
+unpacks a package's own `.vscode` or `AGENTS.md`. On Linux only the files that already exist are
+protected: bubblewrap would have to create a missing one to deny it.
+
+Denied connections are logged too: `connect tcp:<port>` (the kernel gives the port, not the
 host) or the socket path, once per target per run. `seisin walls` says whether the port is
 missing from `local_ports`, listed but dialled directly, or a socket. No request is filed: a
 port isn't anyone's territory. macOS only.
 
-`seisin init` will propose this from whatever your repo already says: `.claude/agents/`, then `CODEOWNERS`, then a blank start. It **proposes** — a generated policy you did not read is not a policy.
+So are the denials that are neither a file nor a connection: a Mach service, a `sysctl`, as
+`mach-register org.chromium.Chromium.MachPortRendezvousServer.7354`, once per operation and
+name per run, and never as a request. Most are the sandbox doing its job and the program
+carrying on; one of them is how a browser dies at start, and `seisin run` names the preset
+that answers it. macOS only.
+
+`seisin init` will propose this from whatever your repo already says: `.claude/agents/`, then `CODEOWNERS` (one role per owner, with all of that owner's paths), then one role per top-level folder that holds code. It declares `[keys] dir` when `.secrets/`, `secrets/` or `.keys/` is there, and adds `.seisin/` to an existing `.gitignore`. It **proposes** — a generated policy you did not read is not a policy — and a second `init` changes nothing without `--force`, which keeps the old one as `seisin.toml.bak`.
 
 ## What will look like a bug on the first day
 
-Four shapes a correct policy still produces that read as breakage: a granted file whose
-neighbours are not granted, a lock file in somebody else's repository, a tool that reports a
-denied write as a *readonly database*, and an agent that diagnoses file permissions when the
-answer is ownership.
+Shapes a correct policy still produces that read as breakage: a granted file whose
+neighbours are not granted, a lock file in somebody else's repository, a worktree that is two
+paths for one repository, a tool that reports a denied write as a *readonly database*, and Go
+or Dart failing TLS on macOS with the domain allowed. The first four came out of one
+production window where none of them was the boundary misbehaving.
 
-All four came out of one production window where none of them was the boundary misbehaving.
+One more comes with protected files: **a role's `git checkout`, `pull` or `rebase` cannot update
+a file the role may not write.** Git exits 0, the branch moves, and the old `.vscode/settings.json`
+stays behind as a modification — which a later `commit -a` would turn into a revert. Switch
+branches outside the sandbox, or hand that role the family if keeping those files is its job.
 
-**[What each one looks like, and what to do →](docs/first-day.md)**
+**[What each one looks like, and what to do →](https://github.com/carlostapiacl/seisin/blob/main/docs/first-day.md)**
 
 ## Which agents it has been run with
 
-Claude Code, opencode, codex, gemini and a LangGraph script, each against a real policy with
-the boundary actually applied — not a smoke test.
+Four: Claude Code, opencode, codex and a LangGraph script, each against a real policy with
+the boundary actually applied — not a smoke test. gemini 0.57.0 has only been started under it,
+which is not the same claim.
 
 **One thing is worth knowing before you start: an agent that sandboxes itself has to be told
 to stop.** `codex` confines every command it runs, and no OS applies a second profile to a
 process that already has one. seisin says so before it starts one, because the error you get
 otherwise names neither seisin, nor the agent, nor the fix.
 
-**[Every agent, its version, what it needed, and how each reacted to being stopped →](docs/agents.md)**
+**[Every agent, its version, what it needed, and how each reacted to being stopped →](https://github.com/carlostapiacl/seisin/blob/main/docs/agents.md)**
 
 ## What the log says about the policy
 
@@ -324,27 +541,48 @@ actually happened and tells you where the config was wrong about it.
 ```
 $ seisin review
 
-  60 decisions, 2026-08-23 to 2026-09-11
+  60 entries, 2026-08-23 to 2026-09-11
+
+  Denied repeatedly
+  a role denied on the same place over and over is a policy that is wrong,
+  not an agent that is misbehaving
 
-  Stopped, repeatedly
        9×  frontend write src/api/checkout — belongs to backend
        4×  backend write src/web — belongs to frontend
 
+  seisin grant, or move the territory. Either way it is a decision, not noise.
+
   Granted, never used
+  nothing was written here in the window above. This is the only evidence
+  anyone will ever have for making a policy smaller
+
     frontend  public/**
-    backend   migrations/**
+    backend  migrations/**
 
-  Owned by nobody
-       5×  legacy
+  A short window proves nothing. Check the dates before you delete a line.
+
+  Unowned
+  touched by an agent, claimed by no role. Only an ownable path (kind `territory`)
+  is a hole in the map; the rest is a kind of thing with its own answer, and none
+  of them is an owner
+
+       4×  territory  legacy
+
+  territory: an ownable path no role claims: a real decision — give it an owner, or tell the agent not to write there
 ```
 
+`--since 2026-10-01` or `--since 7d` reads only that stretch of the log: on a log months long,
+"Denied repeatedly" is otherwise led by paths fixed long ago. A denial that is correct and needs
+nothing — Claude Code updating its plugins from inside the sandbox — is listed apart as "Denied as
+expected" and does not make `review` exit 1.
+
 Three questions, and the middle one is the reason this exists. **Every
 permission file only ever grows**, in every system, and always for the same
 reason: nobody can prove a line is dead, so the safe move is to leave it. Here
 the log can prove it — `public/**` was granted and nothing was written there in
 three weeks. That is the only direction that makes a policy *smaller*.
 
-The first is the one that changes how a denial reads. Forty blocks on one
+The first is the one that changes how a denial reads. Forty denials on one
 directory is not an agent misbehaving; it is a policy that is wrong, and until
 you add them up it looks like forty tidy amber lines.
 
@@ -361,10 +599,17 @@ the first unjustified denial is when the tool gets uninstalled. So don't write i
 write:
 
 ```bash
-seisin run frontend --observe -- claude -p "…"   # records, denies nothing
+seisin wire                                      # the hook is what records
+seisin run frontend --observe -- claude -p "…"   # the repo opens, the network does not
 seisin init --from-observations                  # writes seisin.toml.observed
 ```
 
+What `--observe` changes: the whole repo is writable for that run, so a write outside the
+territory is recorded instead of refused. What it does not: the key directories, the policy and
+`.seisin/` stay denied, and so does every domain not on the allowlist. What gets recorded is what
+the hook sees — the tool calls of an agent (Claude Code, Codex…) in a repo where `seisin wire` ran.
+A plain shell command (`--observe -- npm test`) goes through no hook and records nothing.
+
 It lands as `.observed`, not as your config. A policy generated behind your back is not a
 policy: diff it, then move it.
 
@@ -372,35 +617,49 @@ policy: diff it, then move it.
 
 A permission tool that can only say no is a tool people uninstall — the loop of *denied,
 stop, edit a config, run again* is three context switches for one line of policy, and the
-cheapest way to stop it is to widen the policy and never look again. That is how a permission
-file becomes seven hundred entries nobody reads.
+cheapest way to stop it is to widen the policy and never look again. That is how an allowlist
+becomes seven hundred entries nobody reads.
 
 So a denial leaves something to act on, and many denials in one directory are **one** request:
 
 ```
+$ seisin requests
+
   1 pending request(s)
 
     #1  frontend wants write on src/api/** (owned by backend) · asked 3×
         first asked over src/api/orders.ts
+        id frontend:write:src/api
 
-    seisin grant 1 --reason "…"   ·   seisin decline 1 --reason "…"
+    seisin grant <n|id> [--reason "…"]   ·   seisin decline <n|id> [--reason "…"]
+    #n is a position and shifts as requests are settled; the id does not.
 ```
 
 The grant writes its own provenance next to the line it adds:
 
+```
+$ seisin grant 1 --reason "frontend owns checkout now"
+
+  granted  frontend → src/api/**
+  written into /path/to/repo/seisin.toml with its provenance. It applies on the next run.
+```
+
 ```toml
-writes = ["src/api/**"]   # granted 2026-09-12 · asked 3× · "frontend owns checkout now"
+[roles.frontend]
+writes = ["src/web/**", "public/**",
+  "src/api/**"   # granted 2026-09-12 · asked 3× · «frontend owns checkout now»
+]
 ```
 
-**Approving is never a tool call.** An agent can read the queue and draft the change; only a
+**Granting is never a tool call.** An agent can read the queue and draft the change; only a
 person applies it, in a terminal or in the console. That asymmetry is deliberate and it is
 the reason the MCP server exists at all.
 
 **A person hears about it.** With `[notify]`, the parent process sends one message per new
-request — the role, the path, whose it is, and `seisin grant <n>` — to ntfy, Slack or any
+request — the role, the path, whose it is, and `seisin grant '<id>'` — to ntfy, Slack or any
 webhook. The URL lives in a key directory no role declares (`url_file`) or in the parent's
 `SEISIN_NOTIFY_URL`; written plainly into `seisin.toml`, which every role can read, it refuses to
-load, because whoever reads it can send you a fake "approve".
+load, because whoever reads it can send you a fake "grant this".
 
 ```toml
 [notify]
@@ -409,12 +668,12 @@ format   = "text"                      # or "slack", "json"
 ```
 
 **And so does the agent.** `seisin wire` installs the hook for four events. Before a tool call
-it explains a refusal it can see coming; after a command fails it reads the kernel's own refusal
-from the log and tells the agent whose the path was and how many times it has been refused —
+it explains a denial it can see coming; after a command fails it reads the kernel's own denial
+from the log and tells the agent whose the path was and how many times it has been denied —
 the half PreToolUse never sees; and when a session starts, resumes or is compacted it hands the
 agent its territory and its walls, before the first one.
 
-**[How a denial becomes a request, why it deduplicates, and what a grant records →](docs/permission-requests.md)**
+**[How a denial becomes a request, why it deduplicates, and what a grant records →](https://github.com/carlostapiacl/seisin/blob/main/docs/requests.md)**
 
 ## Ask your own assistant
 
@@ -447,33 +706,75 @@ seisin ui                        # the same thing, for a person deciding
 ```
 
 ```
-04:13:26  allowed  frontend write src/web/app.ts
-04:13:26  denied   frontend write src/api/server.ts  → backend
-04:13:27  denied   frontend read .secrets/database.txt  → backend
+$ seisin log
+
+  04:13:26  allowed  frontend write src/web/app.ts
+  04:13:26  denied   frontend write src/api/orders.ts  → backend
+  04:13:27  denied   frontend read .secrets/database-url.txt  → backend
+  04:13:31  denied   frontend write src/api/orders.ts  → backend  [kernel]
+
+  4 entries · 3 denied
 ```
 
+`[kernel]` marks a line the kernel reported; the others came from the hook.
+
 One append-only JSONL under `.seisin/`, and that is the whole storage design — no daemon, no
-database, and `watch` is a tail.
+database, and `watch` is a tail. A run started with a W3C `TRACEPARENT` (a launcher's trace)
+stamps its `trace_id` and `span_id` on every line, so the log joins that trace in any
+OpenTelemetry tool.
+
+Each line carries the hash of the one before it, and the first time a chained line is written
+the start of the chain is recorded beside the log (`log.jsonl.genesis`). `seisin log verify`
+checks both, so a line edited, removed or reordered breaks it, and so does stripping the chain
+from every line to make the log read as one written before chaining:
+
+```
+$ seisin log verify
+
+  broken  4 chained line(s), 2 break(s):
+    line 1: expected prev 106c24967e0bdde077d73073b648f218, found 43918a17f2089effc44394a72e4289e9
+    line 2: expected prev 43918a17f2089effc44394a72e4289e9, found 106c24967e0bdde077d73073b648f218
+  a line was edited, removed or reordered just before each of these
+```
+
+Tamper-evident, not tamper-proof: whoever can write `.seisin/` could rewrite both files
+together, which is why no role can write it.
 
 **The agent cannot reach that file.** `.seisin/` is in no role's territory, because a record
 the recorded process can edit is not a record. The hook sends each line to `seisin run` over
 a unix socket granted by path and the parent does the writing, so the only verb available
-from inside the box is *append one line*. A hostile agent can still add noise to its own
+from inside the sandbox is *append one line*. A hostile agent can still add noise to its own
 history; what it cannot do is change what is already there.
 
 **Two writers, and they see different things.** The **hook** reports the attempt before it
 happens — which is how an *allowed* action gets recorded at all — and it is text-based and
 evadable, on purpose. The **kernel** reports what it actually denied, and is not fooled by
-anything. What escapes the hook goes unexplained, never unblocked.
+anything. What escapes the hook goes unexplained, never unenforced.
+
+![the console: requests waiting on a person, a grant that needs a reason and a second click for another role's path, the line it wrote, the denials grouped by path with the kind of each unowned one, the walls each role keeps hitting, the roles, and a control-files change shown before it is saved](https://raw.githubusercontent.com/carlostapiacl/seisin/main/docs/img/console.gif)
 
+It opens on what needs a decision, not on the policy. Four numbers sit on top — waiting on
+you, denied, the **top cause**, and calls **spent retrying** walls — each a link to the page
+that explains it, and the last two are recomputed against the policy, which a log alone cannot
+do: something granted since stops counting.
 
+**A decision needs a reason.** Grant without one asks for it; Decline without one fills in
+a default and asks again, so what is recorded is on screen first. The request says what a
+grant covers before the click — *asked for `src/api/routes.ts` → granting
+covers all of `src/api/**`*, and whose it is today. Sharing another role's territory takes a
+second click that names it. After it, the console shows the line it wrote to `seisin.toml`
+and where.
 
-![the console: what is waiting on a decision, the day's denials grouped by cause, the walls a role keeps hitting, and the policy behind them](docs/img/console.gif)
+**Denied and Walls say the same thing about one path.** A path no role owns says what kind
+of thing it is — *ownable*, or git's, temporary, build output, a credential — and the move
+that fits each, which for all but the first is not an owner.
 
-It opens on what needs a decision, not on the policy. Five numbers ride on every screen and
-each is a link to the page that explains it — including two a log cannot answer, because
-they are recomputed against the policy: how much of the day is **one cause**, and how many
-of those causes are on paths **nobody owns**.
+**Live, the roles are read-only:** territories and keys change in `seisin.toml`. The two
+writes are decisions and the control files: beside each role, a toggle for each family it can
+be handed (editor settings, instruction files), and one for `[protect] instructions`. A
+toggle saves nothing. It shows the sandbox settings each role gains or loses and the exact
+line it would write, and a second button, with a reason, saves it. If the server stops, the
+page says *offline* and turns every write off until it answers again.
 
 ## How it holds
 
@@ -481,7 +782,7 @@ of those causes are on paths **nobody owns**.
 |---|---|---|
 | your agent's `allow`/`deny` rules | match the command string before it runs | yes — `/bin/rm`, a heredoc, a child process |
 | **seisin** | decides what to ask for, and names the owner | it doesn't enforce, it explains |
-| **sandbox-runtime → Seatbelt / bubblewrap** | the OS denies the syscall | no |
+| **the sandbox → Seatbelt / bubblewrap / Landlock** | the OS denies the syscall | no |
 
 ```
    Write tool · Bash `rm -rf` · /bin/rm · python -c "open(…)" · a grandchild
@@ -505,6 +806,10 @@ of those causes are on paths **nobody owns**.
                                     explanation — never the boundary
 ```
 
+`sandbox-runtime` is the default enforcer, not the only one. `[sandbox] provider` picks another —
+`tartaros`, or any sandbox declared as a command — per role, and only where it enforces the whole
+policy: see [docs/sandboxes.md](https://github.com/carlostapiacl/seisin/blob/main/docs/sandboxes.md).
+
 That split is deliberate, and it is why seisin is small. Because the kernel is the boundary, seisin never has to be airtight — it only has to be *legible*. A leaky explainer costs you a confusing log line. A leaky enforcer costs you the repo.
 
 Verified by the test suite, which runs real commands in a real sandbox:
@@ -530,7 +835,7 @@ than hidden.
 | reading another role's key file | the kernel — the key directory is denied, each declared key re-allowed |
 | a key riding in the environment | the launcher — the child's environment is **built, not inherited** |
 | spilling a key the role does hold | the launcher — masked on stdout and stderr, even split across buffers |
-| sending it somewhere | the kernel — egress is allow-only, by hostname. HTTP(S) works; [SSH does not](docs/decisions.md#ssh-does-not-work-and-it-is-not-seisin-that-decided-that) |
+| sending it somewhere | the kernel — egress is allow-only, by hostname. HTTP(S) works; [SSH does not on macOS](https://github.com/carlostapiacl/seisin/blob/main/docs/decisions.md#ssh-does-not-work-and-it-is-not-seisin-that-decided-that) |
 | **a key stored outside the declared directories** | **nothing.** `seisin scan` finds them so you know |
 
 ```toml
@@ -548,19 +853,31 @@ A **provider** is a command with a `{ref}` placeholder, so adding 1Password, Bit
 `sops` is TOML and not code. `file://` ships built in. The parent resolves, never the
 confined process. Nothing degrades: a provider that fails stops the run.
 
-**[Key directories, references, providers, delivery modes and nine recipes →](docs/keys.md)**
+A key reaches the role as a variable (`key_mode = "env"`), as a file in the run's private
+directory (`"run-file"`), or, on Linux, not at all: with `"inject"` the agent holds a
+placeholder and the sandbox swaps in the real value only on the way to the hosts you list for
+it. That costs terminating TLS to those hosts, which `seisin check` names, and a host that
+stores what it is sent can still hand the value back — use a least-scope token.
+
+**[Key directories, references, providers, delivery modes and nine recipes →](https://github.com/carlostapiacl/seisin/blob/main/docs/keys.md)**
 
-**Measured, over four agent cells and three days: every refused read was a read of something
+For agents you would not trust with your machine, `[runtime] read = "territory"` denies the places
+data lives — homes, temp directories, volumes — and leaves each role its repo, its territory and
+a toolchain it declares, which `seisin check --verify` proves it can run. Every run, in every
+mode, starts with a canary that tries the policy from inside and refuses to start the agent if
+it does not hold. **[What it closes, what it costs →](https://github.com/carlostapiacl/seisin/blob/main/docs/scratch.md#reading-only-what-the-role-needs)**
+
+**Measured, over four teams of agents and three days: every denied read was a read of something
 the policy had declared a key.** 148 of them, no exceptions, from five roles — all running
 searches that swept a repository root. That is how a key gets read without anyone deciding
-it should.
+it should. ([The measurement, ~370 confined runs over one production window →](https://github.com/carlostapiacl/seisin/blob/main/docs/keys.md))
 
 ## When the boundary is right and the agent cannot hear it
 
 seisin answers *whose is this* at the moment of the denial — once, mid-turn — and then the
 sentence is gone. Nothing carries it forward, so the agent tries again.
 
-Measured on a real team: of **345 denials, 88 (25%) were a repeat of something that same role
+Measured in the author's own multi-agent setup: of **345 denials, 88 (25%) were a repeat of something that same role
 had already been denied.** One role spent 37 calls on two walls, hitting one of them nineteen
 times. Every denial was correct. Not one was a false positive. It still cost thirty-seven
 calls, because *correct* and *heard* are different properties and only the first was being
@@ -569,29 +886,43 @@ measured.
 So a denial now carries its own history:
 
 ```
-deploy/x.yml belongs to infra. It is not dev's to change — hand it over rather than
-working around it. You have been denied this 3 times now; it is not going to work on
-the fourth try. Already queued for a person to answer…
+deploy/x.yml belongs to infra. It is not dev's to change. It is handed to infra: hand it
+over rather than working around it. Do not put the change somewhere else instead (another
+path, a copy, /tmp). You have been denied this 3 times now; it is not going to work on the
+fourth try. Already queued as a handoff to infra…
 ```
 
 And the standing list is a command:
 
 ```
 $ seisin walls dev
-WALLS — you have already been refused these, and the policy still refuses them.
-Do not retry; the reason is where the other way in is.
-  19× write ../equipo/.git/index.lock
-      ../equipo/.git/index.lock belongs to plataforma-dev
-  6× read ~/.npmrc
-      no role declares ~/.npmrc — add it under a [roles.<name>] keys list
-  (23 of your calls went into retrying these.)
+
+  dev keeps hitting:
+
+     19×  write ../shared/.git/index.lock  belongs to platform
+      6×  read ~/.npmrc  no role declares ~/.npmrc — add it under a [roles.<name>] keys list
+
+  23 of its calls went into retrying these.
+```
+
+That is the list said to the person at the terminal. The agent gets it in its own voice, at the
+start of every session the hook is wired for:
+
+```
+Already denied more than once, and still denied — do not try again, hand it over:
+- write ../shared/.git/index.lock (19×) — belongs to platform
+- read ~/.npmrc (6×) — no role declares ~/.npmrc — add it under a [roles.<name>] keys list
 ```
 
+and, on request, as data from the MCP server's `seisin_walls`. In a run handed along a chain, a
+wall where the chain stops is listed without its owner: a person decides it, and the agent is
+to pass on the one sentence its denial gives ([where a request goes](https://github.com/carlostapiacl/seisin/blob/main/docs/requests.md#where-a-request-goes)).
+
 **A wall is recomputed against the policy, not read out of the log.** If the role would be
 allowed today, it is not a wall — whatever happened yesterday. The obvious implementation is a
 time window, on the argument that an old wall may have been granted since; the window is a
 proxy for the question, and seisin has the policy right there, so it asks the question. A grant
-makes its wall disappear on the next turn instead of when a window expires. Same move as
+makes its wall disappear on the next run instead of when a window expires. Same move as
 `owners` and the request queue: recompute rather than believe.
 
 Silent on the first denial, by design. A counter that reads `1×` every time is noise on the
@@ -602,7 +933,7 @@ obvious way to check is to compare repeats before and after — but the repeats
 lock file, and the release before this one deleted that wall outright with
 `GIT_OPTIONAL_LOCKS=0`. Repeats did fall, by a lot, and **the fall is the wall going away,
 not the sentence landing**: both shipped within days of each other and the bigger cause is the
-other one. Isolating this needs a forward test — walls per role, rounds with the hook wired
+other one. Isolating this needs a forward test — walls per role, runs with the hook wired
 and no git locks in the way — not the history. Measured in the field and written up rather
 than smoothed over, because the alternative is a claim the numbers do not carry.
 
@@ -610,15 +941,20 @@ than smoothed over, because the alternative is a claim the numbers do not carry.
 
 Territory alone is correct and unusable: an agent writes session state under its own config
 directory and its tools write to the temp dir, so *your folders and nothing else* stops the
-agent from starting. Every role gets `~/.claude`, `~/.cache`, `$TMPDIR` and `/tmp` — and that
-is a real hole, because two roles share a temp directory and territory does not hold in it.
-It is one line to turn off.
+agent from starting. Every role gets `~/.cache`, `$TMPDIR` and `/tmp`, and a run of Claude Code
+or Codex gets that agent's own directory (`~/.claude`, `~/.codex`) — never the other's, nor the
+other's sign-in. Shared scratch is a real hole, because two roles share a temp directory and
+territory does not hold in it. A repo that lives inside scratch — a toy repo under `/tmp` — is
+writable by every role whatever its `writes` say; `seisin check` says so (*every role can write
+the whole repo*), and the same for a `writes` entry whose real path is in scratch.
+It is one line to turn off. The runtime's own shared temp directory, `/tmp/claude`, is never
+writable: each run gets a temp directory of its own instead.
 
-**[What that costs, and how to close it →](docs/scratch.md)**
+**[What that costs, and how to close it →](https://github.com/carlostapiacl/seisin/blob/main/docs/scratch.md)**
 
 ## What it is not
 
-- **Not a sandbox.** [`sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) is the sandbox, and it is Anthropic's. seisin writes its settings and explains its refusals.
+- **Not a sandbox.** The sandbox is the one you choose: [`sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) by default, or [tartaros](https://github.com/carlostapiacl/tartaros). seisin writes its settings, checks that it can hold them and explains its denials.
 - **Not an orchestrator.** It does not run your agents, schedule them, or merge their work. It runs one command as one role.
 - **Not a secret manager.** It scopes *reads* of files you already have. Where those files come from is your problem.
 - **Not what a single agent needs first.** If only one agent ever touches the repo,
@@ -653,8 +989,8 @@ files, the same keys, no answer to *whose is it*. That question is not about
 isolation strength at all — it is about ownership, and it is the one thing an
 operating system cannot know for you.
 
-Which is also why this is thin. Enforcement is
-[`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime)
+Which is also why this is thin. Enforcement is the sandbox — by default
+[`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) —
 asking the kernel; seisin is the layer that decides what to ask for and says
 whose file it was when the answer is no. The two compose — put seisin inside a
 container if you want both, and the roles still hold.
@@ -671,28 +1007,28 @@ This space already has good work, and seisin is not the first thing here:
 
 - [`anthropics/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) — the enforcement. seisin is a thin thing on top of a serious one.
 - [`kornysietsma/claude-code-permissions-hook`](https://github.com/kornysietsma/claude-code-permissions-hook) — granular `PreToolUse` rules, one global policy.
-- [`XuebinMa/agent-guard`](https://github.com/XuebinMa/agent-guard) — a permission-enforcement SDK, also one global policy.
-- [`NVIDIA/OpenShell`](https://github.com/NVIDIA/openshell) — a runtime that sandboxes an agent with Landlock and seccomp, under a declarative policy. Serious, and the closest thing here by weight. It was evaluated as a possible backend; [the measured compatibility decision](docs/openshell.md) explains why it is currently an execution target candidate rather than a drop-in replacement.
+- [`XuebinMa/agent-guard`](https://github.com/XuebinMa/agent-guard) — an SDK that enforces what an agent may do, also one global policy.
+- [`NVIDIA/OpenShell`](https://github.com/NVIDIA/openshell) — a runtime that sandboxes an agent with Landlock and seccomp, under a declarative policy. Serious, and the closest thing here by weight. It was evaluated as a possible backend; [the measured compatibility decision](https://github.com/carlostapiacl/seisin/blob/main/docs/openshell.md) explains why it is currently an execution target candidate rather than a drop-in replacement.
 - [`dredozubov/hazmat`](https://github.com/dredozubov/hazmat) — runs the agent as a different system user, with `pf` rules and snapshots.
 - [`nolabs-ai/nono`](https://github.com/nolabs-ai/nono) — a kernel sandbox for agents on the host (Seatbelt, Landlock), with per-tool child sandboxes, a credential proxy with endpoint filtering, approval webhooks and a tamper-evident audit log. The most complete sandbox here, and on a Mac the one that enforces through the same kernel seisin does. `nono why` explains *which rule* denied something and how to allow it; it has no notion of *whose* it was.
-- *Directory ownership* is recommended in half the multi-agent write-ups. As far as I could find, nobody enforces it, and nobody names the owner in the refusal. That gap is the reason for this repo.
+- *Directory ownership* is recommended in half the multi-agent write-ups. As far as I could find, nobody enforces it, and nobody names the owner in the denial. That gap is the reason for this repo.
 
 ### One sentence to tell these apart, because the names all sound the same
 
 **OpenShell, hazmat and nono isolate the agent from your machine. seisin separates roles from
-each other inside one repository, and when it blocks something it names the owner.**
+each other inside one repository, and when the kernel denies something it names the owner.**
 
 Those are different problems and the first one is not the one this solves. If what you want
-is "this agent cannot touch anything outside its box", they do that and OpenShell does it
+is "this agent cannot touch anything outside its sandbox", they do that and OpenShell does it
 with a large organisation behind it. If what you want is "four agents work in the same
-repository and none of them edits another's files — and when one is stopped it is told whose
+repository and none of them edits another's files — and when one is denied it is told whose
 those files are", nothing above answers that, which is why this exists.
 
 They compose rather than compete: the agent seisin confines could be running inside one of
 them.
 
 *One detail worth knowing before you compare, and it is about placement rather than quality.
-OpenShell was [evaluated here on 2026-09-27](docs/openshell.md), through its Docker driver on
+OpenShell was [evaluated here on 2026-09-27](https://github.com/carlostapiacl/seisin/blob/main/docs/openshell.md), through its Docker driver on
 an Intel Mac. That confines an agent inside Docker Desktop's Linux VM; seisin confines a
 process on the host through Seatbelt. OpenShell also offers other drivers, including a local
 microVM path on supported Apple Silicon Macs. These are kernel-enforced boundaries, but not
@@ -700,16 +1036,24 @@ the same kernel or workspace, and which one you want depends on what you are pro
 
 ## Status
 
-`0.4.2`, 500 tests, of which **26 need `@anthropic-ai/sandbox-runtime` installed**
-and run real commands through the real kernel — and CI fails if the sandbox half *skips*, because
-a green run that quietly tested nothing looks exactly like a real one. That is not hypothetical:
-those eighteen skipped on Linux for a day, behind a runtime check that looked for the global
+**1089 tests on macOS, 1082 passing and 7 platform skips** (0.6.0, 2026-10-23, local); in CI the
+same day, on `ubuntu-latest` **1088, 1059 passing and 29 platform skips**, and on macOS 1089,
+1079 passing and 10 skips, Node 18/20/22/24, with the 26 core boundary tests skipping none. On 2026-10-12, 91 of the suite's tests
+needed `@anthropic-ai/sandbox-runtime` installed — counted by running it with the runtime
+hidden — and run real commands through the real kernel; 26 of them are the core boundary file,
+`test/sandbox.test.js`, which the CI gate fails if it *skips*, because a green run that quietly
+tested nothing looks exactly like a real one. That is not hypothetical:
+when there were eighteen of them, they skipped on Linux for a day, behind a runtime check that looked for the global
 install and missed the bundled one, and hid a defect that broke `seisin run` on that platform
-entirely. **500 tests on macOS 15, 499 passing and 1 skipped** (it is Linux-only) — 2026-09-29;
-`ubuntu-latest` under bubblewrap runs the same suite, Node 18/20/22/24 in CI at every push — and 225/225 the same way on Debian 12.15
-with bubblewrap 0.8.0, the last time the suite was run in Docker.
-[Which claim was measured where](docs/what-it-has-been-put-through.md#where-each-claim-was-actually-run),
-and [what running agents behind it cost the people using it](docs/field-notes.md).
+entirely.
+
+A release is published only from CI, after the full suite passes on macOS and `ubuntu-latest`,
+Node 18/20/22/24 (`publish.yml`), with npm provenance.
+Historically: 811 tests on macOS 15, 809 passing and 2 skipped, on 2026-09-30.
+[Which claim was measured where](https://github.com/carlostapiacl/seisin/blob/main/docs/what-it-has-been-put-through.md#where-each-claim-was-actually-run),
+and [what running agents behind it cost the people using it](https://github.com/carlostapiacl/seisin/blob/main/docs/field-notes.md).
+The [2026-10-02 review](https://github.com/carlostapiacl/seisin/blob/main/docs/reviews/2026-10-02.md) and its [follow-up](https://github.com/carlostapiacl/seisin/blob/main/docs/reviews/2026-10-02-followup.md)
+added 32 regressions and record their portable checks apart from the kernel measurements above.
 The config format may still move before `1.0` — if it does, `seisin check` will
 tell you what changed.
 
@@ -719,19 +1063,19 @@ already done:
 | | |
 |---|---|
 | **Windows** | the runtime has a backend. seisin has never been pointed at it, and no CI runner covers it |
-| **Deleting inside your own territory** | not covered, and not coverable here — the ask is upstream as [issue #545](https://github.com/anthropics/sandbox-runtime/issues/545), open and unanswered since 2026-09-13, [with the measurement behind it](docs/upstream/denyUnlink.md) and [a demo](docs/demo/) |
-| **`init` heuristics** | it reads `.claude/agents/` then `CODEOWNERS`. Every other convention is a guess nobody has made yet |
-| **SSH inside a turn** | the `ProxyCommand` the runtime sets can't authenticate to its own proxy, so `git` over SSH fails at the handshake. Fix upstream: [PR #516](https://github.com/anthropics/sandbox-runtime/pull/516). Use an HTTPS remote |
-| **A browser inside a role (macOS)** | Chromium only starts with `--single-process`, which is unstable with several browsers. Fix upstream: [PR #598](https://github.com/anthropics/sandbox-runtime/pull/598). [Measurement](docs/upstream/mach-register.md) |
+| **Deleting inside your own territory** | the sandbox's to enforce, and `srt` cannot: write includes delete. The ask is upstream as [issue #545](https://github.com/anthropics/sandbox-runtime/issues/545), open and unanswered since 2026-09-13, [with the measurement behind it](https://github.com/carlostapiacl/seisin/blob/main/docs/upstream/denyUnlink.md) and [a demo](https://github.com/carlostapiacl/seisin/tree/main/docs/demo/) |
+| **`init` heuristics** | it reads `.claude/agents/`, then `CODEOWNERS`, then the top-level folders that hold code. Every other convention is a guess nobody has made yet |
+| **SSH inside a run (macOS)** | on macOS the `ProxyCommand` the runtime sets can't authenticate to its own proxy, so `git` over SSH fails at the handshake (on Linux the runtime routes it through an authenticated proxy — read from its source, not measured here). Fix upstream: [PR #516](https://github.com/anthropics/sandbox-runtime/pull/516). Use an HTTPS remote |
+| **A browser inside a role (macOS)** | headless Chromium runs with `browsers = ["chromium"]`. Not covered yet: Chrome and Chrome for Testing, and `@playwright/mcp` under srt (it runs under tartaros). [docs/browsers.md](https://github.com/carlostapiacl/seisin/blob/main/docs/browsers.md#what-is-not-covered-yet) |
 
-Every word above has one meaning, listed in [the glossary](docs/glossary.md) — the boundary
-**denies**, a person **declines**, seisin **refuses** a config it cannot enforce. A tool whose
+Every word above has one meaning, listed in [the glossary](https://github.com/carlostapiacl/seisin/blob/main/docs/glossary.md) — the boundary
+**denies**, a person **grants** or **declines**, seisin **refuses** a config it cannot enforce. A tool whose
 product is a sentence cannot afford two words for one thing.
 
-Issues and pull requests welcome — [CONTRIBUTING.md](CONTRIBUTING.md) says what is actually
+Issues and pull requests welcome — [CONTRIBUTING.md](https://github.com/carlostapiacl/seisin/blob/main/CONTRIBUTING.md) says what is actually
 different about contributing here, which is mostly that a claim has to be downstream of
 something measured. If you are reporting something that got past the boundary, do it
-[privately](SECURITY.md); `seisin log --verdict denied` and the `seisin.toml` are the two
+[privately](https://github.com/carlostapiacl/seisin/blob/main/SECURITY.md); `seisin log --verdict denied` and the `seisin.toml` are the two
 things that make it reproducible.
 
 ## The name