@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/reference/decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md

@@ -0,0 +1,295 @@
+# A Machine cuts a Worktree, and the Workspace only clones
+
+`workspace()` made one branch Worktree for each Repo Slot from `spec.branch`, and one detached Worktree from
+`spec.reviewSha`. So `spec` collected kinds of Worktree, a slot that is only read got a Worktree that no Agent used, and
+a Machine could not run two coders in one clone, retry a review in a clean folder, or name a branch after its plan. Now
+the Workspace only clones. A Worktree is a folder that a Machine names and makes with a kit Effect, `worktree()`.
+
+The layout and the branch order follow the conventions that [gwtmux](https://github.com/snapwich/gwtmux) defined: jr2
+does not call gwtmux and does not depend on it. Three designs were built on real files, attacked, and judged: a design
+with the path as the reference (this one), a design with the branch as the reference, and a design with no step that
+makes a Worktree. A prototype of the chosen design passed 62 of 62 `@kind` scenarios in real pods.
+
+## Decision
+
+### The Workspace
+
+- **The Workspace clones.** `spec`, `workspace.branch` and `workspace.review` go. `workGroup` is an option of
+  `workspace()`: `workspace(body, { workGroup: 2000 })`.
+- **A handle is the slot's folder, and not a Worktree.** `context.workspace.repos.app` is `/work/app`.
+- **`default/` stays on the Binding's base.** A branch is attached, and a tag or a commit is detached. With no base, it
+  is the Repo's default branch. A slot that is only read needs nothing more: an Agent reads `/work/<slot>/default`. No
+  work happens in `default/`, and a cut of the branch that it holds is `refused`, and the reason names
+  `/work/<slot>/default`.
+- **The author chooses how many Agents work in a Workspace.** The rule "one Agent at a time" goes. Agents in one
+  Worktree share git as people in one checkout do. Each coder that needs its own branch gets its own Worktree of the one
+  clone.
+- **`/work/.jr2/` is reserved for jr2.** A Repo Slot name cannot start with `.`. An Agent can write under `/work`, so
+  nothing there is a record that jr2 trusts.
+
+### `worktree()`
+
+```ts
+worktree();                       // a local branch, then origin (tracked), then new
+worktree({ expect: "new" });      // refuse a branch that exists
+worktree({ expect: "existing" }); // refuse a branch that does not exist, and make nothing
+
+{ path: "/work/app/fix", branch: "docs/123", from?: "v3" }  // a branch Worktree
+{ path: "/work/app/review", detach: sha }                   // forced and cleaned on each cut
+
+{ outcome: "ready", slot, path, branch: string | null, head, found, stale? }
+{ outcome: "refused", reason }  // nothing changed
+{ outcome: "unknown", reason }
+```
+
+- **The path is the reference, and the Machine knows it before the cut.** It is exactly `/work/<slot>/<name>`, with one
+  segment that is not `default` and starts with neither `.` nor `-`. So a door word or a planner's word does not become
+  a folder tree, and a `run` branch and a `run/a` branch never need nested folders.
+- **`branch` is required unless `detach` is given.** The branch is read from the cut's record, never from the folder or
+  from HEAD. A Machine can use one word for both. The rule can relax after v1, and the reverse is a break.
+- **A cut resolves a branch in one order, after a fetch:** a local branch, then `origin/<branch>` with tracking, then a
+  new branch from `from` or the Binding's base with no upstream. `found` says which: `local`, `remote` or `none`. A path
+  that a cut already made needs no fetch, and `found` is `held`. A detached cut says `commit`.
+- **A failed fetch degrades.** `stale` carries ADR-0053's warning, and the cut uses what the clone holds. A name that
+  the clone does not hold is `refused`, because the remote cannot confirm that it is new.
+- **`expect` is static**, so a Chart cannot change it. The string can grow. A boolean cannot, and its absent value and
+  its `false` would mean different things.
+- **A cut runs on the `command` machinery**: a kit program in the Harness container, no new wire kind, marked
+  idempotent. Each thing that an Agent's word can cause settles as `refused`, and never as `onError` (ADR-0067). A cut
+  writes a record before it changes git, so `refused` changes nothing and the next cut in the clone repairs a killed
+  cut. It never removes a folder that its record does not name. A re-cut that disagrees with the first cut is `refused`.
+  Cuts of one clone are serialized by a lock.
+- **A detached cut is forced from its own record** and cleaned with `-ffd`. Ignored files stay, because a reviewer runs
+  the tests (ADR-0028).
+- **A cut needs a Repo Slot.** `jr2 up` and the invoke refuse `worktree()` under a Workspace with no Repo Slot, as they
+  refuse a `push` (ADR-0051).
+- **v1 has no kit removal.** The docs give a `command` that runs `git worktree remove`.
+
+### What names a Worktree
+
+```ts
+coder:   { prompt, cwd: "/work/app/fix" }          // required under Repo Slots
+publish: { worktree: "/work/app/fix", sha }        // push
+test:    { worktree: "/work/app/fix" }             // command
+send:    { name: "r.md", worktree: "/work/app/fix" } // http with a file body
+```
+
+- **`cwd` and `worktree` are required under Repo Slots.** A Workspace that only clones has no Worktree for a default to
+  name, and `/work` is the wrong default: an Agent's search hits `default/`, and a relative write lands outside each
+  Worktree. That is the incident in ADR-0057. A Turn that wants `/work` states it. A Workspace with no Repo Slot, and an
+  Agent with `workspace: "none"`, need no `cwd`.
+- **`push` has no `to` and no `branch` in its input.** It keeps its static `slot`. The Orchestrator finds the cut's
+  settled row in the run's ledger, by the path and this Sandbox, and tells the Effector which branch to publish. An
+  Agent can change all of git in the pod, and it cannot change that row. With a read of HEAD, `git switch main` would
+  publish `main`. With an input key, a Chart could aim at any remote branch. A push with no row, a row of another slot,
+  or a detached Worktree is `rejected` at stage start. The ledger key is (slot, branch). The local name equals the
+  remote name, so an Agent, a Gate and a person in the pod all see the real branch.
+- **A `command` that names a secret and an `http` file body need the same row.** A path alone does not name the target
+  of a credential.
+- **A bad Worktree does not add an outcome.** A `command` settles `exited` 127 with the reason in its tail, and an
+  `http` file body settles `refused`.
+- **A compile error catches a wrong slot.** `Workspaced` types a handle as the literal `/work/<slot>`, and `jr2Setup`
+  maps the body's slots to each Worktree input. The compile check is a help and the guarantee is at run time. It sees
+  the slot and the first character of the name, under `jr2Setup`, on a literal path. It does not see a path held as
+  `string`, a plain `setup()`, a `repos: open` Machine, or a body that is generic in its slots. A helper must return
+  `as const`.
+
+### A Chart
+
+- A cut lent to a Chart must state `expect`, and a Chart reads it with the kit guard `jr2.ready`.
+- The door refuses `expect: "existing"` beside a lent force push, because together they let a Chart force-push any
+  existing branch that `default/` does not hold.
+- The door refuses a `cwd` that is a slot's folder.
+- A Chart's payload has no `pattern`, so a Chart cannot state the branch rule, and the cut refuses a bad name. A
+  hand-written Machine's pick param uses the kit schema `branchName`, so a bad name is refused at the Menu. The cut and
+  the push share that rule. Names with `@`, `#` or `+` are refused, as the Effector refuses them.
+
+### Output and the walk
+
+- **Every Effect outcome is open.** `worktree()`, `push`, `command` and `http` each hold a stand-in member in their
+  union, so that no author can write an exhaustive check. A later outcome is then no break.
+- **The load-time walk refuses an Effect's `onDone` with no unguarded last arm.** A type cannot see a missing arm, and
+  with no match a run stays in that state and shows no fault.
+
+### Fetches in one clone
+
+All Worktrees of a clone share `refs/remotes/origin/*`. A `git fetch` updates a ref only if it still holds the value
+that the fetch read, so two fetches that overlap on a moved remote can fail with
+`cannot lock ref … is at <sha> but expected <sha>`. The failure does no harm: the ref is already newer, and a second
+fetch works. But it costs a Turn, so `jr2-upload-pack` takes a per-clone lock and keeps it until the fetch ends. It
+takes the lock after it asks the node cache, so a dead remote does not make coders wait in line. The program execs
+`git upload-pack`. That process can end before the fetch writes its refs: that happens when a pack moves. In a shared
+clone, git often keeps the connection open to the end. The lock must last to the end of the fetch in both cases, so a
+small child process that watches the fetch holds it, and ends when the fetch ends. The child watches the `git fetch`
+process and not its parent, because `git remote-ext` ends with the connection.
+
+A cut keeps its own lock, and fetches under it. A fetch waits only for a fetch: a cut can wait for the fetch lock, and
+nothing that holds the fetch lock waits for a cut, so the two cannot deadlock. A fetch waits at most 30 s in line, then
+runs with no lock, because the lock only helps and must not fail a fetch.
+
+| Measured                                                               | 4 coders              | 8 coders |
+| ---------------------------------------------------------------------- | --------------------- | -------- |
+| Real pod, `ext::` path, 90 s, moving remote, no lock                   | 29% of fetches failed | 39%      |
+| Local, no lock                                                         | 8%                    | 11%      |
+| Local, `core.filesRefLockTimeout=5000`                                 | 8%                    | 11%      |
+| Local, lock for the connection only                                    | 3%                    | 4%       |
+| Local, lock held to the end of the fetch                               | 0%                    | 0%       |
+| Real pod, same load, lock held to the end of the fetch: failed fetches | 0 of 349              | 0 of 725 |
+| Real pod, same load, with the lock: fetch p95                          | 1066 ms               | 1078 ms  |
+| Real pod, same load, with the lock: cut p95                            | 4289 ms               | 8256 ms  |
+
+Git's lock timeout does not help, because no lock is busy: the compare fails. If the wait under the lock is too long in
+a pod, jr2 drops this lock and adds a `@model` claim that an Agent runs the fetch again.
+
+### Smaller rules
+
+- **A Pool's `next` reads `{ active, settled, input }`.** `input` is the Pool's input and `settled` holds the ids of the
+  finished and failed items, so a Source can fan out over a plan with no state of its own.
+- **A wrapper's door is parsed under a parent too**, so a parent that passes less than a `workspace()` or a `pool()`
+  requires fails (ADR-0033).
+- **A Sandbox delete waits for its pod**, because a retry can take the name of a pod that is still going away
+  (ADR-0021).
+- **An Agent's commits on a side branch are not published**, and `found` says `held`. A warning field can follow after
+  v1.
+- **`jr2 status <run>` shows each path and branch.** `jr2 ls` shows only Sandboxes, because it reads cluster labels.
+
+## Example
+
+A coder, a detached reviewer, and a signed push of the commit that the reviewer read. The reviewer has its own folder,
+which each round forces to the commit and cleans.
+
+```ts
+type BodyInput = Workspaced<{ prompt: string; branch: string }, "app">;
+const coderTree = (c: BodyInput) => `${c.workspace.repos.app}/work` as const;
+const reviewTree = (c: BodyInput) => `${c.workspace.repos.app}/review` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput & { reviewed?: string } },
+  actors: {
+    coder: agent({ model, instructions: "You fix the bug. You commit the fix." }),
+    reviewer: agent({ model, workspace: "read", instructions: "You review one commit. You change nothing." }),
+    cut: worktree(),
+    publish: push({ sign: true, pin: true }),
+  },
+}).createMachine({
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: context.prompt, cwd: coderTree(context), continue: true }),
+      },
+      on: { finished: "reading" },
+    },
+    // A cut is idempotent, so it also reads a Worktree. `head` is the tip of the branch, whatever HEAD the coder left.
+    reading: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [
+          {
+            guard: ({ event }) => isReady(event.output),
+            target: "detaching",
+            actions: assign({ reviewed: ({ event }) => readyOf(event.output).head }),
+          },
+          { target: "notCut" },
+        ],
+      },
+    },
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review ${context.reviewed}.`, cwd: reviewTree(context) }),
+      },
+      on: { pass: "publishing", revise: "coding" },
+    },
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: coderTree(context), sha: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "coding" }],
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+  },
+});
+```
+
+Concurrent coders in one clone. A Pool in the body runs one worker for each task, and each worker cuts its own Worktree.
+The body cuts its merge target first, so a name conflict is refused before a coder works. Then it merges each branch, in
+one clone with no fetch, and pushes once.
+
+```ts
+const taskTree = (c: WorkerInput) => `${c.workspace.repos.app}/task-${c.id}` as const;
+const mergeTree = (c: BodyInput) => `${c.workspace.repos.app}/merge` as const;
+
+// In the worker:
+cutting: { invoke: { src: "cut", input: ({ context }) => ({ path: taskTree(context), branch: `task/${context.id}` }) } },
+coding: { invoke: { src: "coder", input: ({ context }) => ({ prompt: context.title, cwd: taskTree(context) }) } },
+
+// In the body:
+cutting: { invoke: { src: "cut", input: ({ context }) => ({ path: mergeTree(context), branch: context.branch }) } },
+working: { invoke: { src: "coders", input: ({ context }) => ({ tasks: context.tasks, workspace: context.workspace }) } },
+merging: {
+  invoke: {
+    src: "merge", // command(["git", "merge", "--no-edit", arg("branch")])
+    input: ({ context }) => ({ branch: `task/${context.left[0]!}`, worktree: mergeTree(context) }),
+  },
+},
+publishing: { invoke: { src: "publish", input: ({ context }) => ({ worktree: mergeTree(context) }) } },
+```
+
+## Considered options
+
+- **The branch as the reference: `worktree({ slot, branch })`, with the path as output.** Rejected. The path is known
+  only after the cut, so each later state reads it from context, and a Chart needs an output read. `/` in a branch must
+  map to a folder. S1 cost 29 more lines against 8 for this design, and its attack found three fatal faults.
+- **No step: a Worktree named as data, made on first use.** Rejected. A Turn has no route for a refused cut, and that is
+  the fault of its central idea. A planner's typo becomes a Turn that cannot start. It saves lines in the hard
+  scenarios, and it saves nothing in the common one.
+- **The name is the local branch.** Rejected. A door word then reaches a path, a slash needs a mapping, and `run` beside
+  `run/a` collides.
+- **`to` on `push`.** Rejected for v1: no scenario needs it, and it can be added with no break. A name chosen after the
+  work needs a cut first.
+- **`push` reads HEAD.** Rejected. An Agent can move HEAD.
+- **`default/` always on the Repo's default branch.** Rejected. An Agent would read the wrong version of a pinned
+  handbook with no sign, and a read-only slot is a reason for this design.
+- **`cwd` defaults to `/work`.** Rejected, as ADR-0057 rejected it.
+- **A bad path goes to `onError`.** Rejected by ADR-0067: an Agent's param can cause it.
+
+## Consequences
+
+- After v1, these are additive: a removal Effect, a sparse checkout, a new Worktree source, `to`, a relaxed `branch` or
+  `cwd`, a later outcome, and durable output under `/work/.jr2/` or on its own mount.
+- Park and restore can only restore all of `/work`. A restore from the remote alone cannot work: settled cuts do not run
+  again, and unpushed work is gone. v1 does not promise that form.
+- A packaged Machine with two slots still needs a static `slot` on its `push`.
+- A kill of the cut's node process alone can leave `git worktree add` running after the cut's lock frees, because git
+  does not inherit the lock.
+- The fetch lock's holder ends as an orphan, so PID 1 must reap it. A User Container whose PID 1 does not reap keeps one
+  more zombie for each fetch there: 50 fetches left 50, beside the 52 that git leaves by itself with no jr2 program.
+- A kill in the short `update-ref` step leaves a stale ref lock, and no cut removes it. So that name stays `refused`.
+- Several Agents now share one Sandbox (concurrent coders, or a reviewer beside a coder), and so do the workers of a
+  Pool in one clone. They share the one Harness and `/work`. Only the Harness process holds the control credential, and
+  each process it starts in `/work` runs confined, so no Agent's code can act as another Agent
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
+- This change alters the Frame, the Chart briefing and the door's refusal text. The full `@model` run read 18 of 19
+  scenarios. `chart-refusal/off` read 6 of 10, below its floor of 7, and each miss failed at the Menu's validation,
+  before the door, on the JSON-string Chart that ADR-0070 records. Run alone, two runs on each side at one time, `main`
+  read 8 and 8 of 10, and this change read 9 and 7 of 10. So this change does not lower the cell. The floor stays, and a
+  full run can miss it.

package/docs/reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md

@@ -0,0 +1,320 @@
+# An Agent's control credential lives only where no Workspace code runs
+
+[ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md) scoped an Agent's control
+credential to its Sandbox. That stops a coder in one Sandbox from delivering a pick to a reviewer in another Sandbox.
+[ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md) made several Agents in one Sandbox normal:
+concurrent coders in one clone, or a coder beside an independent reviewer. In one Sandbox the Sandbox scope is not
+sufficient. Every Agent's `bash` is a child of the one Harness process, at the one uid, and it inherits the env of that
+process. So a coder's `bash`, driven by a prompt injection, can read the Stand-in of the control credential, send
+`POST /agents/<reviewer-iid>/events` through the Custodian, and approve its own review. The reviewer did nothing.
+
+The attack does not need the coder's own `bash`. The Agents of one Workspace share a writable `/work`. Code that one
+Agent writes there — a test file, a git hook, `core.fsmonitor`, a smudge filter — runs when another process runs on
+`/work`: the reviewer's `bash`, its `node --test` or `git diff`, or a `command` Effect. That code then has whatever
+credential its process can read. So the question is not which container holds the credential. It is which processes run
+code from `/work`.
+
+## Decision
+
+- **The boundary.** A credential that lets a request act for an Agent lives only where no Workspace code runs.
+  **Workspace code** is each process whose program or input comes from `/work`: the Working tools, tests, builds, git
+  (its hooks, its filters, fsmonitor, textconv and each repository-local config) and `command` Effects. The boundary
+  needs no separate container for each Agent.
+- **One Harness container for each Sandbox.** It serves every workspace-ful Agent below the `workspace()`
+  ([ADR-0005](0005-sandbox-pod-composition.md)). A Menu-only Agent has no Sandbox, and it runs on the Instance Harness,
+  as before ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)).
+- **The Harness process is trusted, and every program that a model drives runs confined.** The Harness process runs
+  jr2's code only. It runs the engine loop for each conversation, and it holds the control credential. Each other
+  process in the Harness container runs in one Landlock domain, which the Harness is not in:
+  - each `bash` call, and so each test, build, git hook and planted program that it runs;
+  - each process of a search tool (`rg`, `grep`);
+  - the I/O of the file tools (read, write, edit);
+  - jr2's own git for the attach, the cut and the sync
+    ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md),
+    [ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), because a smudge filter or a textconv
+    in the shared `.git/config` runs in git's process;
+  - each `command` Effect that is placed in the Harness, which is each `command` that names no secret.
+
+  So the trust boundary is inside the Harness container: the Harness process on one side, the domain on the other.
+  [ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md) makes Landlock a requirement of jr2, so no path runs a
+  program unconfined.
+
+- **One spawner makes the domain.** At its start, the Harness starts the **spawner**, `effector spawner` on the runtime
+  volume ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)), confined once. The spawner
+  starts each process that the Harness asks for, and it does each file tool's I/O and each read, list and remove of a
+  path that the Harness needs in the Agent's files (the sync's git folders and its bundle). It sends back the output,
+  the exit status, the file's bytes and the names in a folder. A process inherits its parent's domain, so every program
+  of every Agent of the Sandbox is in the one domain. They see, signal and trace each other, as one user's processes do
+  on a machine: a later `bash` call can `kill` or `lsof` a server that an earlier call started. The tools that the model
+  calls do not change: `bash` takes a command, and `read`, `write` and `edit` take a path. If the spawner stops, the
+  Harness starts it again, with the same rules. The new spawner makes a new domain, a sibling of the old one, and the
+  processes that the old spawner started run on in the old domain. A process of the new domain cannot trace one of the
+  old domain, or read its `/proc/<pid>/environ` or its open files. Below ABI 6 it can still signal it, so a later `bash`
+  call can end a server from before the restart; at ABI 6 or later it cannot. The confiner never follows a symbolic link
+  to find what a rule allows: a link gets no rule (what it names gets its own rule where it is allowed, and the kernel
+  checks the path that a link resolves to), and the confiner refuses to start when a rule's path has a link on it. A
+  rule on a link would allow what the link names at each restart, and a confined process can change that.
+- **The domain can do what the container's uid can do, except reach jr2's secrets.** The rules give every right on every
+  path, with one exception: `/run/jr2`. There the domain can list the names in each folder, and do nothing else.
+  Landlock only narrows the Unix permissions, so a confined program can do everything that the uid can do without
+  Landlock, except:
+  - reach the contents of `/run/jr2`: read, write, truncate, make, remove, move or link a file or a folder there.
+    `/run/jr2` holds the control Stand-in, each held secret's Stand-in, the folder of the Custodian's control socket,
+    and the Harness's conversations. Every path that jr2 holds for the Harness alone is under `/run/jr2`. Landlock
+    allows a path only by its rules, so the confiner allows every sibling of `/run/jr2` and of each folder above it, one
+    level at a time. It also gives the root the right to list names on its whole tree, so `ls /`, `ls /run` and `find /`
+    work as they do outside jr2. That right lists the names under `/run/jr2` too: a held secret's name, a conversation's
+    file name. These names are not secrets.
+  - trace the Harness process, or read its `/proc/<pid>/environ` or `/proc/<pid>/mem`. A confined process cannot ptrace
+    a process outside its domain.
+  - at Landlock ABI 6 or later, connect to an abstract Unix socket that a process outside the domain made. The
+    containers of the pod share one network namespace, so this keeps the domain off the abstract sockets of the Harness
+    and of the Custodian.
+
+  Landlock does not limit a connect to a named Unix socket. So a confined program can connect to the Custodian's control
+  socket. There the Custodian is the guard: it refuses a request that does not carry the secret control Stand-in, and
+  the fetch Stand-in, which every confined program holds, is valid only on the fetch route. Each listener answers 404 to
+  the other's routes, so the fetch Stand-in gets nothing on the control socket.
+
+  The kernel, not the rules, keeps what other pods share. The Repo caches under `/repos`, the runtime under `/opt/jr2`
+  and the CA bundles are mounted read-only, and the pod mounts no ServiceAccount token. The domain does not limit the
+  network. A request reaches a held credential only through the Custodian
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)).
+
+- **No Harness pod reaches a cloud metadata address.** Where the metadata service of a node answers pods, it gives the
+  node's cloud credential, which no `workspace()` grants. The Custodian's dial guard (ADR-0059) applies only to a
+  request that goes through the Custodian, and a program of the Agent can connect directly. So `jr2 up` converges an
+  egress NetworkPolicy for each Harness pod: `jr2-sandbox-egress` selects each Sandbox pod,
+  `jr2-instance-harness-egress` selects the Instance Harness, and each check pod of the provider preflight gets one of
+  its own, before the pod. Each policy allows all egress except `169.254.169.254/32`, `fd00:ec2::254/128`,
+  `169.254.170.2/32`, `169.254.170.23/32` and `100.100.100.200/32`: the metadata service of AWS, GCP and Azure, the
+  credential agents of ECS and EKS Pod Identity, and the metadata service of Alibaba Cloud.
+  - NetworkPolicy has no deny rule. So the rule allows `0.0.0.0/0` and `::/0`, each with its addresses as `except`, and
+    it also allows every pod of the cluster (`namespaceSelector: {}`).
+  - The Instance Harness and the check pod run no Workspace code. They get the policy because the check pod stands for
+    every Harness pod ([ADR-0019](0019-one-converging-command-against-the-current-context.md)): a model that only the
+    node's credential reaches must fail the check, not a Turn.
+  - The block has two limits. The list is not complete for every cloud provider, and only a CNI that enforces
+    NetworkPolicy applies it. So the shared-cluster guide tells the admin to check the metadata address of their
+    provider, and to give pods no node credential: Workload Identity, or IMDSv2 with a hop limit of 1.
+
+- **The env of the domain is the container's own env, with the granted Stand-ins.** A program in the domain gets the env
+  that the container started with: the image's `ENV`, `harness.env` and `envFrom`, the proxy and CA variables. jr2's own
+  `JR2_*` names are removed, except `JR2_CUSTODIAN_URL`. It also gets `HOME`, `TMPDIR`, and the Stand-ins of the secrets
+  that the `workspace()` grants (its `secrets` list), each under its own name. It never gets what the Harness process
+  added to its own env after the start, and so it never gets the control Stand-in, or the Stand-in of a model key that
+  the `secrets` list does not name. A toolchain and a bring-your-own image work as they work outside jr2.
+- **The Harness process runs with jr2's env alone.** node, glibc and OpenSSL read names from the env that load code or
+  configuration from a path: `NODE_OPTIONS=--require /app/x.js`, `LD_PRELOAD`, `OPENSSL_CONF`. The image's `ENV` can
+  name a file that the domain writes. So the Harness starts as `effector nocore --harness-env -- node …`. The effector
+  and tini are static binaries, so no `LD_*` name changes them. Before it starts node, the effector:
+  - gives node only the names that jr2 composed for the container: each name of its `env`, which the Orchestrator lists
+    in `JR2_HARNESS_ENV_NAMES`, and each key of its `envFrom`, to which the Orchestrator gives the prefix
+    `JR2_ENVFROM_`. The image's `ENV` can also hold a name with that prefix, and node then gets it. The marks keep out a
+    name that an image sets by accident, not one that its author sets to attack: the image's author already controls the
+    Harness process through the image's glibc
+    ([ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md)).
+  - stops, and starts nothing, on an `envFrom` key that starts with `JR2_`. jr2's own names, such as `JR2_MENU_ONLY`,
+    which turns the domain off, come from the container's `env` alone, so a shared Secret cannot set one. `jr2 up`
+    refuses a `JR2_` name in `harness.env`, and a `JR2_` key of a Secret or a ConfigMap that `harness.envFrom` loads.
+  - removes from them each name that loads code or configuration from a path, or writes to one: every `LD_*` and
+    `MALLOC_*` name, `NODE_OPTIONS`, `NODE_PATH`, `NODE_COMPILE_CACHE`, `OPENSSL_CONF`, `GCONV_PATH` and the others of
+    its list, and a `TZ` that names a file.
+  - gives node `HOME=/run/jr2/home`, whatever the start env holds. node reads `HOME` once, at its start, into the
+    folders where a bare `require()` looks last: `$HOME/.node_modules` and `$HOME/.node_libraries`. A provider module
+    that pi-ai loads on its first Turn can miss in `node_modules` and fall through to them. So a Harness process with a
+    `HOME` that the domain writes runs a module that the domain put there.
+  - puts the container's whole start env, each `envFrom` key under its own name, in `JR2_START_ENV`, as base64. The
+    domain's env is made from it, so the image's `ENV` and the container's `HOME` reach each program of the domain. No
+    program reads that name. A `JR2_START_ENV` that the start env already holds is dropped. Without
+    `JR2_HARNESS_ENV_NAMES` the effector starts nothing.
+
+  At its start, before it loads any other module, the Harness refuses to run when a folder where node looks for a module
+  is outside `/opt/jr2` and `/run/jr2`, and it checks that its `HOME` is `/run/jr2/home`. A change of `HOME` after node
+  started is too late, so the Harness never makes one.
+
+  A name of jr2's env that names a credential file which the Harness process reads (`AWS_CONFIG_FILE`,
+  `GOOGLE_APPLICATION_CREDENTIALS`, and the others) is the admin's choice. `jr2 up` refuses such a path in a folder that
+  the domain writes in every pod (`/work`, `/tmp`, `/dev/shm`, `/home/jr2`), and warns on any other path: whether the
+  Sandbox's uid can write a folder of the image is the image's, and jr2 cannot read it.
+
+- **The file tools reach what `bash` reaches.** Their I/O runs in the spawner, so the kernel applies the domain's rules
+  to them. A path under `/run/jr2`, or a symbolic link to one, fails with the error that an unreadable file gives. `~`
+  in a path is the domain's `HOME`, as it is for `bash`.
+- **The Harness process touches no path that the domain can write.** Each path in the Agent's files that the Harness
+  reads, lists or removes goes through the spawner. The one exception is the file that holds the full output of a `bash`
+  call. The Harness makes it in the domain's `TMPDIR`, with a name that must be new and must not be a link, and it
+  writes through that open file alone. If the file did not land in `TMPDIR`, the Harness removes it and refuses. The
+  Harness process has its own `HOME`, `/run/jr2/home`, from its start (above), which does not exist and which no process
+  can make, because code in the Harness process reads files under `HOME`: node looks for modules in `~/.node_modules`,
+  the AWS SDK reads `~/.aws/config`, which can name a `credential_process` to run, and Google's library reads
+  `~/.config/gcloud`. The domain keeps the Workspace's `HOME`.
+- **One secret control Stand-in for each Sandbox.** Only the Harness process holds it, as a file under `/run/jr2`. It is
+  in no env of the domain. The Custodian puts the Sandbox's control token in its place on the control routes (ADR-0059),
+  and the real token never leaves the Custodian.
+- **The control routes are a Unix socket under `/run/jr2`.** The Harness sends each control request to the Custodian's
+  control socket, not to a loopback port. A confined program cannot make a socket under `/run/jr2`, so it cannot take
+  the control listener's place while the Custodian restarts, and it cannot receive the control Stand-in. It can connect
+  to the socket, and the Custodian refuses what it sends (above). The fetch route stays on loopback, because its
+  Stand-in is public.
+- **The Harness states the slot.** On each control request, the Harness states the Agent that the conversation belongs
+  to: its slot. It takes the slot from its own record of the conversation, never from the URL. The slot is the Agent's
+  full identity below the run: the actor path of its Machine and its agent name, which is a continued conversation's
+  Instance ID without the run id ([ADR-0057](0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md)). So two
+  Agents with one key in two child Machines are two slots. The Orchestrator checks that the stated slot is the slot of
+  the target registration, on the surface read, the pick, the delivery poll and the acknowledgment of a notice
+  ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). This check finds a routing fault. It is not
+  the security boundary: the boundary is that only the Harness holds the credential.
+- **Two tokens, each checked on its own routes.** This is defence in depth:
+  - The **control token** is what the Custodian puts in place of the secret control Stand-in. It is valid only on the
+    agent routes (`/agents/<iid>/surface`, `/agents/<iid>/events`, `/agents/<iid>/deliveries/<id>`, and the route on
+    which the Harness acknowledges a notice), and it carries the stated slot.
+  - The **fetch token** is what the Custodian puts in place of the public Sandbox Stand-in that `jr2-upload-pack` holds
+    as a constant. It is valid only on `POST /sandboxes/<sandbox>/fetch`
+    ([ADR-0053](0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md)). The Custodian
+    accepts the public Stand-in on the fetch route only.
+  - The Orchestrator accepts each token only on its own routes. A Gate accepts neither, and no other principal of an
+    Agent: an Agent never reaches a Gate (ADR-0013).
+- **An engine runs its loop in the Harness process.** pi does: its loop is in the Harness process, and only its tools
+  run in the domain. Each engine adapter states where its loop runs, and `engine.ts` refuses an adapter whose engine
+  runs in the domain. Every process of the one domain can see, trace and signal every other one, so another Agent's code
+  could write such an engine's stdin, read its environ and forge its Menu calls.
+- **An engine with its own process, such as Claude Code, needs a domain for each Agent first.** The root domain then
+  holds only the spawner, which no process can trace or read (`PR_SET_DUMPABLE 0`). For each conversation, the spawner
+  starts a sub-spawner one Landlock layer deeper, with a socket pair as its stdio and as the subreaper
+  (`PR_SET_CHILD_SUBREAPER`) of what it starts. Every process of that Agent comes from its sub-spawner: the engine, its
+  `bash` and its git. Landlock denies a process of one nested domain the `/proc/<pid>/fd` and the environ of a process
+  in a sibling domain, so an Agent's code cannot drive another Agent's engine. They still share `/work`. Such an engine
+  also needs these, as mechanisms:
+  - **Authority stays in the Harness.** The engine holds no token in its env, its argv or a file. The Harness knows the
+    engine by the socket that it gave it. The Harness accepts a Menu call only when it matches a tool call of a model
+    answer that the Harness relayed, and only the first pick of that answer
+    ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)). The Turn's safety hooks become decisions
+    of the relay and of the Menu server.
+  - **The model endpoint is not a proxy.** It sets the path, the model and the Dials, and refuses every other API of the
+    provider (files, batches, fine-tuning). It counts the usage into the Settlement, and it refuses a request outside a
+    Turn. The context of each request comes from jr2's record: the engine's own session file is a cache that jr2 does
+    not trust. It is never on the Harness's wire port.
+  - **Spawns go through the spawner.** An adapter starts its engine through the spawner, with the domain's env, never
+    with the Harness process's env.
+  - **No such engine on the Instance Harness.** The Instance Harness has no domain, and its control Stand-in is valid
+    for each Menu-only Agent of the Instance. A Menu-only Agent's engine runs its loop in the Harness process
+    ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)).
+- **Chart Agents and Pool workers need no provisioning.** The Agents that a Chart makes
+  ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)) and each Turn of a Pool worker run in the one Harness, and
+  the Harness states their slot. The provision knows nothing of the Agents of the Sandbox.
+
+## Considered options
+
+- **One Harness container for each agent slot, each with its own secret Stand-in.** Rejected. Kubernetes isolates one
+  container from another, but all the slots share the writable `/work`. Code that one Agent plants there runs in a
+  sibling's container when the sibling's `bash`, git or tests run, or when a `command` Effect runs there, and that code
+  reads the credential of the container that runs it. So container isolation between Agents gives nothing against an
+  attack that goes through `/work`. It also costs a container, a port, a Secret and a share of the Size for each slot,
+  and it has no container for an Agent that a Chart makes at run time.
+- **A trusted control container and a tools container with no credential.** Rejected. It gives the same protection as
+  confinement: no Workspace code runs where the credential is. But it adds a container, it sends each tool call across a
+  container edge, and it changes [ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md) (the
+  Harness is one server). jr2 already confines the code that an Agent wrote in the Effector (ADR-0068). One mechanism
+  serves one problem.
+- **A second uid inside the Harness container**, so that `bash` runs as a uid that cannot read the credential. Rejected.
+  Under `runAsNonRoot`, `allowPrivilegeEscalation: false` and `capabilities: drop ALL`, no process can `setuid` without
+  `CAP_SETUID`, and under `no_new_privs` that likely also needs `allowPrivilegeEscalation: true`. It adds privilege to
+  the container that runs code a model controls.
+- **A user namespace**, so that the Harness maps a second uid with no host privilege. Rejected: the default seccomp
+  profile (`RuntimeDefault`) blocks `unshare(CLONE_NEWUSER)` from a process with no privilege. It needs a custom seccomp
+  profile and a kernel that permits it, so it is not portable to a self-hosted cluster.
+- **No right to list `/` and the folders above `/run/jr2`.** Rejected. `ls /`, `ls /run`, `find /` and a glob such as
+  `/*` then fail, which stops normal work. Landlock can only add rights, and a right on a folder holds on its whole
+  tree, so a right to list `/` also lists `/run/jr2`. The names there are not secrets.
+- **The Harness process inherits the image's env.** Rejected: the image's `ENV` can hold
+  `NODE_OPTIONS=--require /app/x.js`, and `/app` can be a folder that the Sandbox's uid owns. Workspace code writes
+  `/app/x.js`, ends the Harness (below ABI 6 a signal can), and the restarted Harness runs that file with the control
+  Stand-in in its memory. A deny-list alone on the image's env is not sufficient: the next name that loads code is not
+  on it.
+- **The Harness process keeps the domain's `HOME`, or takes its own after node starts.** Rejected: the domain writes
+  that folder, and code in the Harness process reads files there. A planted `~/.aws/config` with a `credential_process`
+  would run a program outside the domain. node reads `HOME` once, at its start: a module planted in
+  `$HOME/.node_modules` or `$HOME/.node_libraries` would run in the Harness process, as one named by `NODE_OPTIONS` or
+  `NODE_PATH` would. So the Harness gets its `HOME` when it is started.
+- **Rules that allow only `/work`, `HOME`, `TMPDIR` and the system paths.** Rejected. It stops what an Agent does on a
+  machine: a write to a folder of the image that the uid owns (`/app`, a virtualenv, `/usr/local`), a read of `/var` or
+  `/srv`, a write to `/proc/self/oom_score_adj`. A bring-your-own image breaks in ways that its author cannot see. The
+  secrets are under one path, so a rule that denies that path is sufficient.
+- **A new domain for each process that the Harness starts.** Rejected. Each `bash` call is then its own domain, so a
+  later call cannot signal, trace or `lsof` the server that an earlier call started. That is normal behaviour for an
+  Agent.
+- **One spawner for each conversation, today.** Rejected while every engine runs its loop in the Harness process. Then
+  an Agent's processes hold nothing that another Agent's code can use to act as that Agent: the credential and the loop
+  are in the Harness, and each process gets the one env of the Sandbox. Through `/work`, one Agent can only try to
+  persuade another Agent's model. The separation costs a process and a layer for each conversation. It is the path for
+  an engine with its own process (above): there, a sibling in the one domain forges the engine's Menu calls at once.
+- **The file tools do their I/O in the Harness, with a check of the path.** Rejected. It puts the rule in two places,
+  the kernel and jr2's code, and the check in code must handle each symbolic link and each race.
+- **The control routes on a loopback port.** Rejected. A confined program can bind `127.0.0.1:<port>` while the
+  Custodian restarts, and it then receives the secret control Stand-in on the Harness's next request.
+- **The Custodian authenticates the caller.** Rejected alone: every process reaches the Custodian over the one pod
+  loopback. The Custodian can tell the Harness from a child only by a secret that the child cannot read, which is this
+  decision.
+- **Keep the Sandbox-scoped credential, and call the Agents of one Workspace mutually trusting.** Rejected: a coder
+  beside an independent reviewer in one Workspace is a motivating case.
+- **Refuse all of `169.254.0.0/16` at the egress.** Rejected: NodeLocal DNSCache answers on `169.254.20.10`, so the pods
+  of a cluster that runs it lose DNS.
+- **An egress policy with `ipBlock` peers only.** Rejected: a CNI that applies an `ipBlock` to the address of a pod
+  (Cilium) then cuts DNS, the Orchestrator and each Service. So the rule also allows every pod of the cluster.
+- **The egress policy on the Sandbox pods only.** Rejected: the check pod of the provider preflight stands for every
+  Harness pod. Without the policy there, a model that only the node's credential reaches passes the check and fails in a
+  Turn.
+
+## Consequences
+
+- **No Workspace code can act as an Agent.** Planted code finds no control credential: not in its env, not in a file
+  that it can read, not through the Harness's `/proc`. It cannot deliver a pick for any Agent, its own included. Only
+  the Harness process delivers a pick, for the conversation whose model called the pick.
+- **What remains.**
+  - An Agent can still try to persuade another Agent through what that Agent reads: a file, a commit message, the output
+    of a test. That is an attack on content, not a forged pick. The other Agent's model chooses each pick, and the
+    Orchestrator judges it against that Turn's Allowed picks
+    ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)).
+  - A confined child can spend only a held secret that its `workspace()` grants. Every Stand-in but the fetch Stand-in
+    is secret, and the child's env holds only the granted ones (ADR-0059). So code in `/work` reaches a model key only
+    when the author grants that key.
+  - Below Landlock ABI 6, a confined process can still send a signal to the Harness process, which has the same uid. So
+    the Harness starts with no core file (`effector nocore`, a core limit of zero), and with Node's `--disable-sigusr1`.
+    Without them, a dumping signal writes the Harness's memory, with its Stand-ins, to a file in its working folder, and
+    SIGUSR1 opens Node's inspector on the pod loopback, which runs the child's code in the Harness. What a signal can
+    still do is stop or end the Harness. That is a denial of service in the Agent's own Sandbox, not an impersonation.
+    The Harness names its process `jr2-harness`, so an Agent's `pkill node` does not end it by accident. ABI 6 scopes
+    signals and abstract Unix sockets to the domain, and the confiner uses both scopes when the kernel offers them
+    (ADR-0077): the Harness is then outside each signal from the domain.
+  - The domain can connect to the Custodian's control socket. The Custodian refuses each request that does not carry the
+    control Stand-in, which no process of the domain holds.
+  - The domain can see that a path under `/run/jr2` exists, by its name or by `stat`, and its size. It cannot read what
+    is in it.
+  - The node's cloud credential is closed only at the metadata addresses that jr2 knows, and only on a CNI that enforces
+    NetworkPolicy (the decision above).
+- **The pod is ADR-0005's pod**: one Harness, a Custodian, and an optional User Container and Sandbox Effector. The
+  count of Agents does not change it, and the Size splits as before
+  ([ADR-0060](0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)).
+- **The Instance Harness runs no Workspace code.** A Menu-only Agent has no Working tools (ADR-0031), so the credential
+  of the Instance Harness is already where no Workspace code runs.
+- **Tests.** The `@kind` tier proves the boundary from the model's own `bash`: it finds no Stand-in of the pod in its
+  env, in a file or through the Harness's `/proc`; a test that the coder plants and the reviewer's own `node --test`
+  runs cannot deliver a pick as the reviewer, and the run does not settle; a granted held secret works, and no model key
+  is in the env; a second Agent runs git on its Worktree, and the step checks the output. It also proves that the domain
+  does not stop normal work: a server that one `bash` call starts is found and ended by a later call; a write to a
+  folder of the image that the uid owns, outside `/work`, succeeds; a move of a file into another folder succeeds;
+  `ls /` and `ls /run` succeed; and `read` reads the full output of a `bash` call. It proves the metadata block: kind
+  has no metadata service, so the step gives `169.254.169.254` to the node, and a pod that the policy does not select
+  gets the node's refusal there. The Agent's `bash` does not, and it still connects to the model's host and to the
+  Orchestrator's Service. A unit test pins the policy that `jr2 up` composes. The unit and conformance tests refuse the
+  control token on the fetch route, the fetch token on an agent route, a stated slot that is not the registration's, and
+  both tokens at a Gate, and they check the slot on the delivery poll. A test reads the Harness container's mounts from
+  the pod spec. It fails on a mount that is not read-only, not under `/run/jr2`, and not the Workspace's own (`/work`,
+  `HOME`), so a new mount is classified before it ships. Unit tests start node through `effector nocore --harness-env`
+  with a `HOME` that holds a planted `.node_modules`, and check that node looks for no module there; they also retarget
+  a link onto `/run/jr2`, restart the spawner, and check that the new domain reads nothing there. The `@kind` tier reads
+  the Harness process's environ from outside the pod and checks its `HOME`.
+- **The `@model` tier runs after the build.** The change alters what the Working tools can do and where a notice is
+  delivered ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)), so it is a `@model`-tier change
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)).