@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md

@@ -0,0 +1,285 @@
+# A Caller comes from one authenticator seam and acts within its scopes
+
+The Instance token is the operator's credential for everything that acts on an Instance from outside its Machines. The
+CLI reads it from its Secret over the kube API, so kube RBAC is the gate
+([ADR-0019](0019-one-converging-command-against-the-current-context.md)). That serves the person who runs `jr2 up`. It
+does not serve the other Callers of the v1 target user: a CI job that starts runs, a bridge to a chat service that
+answers Gates, a forge that sends deliveries, and a teammate with a browser and no cluster access. Each needs less than
+the Instance token, and with one token each holds all of it. A run must also record who acted on it. So this decision
+gives jr2 a way to know a Caller with no kube credentials, a scope for each act, and a record of each act.
+
+## Decision
+
+- **One seam: an ordered list of authenticators.** Each authenticator takes the credential of a request and gives one of
+  two answers: a **Caller** `{ via, name, may, onBehalfOf? }`, or "not mine". The first authenticator that claims the
+  credential decides. A credential that an authenticator claims and then finds bad is 401; it never falls through to the
+  next one. A credential that no authenticator claims is 401. `via` names the authenticator (`token`, `jwt`, `hook`),
+  `name` is the Caller's name for that authenticator, `may` is its scopes (below), and `onBehalfOf` is the Caller's
+  claim about the party it acts for. The principals inside the Orchestrator stay outside the seam: an Agent's control
+  token, a Sandbox's fetch token and the publish token
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)) are not Callers, and no
+  authenticator makes a Caller from one. So a Sandbox token still reaches no Gate (ADR-0013).
+- **The Instance token is one authenticator.** It gives the Caller `{ via: "token", name: "instance" }`, with every
+  scope for every Workflow. Its meaning does not change: it is the operator's credential.
+- **Named Caller tokens.** The Instance declares them in the `callers` block of `jr2.config.ts`, each with a name and
+  its scopes (`callers.tokens.<name>.may`). A name is a DNS label of at most 40 characters, because it is part of the
+  name of its Secret, and `instance` is the Instance token's name, so the config load refuses it. `jr2 up` makes the
+  value of each one, once, in a Secret of its own, and gives the Orchestrator only the sha-256 of each value, in hex. A
+  value is `jr2c_` and 32 random bytes in base64url. The prefix lets the seam say "not mine" with no lookup, and lets a
+  secret scanner find a value that leaked. The digests go in one Secret, `jr2-caller-digests`, as one JSON object from
+  name to digest, and the Orchestrator reads it through a mount. It reads the file again when it changes, so a new token
+  or a rotation needs no restart. The kubelet updates a mounted Secret on its own period, about a minute. Thus
+  `GET /assembly` reports a digest of the file that the Orchestrator holds now, beside the digests of its mounted
+  ConfigMaps, and `jr2 up` and `jr2 caller rotate` wait until it is the file that they applied: when `jr2 up` says
+  `converged`, a new token works, and when `rotate` returns, the old value no longer works. After 150 s, each stops with
+  exit code 1 and says that the change does not work yet. The scopes come from the config of the current Assembly: a
+  name that has a digest and no entry in the config opens nothing, and a file that does not parse keeps the digests that
+  the Orchestrator read last. `jr2 caller token <name>` prints the value, which it reads from the Secret over the kube
+  API (RBAC is the gate, as for the Instance token), so it takes `-n` and `--context` and never `--url`.
+  `jr2 caller rotate <name>` makes a new value, and the old value stops working. It writes the value's Secret first and
+  the digests after, from every token Secret of the namespace, so a rotate that fails between the two runs again and
+  loses no value. A name that the config no longer declares stops working at the next `jr2 up`, which deletes its
+  Secret. Each token Secret carries its name in the label `jr2.dev/caller-token`, which is how `jr2 up` finds the
+  undeclared ones.
+- **JWTs from an identity provider.** The `callers` block also declares issuers
+  (`callers.issuers: [{ issuer, audience, jwks?, claims?, groups, login? }]`). The JWT authenticator claims a bearer
+  that is a JWT whose `iss` is the `issuer` of an entry; a JWT of another issuer is not its. For each issuer, jr2 checks
+  a JWT's signature against the issuer's published keys, and its issuer, audience and expiry, with 30 seconds for the
+  clocks to differ. It takes only asymmetric signatures, because a published key must not be able to sign. The keys come
+  from `jwks`, or else from the `jwks_uri` of the issuer's `/.well-known/openid-configuration`. The Orchestrator keeps
+  them for 10 minutes, and for a JWT with a key that it does not know it fetches them again at once, at most once in 30
+  seconds, so a key that the issuer rotated works with no restart. When the fetch of the discovery document fails, the
+  Orchestrator keeps the failure for 30 seconds, so many JWTs of that issuer cause at most one fetch in 30 seconds. It
+  keeps keys only for the issuers that the current config names. The Caller's `name` is the `sub` claim and the name
+  that jr2 shows is the `email` claim; `claims` names other claims for each. The scopes come from the values of one
+  claim (a list of groups or roles, `groups` by default), through the map `groups` from a value to scopes; a JWT with
+  more than one value gets the scopes of each, joined. A JWT that gets no scope from the map is 403 on every route that
+  needs a scope. jr2 never treats it as read-only. `GET /whoami` answers it, with no scope, so that a person can see why
+  the other routes refuse it.
+- **Login in the Console's browser.** The Console logs a person in against a JWT issuer with `login: true`, with OIDC
+  (the authorization code flow with PKCE, as a public client whose client id is the issuer's `audience`), and sends the
+  ID token that it gets as the bearer. So login adds no authenticator: it is a way to get a JWT credential. The Console
+  keeps the JWT as it keeps a typed token ([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)). A login
+  that jr2 hosts on the server side, with a session, comes later through the seam.
+- **Five scopes, each one for every Workflow or for named Workflows.** `start` starts a run, `answer` answers a Gate,
+  `cancel` cancels a run, `read` reads a run's state, and `steer` sends a Steering message
+  ([ADR-0002](0002-duplex-streaming-actor.md)). A scope's value is `"all"` or a list of Workflow names. A Chart
+  wrapper's name in the list also opens each named Chart of that wrapper (`plan` opens `plan/weekly`), because a named
+  Chart runs its wrapper's Machine ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)); the name `plan/weekly`
+  opens that Chart alone. For a route that addresses a run, jr2 checks the scope against that run's Workflow. Which
+  scope opens which route is [ADR-0014](0014-observation-is-open-run-state-is-not.md)'s table. A 403 names the scope and
+  the Workflow that the request needed. A Caller with the scope for no Workflow at all is refused before the Workflow is
+  read, and the 403 names the scope.
+- **`answer` can name single Gates.** Its list takes an item `{ workflow, gates: [<name>] }` beside a bare Workflow
+  name, which still means every Gate of that Workflow: `answer: ["triage", { workflow: "deploy", gates: ["approve"] }]`.
+  The same form is a value of the `groups` map, so a team's group answers its own Gate of a Workflow and not the others.
+  A Hook's `may.answer` stays per Workflow: the Gate slot's handlers already say which Gates hear its kind. A Gate's
+  name is its invoke id, its static name in the Machine that invokes it ([ADR-0011](0011-workflow-defined-events.md)).
+  One name covers every Gate of the Workflow with that id, and `jr2 up` refuses a name that the Workflow's Machines do
+  not have, so a typo fails at the door and not at the first answer, and a name that matches Gates in more than one
+  Machine of the Workflow, so one name never opens two Gates without the author's word. An item for a Chart wrapper,
+  `{ workflow: "plan", gates }`, opens those Gates in each named Chart of `plan` too, and `jr2 up` checks its names
+  against the wrapper's Machine and each named Chart of the Assembly; an item for `plan/weekly` opens and checks that
+  Chart alone. A runtime Chart's Gates do not exist at `jr2 up`, so `jr2 up` cannot check them: a name that no Machine
+  and no Chart file of the wrapper has, and an item for a Chart that is no Chart file, are warnings and not refusals,
+  and at run time the item opens the Gates of that name in the runtime Charts too. `GET /gates`, `GET /runs/:id` and the
+  404 of a gate POST list only the Gates that the Caller may answer. A gate POST to an open Gate that the Caller may not
+  answer is a 403 that names the scope, the Workflow and the Gate. The check and the delivery are one step, so a Gate
+  that opens while the request is in flight is checked too. So a 403 and a 404 tell a Caller which Gate is open. That is
+  not a secret: which state a run is in is observation, and the open run projections show it
+  ([ADR-0014](0014-observation-is-open-run-state-is-not.md)). The other four scopes stay per Workflow: each of them acts
+  on a whole run.
+- **The CLI is the Caller `token/instance`.** It reads the Instance token as before, and it sends `onBehalfOf`: the user
+  name that a kube `SelfSubjectReview` gives for the current context. It asks for the name beside the port-forward, and
+  a server that does not answer gives no claim and no failure. A name that is not printable ASCII is not sent, because a
+  header cannot carry it, and a longer name is cut to the bound. A Caller sends `onBehalfOf` in the header
+  `jr2-on-behalf-of`, at most 256 characters. A Hook's `onBehalfOf` comes from its signed payload, and the door ignores
+  the header for a Hook. With `--url` and `JR2_TOKEN`, the CLI sends any Caller's credential, and it is that Caller.
+- **`GET /whoami` and `jr2 whoami` give the request's Caller record**: `via`, `name`, the name that jr2 shows, `may` and
+  `onBehalfOf`. A person uses it to see what a credential may do before it fails.
+- **`cors` is an allowlist of origins in `jr2.config.ts`, empty by default.** The Console is served from the
+  Orchestrator's own origin and needs no entry. A browser app on another origin needs its origin in the list. Each entry
+  is an origin alone (`https://ops.example.com`, no path, no pattern), and the config load refuses any other text. The
+  Orchestrator reads the list of the current Assembly on each request.
+- **The run records the Caller of each act on a guarded route.** A Caller in a record is
+  `{ via, name, shown?, onBehalfOf? }`: never its scopes. The run's record holds `startedBy`, which is
+  `{ kind: "caller", via, name, shown?, onBehalfOf? }`; `{ kind: "run", run, slot }` for a run that a local `dispatch`
+  started (ADR-0071); or `{ kind: "jr2", why }` for a standing run, which has no Caller because jr2 starts it, at
+  `boot`, at a `publish`, at a `hand-over` or at a `resume` ([ADR-0017](0017-pool-over-a-source-port.md)). A resume also
+  records the Caller of the `jr2 run` that resumed the run, as `resumedBy`. A run that a foreign `dispatch` started
+  records the Caller whose credential the other Instance sent. The record also holds `cancelledBy`, and `answers`: the
+  last 100 answers to the run's Gates, each `{ gate, type, at, answeredBy }`. It keeps the last 100 because a standing
+  run's Gate can take an answer for each delivery, and the record is saved on each transition. A gate event's Sender
+  carries the Caller too (`via`, `name`, `onBehalfOf`), and `checked` names which of its fields jr2 checked
+  ([ADR-0011](0011-workflow-defined-events.md)). `jr2 status` walks the `startedBy` chain to the first Caller and prints
+  it, and the Console shows it. The walk reads one run at a time, as the Caller that asks, and names the runs between; a
+  run it may not read, or that is no longer known, ends the walk, and the line says so. It reads at most 16 runs. The
+  record is on the guarded routes only, never on the open observation projection (ADR-0014).
+- **`onBehalfOf` is a claim.** jr2 records it and shows it, and it never checks it. The one exception is a Hook (below):
+  there the signature covers the payload that `onBehalfOf` comes from.
+- **A Caller's scope does not limit what its run dispatches.** A Caller with `start` on `triage` starts a run whose
+  Machine can dispatch `deploy`. The Machine is the author's, and it is the boundary of what its run does, as it is for
+  every Effect. The docs say this where they describe scopes.
+- **A Hook is a Caller with `via: "hook"`.** The `hooks` block of `jr2.config.ts` declares each Hook by its name (the
+  last segment of its address) and its Hook kind, which the config imports. A Hook's name has the form of a Caller
+  token's name. The config load refuses another name, a value that no kind's constructor made, and two kinds with one
+  id. The kind's constructor takes only the credential and the Workflows whose Gates the Hook may answer (`may.answer`,
+  every Workflow by default): `github({ secret: secret("GH_HOOK"), may })`,
+  `slack({ secret: secret("SLACK_SIGNING"), may })`, `discord({ publicKey: "…", may })`. A Hook has the `answer` scope
+  only. A Hook never starts a run. To bring items to a Pool, it needs `answer` on the Pool's Workflow, because it
+  reaches the Pool's `source` Gate ([ADR-0017](0017-pool-over-a-source-port.md)). The Hook's route has its own
+  authenticator, its verifier, which gives `{ via: "hook", name, may: { answer }, onBehalfOf }`.
+- **A Hook kind owns the service's protocol.** The kind gives what the service signed, the handshake, the decoding of
+  the body (Slack sends a form), a zod schema for each event key, the event key, the delivery id, `onBehalfOf` and the
+  envelope of a text that a person reads. The author writes none of them. Each is a fact of the service, the same for
+  every Instance. jr2 ships a kind for each service that has a handshake, an envelope or a scheme of its own:
+  - `github`: the event key is the event name and its action (`pull_request_review.submitted`), the id is
+    `X-GitHub-Delivery`, and `onBehalfOf` is `sender.login`.
+  - `gitlab`: the `token` verifier on `X-Gitlab-Token`. The event key is `object_kind` and the noteable type for a
+    `note`, else the action or the status (`merge_request.approved`, `note.MergeRequest`, `pipeline.success`), the id is
+    `Idempotency-Key` (else `X-Gitlab-Event-UUID`), and `onBehalfOf` is `user.username`.
+  - `slack`: the event keys are `slash_command./jr2` (the command is in the key, so a Source for `/jr2` never hears
+    `/deploy`), `block_actions.<action_id>` and `event_callback.<event type>`. The id is `event_id` for an event and
+    `trigger_id` for a command or a click. `onBehalfOf` is the Slack user id, never a display name. The handshake
+    answers `url_verification` with its `challenge`.
+  - `discord`: the event keys are `application_command.<name>` and `message_component`, the id is the interaction's
+    `id`, and `onBehalfOf` is `member.user.id`, or `user.id` in a direct message. The handshake answers `PING` with
+    `PONG`. Another type of interaction (an autocomplete, a modal) gets the key `interaction.<type>`, which has no
+    schema, so it reaches nothing.
+
+  `onBehalfOf` comes from the verified body, so the signature covers it. The handshake, the parse and the envelope are
+  [ADR-0011](0011-workflow-defined-events.md)'s door.
+
+- **`webhook()` makes a kind from config data, for a service that has no kind.** Its config gives the verifier (`mac`
+  over the raw body, with the header, its prefix and the algorithm; or `token` in a header), the event name, the
+  delivery id and `onBehalfOf` (each by a header or a JSON path), and a zod schema for each event name. It has no
+  handshake, and its answer is the outcome JSON. It makes a kind, not a Hook: the Instance writes it in a module of its
+  own, which the config imports for its Hooks and the Workflows import for their handlers. A service that needs a
+  handshake, a body that is not JSON, a signature over more than the body, a signed timestamp or an answer that a person
+  reads needs a kind module. Sentry, the alert service of the standing Pool
+  ([ADR-0017](0017-pool-over-a-source-port.md)), fits `webhook()` or a kind from another package.
+
+- **A Hook kind is a module of the `@jr2/orchestrator/hooks` interface, from any package or a local file.**
+  `jr2.config.ts` declares it by `import`, and `jr2 up` bundles it into the Assembly
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). jr2 loads no kind at run
+  time and discovers none from a folder. jr2's own kinds (`@jr2/orchestrator/hooks/github` and the others) use the same
+  interface, and nothing more. The interface and the kinds are subpath exports of `@jr2/orchestrator`, so the
+  Orchestrator Kit image holds their one copy, and each kind in an Assembly uses that copy. The door reads a Hook and a
+  kind through a module that the package does not export, because it is not part of a kind's interface. It sits beside
+  the module that makes a Hook, because that module decides the shape of a Hook.
+  - **A kind never gets the credential.** jr2 makes the kind's constructor, so the credential goes from the config to
+    the door and never through code that the kind wrote. For `token`, the door removes the header before any code of the
+    kind runs.
+  - **A kind is pure and synchronous**: no I/O, no Promise, no clock. It is trusted code in the Orchestrator, as is
+    every package that a Workflow imports. Its types refuse a Promise, but they cannot stop I/O. The firm guarantee is
+    that no kind holds a `mac` secret, because the Orchestrator holds none
+    ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)).
+  - **A kind's id is short** (`sentry`): lowercase letters, digits and `-`, and it starts with a letter. One id is one
+    kind in an Assembly. Two kinds with one id fail the typecheck and `jr2 up`. `defineHookKind` refuses an id of
+    another form, an `api` that it does not know, and a `posts` entry that is not an `https://` url that ends in `/`. A
+    kind's constructor refuses a credential of the wrong form: a `publicKey` that is not 64 hex characters, or a
+    `secret` that is not a named secret.
+  - **A follow-up is data.** A kind's answer to a person can give one POST for the door to make after the answer, with
+    its url and its JSON (the reply to a Slack click). The kind declares the hosts of its posts, and `jr2 up` adds them
+    to the Instance Effector's fence (ADR-0068).
+  - **The interface is a public surface of v1.** A kind states `api: 1`, and a kind's package has a peer dependency on
+    `@jr2/orchestrator`. The `api` is the contract, not the package version: the door refuses a kind whose `api` it does
+    not know. Within `api: 1`, a new field of the interface is optional. A change that breaks a kind is `api: 2`.
+
+- **Three verifiers, a closed set, and the Effector knows no Hook kind.** A kind chooses one, and gives the door what to
+  verify: the bytes that the service signed, the signature, and the signed timestamp `at` when the signature covers one.
+  The door runs the verifier:
+  - `mac`: the kind gives the bytes (GitHub: the raw body; Slack: `v0:{timestamp}:{body}`), and the door makes every
+    check that needs no secret, such as the window on `at`. Then the Instance Effector computes an HMAC over those bytes
+    with the named secret and algorithm, compares it with the signature in constant time, and answers only "match" or
+    "no match" ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). A secret that verifies a
+    delivery can also forge one, so the Orchestrator never holds it.
+  - `token`: the service sends a shared token in a header (GitLab). The door, in the Orchestrator, compares its sha-256
+    with the digest that `jr2 up` gave it, and then removes the header. The digests go in one Secret,
+    `jr2-hook-digests`, as one JSON object from the secret's name to its digest. It is not `jr2-caller-digests`, because
+    `jr2 caller rotate` writes that Secret whole. The Orchestrator reads it through a mount, and again when it changes,
+    and `jr2 up` waits for it, as for the Caller digests. `jr2 up` applies it at each converge, empty when no Hook is
+    `token`. It computes each digest on the host, from the entry of the `secrets` list: a literal, or the key of the
+    user's Secret with one trailing newline removed, as the Effector reads a value. The value goes into no object that
+    `jr2 up` writes.
+  - `ed25519`: the door, in the Orchestrator, checks the signature over the timestamp and the body (Discord) against the
+    application's public key. A public key can verify a signature and cannot make one, so it is not a secret, and the
+    config holds it as a literal.
+
+  **One window: 300 seconds, for every signed timestamp.** The door refuses a delivery whose `at` is more than 300
+  seconds from its clock. A kind gives the timestamp and never the window, and no config changes it. Slack asks for 5
+  minutes. Discord states no window, and its signature covers its timestamp, so the same window applies. The window
+  closes a replay after the hook log forgets the delivery, `runs.retain` later
+  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)). A failed check, or a timestamp
+  out of the window, is 401 (Discord sends bad signatures on purpose and expects 401). A new scheme is a change to the
+  set. What a delivery does after the verifier is ADR-0011's: the handshake, the parse, the route, the repeat check, the
+  fan-in and the answer.
+
+- **Tests.** The unit tier checks the JWT authenticator against an in-process issuer made with `jose`: a good token, a
+  wrong issuer or audience, an expired token, a key that rotated, and a token with no scope. The `@console` tier checks
+  the browser login against Dex in a container. Before each release, a person checks one login against a real provider
+  by hand. The default tier checks the `token` and `ed25519` verifiers end to end, with a key pair that the test makes,
+  and the window, the handshakes, the decoding, the parse and the envelopes of each kind. It has no Instance Effector,
+  so a `mac` check runs there only through the injected transport (the bytes the Orchestrator builds, and its window);
+  the Effector's Go tests check the comparison, and the `@kind` tier checks a `mac` Hook end to end through the Instance
+  Effector ([ADR-0011](0011-workflow-defined-events.md)). The build must check what the services' docs do not settle:
+  whether Slack signs `url_verification` (the design verifies it first), whether `trigger_id` is unique for each request
+  (the body's digest catches a repeat anyway), whether Discord sends an interaction again, whether a Discord follow-up
+  needs a bot token (the design does not use one), and Slack's limit on the length of a text. The `slack` kind gives the
+  door a limit of 4000 characters, the length that Slack's docs advise for a message's `text`; no one checked the limit
+  of the answer to a command or of a post to a `response_url`. GitLab's `Idempotency-Key` is from GitLab's docs, and no
+  one checked it against a real delivery.
+
+## Considered options
+
+- **One Instance token for every Caller**, the state before this decision. Rejected: a CI job or a bridge holds every
+  act on every run, and the run cannot say who acted.
+- **Headers from an authenticating proxy** (`X-Forwarded-User` from a proxy in front of the Orchestrator). Not refused:
+  it adds later as an authenticator. Not now, because jr2 can trust the header only when nothing but the proxy reaches
+  the Orchestrator, and the v1 target user has no such proxy.
+- **A kube TokenReview of the bearer.** Not refused: it adds later as an authenticator. Not now, because a Caller with
+  kube credentials already has the CLI, and kube RBAC gives jr2 no scope to map.
+- **A login that jr2 hosts on the server side**, with a session cookie. Not refused: it adds later through the seam. Not
+  now, because it brings a cookie, CSRF and a session store. Browser login with a JWT gives the Console a login without
+  them.
+- **Other ways to read a JWT.** The `email` claim as the Caller's name: rejected, because a provider can change or
+  reassign an email, and `sub` is stable for each issuer. Scopes from several claims, or from an expression over claims:
+  rejected, because the groups or roles claim of a provider is one list. A JWT with no scope as `read`: rejected,
+  because a default grant opens run state to every account of the provider. Opaque tokens with introspection: rejected,
+  because each request then calls the provider, in a way that is different for each provider.
+- **The token's value in the Orchestrator.** Rejected: the Orchestrator keeps only a digest, as it does for a Harness
+  token ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)). A digest that leaks starts nothing.
+- **A Caller's scope as a limit on its run's dispatches.** Rejected: a run's Effects are the author's Machine, not the
+  Caller's. A limit there makes the same Machine do different things for different Callers.
+- **`answer` for whole Workflows only.** Rejected: one Workflow can wait on Gates that different people answer (a team's
+  review, a release manager's approval), and a scope for the whole Workflow lets each of them answer the other's Gate.
+- **A scope for each route.** Rejected: the five scopes are the five acts of a Caller. A finer scope names a route,
+  which can change, and not an act.
+- **`may.start` on a Hook**, so that a Hook can start runs of a Workflow. Rejected: a Hook never starts a run
+  (ADR-0017). The authority to start is the `dispatch` slot in the author's code, as for any dispatch, and the Hook only
+  answers the Pool's Gate.
+- **The protocol in the author's config, for a service that jr2 ships a kind for**: the config says where a delivery
+  holds its id, its event name and `onBehalfOf`, and which header holds the signature. Rejected: each of these is a fact
+  of the service, the same for every Instance, so each author writes the service's protocol again; and a handshake or an
+  envelope is not a field. For a service with no kind, this is `webhook()` (above).
+- **A verifier for each service in the Instance Effector** (a `slack` scheme that knows `v0:`, the header names and the
+  window). Rejected: every new service is then a change to the Go binary that is the trust boundary, and nothing in the
+  bytes to check or in the window is secret. The Effector needs only the one operation that needs the secret: an HMAC
+  over given bytes.
+- **A package of its own for the interface and the kinds** (`@jr2/hooks`). Rejected: the Kit releases every package at
+  one version, so a separate package gives the interface no version line of its own, and `api` already is its contract.
+  A kind's package has a peer dependency on the kit either way, because every Instance that loads a kind has
+  `@jr2/orchestrator`. A separate package only adds a public package to publish, pin and stage at each release.
+
+## Consequences
+
+- ADR-0013's open question, the authentication of a Caller without kube credentials, is closed: a named token, a JWT, or
+  a browser login.
+- [ADR-0014](0014-observation-is-open-run-state-is-not.md)'s guarded band becomes a scope check for each route.
+  [ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)'s Console takes any Caller's credential, and shows
+  only what its scopes allow. ADR-0071's foreign dispatch takes any token with `start` for that Workflow.
+- `@jr2/orchestrator` gains the subpath exports `@jr2/orchestrator/hooks` (the interface of a Hook kind) and
+  `@jr2/orchestrator/hooks/github`, `/gitlab`, `/slack`, `/discord` and `/webhook` (jr2's kinds and `webhook()`).
+- `jr2.config.ts` gains `callers`, `hooks` and `cors`. The CLI gains `jr2 caller token|rotate <name>` and `jr2 whoami`
+  ([ADR-0009](0009-cli-and-instance-interface.md)).
+- GLOSSARY.md: **Caller** names the Steering message and the Hook. **Hook** and **Hook kind** are new terms.

package/docs/reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md

@@ -0,0 +1,198 @@
+# An Agent holds MCP tools, a Machine calls them as an Effect, and the Machine is the approval
+
+An Agent of the v1 target user works with services: it reads a Jira ticket, posts to Slack, opens a GitHub issue. Before
+this decision an Agent had two kinds of tool, its Working tools and its Menu, and no third
+([ADR-0028](0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)). It could reach a service only
+from Workspace code, with `curl` and a Held secret that its `workspace()` grants, or through a Machine's `http` Effect.
+The first gives the Agent the whole credential: Workspace code can spend it on every API that the token opens. The
+second makes the author write each call of the service again as an Effect. The services ship MCP servers, and each agent
+framework that we read speaks MCP. So jr2 takes MCP as the one contract for tools beyond its own.
+
+Each of those frameworks (Claude Code, the OpenAI Agents SDK, LangGraph, Mastra, the Vercel AI SDK) puts an approval in
+the harness: a mode or a callback that stops the loop before a tool call and asks a person. jr2 has an approval already.
+A Machine's Gate stops the run, keeps it across a restart, names who answered
+([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)) and routes on the answer. A
+second approval in the Harness would be a state that the Machine cannot see.
+
+## Decision
+
+- **Two ways to use an MCP server, both in v1.** An Agent holds **MCP tools**: its definition names a server, and the
+  server's tools join the Agent's tools. The Harness is the MCP client, and the server's credential is a Held secret
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). A Machine calls a server as an
+  Effect: the `mcp` Effect runs in the Instance Effector, with an Effect secret and no model
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)).
+- **The Machine is the approval.** An Agent's MCP tool runs when the model calls it, within its allowlist (below). The
+  Harness has no `requireApproval`, no ask mode and no callback. A call that needs approval is the Machine's: the Agent
+  makes a pick, a Gate takes the approval, and an `mcp` Effect makes the call. The Effect's output is the pick's answer
+  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)). So the approval is in
+  the run's record, it survives a restart, and a Caller with the `answer` scope gives it.
+- **MCP is the one extension contract for tools.** jr2 has no tool API of its own. An author's own tool is an MCP
+  server: a remote server that the author deploys, or a stdio server in the Sandbox Image. A guide in the docs shows a
+  small TypeScript server in the Sandbox Image. An Instance `tools/` folder and a server that the Effector hosts are
+  Later.
+- **The config declares each server, by the author's name.** The `mcp` block of `jr2.config.ts` maps a name to a server:
+  `{ url, secret?, timeout? }` for a remote server (Streamable HTTP), or `{ command, args?, timeout? }` for a stdio
+  server. The name is the author's, so one Instance can declare two servers of one service with two secrets
+  (`slack-acme`, `slack-partner`). A name matches `[a-z][a-z0-9-]*`. `jr2` is reserved, because the Menu's tools are
+  `mcp__jr2__<event>` ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)), and the config
+  load refuses it. `secret` names an entry of the top-level `secrets` list. With no `hosts`, that entry is bound to the
+  host of the server's `url`, as a model key is bound to its provider's host. The Harness sends it as
+  `Authorization: Bearer <Stand-in>`, so `jr2 up` refuses explicit `headers` on that entry that leave out
+  `authorization`, explicit `hosts` that leave out the url's host, and explicit `paths` that do not cover the url's
+  path. A server with a `secret` needs an `https://` url, as a model endpoint with a bound key does
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)); a server with no secret can use
+  `http://`, as a keyless model endpoint can. In v1 a credential is a static bearer token, a Held secret or an Effect
+  secret. OAuth grants are the next round. `timeout` is for one call, 60 seconds by default.
+- **An Agent names the servers and the tools that it uses.** `AgentDefinition` gains `mcp?: Array<{ server, tools? }>`.
+  `server` is a name of the config's `mcp` block, and `tools` is the allowlist. The field is plain data, as the
+  definition is ([ADR-0018](0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)). Each entry is an
+  object, so that `resources` can be added beside `tools` later. A packaged Machine's Agent names the server that it
+  needs, and the composer rebinds the list with the existing `customize(machine, { agents: { <slot>: { mcp } } })`
+  ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)). `jr2 up` refuses a server
+  name that the config does not declare. It prints the `customize(machine, { agents: { <slot>: { mcp } } })` line that
+  binds the slot to a declared server, and the `mcp` block entry that declares a new one. A Menu-only Agent can name a
+  remote server only: `jr2 up` refuses a stdio server on a `"none"` Agent (below).
+- **The allowlist is offered only where jr2 can keep it.** It guards the server's credential:
+  - A remote server needs `tools`: a list of tool names, or `"*"`. The list is a guarantee. The Harness offers only
+    those tools and runs only those tools, and no Workspace code can spend the server's secret.
+  - A remote server whose secret Workspace code of the Sandbox where the Agent's Turns run can spend takes only `"*"`,
+    and `jr2 up` refuses a list. That is the case when the `workspace()` of that Sandbox grants the secret, when a
+    credentialed `command` of that Workspace names it, or when an `http` Effect of that Workspace whose body is a
+    Worktree file names it ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). Each lets a
+    file that the Agent wrote call every tool of the server, so a list would be a hint, and jr2 does not give a hint the
+    form of a guarantee. A `"none"` Agent's Turns run on the Instance Harness, where no Workspace code runs, so it keeps
+    its list.
+  - A stdio server has no `tools` field. The Agent gets every tool of the server. The server's version is fixed in the
+    Sandbox Image, and it runs as Workspace code (below), so a list would guard nothing.
+
+  The token's own scopes are the outer limit: the allowlist narrows what the Agent can do with a token, and never widens
+  it. One token under two secret names is the author's own act, and jr2 cannot see it.
+
+- **The tool list is fixed for a conversation.** `jr2 up` checks each allowlisted name against the live server, from the
+  check pod and through its Custodian, as the provider preflight checks a model
+  ([ADR-0019](0019-one-converging-command-against-the-current-context.md)). It refuses a name that the server does not
+  list, and it fails when the server refuses the request (a 401 or a 403: a wrong or expired token), as it fails on a
+  model key that the provider refuses. It only warns when the server does not answer. The Harness reads `tools/list` at
+  the first Turn of a conversation. It keeps the allowed tools, sorted by name, records them with the conversation, and
+  offers the same tools until the conversation ends, across a park and a Harness restart. It never reads the list again
+  for a Turn, because a tools block that changes misses the provider's prompt cache
+  ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). It ignores a
+  `listChanged` notice. A tool that the server took away fails its call with jr2's text. The tools block is the Working
+  tools, then the MCP tools, then the Menu.
+- **Names.** An MCP tool is `mcp__<server>__<tool>`, and the name must match `[A-Za-z0-9_-]{1,128}`, Anthropic's bound.
+  `jr2 up` refuses an allowlisted tool whose name breaks it. A tool that `"*"` reaches and whose name breaks it is not
+  offered, and the Harness writes one log line that names it. A name is in the tools block one time: `jr2 up` refuses an
+  allowlist that names a tool twice, and the Harness keeps the first tool of a name that a server lists twice. A server
+  name has no `_`, so the prefix is never ambiguous.
+- **A server that does not answer at the first Turn fails the Turn.** The Turn fails with a named error,
+  `slack-acme did not answer: <reason>`, before the model reads anything. The Machine gets it as `agent.fault`, with
+  that text as its `reason` ([ADR-0016](0016-agent-turn-mechanics-are-internal.md),
+  [ADR-0074](0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md)). A server that does not answer
+  at a later call fails that call with jr2's text, and the model reads it.
+- **A stdio server is Workspace code.** The Harness starts it through the spawner, inside the Landlock domain
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)), with the domain's env:
+  only the Stand-ins that the `workspace()` grants. Its program comes from the Sandbox Image. A stdio server has no
+  `secret` of its own: the secrets that it can spend are those that its Workspace grants. The Harness never starts a
+  server with pi-mcp's own spawn: that process would be outside the domain, and it would inherit the env of the Harness
+  process, every Stand-in and the path to the control Stand-in with it. The Instance Harness has no domain
+  ([ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)), so a Menu-only Agent gets remote servers only.
+- **Lifetimes.** A stdio server runs one process for each Agent conversation, from its first Turn to the end of the
+  conversation or of the Harness. Two Agents never share a process. When the process stops, the call fails with jr2's
+  text, and the next call starts a new process. A remote server has one connection for each Harness, which every
+  conversation of that pod uses.
+- **What an Agent gets: tools, and the text and images of each result.** The model reads a result's text content and its
+  images. The engine replaces an image with a line of text for a model that reads no image, and an image larger than
+  about 5 MiB is one line of jr2's text. A result with `structuredContent` and no text gives the model the JSON as text.
+  Other content (audio, a resource) is replaced by one line of jr2's text that names its kind. A result with `isError`
+  reaches the model as an error. A result longer than 64 KiB is cut, and the model reads
+  `[jr2 cut this result at 64 KiB]` at the cut. The text of a failure that holds the server's words, such as a JSON-RPC
+  error's message, is cut in the same way. A call past the server's `timeout` is cancelled, and the model reads jr2's
+  text. The Harness gives the server no elicitation capability, and a call that asks for input fails with jr2's text.
+  Not in v1: elicitation, tool search, sampling, roots, and an Agent's resources and prompts (Later).
+- **The `mcp` Effect has the shape of `http`.** `mcp.call(server, tool, { input })`, `mcp.read(server, uri)` and
+  `mcp.prompt(server, name, { input })`. `server` and `tool` can each be Open and bind under
+  `customize(machine, { effects: { <slot>: { server } | { tool } } })`, one object with both keys when both are Open, as
+  `url` and `secret` bind for `http`. The `server` of `mcp.read` and `mcp.prompt` can be Open too; their `uri` and
+  `name` are the author's. `fromPick` gives a pick's params to `input`. The server's secret is its Effect secret, placed
+  in the Instance Effector. `jr2 up` refuses an `mcp` Effect whose server the config's `mcp` block does not declare, or
+  whose server is a stdio server. It prints the `mcp` block entry that declares a remote server, and the
+  `customize(machine, { effects: { <slot>: { server } } })` line for an Open server. An Effect's `timeout` replaces the
+  server's `timeout` for that Effect. Outputs: `returned { isError, text, structured?, truncated? }` for a call
+  (`{ text, structured?, truncated? }` for a read and a prompt), `refused`, `unreachable`, `input-required` and
+  `unknown`. A call's `structuredContent` is `structured`, typed `unknown`; a read's `structured` is its `contents`
+  list, and a prompt's is its `messages` list. An `output:` schema is Later. The Effector bounds `text` and `structured`
+  as it bounds an `http` body, and sets `truncated` when it cuts one. It cuts a JSON-RPC error's message in a reason at
+  1 KiB, with a jr2 marker at the cut. The client speaks the revisions `2025-11-25`, `2025-06-18` and `2025-03-26`; a
+  server that answers `initialize` with another revision is `unreachable`. When a server closes the event stream of the
+  request before its answer, after an event id, the client opens the stream again with a GET and `Last-Event-ID` (within
+  the timeout, and at most five times in a row that bring no new event). It does not send the request again. `refused`
+  means that the request did not run: an HTTP 3xx or 4xx at any step (a 401 or a 403 included), a refused handshake, or
+  one of the JSON-RPC errors `-32700`, `-32600`, `-32601` and `-32602`, or `-32002` (resource not found) for a read,
+  which does not act. Another JSON-RPC error, or a 5xx, after the request was sent is `unknown`, because the tool may
+  have acted. `input-required` is a server that asked for input: the error `-32042` (URL elicitation required), before
+  the tool ran, or an `elicitation/create` request, which the client declared no capability for. That request comes
+  while the tool runs, so the tool may have begun. jr2 does not send the request again. It is a named outcome that the
+  Machine can route. The client reads an event stream whose lines end with CRLF, LF or a lone CR. It scrubs a server's
+  words in a reason before it cuts them, so that no part of a secret stays at the cut. ADR-0067 states each outcome. An
+  `mcp` Effect runs at most once unless the author marks it `idempotent` (ADR-0067). The server's `idempotentHint` is
+  ignored: the server is not the author. In v1 an `mcp` Effect calls a remote server only, from the Instance Effector. A
+  stdio server for an Effect is Later.
+- **Two clients, one protocol.** The Harness uses `@earendil-works/pi-mcp` behind a jr2 interface, with a jr2 stdio
+  transport over the spawner. The interface does not depend on the engine, so another engine keeps the MCP tools. The
+  Effector has a small MCP client of its own in Go, with the standard library only, over Streamable HTTP. Both speak
+  protocol `2025-11-25`, the revision that pi-mcp speaks.
+- **The printed conversation shows an MCP call as `<server>/<tool>`**, with its input bounded as every call's is
+  ([ADR-0023](0023-the-harness-prints-the-conversation.md)). A pick prints by its event's name, as before, so the two
+  never print alike. The result of an MCP call does not print, as the result of a Working tool does not.
+- **The Briefing says that MCP tools are not picks.** An Agent with MCP tools reads one more line in the standing part
+  ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)).
+
+## Considered options
+
+- **An approval mode in the Harness**, as every other framework has: a `requireApproval` on a tool, and a Turn that
+  stops until a person answers. Rejected. The stop would be a state in the Harness that the Machine cannot see, keep or
+  route on. A Gate already does each of these, and the Machine already decides which act needs a person. A Turn that
+  waits on a person also holds a conversation, a Sandbox and its Size for that time.
+- **Servers on the Agent definition** (the shape of 2026-10-27: `mcp: { slack: { url, secret, tools? } }` in `agent()`).
+  Rejected. A url and a secret are facts of the Instance, not of the Agent's definition, so a packaged Machine would
+  ship them. Two Agents of one server would declare it twice, and an Effect could not name the same server.
+- **Read the tool list again on each Turn.** Rejected. A changed tools block misses the provider's prefix cache
+  (ADR-0029), and the history then calls tools that the request no longer defines.
+- **An allowlist that is only a hint**, offered on every server. Rejected. Where Workspace code holds the Stand-in, or a
+  stdio server holds the token, the list stops nothing. A field that reads as a limit and is not one is worse than no
+  field.
+- **A tool API of jr2's own** (a TypeScript function and a schema, run by the Harness). Rejected. It is a second
+  contract beside MCP, its code would run in the Harness process or in the domain with a new seat, and an engine change
+  would carry it again. An MCP server is the same function behind a contract that every engine speaks.
+- **One secret for each host and header**, which `jr2 up` refused before this decision (ADR-0059's R5). Rejected: two
+  servers of one service (two Slack workspaces) send their tokens to one host in one header, and the Menu-only Agents of
+  an Instance share one Custodian. The Custodian already chose the value by the Stand-in in the header, so only the
+  refusal went.
+- **Start a stdio server with pi-mcp's own spawn.** Rejected: the process would be outside the domain, with every
+  Stand-in in its env (ADR-0076).
+- **Protocol `2026-07-28`.** Not now: pi-mcp speaks `2025-11-25`, and the servers that the target user runs speak it.
+
+## Consequences
+
+- `jr2.config.ts` gains the `mcp` block, and `AgentDefinition` gains `mcp`. The Effect kinds gain `mcp` (ADR-0067).
+- A Custodian holds what its pod's Agents name, the Instance Harness's too (ADR-0059): an Agent's MCP server secret is
+  held in the pod where its Turns run. The Custodian chooses a secret by the Stand-in that a request carries, so two
+  secrets can share one host and one header.
+- An Agent's MCP tools reach the model, so the `@model` tier gains the claim `mcp-then-pick` (ADR-0066).
+- A stdio server shares the domain with the other Workspace code of its Sandbox. Other Agents' code can trace it and
+  write to its stdin. It holds no control credential, but its results are as trusted as the output of `bash`, and no
+  more.
+- An `elicitation/create` request does not name the call that sent it. When it comes on a connection with one call in
+  flight, that call fails with jr2's text. When more calls are in flight, which a remote server's one connection for
+  each Harness makes possible, jr2 cannot tell which call asked: no call is marked, and each fails with the server's own
+  error.
+- A remote server's results come from outside the Instance. They can carry a prompt injection, as a web page can. The
+  allowlist bounds what the Agent can do with the server's token; the Machine bounds what the run does.
+- Tests: the unit tier checks the config and the allowlist rules, and the Harness's client against an in-memory server.
+  The Harness's tests drive a stdio server through the spawner, and check that it holds only the granted Stand-ins. The
+  default e2e tier checks the refusals of `jr2 up` and of the publish door. The `@kind` tier checks the live tool list
+  from the check pod, an Agent's calls to two servers on one host, each through the Custodian with its own value, and an
+  `mcp` Effect from the Instance Effector; the server sees each value and never a Stand-in. The Effector's Go tests
+  check the `mcp` kind against a test server. The Custodian suite checks two secrets on one host in one header.
+- The OAuth round must look again at client registration: the `2026-07-28` spec deprecates dynamic client registration
+  for Client ID Metadata Documents.

package/docs/reference/decisions.md

@@ -21,7 +21,7 @@ Each architecture decision record (ADR) says what jr2 decided, why, and what it
 | 0011 | [Control events are workflow-defined and delivered by closure, not routed](decisions/0011-workflow-defined-events.md) |
 | 0012 | [`workspace()` wraps a body Machine and owns only Sandbox lifecycle](decisions/0012-workspace-wrapper-machine.md) |
 | 0013 | [The Agent reaches its Machine through a container it cannot read](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md) |
-| 0014 | [Observation is open; run state and control need the Instance token](decisions/0014-observation-is-open-run-state-is-not.md) |
+| 0014 | [Observation is open; run state and control need a Caller's scope](decisions/0014-observation-is-open-run-state-is-not.md) |
 | 0015 | [Workflows are authored through `jr2Setup`; vocabulary and agent menus derive from the machine](decisions/0015-authoring-surface-absorbs-the-mechanism.md) |
 | 0016 | [Agent-turn mechanics are jr2-internal: ambient coordinates, host-side offsets, absorbed retries, fresh sessions](decisions/0016-agent-turn-mechanics-are-internal.md) |
 | 0017 | [The run loop is a jr2 `pool` over a generalized source port](decisions/0017-pool-over-a-source-port.md) |
@@ -30,7 +30,7 @@ Each architecture decision record (ADR) says what jr2 decided, why, and what it
 | 0020 | [Private-CA trust is a named concept, not volume plumbing](decisions/0020-private-ca-trust-is-a-named-concept.md) |
 | 0021 | [Workspace continuity is watched; the lease asserts](decisions/0021-workspace-continuity-is-a-lease-that-answers-back.md) |
 | 0022 | [Observation is a level-triggered feed, and an API before it is a page](decisions/0022-observation-is-a-level-triggered-feed.md) |
-| 0023 | [The Harness prints the conversation, and the reasoning is the part that prints](decisions/0023-the-harness-prints-the-conversation.md) |
+| 0023 | [The Harness prints the conversation and the Orchestrator keeps it, and the reasoning is the part that prints](decisions/0023-the-harness-prints-the-conversation.md) |
 | 0024 | [An Agent's turn ends with the state that asked for it](decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) |
 | 0025 | [CANCEL ends a run; stopping one parks it](decisions/0025-cancel-ends-a-run-stop-parks-it.md) |
 | 0026 | [A Turn that is over is never prompted, and only a Turn that is over answers 404](decisions/0026-a-turn-that-is-over-is-never-prompted.md) |
@@ -39,7 +39,7 @@ Each architecture decision record (ADR) says what jr2 decided, why, and what it
 | 0029 | [A Menu is fixed for a conversation, and a Turn is told its Allowed picks](decisions/0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md) |
 | 0030 | [A snapshot names the Machine it was written under](decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md) |
 | 0031 | [Menu-only Agents run on the Instance Harness](decisions/0031-menu-only-agents-run-on-the-instance-harness.md) |
-| 0032 | [The Console unlocks with the Instance token, and the bands do not move](decisions/0032-the-console-unlocks-with-the-instance-token.md) |
+| 0032 | [The Console unlocks with a Caller's credential, and shows what its scopes allow](decisions/0032-the-console-unlocks-with-a-callers-credential.md) |
 | 0033 | [A Machine declares the input that starts it](decisions/0033-a-machine-declares-the-input-that-starts-it.md) |
 | 0034 | [The Console renders with Preact, and the server erases the types](decisions/0034-the-console-renders-with-preact-and-the-server-erases-the-types.md) |
 | 0035 | [A runaway turn is ended by the Harness, rerolled once, then a fault](decisions/0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md) |
@@ -71,7 +71,7 @@ Each architecture decision record (ADR) says what jr2 decided, why, and what it
 | 0062 | [jr2 briefs the Agent on its seat, never on its task](decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md) |
 | 0063 | [The Orchestrator watches the cluster](decisions/0063-the-orchestrator-watches-the-cluster.md) |
 | 0064 | [A Workspace waits for capacity](decisions/0064-a-workspace-waits-for-capacity.md) |
-| 0065 | [A persist survives a crash, and history is a week](decisions/0065-a-persist-survives-a-crash-and-history-is-a-week.md) |
+| 0065 | [A persist survives a crash, and history is kept for a set time](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md) |
 | 0066 | [A `@model` tier runs a real model, and a change to what the model reads runs the tier](decisions/0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md) |
 | 0067 | [An Effect is an actor slot, and runs at most once unless marked idempotent](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md) |
 | 0068 | [An Effector holds an Effect's secrets and signs its wire](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md) |
@@ -81,3 +81,8 @@ Each architecture decision record (ADR) says what jr2 decided, why, and what it
 | 0072 | [The docs ship inside the Kit, and an Instance's `AGENTS.md` indexes them](decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md) |
 | 0073 | [A Machine fails a run with `fail()`, and an uncaught Failure ends it `failed`](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md) |
 | 0074 | [An unrouted mechanism event is refused at load and faults the run](decisions/0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md) |
+| 0075 | [A Machine cuts a Worktree, and the Workspace only clones](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md) |
+| 0076 | [An Agent's control credential lives only where no Workspace code runs](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md) |
+| 0077 | [jr2 requires Landlock on every Sandbox node](decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md) |
+| 0078 | [A Caller comes from one authenticator seam and acts within its scopes](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md) |
+| 0079 | [An Agent holds MCP tools, a Machine calls them as an Effect, and the Machine is the approval](decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md) |