seisin 0.4.0 → 0.5.0

package/README.md

@@ -11,13 +11,13 @@
 
 > **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.
 
 *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)*
+*And what running four teams 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
@@ -38,7 +38,7 @@ says why, and a test holds one half of it.
 
 **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)
+**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) · [Requests](docs/permission-requests.md) · [Contributing](CONTRIBUTING.md)
 
 </details>
 
@@ -46,7 +46,7 @@ says why, and a test holds one half of it.
 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"])
@@ -60,7 +60,7 @@ 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.
+denial 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)
 
@@ -77,11 +77,11 @@ $ seisin run frontend -- sh -c 'echo // fix >> src/api/orders.ts'
     seisin grant <n> [--reason "…"]   ·   seisin decline <n> [--reason "…"]
 ```
 
-**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.
+**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](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
@@ -106,7 +106,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:
 
@@ -157,12 +157,12 @@ fixtures:
 | it can write anything inside its own territory | including staging an exfiltration, or destroying its own uncommitted work with `rm` |
 | `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 |
+| 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 |
 
 And three things that outweigh all of the above:
 
-1. **It is days old and has one author.** Around three thousand lines that nobody has
-   audited except its writer and one field report. "Secure" is not a word earned that fast.
+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.**
@@ -215,6 +215,25 @@ seisin wire                              # install the PreToolUse hook in this r
 seisin ui                                # a console for editing the map
 ```
 
+`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; 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 | |
+| `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 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.
@@ -247,7 +266,7 @@ role, including the ones whose whole job is to have nothing to reach.
 > 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.
+> **Use an HTTPS remote for git**, and run SSH deploys outside the confined run.
 > [Why, exactly, and whose gap it is →](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
@@ -260,8 +279,8 @@ 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.
 
@@ -275,8 +294,8 @@ private loopback, serves without the key, and reaches nothing on the host either
 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
+Node's `fetch` and Python's `urllib` do. A database driver or a raw socket don't, and are
+denied. 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.
 
@@ -286,7 +305,33 @@ 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
+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.
@@ -302,6 +347,11 @@ answer is ownership.
 
 All four came out of one production window where none of them was the boundary misbehaving.
 
+A fifth 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)**
 
 ## Which agents it has been run with
@@ -324,18 +374,34 @@ 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
 ```
 
 Three questions, and the middle one is the reason this exists. **Every
@@ -344,7 +410,7 @@ 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 +427,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,8 +445,8 @@ 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:
 
@@ -392,7 +465,7 @@ The grant writes its own provenance next to the line it adds:
 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
+**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.
 
@@ -400,7 +473,7 @@ the reason the MCP server exists at all.
 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".
+load, because whoever reads it can send you a fake "grant this".
 
 ```toml
 [notify]
@@ -409,8 +482,8 @@ 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.
 
@@ -458,23 +531,27 @@ database, and `watch` is a tail.
 **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: 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)
 
-It opens on what needs a decision, not on the policy. Five numbers ride on every screen and
+It opens on what needs a decision, not on the policy. Four 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**.
 
+Beside each role it also holds the two families a policy can hand out, editor settings and
+instruction files, and the `[protect] instructions` switch. A change there is shown first as
+what it does to each role's sandbox settings, and written to `seisin.toml` only when you confirm.
+
 ## How it holds
 
 | layer | what it does | can it be talked around? |
@@ -550,7 +627,7 @@ confined process. Nothing degrades: a provider that fails stops the run.
 
 **[Key directories, references, providers, delivery modes and nine recipes →](docs/keys.md)**
 
-**Measured, over four agent cells and three days: every refused read was a read of something
+**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.
@@ -560,7 +637,7 @@ it should.
 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
@@ -578,20 +655,31 @@ 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`.
+
 **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 +690,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.
 
@@ -618,7 +706,7 @@ It is one line to turn off.
 
 ## 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.** [`sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) is the sandbox, and it is Anthropic's. seisin writes its settings 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,
@@ -671,46 +759,42 @@ 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.
+- [`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](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.
-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
+OpenShell was [evaluated here on 2026-09-27](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
+the same kernel or workspace, and which one you want depends on what you are protecting.*
 
 ## Status
 
-`0.4.0`, 470 tests, of which **26 need `@anthropic-ai/sandbox-runtime` installed**
+`0.5.0`, 780 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
+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. **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
+entirely. **780 tests on macOS 15, 778 passing and 2 skipped** (they are Linux-only) — 2026-09-30;
+`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).
@@ -725,11 +809,11 @@ 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 |
+| **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). 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
+**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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "seisin",
-  "version": "0.4.0",
-  "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it blocks it tells you whose file it was.",
+  "version": "0.5.0",
+  "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it denies something it tells you whose file it was.",
   "keywords": [
     "ai-agents",
     "claude-code",
@@ -39,7 +39,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "0.0.77"
+    "@anthropic-ai/sandbox-runtime": "0.0.78"
   },
   "scripts": {
     "test": "node --test test/*.test.js",