@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/reference/decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md

@@ -48,9 +48,13 @@ composition and does not replace it. The two uses stay two mechanisms.
   the url and the token together, one Open part, with `customize(m, { effects: { task: { target: { url, token } } } })`
   ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)); `secret(open)` inside a
   target is refused, since the whole target is the part. Another Instance may run another Kit version, so the HTTP door
-  is the only contract there. The token is the Instance token, which unlocks all control
-  ([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)); a start-only token is a token kind of its own and
-  is deferred.
+  is the only contract there. The token is any Caller's credential of the other Instance with `start` for the callee
+  Workflow ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): a named Caller
+  token made for this, or that Instance's Instance token. A `wait` also polls `GET /runs/<id>`, so its token needs
+  `read` for that Workflow too. The start carries the first Caller of the calling run's `startedBy` chain as
+  `onBehalfOf`, in the header `jr2-on-behalf-of`, which the other Instance records and does not check: that Caller's own
+  `onBehalfOf`, else the name that jr2 shows, else `<via>/<name>`. A chain that jr2 started, or a text that is not
+  printable ASCII of at most 256 characters, sends no claim.
 - **Two settlements, `started` by default, and every outcome is output.** `{ outcome: "started", run }` settles when the
   Orchestrator accepts the run; the watcher goes round again. `wait: true` settles
   `{ outcome: "settled", run, status, output }` when that run ends, `status` in the store's own words (`done`, `failed`,
@@ -69,12 +73,12 @@ composition and does not replace it. The two uses stay two mechanisms.
   a DELETE of the Effect ends that poll and never touches the run. No callback from the callee: a callback needs the
   callee to hold its caller's address and a token for it, which inverts the trust. A door refusal is OUTPUT,
   `{ outcome: "refused", status, report }`, with the door's status — 400 for bad input, 404 for a name the current
-  Assembly lacks, 409 for an unrunnable named Chart or a key another Workflow's run holds, 422 for a Chart the door
-  refuses, 413 for a start over the bytes an Effector reads, 0 when the Effector refused it before anything was sent —
-  as a Chart refusal is ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)): the body may have come from a model,
-  and the report must be able to reach it through the Chain. A target no replica could reach is
-  `{ outcome: "unreachable" }`, output, as an `http` Effect's is (ADR-0067): nothing was started. The invoke's error is
-  kept for defects: no run host or Effector, input that fails the slot's schema, a refused or malformed wire.
+  Assembly lacks, 409 for an unrunnable named Chart, 422 for a Chart the door refuses, 413 for a start over the bytes an
+  Effector reads, 0 when the Effector refused it before anything was sent — as a Chart refusal is
+  ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)): the body may have come from a model, and the report must
+  be able to reach it through the Chain. A target no replica could reach is `{ outcome: "unreachable" }`, output, as an
+  `http` Effect's is (ADR-0067): nothing was started. The invoke's error is kept for defects: no run host or Effector,
+  input that fails the slot's schema (when no run has the key, below), a refused or malformed wire.
 - **The two runs are independent.** Cancelling the caller never cancels the callee; the caller's end never ends it;
   leaving the state stops a wait and never the run; the callee's Workspaces are its own. Temporal's parent-close policy
   (`TERMINATE` by default, `REQUEST_CANCEL`, `ABANDON`) exists because a child there is both a run and a child, and its
@@ -89,7 +93,8 @@ composition and does not replace it. The two uses stay two mechanisms.
   `dispatched [{ slot, run, at }]`, the chain's other direction. `jr2 runs` carries `dispatchedBy` after the id,
   `jr2 status` prints `dispatched by:` and `dispatched:` lines, and the Console shows both. The word is **dispatched
   by**. The callee reads nothing of its caller from its input: a Machine that wants to tell its callee something passes
-  it as input like any caller.
+  it as input like any caller. A local dispatch records its caller's run as the callee's `startedBy`,
+  `{ kind: "run", run, slot }`, and `jr2 status` walks that chain to the first Caller (ADR-0078).
 - **A chain of dispatches is unbounded.** A run may dispatch a Workflow that dispatches another, or itself: a run that
   dispatches its own successor and ends is Temporal's continue-as-new, the honest way to keep a watcher's snapshot
   small, and a depth ceiling would refuse it. A runaway chain is a resource problem the cluster owner's quota and
@@ -100,24 +105,45 @@ composition and does not replace it. The two uses stay two mechanisms.
   key, out of band — the `jr2-dispatched-by` header, the `dispatchedBy` record as JSON, never a body field the callee's
   door would have to reserve — and `POST /workflows/<name>/runs` asks the key before anything else, so a re-sent start
   answers its run even when the name would be refused now: 201 with the run for a new one, 200 with
-  `{ runId, instanceId, existing: true }` for a repeat, 409 when a run of ANOTHER Workflow holds the key (the caller
-  asked for one Workflow and would wait on a run of another), 400 when the header does not parse, and 500, never 404,
-  for any other throw, since a foreign caller reads a 404 as "nothing was started" (ADR-0033 as amended). The key lives
-  in the callee's blob, and the store copies it into a `dispatch_effect` column of its own at every save and indexes
-  that, not an expression index over `json_extract`: SQLite's JSON parser refuses a blob nested about a thousand deep,
-  and such an index would fail that row's save and every later open of the volume. A run restore marks `lost` keeps its
-  row and its blob, so its key keeps answering; the weekly sweep
-  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md)) removes the key with the row, and a re-send
-  after it starts a new run: known, and not guarded. In-process the ledger is consulted directly, through the same start
-  under the same key, with the starts in flight held so two arrivals of one key before the first save are one run. So a
-  dispatch is idempotent whatever its author writes: its intent row says `idempotent: true`, a restore that cannot tell
-  whether its start arrived sends it again under its key with what is left of the bound, the Instance Effector sends a
-  start whose answer was lost again under its key with backoff until the bound, and the Effector's rollout grace is
-  never stretched by a dispatch's wait. Once the answer names the run, the intent row carries it, the Effector's
-  `running` state carries it on the wire, and a restore with it starts nothing: it settles `started` at once, or resumes
-  the wait. Without it a watcher double-starts a run after a restart, which a human notices as two pull requests. What
-  it does not guard: a door at a Kit version before this decision ignores the header, so a re-send to it starts a second
-  run, and neither the Effector nor the preflight can tell. A capability check is named and deferred.
+  `{ runId, instanceId, existing: true }` for a repeat, 200 with `{ existing: false }` for a key-only ask (below) with
+  no run under the key, 400 when a header does not parse, and 500, never 404, for any other throw, since a foreign
+  caller reads a 404 as "nothing was started" (ADR-0033 as amended). **The key is scoped to the callee Workflow**: the
+  store finds a key with the Workflow's name, so the same key in two Workflows is two runs, and a key never answers with
+  a run of another Workflow. A key answers `existing` while its run's row lives, in any status: live, and for
+  `runs.retain` after it ends ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)). A
+  retry after a failure is then a person's act, not a re-sent start's. The Effect checks the key before it checks its
+  input against the slot's schema, in-process and on the foreign path, as the door does: a start sent again across a
+  change of the callee's door answers `existing`, not an error. In-process it asks the run host for the key before it
+  reads the input, within the slot's bound. On the foreign path, a body that the slot's schema refuses is never sent:
+  the start is a **key-only ask**, the header `jr2-key-only: true` beside `jr2-dispatched-by` and no body, out of band
+  as the key is. The door keeps its order: the scope check (ADR-0078), then the key. With a run under the key it answers
+  `existing`, as for any start; with none it starts nothing and answers 200 with `{ existing: false }`, which a foreign
+  caller cannot read as a refused name (404) or a defect (5xx). The Instance Effector settles that answer as `absent`,
+  an outcome of the wire alone, and the Effect makes it the slot's schema refusal, the invoke's error. So input that
+  fails the slot's schema starts nothing on either path, and a run that its key already started is answered on both. A
+  body that the slot's schema takes goes as before, in one request. This is the same for a first send and for a send
+  again (a restore, a retry): a Pool's hand-over is a first send of a new run's Effect under a key that may already name
+  a run of a callee whose door changed. A `wait` sent again under a key that answers `existing` follows that run, and
+  settles when it ends. **A Pool's worker sends its `itemId` as the key** ([ADR-0017](0017-pool-over-a-source-port.md)),
+  so a Pool's hand-over re-attaches to each live run. An author's own key (`dispatch({ key })`) is not offered now; to
+  add it later breaks nothing. The key lives in the callee's blob (a Pool's `dispatchedBy.key`, else
+  `dispatchedBy.effect`), and the store copies it and the Workflow into columns of their own (`dispatch_effect`,
+  `dispatch_workflow`) at every save and indexes the pair, not an expression index over `json_extract`: SQLite's JSON
+  parser refuses a blob nested about a thousand deep, and such an index would fail that row's save and every later open
+  of the volume. A run restore marks `lost` keeps its row and its blob, so its key keeps answering; the sweep of rows
+  older than `runs.retain` ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)) removes
+  the key with the row, and a re-send after it starts a new run: known, and not guarded. In-process the ledger is
+  consulted directly, through the same start under the same key, with the starts in flight held so two arrivals of one
+  key before the first save are one run. So a dispatch is idempotent whatever its author writes: its intent row says
+  `idempotent: true`, a restore that cannot tell whether its start arrived sends it again under its key with what is
+  left of the bound, the Instance Effector sends a start whose answer was lost again under its key with backoff until
+  the bound, and the Effector's rollout grace is never stretched by a dispatch's wait. Once the answer names the run,
+  the intent row carries it, the Effector's `running` state carries it on the wire, and a restore with it starts
+  nothing: it settles `started` at once, or resumes the wait. Without it a watcher double-starts a run after a restart,
+  which a human notices as two pull requests. What it does not guard: a door at a Kit version before this decision
+  ignores the header, so a re-send to it starts a second run, and a door that knows the key but not the key-only ask
+  reads one as a start with no body; neither the Effector nor the preflight can tell. A capability check is named and
+  deferred.
 - **`jr2 up` checks what it can see, and the severity follows who owns both sides.** For a same-Instance name the walk
   resolves it in the Assembly and REFUSES a miss, naming the fix: on the host, among the Machines and the Chart files,
   and a slashed name whose wrapper exists but whose Chart the host cannot see is a warning there, since a runtime Chart
@@ -172,7 +198,7 @@ composition and does not replace it. The two uses stay two mechanisms.
 - ADR-0049's "no sub-run" is restated, not reversed: a nested Machine is reached by `import`, never by name; a run that
   starts a run is a `dispatch`, by name, and the two are different uses. ADR-0067 gains the kind and a fourth Placement,
   `orchestrator`. ADR-0068's Instance Effector gains the `dispatch` kind, its stop route stops a dispatch's wait too,
-  and its `running` state carries the run. ADR-0033's door gains an idempotency key.
+  and its `running` state carries the run. ADR-0033's door gains an idempotency key and the key-only ask.
 - The GLOSSARY's **Effect** gains "or starts a run", and `_Avoid_: sub-run, child run, nested run, spawned run` for the
   relation, which is **dispatched by**; its **Effector** and **Instance Effector** entries name the in-process exception
   and the new kind.
@@ -180,4 +206,4 @@ composition and does not replace it. The two uses stay two mechanisms.
   routing of both, without the key.
 - An Open body may lend a `dispatch` slot as it lends any Effect (`lends.effects`), so a Chart can start a run of a
   Workflow its wrapper chose; the Chart fills the body only.
-- Deferred, named: a start-only token; a depth ceiling; a capability check for a door that ignores the key.
+- Deferred, named: a depth ceiling; a capability check for a door that ignores the key; an author's own key.

package/docs/reference/decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md

@@ -15,22 +15,27 @@ Next.js ships the same design: its docs as Markdown inside the `next` package, a
   - **The bundle.** `@jr2/orchestrator` ships `docs/`: every page of the sitemap, the generated Reference, the Glossary
     and the Decisions, as plain Markdown. No site-generator syntax reaches it. It is the main channel for an Assistant.
     Each page is at its slug, such as `concepts/gates.md`, and each ADR is at `reference/decisions/<file>`. An Assistant
-    reads a page with its file tool, which cuts off a long file. So the Authoring surface is two parts:
-    `reference/authoring-surface.md`, a contents page that gives each name its kind and the first sentence of its TSDoc,
-    and `reference/authoring-surface/<anchor>.md`, one page for each export and for each type that a signature names.
-    One page of all the names is about 200 KB, and the contents page is less than 25 KB. No line of the contents page or
-    of an entry page is longer than 1,000 characters, so the type plumbing is a list, not a paragraph. When the contents
-    page passes 25 KB, first make the long first sentences shorter; if it still passes, give each group of the contents
-    page a page of its own, and make the contents page a list of the groups. The first sentence ends at a stop, not at a
-    colon, because the words before a colon often tell nothing alone ("An invoke."). A link to an entry goes to its
-    page. Each of the other generated Reference pages (CLI, config, machines, mechanism events, HTTP API) stays one
-    page. Each is less than 30 KB, the size that one read of a file tool shows, with one exception: the HTTP API page is
-    about 50 KB. It is one page because its routes come first and are less than 30 KB, so one read shows every route;
-    the types of the bodies come after the routes, and an Assistant reads one of them with an offset or by its heading.
-    When the routes pass 30 KB, give the types a page of their own. The alternative, a split of the HTTP API page now,
-    is rejected because a route and the types it names are then on two pages, and one read shows all routes already. The
-    Glossary and the Decisions are not generated, and this rule does not hold them: an ADR can be about 50 KB, and an
-    Assistant reads the one ADR that a page links to.
+    reads a page with its file tool, which cuts off a long file. So the Authoring surface is three parts.
+    `reference/authoring-surface.md` is a contents page that gives each group of the root's `src/index.ts`, and the
+    group of the types that the signatures name, its description and its names.
+    `reference/authoring-surface/group-<title>.md` is one page for each group, which gives each name of the group its
+    kind and the first sentence of its TSDoc. `reference/authoring-surface/<anchor>.md` is one page for each export and
+    for each type that a signature names. The `group-` prefix keeps a group page apart from an entry page, and
+    `docs:build` fails when two pages have one path. One page of all the names is about 200 KB. The contents page and
+    each group page are less than 25 KB, and each entry page is less than 15 KB. On the contents page, a type that a
+    signature names is code with no link, because there are more than a hundred of them; its group page links each one.
+    No line of a contents, group or entry page is longer than 1,000 characters, so the contents page breaks a list of
+    names into lines, and the type plumbing is a list, not a paragraph. When a group page passes 25 KB, first make the
+    long first sentences shorter; if it still passes, divide that group into two groups. The first sentence ends at a
+    stop, not at a colon, because the words before a colon often tell nothing alone ("An invoke."). A link to an entry
+    goes to its page. Each of the other generated Reference pages (CLI, config, machines, Hook kinds, mechanism events,
+    HTTP API) stays one page. Each is less than 30 KB, the size that one read of a file tool shows, with one exception:
+    the HTTP API page is about 50 KB. It is one page because its routes come first and are less than 30 KB, so one read
+    shows every route; the types of the bodies come after the routes, and an Assistant reads one of them with an offset
+    or by its heading. When the routes pass 30 KB, give the types a page of their own. The alternative, a split of the
+    HTTP API page now, is rejected because a route and the types it names are then on two pages, and one read shows all
+    routes already. The Glossary and the Decisions are not generated, and this rule does not hold them: an ADR can be
+    about 50 KB, and an Assistant reads the one ADR that a page links to.
   - **The `AGENTS.md` block.** A compressed index of the bundle, and an instruction in five parts. jr2 is newer than
     your training data, so read the bundled docs before you write a Machine or config. Start with the guide "Write a
     workflow" and the contents page of the Authoring surface. Read one page with each call of the file tool. Run
@@ -63,21 +68,26 @@ Next.js ships the same design: its docs as Markdown inside the `next` package, a
   exists for it. A broken marker pair is reported, and `up` does not change the file.
 - **The Reference is generated from the code wherever the code holds the facts.**
 
-  | Page                                                    | Source                                                 |
-  | ------------------------------------------------------- | ------------------------------------------------------ |
-  | Authoring surface: a contents page, and a page per name | TSDoc on the exports, exactly the root's list          |
-  | `@jr2/machines`                                         | TSDoc on the exports                                   |
-  | `jr2.config.ts`                                         | TSDoc on the `JR2Config` fields                        |
-  | CLI                                                     | a structured command table, which also prints `--help` |
-  | HTTP API                                                | the route table in `http.ts`, made data                |
-  | Mechanism events                                        | the code that defines them                             |
-  | Glossary, Decisions                                     | `GLOSSARY.md` and `docs/adr/`, rendered as they are    |
+  | Page                                                                      | Source                                                         |
+  | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
+  | Authoring surface: a contents page, a page per group, and a page per name | TSDoc on the exports, exactly the root's list                  |
+  | `@jr2/machines`                                                           | TSDoc on the exports                                           |
+  | `@jr2/orchestrator/hooks`                                                 | TSDoc on the exports of each module but `door`, one group each |
+  | `jr2.config.ts`                                                           | TSDoc on the `JR2Config` fields                                |
+  | CLI                                                                       | a structured command table, which also prints `--help`         |
+  | HTTP API                                                                  | the route table in `http.ts`, made data                        |
+  | Mechanism events                                                          | the code that defines them                                     |
+  | Glossary, Decisions                                                       | `GLOSSARY.md` and `docs/adr/`, rendered as they are            |
 
   The TSDoc on an Authoring surface export is written for the author: what it does, what it refuses, what to read next,
   and one example. Maintainer reasoning goes in `//` comments in the body. The packages ship their `.ts` source, so an
   Assistant that follows an import into `node_modules` reads the same text the site shows. The Authoring surface is
   exactly what `@jr2/orchestrator` exports from its root: what the kit's packages share is internal even where it can be
   imported, and `@jr2/machines` is not part of it, because it ships Machines, not names to author with.
+  `@jr2/orchestrator/hooks` is not part of it either, because a Hook kind is a module of its own interface, which a kind
+  from another package imports too
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Its page leaves out
+  `hook-kinds/door.ts`, which only the Orchestrator reads.
 
 - **`docs:build` assembles the bundle at pack time.** Its inputs are the hand-written pages in `docs/site/`, the
   generated Reference, `GLOSSARY.md`, and `docs/adr/`. It runs in `@jr2/orchestrator`'s `prepack` and before the site

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

@@ -106,8 +106,8 @@ send:    { name: "r.md", worktree: "/work/app/fix" } // http with a file body
 
 ### 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.
+- **Every Effect outcome is open.** `worktree()`, `push`, `command`, `http` and `mcp` 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.
 
@@ -151,7 +151,8 @@ a pod, jr2 drops this lock and adds a `@model` claim that an Agent runs the fetc
   (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.
+- **`jr2 status <run>` shows each path and branch.** `jr2 workspace ls` shows only Sandboxes, because it reads cluster
+  labels.
 
 ## Example
 

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

@@ -18,8 +18,8 @@ code from `/work`.
 
 - **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.
+  (its hooks, its filters, fsmonitor, textconv and each repository-local config), `command` Effects and stdio MCP
+  servers. 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)).
@@ -33,7 +33,10 @@ code from `/work`.
     ([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.
+  - each `command` Effect that is placed in the Harness, which is each `command` that names no secret;
+  - each stdio MCP server of an Agent
+    ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)),
+    which the Harness starts through the spawner, never with its MCP client's own spawn.
 
   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
@@ -54,17 +57,33 @@ code from `/work`.
   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.
+- **A person's shell is a process of the domain.** `jr2 workspace shell`
+  ([ADR-0009](0009-cli-and-instance-interface.md)) is `kubectl exec -c harness` of a small client in `/opt/jr2`, which
+  starts as the Harness starts (`effector nocore --harness-env`). The client starts nothing itself. It asks the Harness,
+  on a Unix socket in `/run/jr2/shell`, for the shell or for the one command after `--`, and the Harness asks the
+  spawner. So the shell is in the one domain, with the domain's env (the Stand-ins that the Workspace grants), its umask
+  and git identity, and the Workspace's cwd. It sees, signals and traces the Agents' processes, as a later `bash` call
+  does: a person can stop a dev server that an Agent left. With a terminal, the spawner opens a pseudo-terminal for the
+  shell, as its controlling terminal in a session of its own. The client sends the keys, the terminal's size and the
+  hang-up, and the spawner closes the terminal when the shell exits. The output has flow control: while the socket to
+  the client is full, the Harness pauses the spawn, and the spawner reads none of its output until the resume. So the
+  terminal fills and the shell's writes block, as on a slow terminal, and a fast shell does not fill the memory of the
+  Harness that serves the Agents' Turns. `/run/jr2/shell` is an emptyDir of the Harness container alone, and the domain
+  can make no file under `/run/jr2`, so no process of the domain listens in the Harness's place. A process of the domain
+  can connect to the socket, because Landlock does not control a connect. So the client proves that it is not one: its
+  first frame carries a digest of the control Stand-in, which it reads from the file and which the domain cannot read.
+  The Stand-in itself never goes on the socket. Without the proof, the Harness starts nothing.
 - **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.
+    the folder of the shell's 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
@@ -167,8 +186,9 @@ code from `/work`.
   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.
+    agent routes (`/agents/<iid>/surface`, `/agents/<iid>/events`, `/agents/<iid>/deliveries/<id>`, the route on which
+    the Harness acknowledges a notice, and `/agents/<iid>/conversation`, on which it sends the entries of the
+    conversation, [ADR-0023](0023-the-harness-prints-the-conversation.md)), 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
@@ -206,6 +226,13 @@ code from `/work`.
 
 ## Considered options
 
+- **A raw `kubectl exec -c harness` shell (the old `jr2 ssh`).** Rejected: it runs outside the Landlock domain and can
+  read `/run/jr2`, so a person's shell, and any code that the person runs in it, reaches the control Stand-in.
+  `jr2 workspace shell` is a process of the spawner's domain ([ADR-0009](0009-cli-and-instance-interface.md)).
+- **A person's shell in a sibling domain with the same rules**, which the client makes again with the confiner, so the
+  spawner needs no pseudo-terminal and the Harness needs no socket. Rejected: the shell reaches what an Agent's `bash`
+  reaches and nothing more, but it is not in the Agents' domain. It cannot trace their processes, and at ABI 6 or later
+  it cannot signal them, so a person cannot stop a runaway dev server, which is a usual reason to open a shell.
 - **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