seisin 0.1.0 → 0.1.1

package/README.md

@@ -31,7 +31,7 @@ $ seisin run frontend -- sh -c 'echo // fix >> src/api/orders.ts'
 
 **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.
 
-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).
+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 agent can ask directly too, from inside the box:
 
@@ -54,7 +54,7 @@ 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) · [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)
+**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)
 
 ---
 
@@ -196,6 +196,61 @@ 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)
+```
+
+Grant the folder where the tool needs neighbours. `seisin check <role>` names the paths.
+
+**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.
+
+**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.
+
+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.
+
+**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.
+
+**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.
+
+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.
+
 ## 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
@@ -498,7 +553,10 @@ 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).
+upstream](docs/upstream/cli-violations.md) as [issue #582][582], filed 2026-09-20
+against 0.0.77, open and unanswered.
+
+[582]: https://github.com/anthropics/sandbox-runtime/issues/582
 
 ## How it holds
 
@@ -569,6 +627,17 @@ env  = ["BUILD_ID"]            # everything else in the environment is dropped
 
 **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.
+
+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.
+
 **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
@@ -696,13 +765,14 @@ This space already has good work, and seisin is not the first thing here:
 
 ## Status
 
-`0.1.0`, 225 tests, of which **18 need `@anthropic-ai/sandbox-runtime` installed**
+`0.1.1`, 228 tests, of which **18 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. **225/225 on macOS 15 and on Debian 12.15 with bubblewrap 0.8.0**, nothing skipped on
-either, plus Node 18/20/22 in CI.
+entirely. **228/228 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).
 The config format may still move before `1.0` — if it does, `seisin check` will
 tell you what changed.
@@ -713,7 +783,7 @@ 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](docs/upstream/denyUnlink.md), with the measurement behind it and [a demo](docs/demo/) |
+| **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 |
 
 Issues and pull requests welcome. If you are reporting something that got past

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seisin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.",
   "keywords": [
     "ai-agents",

package/src/env.js

@@ -28,6 +28,37 @@ export const BASE = [
   "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS",
 ];
 
+/**
+ * Set for the child whether or not the parent has them.
+ *
+ * `BASE` is an allowlist: it decides what *crosses*, so a variable the parent
+ * never set cannot reach the child through it. These are the ones the sandbox
+ * needs **set**, not forwarded.
+ *
+ * `GIT_OPTIONAL_LOCKS=0` is the whole list, and it is here because of what the
+ * denial log looks like without it. Measured on a real portfolio: of the last
+ * 60 refusals, **58 were `.git/index.lock`** — 97% — and most carried no owner
+ * at all, so not one of them was a territory question. `git status` and
+ * `git diff` refresh the index as a courtesy, refreshing it takes the lock, and
+ * a role reading a repo it does not own trips the boundary while doing nothing
+ * but looking. The human approving those is arbitrating a mutex.
+ *
+ * Git's own switch turns that courtesy off, and only that. Measured here rather
+ * than read from the manual: with the variable set, `status` leaves `.git/index`
+ * untouched (same mtime across a forced refresh), while `add`, `commit` and
+ * `checkout -b` still take the locks they require and still work — the commit
+ * contains the staged file.
+ *
+ * So this **removes the need for a grant** instead of widening one. The
+ * boundary does not move; the noise against it stops. That distinction is the
+ * point: the alternative on the table was declaring git's machinery as
+ * territory in every role, which is more policy describing less confinement.
+ *
+ * A role that wants the old behaviour names `GIT_OPTIONAL_LOCKS` in its `env`
+ * and sets it in the parent — the loop below then overwrites this.
+ */
+export const DEFAULTS = { GIT_OPTIONAL_LOCKS: "0" };
+
 /**
  * Names that must never ride along, even if a role asks for them by pattern.
  *
@@ -47,7 +78,10 @@ const NEVER = /(^|_)(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|SESSION|CO
  */
 export function buildEnv(parent, role, extra = []) {
   const wanted = new Set([...BASE, ...extra, ...(role.env ?? [])]);
-  const env = {};
+  // Seeded, not merged afterwards: the loop below must be able to overwrite a
+  // default when the role named it and the parent carries it. Merging the other
+  // way round would make the opt-out silently do nothing.
+  const env = { ...DEFAULTS };
   const dropped = [];
 
   for (const [name, value] of Object.entries(parent)) {

package/src/index.js

@@ -23,7 +23,7 @@ export { covers, ownersOf, keyHolders, explain } from "./owners.js";
 
 /** A policy, resolved into sandbox settings and a child environment. */
 export { settingsFor, RUNTIME_WRITES, expand } from "./srt.js";
-export { buildEnv, BASE as BASE_ENV } from "./env.js";
+export { buildEnv, BASE as BASE_ENV, DEFAULTS as DEFAULT_ENV } from "./env.js";
 
 /** The report `check` prints, without the printing. */
 export { inspect, sharedPaths } from "./inspect.js";

package/ui/index.html

@@ -457,7 +457,7 @@ button.btn:active,button.tag:active,button.add:active,button.sw:active{transform
       }
       // Below the threshold there is nothing to summarise and a fold would only hide what
       // already fits. Above it, the folder counts ARE the reading: "this role writes 43
-      // files under equipo/" is the fact, and the forty-three names are the footnote.
+      // files under src/" is the fact, and the forty-three names are the footnote.
       if(r.writes.length<=FOLD_AT||OPEN[r.name]){
         r.writes.forEach(function(p,i){ t2.appendChild(tagFor(p,i)); });
         if(r.writes.length>FOLD_AT){