@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md

@@ -9,6 +9,15 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
 
 ## Decision
 
+- **What an Effector is for.** It holds the secrets that the Orchestrator must not hold, and it makes every call that
+  jr2 makes to the outside for a Machine or a Hook: every `http` and `mcp` Effect runs in an Effector
+  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)), and the
+  Orchestrator's one call out of the Instance is the fetch of a JWT issuer's public keys (and of its discovery document,
+  which names where the keys are), which spends no secret
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). It serves two clients: a
+  Machine's Effects, in both placements, and the Orchestrator's Hook door, in the Instance Effector only, which uses two
+  operations: the `mac` check and one `http` call (below). It knows no Hook kind and no service. The reason above holds
+  for both clients, and a Hook's secret adds one: it can forge a delivery that answers a Gate.
 - **One static Go binary, `effector`.** A top-level Go module, `effector/`, beside `operator/`: the same toolchain and
   lint, `make test` and `make lint`, the standard library only. Go because the Effector is the trust boundary, and the
   safe file opener (`os.Root`, `openat2`) is Go's. It is configured by its env, which names where its own mount holds
@@ -48,21 +57,46 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   (`the remote could not be reached: ssh: …`), with both in the detail: git's own words for an ssh failure name no
   cause.
 
-- **Two placements, one binary.** The Instance Effector runs `http` with no Worktree file, and `dispatch` toward another
-  Orchestrator ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), the other Orchestrator's Instance
-  token being an Effect secret it holds. A Sandbox Effector — the binary with `JR2_EFFECTOR_WORK` set, a read-only view
-  of the Agent's `/work` — runs an `http` whose body is a Worktree file, `push` and a credentialed `command` (ADR-0067);
-  the Instance Effector refuses the last two, and a file body, as a defect, and a Sandbox Effector refuses a `dispatch`.
-  Its env names where its mount holds the rest: `JR2_EFFECTOR_REPOS` (the node's Repo caches, read-only),
-  `JR2_EFFECTOR_GIT` (the push credentials: one directory per `git.credentials` entry the Sandbox's pushes spend, the
-  entry's own Secret as the operator projects it — `entry.json`, what the entry is; `identity` and `known_hosts` for an
-  ssh key; `password` for a token; `sign.identity` or `sign.private.asc` for the signing key; see the Sandbox Effector's
-  objects below), `JR2_EFFECTOR_SCRATCH` (its own writable scratch). What jr2 guarantees is stated per kind: for `push`
-  and a file body, git never takes config or hooks from the Agent's repository and no program the Agent's files name
-  runs — the clean-repository procedure of ADR-0067 and the opener below. jr2's own programs (`git`, `ssh`,
-  `ssh-keygen`, `gpg`, `gpg-agent`) run by an absolute path found in one fixed PATH, `/usr/local/bin:/usr/bin:/bin`,
-  never by the PATH the image set: an image that puts a directory of its own first does not choose which `git` runs. For
-  a credentialed `command` the Agent's files are the author's choice to run, and the claims are the next bullet's.
+- **Two placements, one binary.** The Instance Effector runs `http` with no Worktree file, `mcp`
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)), and
+  `dispatch` toward another Orchestrator ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), the other
+  Orchestrator's Caller token being an Effect secret it holds. It also serves the Hook door (below). A Sandbox Effector
+  — the binary with `JR2_EFFECTOR_WORK` set, a read-only view of the Agent's `/work` — runs an `http` whose body is a
+  Worktree file, `push` and a credentialed `command` (ADR-0067); the Instance Effector refuses the last two, and a file
+  body, as a defect, and a Sandbox Effector refuses a `dispatch` and an `mcp` Effect. Under Repo Slots each of the three
+  needs a cut's settled row in the run's ledger, because a path alone does not name the target of a credential: the
+  Orchestrator reads the row before it starts the Effect, and with no row it sends nothing and settles the kind's own
+  outcome ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)). Its env names where its mount
+  holds the rest: `JR2_EFFECTOR_REPOS` (the node's Repo caches, read-only), `JR2_EFFECTOR_GIT` (the push credentials:
+  one directory per `git.credentials` entry the Sandbox's pushes spend, the entry's own Secret as the operator projects
+  it — `entry.json`, what the entry is; `identity` and `known_hosts` for an ssh key; `password` for a token;
+  `sign.identity` or `sign.private.asc` for the signing key; see the Sandbox Effector's objects below),
+  `JR2_EFFECTOR_SCRATCH` (its own writable scratch). What jr2 guarantees is stated per kind: for `push` and a file body,
+  git never takes config or hooks from the Agent's repository and no program the Agent's files name runs — the
+  clean-repository procedure of ADR-0067 and the opener below. jr2's own programs (`git`, `ssh`, `ssh-keygen`, `gpg`,
+  `gpg-agent`) run by an absolute path found in one fixed PATH, `/usr/local/bin:/usr/bin:/bin`, never by the PATH the
+  image set: an image that puts a directory of its own first does not choose which `git` runs. For a credentialed
+  `command` the Agent's files are the author's choice to run, and the claims are the next bullet's.
+- **The Instance Effector serves the Hook door with two operations, and the Orchestrator never holds a Hook's secret.**
+  A Hook with a `mac` verifier
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)) names its secret as an
+  Effect names one, and the secret is placed in the Instance Effector alone.
+  - **The `mac` check.** The Orchestrator sends, on the signed wire (below), the bytes to check, the signature, the
+    secret's name and the algorithm. The Hook's kind gives the bytes, and the door makes every check that needs no
+    secret itself, so the Effector reads no header and no timestamp. The Effector computes an HMAC over the bytes with
+    that secret, compares it with the signature in constant time, and answers only "match" or "no match". It returns no
+    secret and no digest of one.
+  - **One `http` call**: a Hook kind's follow-up, such as the reply to a Slack click, which the door posts to the
+    click's `response_url` ([ADR-0011](0011-workflow-defined-events.md)). It is the `http` kind on the same wire, with
+    no secret, to a host that the Hook's kind declares, which `jr2 up` writes into `effector.json` for each Hook of that
+    kind, and it is sent once. It has no slot, no ledger row and no run.
+
+  `jr2 up` converges the Instance Effector when a Hook has a `mac` verifier or its kind declares a follow-up host, as it
+  does when an Effect is placed there. The `token` and `ed25519` verifiers run in the Orchestrator: a digest and a
+  public key cannot sign anything, so they need no Effector, but a follow-up of their kind goes through it. The check is
+  `POST /mac`, beside the Effects' routes and never an Effect: it has no id, starts nothing and is answered at once, and
+  a secret the Effector does not hold is a defect (400), as an Effect's is. A Sandbox Effector does not serve the route.
+
 - **A credentialed `command`'s child is confined with Landlock.** The child runs as the Effector's own uid in the
   Effector's container, where the placement key, every placed secret and the push and signing keys are files that uid
   can read, and its program is often the Agent's code (`npm run deploy`, `make`, `./scripts/release.sh`, a tool's
@@ -74,28 +108,34 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   The thread is locked from the probe to the `execve`, so the domain is the one `execve` keeps. Landlock is an
   allow-list the kernel enforces and every descendant inherits, and a confined process cannot ptrace a process outside
   its domain, so `/proc/<effector>/mem` and `/proc/<effector>/environ` are closed too. The ruleset handles every
-  filesystem right of ABI 1, and `REFER` and `TRUNCATE` when the kernel offers ABI 2 and 3. It allows: read and execute
-  on the image's system paths — every top-level directory the image holds that is not a denied name, whole, so the rules
-  follow the image and break on no layout (the usual `/usr`, `/bin`, `/etc`, `/opt`, and a tool tree of the image's own
-  such as `/google-cloud-sdk` or `/nix` alike; a link such as `/lib -> usr/lib` is followed when what it names holds
-  none of the Effector's own paths); read and write on the devices (`/dev/null`, `/dev/zero`, `/dev/full`,
-  `/dev/random`, `/dev/urandom`, `/dev/tty`) and the Effect's own scratch, one per Effect (the checkout, `$HOME` and
-  `$TMPDIR`); read on each secret file the command names, by `secret("x")` and `.path` alike. The denied names — the
-  kernel and process pseudo-filesystems (`/proc`, `/sys`, the rest of `/dev`), the runtime tree where jr2 mounts the
-  Effector's own files (`/run`, the key and config under `/run/jr2/effector`), and the volatile and per-user trees that
-  hold no tool an image ships (`/home`, `/root`, `/var`, `/srv`, `/mnt`, `/media`, `/lost+found`) — are denied, and so
-  is every path named in the Effector's own deny list: the secrets the command does not name, the push credentials
-  (`@git`), the Worktree (`/work`), the node caches (`/repos`), the rest of its scratch (another Effect's, and a push's
-  copied keys). Every jr2 mount in the Effector's container that holds a secret or the Agent's files is under a denied
-  name (`/run`: the key, the config, the secrets, `@git`) or in that deny list (`/work`, `/repos`, the scratch). The two
-  others hold only public data and the child may read them: the runtime volume at `/opt/jr2`, which holds the programs
-  jr2 ships, and the instance's caBundle ConfigMap at `/etc/jr2/effector-ca` (ADR-0020). So a jr2 mount that holds a
-  secret goes under `/run/jr2`; one under `/etc`, `/opt` or a new top-level name is readable by the child. A top-level
-  directory that holds one of the Effector's own paths is allowed one level down at a time around it, so a mount placed
-  inside one stays denied. Network is not restricted. Any failure before `execve` ends the confiner with exit 126 and
-  its reason on stderr: nothing runs unconfined. The design needs ABI 1; measured from a hardened non-root pod (every
+  filesystem right of ABI 1, `REFER` (ABI 2) and `TRUNCATE` (ABI 3). At ABI 6 it also sets the scopes of abstract Unix
+  sockets and of signals: the child cannot connect to an abstract socket that a process outside its domain made, or
+  signal such a process. It allows: read and execute on the image's system paths — every top-level directory the image
+  holds that is not a denied name, whole, so the rules follow the image and break on no layout (the usual `/usr`,
+  `/bin`, `/etc`, `/opt`, and a tool tree of the image's own such as `/google-cloud-sdk` or `/nix` alike; a link such as
+  `/lib -> usr/lib` gets no rule, and works through the rule on what it names, because the kernel checks the path that a
+  link resolves to; the confiner opens each rule's path with no link on it, and refuses to start when one is there);
+  read and write on the devices (`/dev/null`, `/dev/zero`, `/dev/full`, `/dev/random`, `/dev/urandom`, `/dev/tty`) and
+  the Effect's own scratch, one per Effect (the checkout, `$HOME` and `$TMPDIR`); read on each secret file the command
+  names, by `secret("x")` and `.path` alike. The denied names — the kernel and process pseudo-filesystems (`/proc`,
+  `/sys`, the rest of `/dev`), the runtime tree where jr2 mounts the Effector's own files (`/run`, the key and config
+  under `/run/jr2/effector`), and the volatile and per-user trees that hold no tool an image ships (`/home`, `/root`,
+  `/var`, `/srv`, `/mnt`, `/media`, `/lost+found`) — are denied, and so is every path named in the Effector's own deny
+  list: the secrets the command does not name, the push credentials (`@git`), the Worktree (`/work`), the node caches
+  (`/repos`), the rest of its scratch (another Effect's, and a push's copied keys). Every jr2 mount in the Effector's
+  container that holds a secret or the Agent's files is under a denied name (`/run`: the key, the config, the secrets,
+  `@git`) or in that deny list (`/work`, `/repos`, the scratch). The two others hold only public data and the child may
+  read them: the runtime volume at `/opt/jr2`, which holds the programs jr2 ships, and the instance's caBundle ConfigMap
+  at `/etc/jr2/effector-ca` (ADR-0020). So a jr2 mount that holds a secret goes under `/run/jr2`; one under `/etc`,
+  `/opt` or a new top-level name is readable by the child. A top-level directory that holds one of the Effector's own
+  paths is allowed one level down at a time around it, so a mount placed inside one stays denied. Network is not
+  restricted. Any failure before `execve` ends the confiner with exit 126 and its reason on stderr: nothing runs
+  unconfined. The design needs ABI 3, the minimum of jr2 (ADR-0077); measured from a hardened non-root pod (every
   capability dropped, `RuntimeDefault` seccomp): kind on WSL2 6.6 — ABI 3; the home cluster's arm64 nodes (6.8) — ABI 4;
-  spark (6.11, arm64) — ABI 5.
+  spark (6.11, arm64) — ABI 5. Landlock is a requirement of jr2
+  ([ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)). The confiner is shared: the Harness runs each
+  process it starts in `/work` through the same program, with its own rules
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
 - **One child cannot reach another.** Three rules, in the Effector:
   1. **The subreaper.** The Effector sets `PR_SET_CHILD_SUBREAPER` when it starts, so a descendant whose parent ends is
      reparented to the Effector, never to the container's init. Every child an Effect starts runs in its own session and
@@ -137,16 +177,16 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   3. **A private TMPDIR.** Each credentialed child gets `TMPDIR` set to a directory of its Effect's own scratch, which
      goes when the outcome is read, and `/tmp` is not in the ruleset: a child neither reads nor writes it, so what one
      child writes no other child reads.
-- **Fail-closed at the pod, not at `jr2 up`.** A Sandbox Effector probes Landlock when it starts
-  (`landlock_create_ruleset` with `LANDLOCK_CREATE_RULESET_VERSION`). When its Workspace holds a credentialed command
-  (`effector.json`'s `commands`, which `jr2 up` writes) and the probe fails, it does not become ready: it ends, and its
-  termination message — written to `/dev/termination-log`, the container's `FallbackToLogsOnError` the fallback — says
-  `landlock: unavailable on node <node> (<why>)`, with the node from the downward API (`NODE_NAME`). The operator copies
-  the Effector container's restarts and last end onto the Sandbox's status (`status.effector`), and the provision fails
-  on an Effector that ended before the pod was Ready, in those words, before any Turn. A Workspace that holds no
-  credentialed command starts on such a node and refuses a command start (400, with the same reason). No `jr2 up` probe:
-  one probe Job reports one node, which says nothing in a mixed cluster, and in a uniform one the provision says the
-  same one step later; a Node's `kernelVersion` does not say whether `landlock` is in its LSM list.
+- **Fail-closed at `jr2 up` and at the pod.** Landlock is a requirement of jr2 (ADR-0077): `jr2 up` refuses to converge
+  while a Sandbox node lacks it, as the Repo cache agent on that node reports, and a Sandbox Effector probes it when it
+  starts (`landlock_create_ruleset` with `LANDLOCK_CREATE_RULESET_VERSION`), whatever its Workspace holds. The Instance
+  Effector confines nothing and does not probe. When the probe fails, the Sandbox Effector does not become ready: it
+  ends, and its termination message — written to `/dev/termination-log`, the container's `FallbackToLogsOnError` the
+  fallback — says `landlock: unavailable on node <node> (<why>)`, with the node from the downward API (`NODE_NAME`). The
+  operator copies the Sandbox Effector container's restarts and last end onto the Sandbox's status (`status.effector`),
+  and the provision fails on an Effector that ended before the pod was Ready, in those words, before any Turn. The pod's
+  probe is the backstop for a node that joins after the converge. A Node's `kernelVersion` does not say whether
+  `landlock` is in its LSM list, so only a probe on the node can tell.
 - **The wire.** `POST /effects/<id>` starts an Effect and answers at once (202, `state: running`). A second `POST` with
   the same id starts nothing and attaches (200). The answer to a `push` start names the commit it runs against
   (`pinned`), read before the answer, so the Orchestrator writes it to the ledger's intent row. `GET /effects/<id>`
@@ -194,8 +234,9 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   `effector/internal/wire` and zod schemas in `@jr2/orchestrator`, the one definition each TypeScript type is inferred
   from. Go decodes with unknown fields disallowed. The golden fixtures in `effector/testdata/wire/` keep the two equal:
   one JSON file per request shape (`request.*`), per answer and outcome (`response.*`), per shape its decoder must
-  refuse (`reject.*`), and the two signatures (`signature.*`). Go decodes each request and encodes each response; the
-  TypeScript tests read the same files by a relative path, encode the requests and decode the responses.
+  refuse (`reject.*`), the two signatures (`signature.*`), and the `mac` check's request, answers and refusals
+  (`mac.*`). Go decodes each request and encodes each response; the TypeScript tests read the same files by a relative
+  path, encode the requests and decode the responses.
 - **Signed requests and signed answers, and no bearer.** The key is the placement's,
   `HMAC(signing key, "effector:" + placement)`, as ADR-0058 derives the Harness bearer: the Orchestrator stores nothing.
   The Effector reads it from a file in its own mount. A request carries `X-Jr2-Time` (Unix milliseconds), `X-Jr2-Nonce`,
@@ -273,9 +314,9 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
     `truncated` past it. A body that is not text is never returned: its size and type are.
   - `unreachable`: nothing was sent — the name did not resolve, the connection or TLS failed.
   - `refused`: the Effector refused it and sent nothing — a path segment that is `.`, `..` or empty (an Agent's param
-    can cause it, so it is output, not a fault), or a host and secrets that no Effect placed there names. The
-    Orchestrator settles an `http` start longer than 4 MiB `refused` the same way, before it sends anything; `refused`
-    is an `http` outcome only.
+    can cause it, so it is output, not a fault), or a host and secrets that no Effect or Hook placed there names. The
+    Orchestrator settles an `http` start longer than 4 MiB `refused` the same way, before it sends anything, and a file
+    body with no cut's row (ADR-0075); a `push` and a `command` have no `refused`.
   - `unknown`: the connection was made and no answer came (the timeout, a reset): the host may have acted.
 
   Each outcome other than `response` carries a `reason` in words. A pick that runs an `http` Effect is answered, by
@@ -284,28 +325,45 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   ``Its answer: the output of `<slot>`: <the output's JSON>.``, already scrubbed. An `answer` action shapes it instead
   ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)).
 
+- **The `mcp` kind.** The Effector holds a small MCP client of its own: Go, the standard library only, Streamable HTTP,
+  protocol `2025-11-25`
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). Each
+  Effect is one session: the handshake, one request (`tools/call`, `resources/read` or `prompts/get`), and a DELETE of
+  the session, so a replica keeps no session between Effects and the replica rules of `http` hold unchanged. The start
+  names the server and nothing else of it: the server's url, the name of its secret and its `timeout` are in
+  `effector.json`, which `jr2 up` writes from the `mcp` block, and the secret goes as `Authorization: Bearer <value>`.
+  The client declares no capability, so a server that asks for input gets none: the Effect settles `input-required`. An
+  answer is read as JSON, or as an event stream until the message that answers the request. A result's `text` and its
+  `structured` are each bounded to the start's `maxBody`, 64 KiB by default as for an `http` body; past it the Effector
+  cuts the text (a `structured` past the bound is dropped, not cut into JSON that does not parse) and sets `truncated`.
+  Every string of the output is scrubbed, as an `http` body is. A redirect is not followed. The outcomes and their
+  meaning are ADR-0067's.
 - **The host is fixed, in the Effector.** The Effector's config (`effector.json`, written by `jr2 up` from the Effects'
   plain data) lists each scheme, host and port an Effect placed there names, with the secrets that Effect names — the
-  host its definition fixes, or for a url the package left Open, the one the composer's `customize()` bound
+  host its definition fixes, the host of an `mcp` Effect's server url in `jr2.config.ts`, or for a url the package left
+  Open, the one the composer's `customize()` bound
   ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)); `jr2 up` refuses a Machine
-  whose Open url nothing bound, so no fence entry is ever a guess. A request to another target, or with another secret,
-  is `refused`. A redirect is the response and is never followed: it would send the request, and its `Authorization`, to
-  a host the definition did not fix. No proxy is read from the environment. The trust is the system roots and the
-  instance's `caBundle` ([ADR-0020](0020-private-ca-trust-is-a-named-concept.md)).
+  whose Open url nothing bound, so no fence entry is ever a guess. Each Hook adds the hosts that its kind declares for a
+  follow-up (the `slack` kind: `https://hooks.slack.com`), with no secret (above). A request to another target, or with
+  another secret, is `refused`. A redirect is the response and is never followed: it would send the request, and its
+  `Authorization`, to a host the definition did not fix. No proxy is read from the environment. The trust is the system
+  roots and the instance's `caBundle` ([ADR-0020](0020-private-ca-trust-is-a-named-concept.md)).
 - **One list of secrets; placement is read, never declared, and naming is placement on both sides.** The top-level
   `secrets` list replaces `harness.heldSecrets`; its entry is ADR-0059's
   (`{ name, value | valueFrom.secretKeyRef, hosts?, headers?, paths? }`). A pod gets the secrets something in it names:
-  a Workspace's pod the Held secrets its `workspace()` lists under `secrets: [...]` and the model keys its Agents'
-  providers read; the Instance Harness the model keys of its `"none"` Agents only; an Effector what its Effects name
-  with `secret("name")` (an `http` Effect: the Instance Effector; an `http` whose body is a Worktree file: the Sandbox
-  Effector of the Workspace whose body invokes it; a credentialed command: that Sandbox Effector), and the name a
-  composer binds to an Effect's `secret(open)` with `customize()` (ADR-0054) is placed the same way, in that Effect's
-  Effector alone, once bound — `jr2 up` refuses an Open secret nothing bound. `hosts`, `headers` and `paths` are a Held
-  secret's binding, never its placement (ADR-0059). One derivation (`secretPlacementsOf`) places both kinds, and the
-  held manifest, the Custodian config and the held values' Secret of each Harness pod come from it. Both is both, and
-  `jr2 up` reports it per pod. An entry nothing names goes nowhere, and `jr2 up` warns:
-  `secrets[i] (<name>) is named by nothing; goes nowhere`. There is no `placement:` key: naming is the placement.
-  `jr2 up` prints one line per secret with its placements, and one per pod with what it holds
+  a Workspace's pod the Held secrets its `workspace()` lists under `secrets: [...]`, the model keys its Agents'
+  providers read and the secrets of the MCP servers its Agents name; the Instance Harness the model keys and the MCP
+  server secrets of its `"none"` Agents only; an Effector what its Effects name with `secret("name")` (an `http` Effect:
+  the Instance Effector; an `mcp` Effect, which names its server's secret through the server: the Instance Effector; an
+  `http` whose body is a Worktree file: the Sandbox Effector of the Workspace whose body invokes it; a credentialed
+  command: that Sandbox Effector), and the name a composer binds to an Effect's `secret(open)` with `customize()`
+  (ADR-0054) is placed the same way, in that Effect's Effector alone, once bound — `jr2 up` refuses an Open secret
+  nothing bound. A Hook with a `mac` verifier places its secret in the Instance Effector the same way. `hosts`,
+  `headers` and `paths` are a Held secret's binding, never its placement (ADR-0059). One derivation
+  (`secretPlacementsOf`) places both kinds, and the held manifest, the Custodian config and the held values' Secret of
+  each Harness pod come from it. Both is both, and `jr2 up` reports it per pod. An entry nothing names goes nowhere, and
+  `jr2 up` warns: `secrets[i] (<name>) is named by nothing; goes nowhere`. There is no `placement:` key: naming is the
+  placement. `jr2 up` prints one line per secret with its placements, and one per pod with what it holds
   (`Workspace of workflow "coding": Custodian holds ANTHROPIC_API_KEY (provider), JIRA_TOKEN`,
   `the Instance Effector: holds jira`,
   `Workspace of workflow "coding": Sandbox Effector (image the Sandbox Image) holds aws; pushes Repo Slot "app" with git.credentials "*"`
@@ -320,9 +378,10 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   short value, for a Secret edited after the converge. A secret reaches only the pods where something names it: a
   literal is written into the placement's own Secret, and a `valueFrom` is projected from the user's Secret by
   reference, never copied. `git.credentials` stays its own list: a fence keyed by url prefix, not a named value.
-- **The Instance Effector's objects.** `jr2 up` converges them when a registered Machine places an Effect there, and
-  deletes them otherwise; it reports either (`instance effector: converging (<workflow>/<slot>; secrets …; grace …)` or
-  `instance effector: none`). All four are named `jr2-instance-effector`:
+- **The Instance Effector's objects.** `jr2 up` converges them when a registered Machine places an Effect there or a
+  Hook has a `mac` verifier or a kind that declares a follow-up host, and deletes them otherwise; it reports either
+  (`instance effector: converging (<workflow>/<slot> or hook <name>; secrets …; grace …)` or `instance effector: none`).
+  All four are named `jr2-instance-effector`:
   - A **Deployment**, one replica, rolling with surge and no gap, so a rollout runs the old pod beside the new one: the
     `jr2-harness` image, command `/opt/jr2/bin/effector`, non-root, no privilege escalation, every capability dropped, a
     read-only root filesystem, an emptyDir scratch as `$HOME`, no ServiceAccount token, the control tier's PriorityClass
@@ -337,12 +396,13 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   - A **NetworkPolicy** of `jr2-sandbox-ingress`'s form ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)):
     ingress from this Instance's Orchestrator only. Egress stays open: the pod calls the hosts its Effects name, and
     holds no Custodian.
-  - The **Secret**: each literal Effect secret placed there, `effector.json` (the targets), and the placement's key,
-    `effectorKey(signing key, "instance")`, which `jr2 up` derives from the kept signing key. "Nothing stored" means
-    nothing stored by the Orchestrator: the Kubernetes Secret is the store, as for every credential. The secrets are
-    files under `/run/jr2/secrets`, mode 0400; the kubelet makes them readable by the pod's `fsGroup`, and the pod has
-    one container. `harness.env` and `harness.envFrom` may not name this Secret, nor a Workspace's `jr2-effector-<pod>`,
-    a Sandbox's `<sandbox>-effector`, or a `git.credentials` entry's `jr2-git-*` (ADR-0059's R13).
+  - The **Secret**: each literal Effect secret placed there, `effector.json` (the targets, and the MCP servers that its
+    `mcp` Effects name), and the placement's key, `effectorKey(signing key, "instance")`, which `jr2 up` derives from
+    the kept signing key. "Nothing stored" means nothing stored by the Orchestrator: the Kubernetes Secret is the store,
+    as for every credential. The secrets are files under `/run/jr2/secrets`, mode 0400; the kubelet makes them readable
+    by the pod's `fsGroup`, and the pod has one container. `harness.env` and `harness.envFrom` may not name this Secret,
+    nor a Workspace's `jr2-effector-<pod>`, a Sandbox's `<sandbox>-effector`, or a `git.credentials` entry's `jr2-git-*`
+    (ADR-0059's R13).
 - **A Workspace's Sandbox Effector's objects** (ADR-0059). `jr2 up` reads, for each `workspace()`, the Effects placed
   there below it, down to the next `workspace()` — every `push`, `http` whose body is a Worktree file and credentialed
   `command`, from their plain data, statically — and writes two objects for a Workspace with one, none for one without.
@@ -393,6 +453,10 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
 - **A StatefulSet for the Instance Effector**, as the Instance Harness is. Rejected: a one-replica StatefulSet deletes
   the old pod before it creates the new one, so a rollout would cut an Effect in flight; the Effector keeps nothing a
   stable name or volume would hold.
+- **Check a Hook's `mac` in the Orchestrator.** Rejected: the Orchestrator runs every Machine's code, and an HMAC secret
+  in its process can sign a forged delivery. The check costs one call on the signed wire for each delivery.
+- **A verifier container of its own** for the Hook door. Rejected: it would be the same binary, with the same secret
+  mount and the same signed wire, so a second pod adds a Deployment, a key and a NetworkPolicy and closes nothing.
 - **A `placement:` key on a secret.** Rejected: naming a secret in an Effect is what places it, and a key would be a
   second statement that can disagree with the first.
 
@@ -402,36 +466,37 @@ only asks. Its Role reads no Secret either: it may create and patch one, never g
   echo, a side channel. The claim is that an Effector does not return a secret it holds, in the forms it sent or in
   common encodings.
 - **What a credentialed command's child can still do.** It reads the secret the command names — the author put it there,
-  and a file the Agent wrote that the argv runs reads it too — and egress is open, so the claim is the three of
-  ADR-0067: the Agent never reads or spends the secret from its own container, the tool sees a pinned commit and not the
-  live Worktree, and the output is scrubbed. It shares the Effector's uid, so it can signal the Effector (a fault of its
-  own run, not a leak) and connect to its port, where nothing without the key is accepted. It cannot outlive its Effect
-  (rule 1), share a temporary tree with another child (rule 3), or be alive beside a `gpg-agent` (rule 2).
+  and a file the Agent wrote that the argv runs reads it too — and egress is open but for the cloud metadata addresses
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)), so the claim is the three
+  of ADR-0067: the Agent never reads or spends the secret from its own container, the tool sees a pinned commit and not
+  the live Worktree, and the output is scrubbed. It shares the Effector's uid, so it can signal the Effector (a fault of
+  its own run, not a leak) and connect to its port, where nothing without the key is accepted. It cannot outlive its
+  Effect (rule 1), share a temporary tree with another child (rule 3), or be alive beside a `gpg-agent` (rule 2).
 - **A long GPG push delays a concurrent credentialed command** by its duration, against that command's timeout, and the
   reverse. Rejected: refusing a credentialed command beside a GPG-signing push at `jr2 up` — the hole is open only while
   a GPG push signs, so the rule is that the two never overlap; and a second container per credentialed placement — its
   child would still share a uid with that container's Effector and could spend that container's key, so it would need
   Landlock anyway, plus a key, a Secret, a port and a NetworkPolicy per placement.
-- **A node with no Landlock runs no credentialed command.** Its Sandboxes that hold one fail at provision, naming the
-  node; the fix is a kernel with `landlock` in its LSM list. The home cluster's nodes are arm64, so the Effector binary
-  and the Kit images need `linux/arm64` builds there.
+- **A node with no Landlock runs no Sandbox** (ADR-0077). A Sandbox placed there fails at provision, naming the node;
+  the fix is a kernel with `landlock` in its LSM list. The home cluster's nodes are arm64, so the Effector binary and
+  the Kit images need `linux/arm64` builds there.
 - An `unknown` outcome is the Machine's to route. jr2 sends an `http` call again only when the author marked it
   `idempotent` ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)).
 - The Effector's Go tests run Landlock for real on the host's kernel: a child that reads the key, an unnamed secret or
   `@git`, or writes the Worktree, ends with a permission error and an answer with no secret in it; one that reads its
   named secret from env and from its file succeeds; a child of the child is confined too; a failing probe stops the
-  start of a Workspace that holds a credentialed command, with the node in the reason. And the three rules of "One child
-  cannot reach another" run with real processes: a `setsid` escapee, and an escapee of that escapee, is dead once its
-  command has settled; a live command's daemon, under its keeper, lives through the settle of another Effect beside it;
-  the keeper ends what its child left and answers the child's own end; a command started during a GPG push runs only
-  after the agent is gone, and the reverse, with no sample of that Effector's processes seeing both alive — the
-  command's child matched to its scratch, and the agent known from a witness in place of `gpg-agent` that tells the test
-  before the launcher runs and, after it exits, which processes the agent left, so an agent that lives less than one
-  sample is never missed; a waiter past its timeout settles timed out and never runs late; a child's `TMPDIR` write is
-  invisible to the next child, and `/tmp` refuses both; a signed DELETE ends a credentialed command's group, `exited`
-  with SIGTERM, a program that catches SIGTERM gives its code beside the signal, a child that ignores SIGTERM is killed
-  past the grace (`exited` with SIGKILL), an unsigned DELETE stops nothing, a DELETE on a push or an `http` path answers
-  405, and a command start that arrives after a DELETE of its id runs nothing, while a push or an `http` start does.
+  start of the Effector, with the node in the reason. And the three rules of "One child cannot reach another" run with
+  real processes: a `setsid` escapee, and an escapee of that escapee, is dead once its command has settled; a live
+  command's daemon, under its keeper, lives through the settle of another Effect beside it; the keeper ends what its
+  child left and answers the child's own end; a command started during a GPG push runs only after the agent is gone, and
+  the reverse, with no sample of that Effector's processes seeing both alive — the command's child matched to its
+  scratch, and the agent known from a witness in place of `gpg-agent` that tells the test before the launcher runs and,
+  after it exits, which processes the agent left, so an agent that lives less than one sample is never missed; a waiter
+  past its timeout settles timed out and never runs late; a child's `TMPDIR` write is invisible to the next child, and
+  `/tmp` refuses both; a signed DELETE ends a credentialed command's group, `exited` with SIGTERM, a program that
+  catches SIGTERM gives its code beside the signal, a child that ignores SIGTERM is killed past the grace (`exited` with
+  SIGKILL), an unsigned DELETE stops nothing, a DELETE on a push or an `http` path answers 405, and a command start that
+  arrives after a DELETE of its id runs nothing, while a push or an `http` start does.
 - The `@kind` tier carries the proofs a unit test cannot: an echo server in the seed namespace answers each header and
   the url in every encoding, and the run's snapshot, its feed and the answer the model reads must hold no form of the
   value — the step decodes every base64 and percent-encoded run it reads, so a leak of what the Effector built

package/docs/reference/decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md

@@ -71,15 +71,16 @@ resolve a Workflow's name only to the new Machine. The grill of 2026-10-18 split
   an image cost: cluster write access. The token lives in the Instance's Secret beside the Instance token, `jr2 up`
   reads it through the kube API alone, and no env var and no `--url` path can supply it, so an ingress-exposed Instance
   exposes no publish door. The Instance token keeps its meaning
-  ([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)): start runs, answer Gates, read. `GET /assembly`,
+  ([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)): start runs, answer Gates, read. `GET /assembly`,
   public like `GET /workflows`: the current hash and Kit version, the Assemblies held with the runs that hold them, and,
   when deployed, the digest of each ConfigMap the process reads through a mount (`jr2-images`, `jr2-held`), so a
-  publisher can see what the process reads. `jr2 status` prints it; `/healthz` prints the current hash where it printed
-  the content hash. A repeat publish of the current hash answers `200 { unchanged: true }` before the body is read;
-  `--force` sends the PUT anyway and gets the same answer, because the hash names bytes the Orchestrator already holds.
-  Rejected: an OCI artifact the Orchestrator pulls, which needs the registry that dropping docker removed; a ConfigMap,
-  at 1 MiB; a git ref the Orchestrator clones, when [ADR-0048](0048-the-orchestrator-boots-without-its-repos.md) just
-  took cloning out of the Orchestrator.
+  publisher can see what the process reads, and each standing Workflow's state and count of held items
+  ([ADR-0017](0017-pool-over-a-source-port.md)). `jr2 status` prints it; `/healthz` prints the current hash where it
+  printed the content hash. A repeat publish of the current hash answers `200 { unchanged: true }` before the body is
+  read; `--force` sends the PUT anyway and gets the same answer, because the hash names bytes the Orchestrator already
+  holds. Rejected: an OCI artifact the Orchestrator pulls, which needs the registry that dropping docker removed; a
+  ConfigMap, at 1 MiB; a git ref the Orchestrator clones, when
+  [ADR-0048](0048-the-orchestrator-boots-without-its-repos.md) just took cloning out of the Orchestrator.
 - **The walk runs twice, with different duties.** On the host, `jr2 up` keeps the typecheck
   ([ADR-0050](0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)) and every duty that needs the
   host or the cluster: it loads the Instance folder with the same `loadWorkflows` and `partsOf` the Orchestrator runs,
@@ -121,8 +122,22 @@ resolve a Workflow's name only to the new Machine. The grill of 2026-10-18 split
   Effector manifests, the held-secret Secrets, and the roots of the image sweep. A held run that still needs one the
   current Assembly dropped fails at that provision, naming the held Assembly; so a publish strands no run whose Machine
   it changed, and a publish that drops a Sandbox Image context a parked run has not yet provisioned is the one edit that
-  still can. The Console draws a run on the current Machine; a held run's `assembly` is in its status, and a Console
-  that marks or draws held runs is a later decision. So a publish strands nothing: the "editing a workflow strands its
+  still can. A held run's `assembly` is in its status and in its `GET /runs` summary. The Console marks a run whose
+  Assembly is not the current one, "older Assembly · <hash>", and draws it on the run's own Machine, not on the current
+  Machine, from `GET /workflows/:name/runs/:runId/machine`; so the lit states are always states of the run's own Machine
+  ([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)). For a live run the route reads the Machine from
+  the Assembly that the run holds. An ended run holds no Assembly, so the run's terminal write keeps its Machine, as
+  structure with the Charts that it bound last compiled in, in a table of its own in `state.db`, once for each distinct
+  doc: the key is a digest of the kept doc. The Machine digest of
+  [ADR-0030](0030-a-snapshot-names-the-machine-it-was-written-under.md) is not the key, because it hashes only what a
+  restore needs, and two Machines that differ in a guard, a description or an Effect's command would share one copy. The
+  Console draws every ended run from the route, because the status of an ended run binds no Chart. The run's row holds
+  only the key, so a thousand runs of one Workflow on one Assembly keep one copy, and the terminal write adds a row only
+  for a doc that the table does not have. The route serves that copy for as long as the row is kept
+  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)), and the run sweep deletes a doc
+  that no kept row names. So the collection rule above does not change for history: an ended run needs no Assembly to be
+  drawn. A `drifted` run has no Machine to keep, because its Assembly could not load: the Console shows no graph for it,
+  and shows its drift reason in place of the graph. So a publish strands nothing: the "editing a workflow strands its
   parked runs" consequence of [ADR-0030](0030-a-snapshot-names-the-machine-it-was-written-under.md) is retired, and
   drift is what it always meant, "I can no longer read what I saved": an Assembly that cannot load after a Kit version
   bump, or a volume that lost it. Such a run is `drifted` with a reason naming the Assembly hash and the import error;
@@ -154,6 +169,14 @@ resolve a Workflow's name only to the new Machine. The grill of 2026-10-18 split
   The agent path is data: [ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md).
 - **Semver-compatible Assemblies.** Rejected above; one line to loosen later.
 - **Keep only the current Assembly and report the runs a publish will strand.** Rejected above.
+- **Hold each Assembly that a kept run names, to draw an ended run.** Rejected: an ended run needs only its Machine's
+  structure, not the code of the Assembly, and a hold for each kept row would keep every Assembly for `runs.retain` and
+  grow the volume with each publish. The run's structure is kept instead.
+- **Keep the Machine in each ended run's row.** Rejected: every run of a Workflow on one Assembly would store the same
+  structure again, the space guard never frees rows, and the copy would add work to the synchronous terminal write. One
+  copy for each distinct structure, named by the row, costs neither.
+- **Draw no graph for an ended run whose Assembly is gone.** Rejected: the graph of a failed run is what a person reads
+  first, and the copy in the row is small.
 
 ## Consequences