seisin 0.1.1 → 0.3.0

package/README.md

@@ -1,11 +1,14 @@
 # seisin
 
-[![test](https://github.com/carlostapiaolguin3-stack/seisin/actions/workflows/test.yml/badge.svg)](https://github.com/carlostapiaolguin3-stack/seisin/actions/workflows/test.yml)
+[![test](https://github.com/carlostapiacl/seisin/actions/workflows/test.yml/badge.svg)](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.
+
 > **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.
@@ -14,6 +17,51 @@ A **permission layer**, not a sandbox — it sits on top of one. The isolation c
 
 *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)*
 
+*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)*
+
+**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.
+
+<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)
+
+**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)
+
+**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) · [Decisions](docs/decisions.md) · [Permission requests](docs/permission-requests.md) · [Contributing](CONTRIBUTING.md)
+
+</details>
+
+```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"]
+    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
+
+    style D fill:#fde,stroke:#c66
+    style W fill:#dfd,stroke:#6a6
+    style H fill:#eef,stroke:#66c
+```
+
+**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)
 
 ```
@@ -26,12 +74,12 @@ $ seisin run frontend -- sh -c 'echo // fix >> src/api/orders.ts'
     #1  frontend wants write on src/api/** (owned by backend)
         first asked over src/api/orders.ts
 
-    seisin grant <n> [--reason "…"]   ·   seisin deny <n> [--reason "…"]
+    seisin grant <n> [--reason "…"]   ·   seisin decline <n> [--reason "…"]
 ```
 
-**Whose it was, at the moment it was refused.** Every other permission layer in this space answers *yes* or *no*. 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.
+**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 kernel is what refuses; 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 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 agent can ask directly too, from inside the box:
 
@@ -54,8 +102,6 @@ seisin run frontend -- claude -p "…"   # run an agent inside its own territory
 
 On Linux, [three system packages first](#install). Everything below is why it works and where it does not.
 
-**Contents** · [Why this exists](#why-this-exists) · [What it is *not* for](#what-it-is-for-and-what-it-is-not-for) · [Install](#install) · [Configure](#configure) · [Day one](#what-will-look-like-a-bug-on-the-first-day) · [Agents it runs](#which-agents-it-has-been-run-with) · [Requests](#when-it-says-no-it-leaves-a-request-behind) · [MCP](#ask-your-own-assistant) · [Why not a container](#why-not-a-container) · [How it holds](#how-it-holds) · [Secrets](#how-it-protects-secrets) · [Decisions](docs/decisions.md) · [What it survived](docs/what-it-has-been-put-through.md) · [Status](#status)
-
 ---
 
 ## Why this exists
@@ -98,9 +144,9 @@ rather than after.
 
 **It holds against an agent that is wrong.** One that edits the file it was not asked
 about, reads the key meant for another role, or calls an API nobody declared. The kernel
-refuses, and it does not care how the command was spelled — verified against a grandchild
+denies, and it does not care how the command was spelled — verified against a grandchild
 process, an absolute path, a symlink, a `python -c`, and a shell redirect the agent fell
-back to when its own file API was refused.
+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:
@@ -194,162 +240,81 @@ network  = ["api.stripe.com"]   # this role only — it replaces [network] rathe
 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.
 
-`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.
-
-## What will look like a bug on the first day
-
-Four shapes that a correct policy still produces, and that a reader reads as breakage. All
-four come out of one production window — four agent cells, ~370 confined turns over three
-days, 1,409 kernel refusals — where none of them was the boundary misbehaving. They are here
-because every one of them cost someone an afternoon before it cost this paragraph.
-
-**1 · Granting a file does not grant its neighbours.** The kernel grants exactly the path you
-wrote. Anything a tool creates *beside* it — a database journal, a lock file, the temporary
-file of an atomic write — is a sibling, and a sibling is outside the grant. The failure then
-arrives in the tool's own words rather than as a permission error, which is why it survives a
-policy review: the policy looks right because it *is* right about the file you named.
-
-`seisin check` says so before you hit it:
-
-```
-N role(s) grant individual files rather than folders: reviewer (3 of 11)
-```
+> ⚠️ **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.
+>
+> **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)
 
-Grant the folder where the tool needs neighbours. `seisin check <role>` names the paths.
+A role can also give something back. `never_writes` subtracts from its own `writes`, and it
+wins however wide the grant is:
 
-**The Claude Code case is worth stating outright**, because it is the agent most people will
-point this at first: `Write` and `Edit` do not write the file you named. They write
-`<name>.tmp.<pid>.<random>` next to it and rename over the target. So a grant on a literal
-file path is both correct and useless — `seisin explain` answers *allowed* about the
-destination, the kernel answers `Operation not permitted` about the temporary, and neither is
-lying. Grant the directory.
+```toml
+[roles.backend]
+writes       = ["services/api/**"]
+never_writes = ["services/api/.git/index.lock"]   # works in a worktree; the canonical index is not its business
+```
+
+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
+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 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.
+
+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.
+
+`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
+(`seisin explain qa mcp tradingview`), but the servers are started by the agent's CLI, so the
+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
+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.
 
-**2 · `.git/index.lock`, in a repo the role does not own.** In that window this single
-filename was **1,071 of the 1,409 refusals** — three quarters of everything the kernel said no
-to. A role runs `git status`, git tries to refresh the index of a checkout that belongs to
-another role, and the lock write is refused.
+`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.
 
-It is noise, not a wall, and the distinction is measurable: inside the box
-`git status --short --branch` and `git log` still exit 0. Git cannot refresh its index cache
-and carries on without it. If a role genuinely needs to commit, give it **its own worktree**
-rather than a share of the main index — two agents staging into one index corrupt each other
-regardless of who is allowed to write it.
+## What will look like a bug on the first day
 
-**3 · Worktrees are two paths for one repo.** A policy names the canonical checkout; the
-process is running in a linked worktree somewhere else entirely, and to the kernel that is a
-different place. seisin resolves the pair rather than making you write both — `seisin whose`
-and `seisin explain` answer the same thing from either side, and say which checkout they are
-talking about. Worth knowing it is handled, because the symptom when a tool does *not* handle
-it is a role denied inside its own territory.
+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.
 
-**4 · SQLite reports a refused write as `attempt to write a readonly database`** — see
-[below](#which-agents-it-has-been-run-with); it is the one that sends you to debug the
-database instead of the policy, and the reason `seisin wire` exists.
+All four came out of one production window where none of them was the boundary misbehaving.
 
-Where these stand: the sibling case is a `check` warning instead of a surprise, the worktree
-case is resolved in the tool, the SQLite case is named by the hook, and the git one is
-friction that gets logged rather than silenced — a boundary that hides what it refused is the
-thing this project exists to argue against.
+**[What each one looks like, and what to do →](docs/first-day.md)**
 
 ## Which agents it has been run with
 
-seisin wraps a process, so in principle it works with any agent that runs as one — CLI or not. In
-practice "in principle" is not a claim worth making about a permission tool, so here is what has
-actually been exercised:
-
-| agent | version | result |
-|---|---|---|
-| **Claude Code** (`claude -p`) | 2.1.x | Territory and keys enforced; network egress refused an undeclared domain by name |
-| **opencode** (`opencode run`) | **1.18.30** | Same, **on a free model with no API key at all** |
-| **LangGraph** (`python graph.py`) | **1.2.11** | Same, **enforced against the interpreter's own `open()`** — in-process tools, no child command to match |
-| **codex** (`codex exec`) | **0.150.1** | Same, with its own sandbox off — see below. Refused twice: its patch tool, then the shell redirect it fell back to |
-
-The codex run is the one that needed a flag. **An agent that sandboxes itself has to stop.** `codex` confines each command it runs with its
-own `sandbox-exec` profile, and macOS refuses to apply a second Seatbelt profile to a process
-that already has one — `sandbox_apply: Operation not permitted`, with the most permissive
-profile that can be written, on both layers. So an agent like that runs under seisin with its
-own sandbox turned off — `codex exec --dangerously-bypass-approvals-and-sandbox`, whose own
-help says it is "intended solely for running in environments that are externally sandboxed".
-It starts fine either way (`codex 0.150.1`, `gemini 0.57.0`, both verified), which is why this
-is worth saying out loud: the failure arrives later, on the first command the agent tries to
-confine.
-
-Asked to write into another role's territory, codex failed through its patch tool, went looking
-for a file ACL with `ls -le@` and `stat`, found nothing, and fell back to a shell redirect that
-failed too:
-
-```
-/bin/zsh -lc "printf 'pisado\n' > qa/informe.md"
-  exited 1: zsh:1: operation not permitted
-```
-
-Same shape as opencode, including the wrong diagnosis — it reasoned about file permissions,
-not about ownership. That is the case for the hook: the boundary holds either way, but only the
-hook can say *whose* it was.
-
-All four on macOS 15 (Seatbelt). Linux is no longer a one-off measurement on one machine:
-[CI](.github/workflows/test.yml) runs the whole suite on Ubuntu and macOS, Node 18/20/22,
-on every push — and fails if the sandbox half *skips*.
-
-The opencode run is the interesting one, because **opencode has no per-path sandbox flag** —
-its only permission control is `--auto`, "auto-approve permissions that are not explicitly
-denied". Asked to write into another role's territory it failed twice: once through its own
-`FileSystem.writeFile`, and again through the shell redirect it fell back to.
-
-```
-Error: Unknown: FileSystem.writeFile (.../qa/informe.md)
-$ echo "revisado" > .../qa/informe.md
-zsh:1: operation not permitted
-```
-
-That is the point of putting the boundary in the kernel instead of in the agent: **an agent
-that cannot confine itself is confined anyway**, and adding a new one costs no adapter.
-
-It also found a real bug. The scratch list named `~/.claude` and `~/.codex` and stopped there,
-so the first agent that was neither did not fail a task — it failed to start, on its own log
-file. A boundary that only fits the agents its author happened to use is a coincidence, not a
-boundary. The XDG directories are in the list now.
-
-The LangGraph run answers a different question: **an agent framework is not a CLI.** Its tools
-are Python calls inside the same process, so there is no child command for a rule to match and no
-argv to inspect — the write is the interpreter's own `open()`. A six-node graph asked to write into
-another role's territory was refused there, refused again through the shell redirect it fell back
-to, refused the other role's key, and refused an undeclared domain. Run as the other role, the same
-graph gave the mirror image — every territory and key answer flipped, the undeclared domain refused
-for both — and its SQLite checkpointer persisted normally inside whichever territory was its own.
+Claude Code, opencode, codex, gemini and a LangGraph script, each against a real policy with
+the boundary actually applied — not a smoke test.
 
-One caveat belongs beside that row rather than after it: **a role is scoped to a process, and a
-graph is one process.** Every node of one graph shares one territory and one set of keys. Per-node
-territory means per-node subprocess, which is the thing an in-process framework exists to avoid.
-seisin fits a multi-agent framework at the boundary of the whole graph, not between its agents.
+**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.
 
-And one failure mode worth meeting here rather than at 2am: SQLite reports a refused write as
-`attempt to write a readonly database`, not as a permission error. That reads like a misconfigured
-database, and you will debug the database. The hook names the owner instead — it is the case
-`seisin wire` is for.
-
-**Re-verified without an agent in the loop**, which is better evidence: an agent in the middle
-makes a permission test non-deterministic — in that first run the agent reported the opposite
-of what it had actually done. Wrapping a plain shell and a plain interpreter instead:
-
-| as `dev`, with `qa/**` owned by `qa` | result |
-|---|---|
-| `sh -c 'echo x > proyecto/FILE.txt'` (own territory) | rc=0, created |
-| `sh -c 'echo x > qa/report.md'` (shell redirect) | `Operation not permitted`, rc=1 |
-| `python3 -c "open('qa/report.md','w')"` (the program's own syscall) | `PermissionError: [Errno 1]` |
-| `rm -f proyecto/FILE.txt` (**destructive, inside** own territory) | **rc=0, file gone** |
-
-The last row is not a bug, it is the shape of the tool: seisin answers *where*, not *what*.
-A team running this in front of an agent fleet measured how often it matters: across ~330
-rounds, sixty-six times a role reached for a command that would have destroyed its own
-uncommitted work, and the kernel boundary permitted every one. The ask that would close it
-is written up in [docs/upstream/denyUnlink.md](docs/upstream/denyUnlink.md), filed against
-the sandbox runtime rather than worked around here.
-
-If you would rather see it than read it, [thirty seconds in a temp
-directory](docs/demo/) — an agent confined to its own project deletes the git history of the
-repo it is working in, and the `.git/` left behind looks intact. Nothing installed, seisin not
-used, because the gap is the runtime's and every tool on top of it inherits the same one.
+**[Every agent, its version, what it needed, and how each reacted to being stopped →](docs/agents.md)**
 
 ## What the log says about the policy
 
@@ -405,79 +370,51 @@ policy: diff it, then move it.
 
 ## When it says no, it leaves a request behind
 
-A permission tool that can only say no is a tool people uninstall. The loop —
-denied, stop, go edit a config, run again — is three context switches for one
-line of policy, and the cheapest way to make it stop is to widen the policy
-generously and never look again. That is how a permission file becomes seven
-hundred entries nobody can read.
+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.
 
-So a denial leaves something you can act on:
+So a denial leaves something to act on, and many denials in one directory are **one** request:
 
 ```
-  frontend  write  src/api/orders.ts
-  denied — src/api/orders.ts belongs to backend
-
   1 pending request(s)
 
     #1  frontend wants write on src/api/** (owned by backend) · asked 3×
         first asked over src/api/orders.ts
 
-    seisin grant 1 --reason "…"   ·   seisin deny 1 --reason "…"
+    seisin grant 1 --reason "…"   ·   seisin decline 1 --reason "…"
 ```
 
-Many refusals in one directory are **one** request, not many — an agent denied
-on `a.ts` and then on `b.ts` is not asking two questions. And the grant records
-where it came from, next to the line it adds:
+The grant writes its own provenance next to the line it adds:
 
 ```toml
-[roles.frontend]
-writes = [
-  "src/web/**",
-  "src/api/**"   # granted 2026-09-12 · asked 3× · "frontend owns checkout now"
-]
-```
-
-```
-   frontend denied on src/api/orders.ts
-              │
-              ▼
-        request #1 ◄──── denied again on b.ts ──── same request, asked 2×
-              │
-              │   nothing inside the box moves it from here
-              ▼
-      ┌───────┴────────┐
-      ▼                ▼
-  seisin grant 1   seisin deny 1
-      │                ▼
-      │           policy unchanged,
-      ▼           the reason recorded
-  one line added to seisin.toml,
-  carrying where it came from
-```
-
-Without that, a policy is a list of permissions with no history, and the only
-safe thing to do with a line nobody remembers is leave it there.
-
-**Approving is deliberately not a tool call.** An agent — or an MCP server on
-your behalf — can read the queue and draft the change. Turning it into policy
-takes a person in a channel the agent does not have. The public API reflects
-that: `pendingRequests` is exported, the functions that approve are not.
-[The reasoning is written down](docs/permission-requests.md).
-
-![the console: a pending request, a reason, and the territory changing when it is approved](docs/img/console.gif)
-
-Two places, both human: `seisin grant <n>` in a terminal, or the console, where
-the queue is a panel with a reason field and two buttons. Approving there edits
-your `seisin.toml` in place and the territory on screen changes with it.
-
-The console is allowed to hold that half and the MCP server is not, and the
-reason is measured rather than asserted: a confined role curling the console's
-own port gets the same nothing it gets from a domain outside its allowlist. The
-MCP server, by contrast, speaks on the agent's own stdio.
-
-The notice rides on what you are already looking at: `seisin run` prints the
-queue when the run ends, in the same terminal that just showed you the denial.
-There is no daemon and nothing to leave running.
+writes = ["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
+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
+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".
+
+```toml
+[notify]
+url_file = ".secrets/notify-url.txt"   # e.g. https://ntfy.sh/<your-topic>
+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 —
+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)**
 
 ## Ask your own assistant
 
@@ -487,6 +424,14 @@ There is no daemon and nothing to leave running.
 
 > *who owns src/api, and what is frontend waiting on?*
 
+Seven tools. Four answer about the policy — `state`, `explain`, `requests`, `draft_grant` —
+and three about what has happened: `activity` is the raw log, and **`causes` and `walls` are
+the two an agent actually wants.** `activity` hands over events and leaves the assistant to
+re-derive the shape without the policy; `causes` returns the day grouped by path and by name
+with how many are on paths nobody owns, and `walls` returns what a role keeps being denied
+*and would still be denied today*. Both are recomputed against the policy, so something
+granted since stops counting — which is the part a log cannot know.
+
 Read-only **by construction** — the server opens nothing for writing, and a test
 asserts that no tool in it mutates anything. It can draft the exact change a
 request would make; applying it is a command a person runs. Zero dependencies:
@@ -498,6 +443,7 @@ descriptors.
 ```bash
 seisin log --verdict denied      # what the agents tried and could not do
 seisin watch                     # follow it live
+seisin ui                        # the same thing, for a person deciding
 ```
 
 ```
@@ -507,56 +453,27 @@ seisin watch                     # follow it live
 ```
 
 One append-only JSONL under `.seisin/`, and that is the whole storage design — no daemon, no
-database. `watch` is a tail. The file is the shared state, so anything that can read it can
-watch it.
-
-**The agent cannot reach that file.** `.seisin/` is not in any 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*: no seek, no truncate, no unlink. What a
-hostile agent can still do is send lines, so it can add noise to its own history. What it can
-no longer do is change what is already there.
+database, and `watch` is a tail.
 
-**Two writers, and they see different things.**
+**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
+history; what it cannot do is change what is already there.
 
-The **hook** reports the attempt before it happens, which is how an allowed action
-gets recorded at all. It has to be installed: `seisin wire` writes the
-`PreToolUse` entry into this repo's `.claude/settings.json` — the project's,
-never your machine's. It is also text-based and evadable, on purpose.
-
-The **kernel** reports what it actually refused. On macOS every Seatbelt denial
-lands in the system log with its operation, its absolute path and the runtime's
-own attribution tag, and `seisin run` reads that stream for the duration of the
-run. Nothing to install, nothing to evade — and it catches exactly what the hook
-missed:
-
-```
-$ 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)
-    #1  frontend wants write on src/api/** (owned by backend)
-        first asked over src/api/orders.ts
-```
+**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.
 
-That is with no hook installed. Before this, the same run left `Operation not
-permitted` on the terminal and an empty log — which is how four real defects in
-production each cost a night to find: every one of them looked like a file that
-had quietly stopped growing.
 
-Skip `wire` and the boundary holds exactly as well, denials are still recorded
-and still queue a request; what you lose is the record of what was *allowed*,
-which is what `init --from-observations` is built out of. `seisin check` says so
-until you run it.
 
-**On Linux only the hook writes.** bubblewrap does not log refusals and the
-runtime's substitute is not readable from outside it, so `seisin run` says so
-once and records nothing from the kernel. [The ask is
-upstream](docs/upstream/cli-violations.md) as [issue #582][582], filed 2026-09-20
-against 0.0.77, open and unanswered.
+![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)
 
-[582]: https://github.com/anthropics/sandbox-runtime/issues/582
+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**.
 
 ## How it holds
 
@@ -564,7 +481,7 @@ against 0.0.77, open and unanswered.
 |---|---|---|
 | 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 refuses the syscall | no |
+| **sandbox-runtime → Seatbelt / bubblewrap** | the OS denies the syscall | no |
 
 ```
    Write tool · Bash `rm -rf` · /bin/rm · python -c "open(…)" · a grandchild
@@ -605,105 +522,99 @@ Verified by the test suite, which runs real commands in a real sandbox:
 
 ## How it protects secrets
 
-Four ways out of a process, and seisin closes three of them. The fourth is named below,
-because a security tool that lists only its wins is not one.
+Four ways a secret leaves a process, and seisin closes three. The fourth is named rather
+than hidden.
 
-| way out | closed by | how |
-|---|---|---|
-| reading another role's key file | the kernel | the key directory is denied, each declared key re-allowed. Survives a grandchild process and an absolute path |
-| a key riding in the environment | the launcher | the child's environment is **built, not inherited**. Measured before this existed: 93 variables crossed into every turn, a planted token among them |
-| spilling a key the role does hold | the launcher | the value is masked on stdout and stderr, including when it lands split across two buffers |
-| sending it somewhere | the kernel | egress is allow-only. `curl` to a domain you did not list gets nothing |
-| **a key stored outside the declared directories** | **nothing** | `seisin scan` finds them so you know what is not covered |
+| way out | closed by |
+|---|---|
+| 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) |
+| **a key stored outside the declared directories** | **nothing.** `seisin scan` finds them so you know |
 
 ```toml
 [keys]
-dir = [".secrets", "config/credentials"]   # one directory or several
+dir = [".secrets"]
 
 [roles.frontend]
-keys = ["netlify-token.txt"]   # everything else in those directories is denied
-env  = ["BUILD_ID"]            # everything else in the environment is dropped
+key_mode = "env"
+keys = ["netlify-token.txt",                       # a file the role may read
+        "TOKEN=file://.secrets/all.env#NETLIFY",   # one value, and no read at all
+        "OP=op://vault/item/field"]                # anything that prints a secret
 ```
 
-**If your agent runs hooks of its own, they need a line here too.** Whatever a hook reads to learn which role it is gets dropped with everything else, and the symptom is two layers disagreeing about one file — your hook refusing a write that seisin just allowed, and the lower one is the one that is right — until the variable is named in `env`.
-
-**What this bought, measured rather than argued.** Over the same production window — four
-agent cells, ~370 confined turns, three days — **every refused read was a read of something
-the policy had declared a key.** 148 of them, no exceptions, from five different roles, and
-not one was doing anything unusual: they were running searches that swept a repository root.
-That is how a key gets read without anyone deciding it should, and it is the whole case for
-declaring the key directory rather than trusting the instruction not to look.
+A **provider** is a command with a `{ref}` placeholder, so adding 1Password, Bitwarden or
+`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.
 
-Refused *writes* were a different story, and both halves are worth reading: those were
-ordinary collisions between roles, the boundary keeping two agents out of each other's work.
-It is the reads where the policy was the only thing there.
+**[Key directories, references, providers, delivery modes and nine recipes →](docs/keys.md)**
 
-**Two things this deliberately does not claim.** Redaction masks a literal value on the way
-through the launcher — a key written straight to a file never passes through it, and neither
-does one the agent base64'd first. It narrows a careless print; it is not a containment
-boundary. And to mask a value seisin must read it, so a role's own keys pass through this
-process in memory. `[runtime] redact = false` turns that off.
+**Measured, over four agent cells and three days: every refused 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.
 
-## Scratch space, and what it costs
+## When the boundary is right and the agent cannot hear it
 
-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 a policy of *your folders and nothing else*
-stops the agent before it starts. Every role therefore also gets:
+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.
 
-```toml
-[runtime]
-# the default, in full — `~/.local/{share,state}` is where an agent that is neither
-# claude nor codex keeps its log, and one that cannot write it does not fail a task,
-# it fails to start
-writes = ["~/.claude", "~/.codex", "~/.local/share", "~/.local/state",
-          "~/.cache", "$TMPDIR", "/tmp"]
-```
+Measured on a real team: 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
+measured.
 
-**Writing this key replaces that list; it does not add to it.** So a `[runtime] writes` copied
-from somewhere to grant one extra path silently drops the six it did not mention. Start from the
-list above and append.
+So a denial now carries its own history:
 
-Two things follow, and both are the kind of thing you want to hear from the tool rather than
-discover:
+```
+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…
+```
 
-- **Scratch is shared.** Every role can write it, so two agents can reach each other's temp
-  files. If your repo lives inside the temp dir, territory does not hold at all — `seisin check`
-  says so out loud when it detects that.
-- **The home directory itself is never granted.** Only those named subdirectories. A grant that
-  reached `~` would hand over the shell profile, the ssh config, and every dotfile with a token
-  in it. There is a test that fails if that ever changes.
-- **Reading your home is a different question, and by default it is open.** None of the above
-  stops a role from *reading* `~/.ssh`, `~/.aws/credentials`, `~/.npmrc` or
-  `~/.config/gh/hosts.yml`. That is the deliberate trade in the table above — an agent that
-  cannot read the machine cannot work — and `seisin check` now says it on every run rather than
-  leaving you to find out.
+And the standing list is a command:
 
-Set `writes = []` to opt out and find out why it is there.
+```
+$ 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.)
+```
 
-### Closing your credentials, without signing the agent out
+**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
+`owners` and the request queue: recompute rather than believe.
 
-```toml
-[runtime]
-isolate = "credentials"   # ~/.ssh, ~/.aws, ~/.npmrc, ~/.config and the rest go dark
-```
+Silent on the first denial, by design. A counter that reads `1×` every time is noise on the
+turn where the sentence is already doing its job.
 
-Measured, on the same machine, same policy, same command:
+**Whether it makes an agent stop is not demonstrated, and will not be for a while.** The
+obvious way to check is to compare repeats before and after — but the repeats were 86% one
+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
+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.
 
-| | `~/.ssh` `~/.aws` `~/.npmrc` `~/.config/gh` | `~/.claude` | `claude -p` |
-|---|---|---|---|
-| default | open | open | **OK** |
-| `isolate = "credentials"` | **closed** | open | **OK** |
-| `isolate = "home"` | **closed** | closed | `Not logged in` |
+## Scratch space, and what it costs
 
-`"home"` also gives each role its own `HOME`, `TMPDIR` and XDG directories, so one role cannot
-read the session another's CLI just wrote. It is the stronger claim and it has a real price:
-**every CLI in the box sees an empty home and asks you to log in again.** That is not this
-sandbox being strict — on macOS the agent's credential is in the login keychain, the keychain is
-found through `$HOME`, and `HOME=/empty claude -p` reproduces the same message with no sandbox
-involved at all.
+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.
 
-Which of the two you want is your threat model, so neither is a default. `"credentials"` is the
-one you can turn on today on a machine you are already working on.
+**[What that costs, and how to close it →](docs/scratch.md)**
 
 ## What it is not
 
@@ -761,19 +672,48 @@ 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.
+- [`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.
 
+### 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.**
+
+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
+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
+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.
+Read from [OpenShell's support matrix][osm] on 2026-09-21, not measured here: macOS is a
+supported platform, and on it "these kernel modules run inside the Docker Desktop Linux VM,
+not on the host kernel". So on a Mac, OpenShell confines an agent inside a Linux VM, and
+seisin confines a process on the host through Seatbelt. Both are kernel enforcement; they are
+not the same kernel, and which one you want depends on whether the thing you are protecting is
+on the host. seisin [says where each of its own claims was
+measured](docs/what-it-has-been-put-through.md#where-each-claim-was-actually-run).*
+
+[osm]: https://docs.nvidia.com/openshell/reference/support-matrix
+
 ## Status
 
-`0.1.1`, 228 tests, of which **18 need `@anthropic-ai/sandbox-runtime` installed**
+`0.3.0`, 452 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
 install and missed the bundled one, and hid a defect that broke `seisin run` on that platform
-entirely. **228/228 on macOS 15 and on `ubuntu-latest` under bubblewrap**, nothing skipped on
+entirely. **326/326 on macOS 15 and on `ubuntu-latest` under bubblewrap**, nothing skipped on
 either, Node 18/20/22 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).
+[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).
 The config format may still move before `1.0` — if it does, `seisin check` will
 tell you what changed.
 
@@ -785,9 +725,17 @@ 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) |
+
+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
+product is a sentence cannot afford two words for one thing.
 
-Issues and pull requests welcome. If you are reporting something that got past
-the boundary, `seisin log --verdict denied` and the `seisin.toml` are the two
+Issues and pull requests welcome — [CONTRIBUTING.md](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
 things that make it reproducible.
 
 ## The name