@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md

@@ -31,11 +31,11 @@ because they are one problem: **what a Machine depends on that is not inside it.
     names of the secrets it names — or the `open` sentinel where a package left the url, the argv or a secret's name for
     its composer ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). `jr2 up` reads them
     without running anything, and a secret named there is what places it.
-  - **The Sandbox Image is a `workspace()` option**, static: `workspace(body, { input, image, repos, spec })` (`repos`
-    is ADR-0051's, and follows the same rule). `image` is a string in one of two shapes — a `file:` URL
+  - **The Sandbox Image is a `workspace()` option**, static: `workspace(body, { input, image, repos, workGroup })`
+    (`repos` is ADR-0051's, and follows the same rule). `image` is a string in one of two shapes — a `file:` URL
     (`import.meta.resolve("./image")`, a docker context the module ships) or a registry ref — or absent, which keeps
-    ADR-0037's fallback. It moved out of the per-run spec because `jr2 up` must find it statically. It is never
-    persisted: the provisioning state re-reads it off the Machine on restore.
+    ADR-0037's fallback. It is static because `jr2 up` must find it with no run. It is never persisted: the provisioning
+    state re-reads it off the Machine on restore.
 - **The definition rides the Turn.** The admission body carries the slot's definition; the Harness runs what it was
   handed and re-reads it per Submission as before. The Instance roster (`agents/`, then `config.agents`), its ConfigMap,
   and `JR2_AGENTS_JSON` retire — a flat roster cannot hold two `researcher`s, and a Machine edit already needs `jr2 up`
@@ -47,27 +47,27 @@ because they are one problem: **what a Machine depends on that is not inside it.
   ADR-0011 adopted for Vocabulary.
 - **Customization is `customize(machine, parts)`**, a plain function in the family of `workspace()` and `pool()`,
   returning a plain `StateMachine`. `parts` has the declaration's own shape, recursively partial:
-  `{ agents?: { <slot>?: Partial<AgentDefinition> }, effects?: { <slot>?: { url } | { argv } | { secret } }, image?, user?, repos?: { <slot>?: Binding }, actors?: { <child>?: parts } }`
+  `{ agents?: { <slot>?: Partial<AgentDefinition> }, effects?: { <slot>?: { url } | { argv } | { secret } | { server } | { tool } }, image?, user?, repos?: { <slot>?: Binding }, actors?: { <child>?: parts } }`
   — the two image seats together, since ADR-0005 gives the User Container the same static option, and the Repo Slots
   beside them, since ADR-0051 makes a Repo a `workspace()` slot a composer binds. `effects` binds an Effect's Open url,
-  argv or secret name, once — an Effect with an Open secret and an Open url or argv takes one object with both keys,
-  `{ url, secret }` or `{ argv, secret }`
-  ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)): the slot's logic is built
-  again with the bound part and substituted as an Agent override is. Internally an Agent override is xstate's
-  `machine.provide({ actors: { researcher: agent(merged) } })`, with the override layered over the stock definition; a
-  child override is the same call one level down, recursing — each level is exactly the one-level reach ADR-0015 found
-  `provide` has, held by the composer who owns the child object, never host-side injection. jr2's wrappers are
-  transparent: `customize(research, { agents })` reaches the body through the `body` slot (and `pool()`'s `worker`, at
-  any depth), so a consumer never writes `body`. The images and the Repo bindings are the parts `provide` cannot carry
-  (xstate copies only implementations, and every part is keyed on the config it passes through by reference), so those
-  fields clone the wrapper's config and rebuild it with the same implementations, re-attaching what the original
-  carried. A bound argv's load warnings are such a part too: `customize()` rebuilds the Machine the author wrote the
-  same way, with the vocabulary, the seats and the door it carried and the warnings the walk gives for the bound argv,
-  so no attachment is keyed on anything but the config. Only DECLARED parts can be retuned, and the compiler is what
-  says so: the slots are read off xstate's own `TActor` parameter, so an Agent, a Repo Slot, or a child the Machine does
-  not carry is a type error (ADR-0050), and the runtime refuses the same call naming the Machine's own slots. Rejected:
-  a `.with()` method on the machine — it needs a jr2-owned machine type over xstate's, which ADR-0015 avoided, and it
-  vanishes after any `.provide()`; a callable-machine hybrid — verified to work, reads as a trick.
+  argv, MCP server and tool, or secret name, once — an Effect with an Open secret and an Open url or argv takes one
+  object with both keys, `{ url, secret }` or `{ argv, secret }`, and an `mcp` Effect with an Open server and tool takes
+  `{ server, tool }` ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)): the
+  slot's logic is built again with the bound part and substituted as an Agent override is. Internally an Agent override
+  is xstate's `machine.provide({ actors: { researcher: agent(merged) } })`, with the override layered over the stock
+  definition; a child override is the same call one level down, recursing — each level is exactly the one-level reach
+  ADR-0015 found `provide` has, held by the composer who owns the child object, never host-side injection. jr2's
+  wrappers are transparent: `customize(research, { agents })` reaches the body through the `body` slot (and `pool()`'s
+  `worker`, at any depth), so a consumer never writes `body`. The images and the Repo bindings are the parts `provide`
+  cannot carry (xstate copies only implementations, and every part is keyed on the config it passes through by
+  reference), so those fields clone the wrapper's config and rebuild it with the same implementations, re-attaching what
+  the original carried. A bound argv's load warnings are such a part too: `customize()` rebuilds the Machine the author
+  wrote the same way, with the vocabulary, the seats and the door it carried and the warnings the walk gives for the
+  bound argv, so no attachment is keyed on anything but the config. Only DECLARED parts can be retuned, and the compiler
+  is what says so: the slots are read off xstate's own `TActor` parameter, so an Agent, a Repo Slot, or a child the
+  Machine does not carry is a type error (ADR-0050), and the runtime refuses the same call naming the Machine's own
+  slots. Rejected: a `.with()` method on the machine — it needs a jr2-owned machine type over xstate's, which ADR-0015
+  avoided, and it vanishes after any `.provide()`; a callable-machine hybrid — verified to work, reads as a trick.
 - **A package exports a Machine, nothing beside it.** The door (ADR-0033), the vocabulary, the Agents, and the image all
   ride the exported object. The three uses:
 

package/docs/reference/decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md

@@ -17,7 +17,12 @@ a definition lives, and the gate that enforces it.
   an Effect names it with `secret("name")`, and the Instance declares it in the top-level `secrets` list
   ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). The name is a string, not a type: the
   walk after the typecheck refuses an Effect that names a secret the list does not hold, before anything is built.
-  `jr2.config.ts` holds reach and credentials (`harness`, `secrets`, `git.credentials`, `registry`).
+  `jr2.config.ts` holds reach and credentials (`harness`, `secrets`, `git.credentials`, `registry`, and the Callers'
+  `callers`, `hooks` and `cors`,
+  [ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). A Machine names no Hook: a
+  Gate's or a Source's handlers are keyed by the Hook's kind ([ADR-0011](0011-workflow-defined-events.md)), and only a
+  Hook's address names it. A Hook kind is code that the config and the Workflows import by name, so it is neither
+  declared nor discovered: it comes in by `import`, as a nested Machine does, and `jr2 up` bundles it into the Assembly.
 - **The slot key types a Repo.** A `workspace()` declares its Repos as slots —
   `repos: { target: open, docs: { url, ref } }` — and the keys are a phantom on the wrapper type, read through
   `pool()`'s `worker` and `workspace()`'s `body` as the image is (ADR-0049). A

package/docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md

@@ -1,7 +1,7 @@
 # A Repo is a slot on the `workspace()` and a cache on the node
 
 ADR-0049 moved Agents and the Sandbox Image into the Machine and left one dependency outside it: the Repo, catalogued in
-`jr2.config.ts` and named by string from a `workspace()` spec, with the name typed back through a `Register` interface
+`jr2.config.ts` and named by string from a `workspace()`, with the name typed back through a `Register` interface
 (ADR-0050). The grill of 2026-09-13 found two faults. A packaged Machine still could not say which repository it works
 on, nor could a consumer bind one, except by the consumer's config holding the right NAME and the door threading it —
 the same encapsulation gap ADR-0049 closed for Agents. And the catalog's shape was dictated by storage: one read-only
@@ -20,28 +20,32 @@ decision: **what a Machine says about a repository, and what the cluster does wi
       target: open, // the consumer's — must be bound
       docs: { url: "https://github.com/acme/handbook.git", ref: "v3" }, // the package's own
     },
-    spec: ({ input }) => ({ branch: input.branch }),
   });
   ```
 
   A slot is in one of three states, and the walk tells them apart without evaluating anything: **bound** (a url, or
   `{ url, ref? }`), **open** (the `open` sentinel — someone downstream binds it), or **per-run** (a mapper over the
   wrapper's door: `feature: ({ input }) => ({ url: input.feature.repo, ref: input.feature.baseRef })`). `ref` is the
-  base the branch worktree is cut from; absent, the repository's own default branch. The spec no longer carries repos —
-  it is `{ branch, workGroup?, reviewSha? }`, or `{ workGroup? }` for a Workspace with no slot (below). The body's
-  handles are keyed by slot (`workspace.repos.target`), and so are the in-pod paths (`/work/<slot>/<branch>`): a slot
-  key is collision-free by construction and the same in every Instance that consumes the package, so a prompt can name a
-  path and be right everywhere.
+  Binding's base: `default/` stays on it, and a new branch starts from it. A branch is attached, and a tag or a commit
+  is detached. Absent, the base is the repository's own default branch. The body's handles are keyed by slot
+  (`workspace.repos.target` is `/work/target`), and so are the in-pod paths (`/work/<slot>/<name>`): a slot key is
+  collision-free by construction and the same in every Instance that consumes the package, so a prompt can name a path
+  and be right everywhere.
 
-- **The handles are the slot map and the branch — no slot is the `workdir`.** `workspace.repos` keeps the slots in
-  declaration order, and jr2 reads nothing into that order. Which checkout an Agent works in is a fact about that
-  Agent's Turn, not about the Workspace: a body with a `backend` and a `frontend` slot frames one Agent with the first
-  path and another with the second, and either may read the other's tree. A body that names no slot may give the order a
-  meaning of its own and document it (`task`: the first slot is the one the coder edits). The order is the kit's promise
-  — a slot key starts with a letter, because JS reads an integer-like key first wherever it was written — and the
-  meaning is the Machine's. Rejected: a `workdir` handle, the first declared slot's worktree — it made a singular
-  "primary repo" a property of every Workspace, which is wrong for a body whose Agents work in different slots or in
-  more than one, and it hid a rule in key order that the body never chose.
+- **The handles are the slot map — no slot is the `workdir`.** `workspace.repos` keeps the slots in declaration order,
+  and jr2 reads nothing into that order. A handle is the slot's folder and not a Worktree: the Workspace only clones,
+  and a Machine cuts each Worktree at `/work/<slot>/<name>`
+  ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)). Which checkout an Agent works in is a
+  fact about that Agent's Turn, not about the Workspace: a body with a `backend` and a `frontend` slot frames one Agent
+  with a Worktree of the first and another with a Worktree of the second, and either may read the other's tree. An
+  Effect names its Worktree as a Turn does, in its input: a `command` and an `http` take no `slot`, and a `push` keeps
+  its static `slot`, which says the Repo Slot whose credential it spends. A slot that is only read needs no Worktree: an
+  Agent reads `/work/<slot>/default`. A body that names no slot may give the order a meaning of its own and document it
+  (`task`: the first slot is the one the coder edits). The order is the kit's promise — a slot key starts with a letter,
+  because JS reads an integer-like key first wherever it was written — and the meaning is the Machine's. Rejected: a
+  `workdir` handle, the first declared slot's worktree — it made a singular "primary repo" a property of every
+  Workspace, which is wrong for a body whose Agents work in different slots or in more than one, and it hid a rule in
+  key order that the body never chose.
 
 - **A Machine whose body names no slot declares the whole map Open: `repos: open`.** A body that enumerates whatever is
   attached — `@jr2/machines`'s `task` — knows nothing a slot name could say, and a `target: open` on it would claim "one
@@ -61,21 +65,18 @@ decision: **what a Machine says about a repository, and what the cluster does wi
   have a second Agent edit it, upload it. Its steps share `/work`, as the steps of one GitHub Actions job share that
   job's folder; two Workspaces are two jobs and share nothing. So `workspace(body, { input })` with no `repos` is a
   Workspace with no Repo Slot: the attach is skipped (there is nothing to clone, and the pod's `fsGroup` already makes
-  `/work` the work group's), the body's handles are `{ repos: {} }` with no branch, typed `Workspaced<…, never>`, and a
-  Turn that frames no `cwd` and a `command` both work in `/work`. The spec has nothing to cut a branch in: `spec` is
-  optional, gives only `workGroup`, and a `branch` or a `reviewSha` in it is refused — at the type, and when the run
-  enters, since a value jr2 silently ignores is the failure the refusals exist for. `repos: {}` is refused with the
-  pointer to leaving it out, so "none" has one spelling and an empty map never reads as one somebody forgot to fill. An
-  Open map still asks `customize` for at least one slot: Open says the composer names the slots, and a body that
-  enumerates its checkouts (`task`) has nothing to do with none. Two Effects need a slot and are refused there, by
-  `jr2 up` and at invoke, with one reason: a `push` publishes a slot's branch, and a `command` with an Effect secret
-  runs against one commit of it (ADR-0067). A file-body `http` reads `/work` and stays. `/work` is an `emptyDir`, so a
-  Lost Sandbox takes everything with it — with a repository, pushed commits outlive the pod; here only what an Effect
-  sent out does, and the body hears `workspace.lost` as any body does. Storage that outlives the pod, the job's
+  `/work` the work group's), the body's handles are `{ repos: {} }`, typed `Workspaced<…, never>`, and a Turn that
+  frames no `cwd` and a `command` both work in `/work`. `repos: {}` is refused with the pointer to leaving it out, so
+  "none" has one spelling and an empty map never reads as one somebody forgot to fill. An Open map still asks
+  `customize` for at least one slot: Open says the composer names the slots, and a body that enumerates its checkouts
+  (`task`) has nothing to do with none. Three Effects need a slot and are refused there, by `jr2 up` and at invoke, for
+  one reason: a `worktree()` cuts in a slot's clone, a `push` publishes a slot's branch, and a `command` with an Effect
+  secret runs against one commit of it (ADR-0067). A file-body `http` reads `/work` and stays. `/work` is an `emptyDir`,
+  so a Lost Sandbox takes everything with it — with a repository, pushed commits outlive the pod; here only what an
+  Effect sent out does, and the body hears `workspace.lost` as any body does. Storage that outlives the pod, the job's
   "artifacts", is a decision of its own. Rejected: a placeholder repository bound to satisfy the rule — a clone nobody
-  uses, a branch that means nothing, a Worktree that becomes every Agent's default `cwd`, and a cache entry to warm.
-  Rejected: a new term for the repository-less Sandbox — the Glossary's Workspace never named a repository, so none was
-  needed.
+  uses, a Worktree that means nothing, a `cwd` that each Turn must then state, and a cache entry to warm. Rejected: a
+  new term for the repository-less Sandbox — the Glossary's Workspace never named a repository, so none was needed.
 
 - **The consumer binds with `customize`**, in the same call as Agents and the image, nested through `actors` like every
   other part: `customize(codeReview, { repos: { target: "git@github.com:ourorg/app.git" } })`. Any of the three forms is
@@ -89,6 +90,14 @@ decision: **what a Machine says about a repository, and what the cluster does wi
   is the thing, not a reference into someone else's file. Two spellings of one repository (`https://`, `git@…:`,
   `ssh://`, with or without `.git`) resolve to one identity — host plus path, scheme and user dropped — and therefore
   one cache. A door that offers a menu of repositories is the Instance's own `z.enum` of urls.
+- **The cache key names one identity.** The key is the Repo CR's name, the hostPath folder, the volume name `repo-<key>`
+  and the mount `/repos/<key>`: a slug of the identity's last segment, at most 16 characters, a dash, and the first 32
+  hex digits (128 bits) of the identity's sha256, at most 49 characters in all. No one can find two identities with one
+  key, and a per-run url is the Agent's text, so a shorter hash is a way into another Repo's cache: with 32 bits, a
+  search found a url of an attacker's repository with the key of a private one in seconds. Each Repo CR states its
+  identity (`jr2.dev/identity`). The Orchestrator refuses to write a CR whose stated identity is not the one that it
+  attaches or binds, and names both urls: no url, no `secretRef` and no clock of one repository is written on a CR of
+  another.
 - **The cluster keeps a bare cache per node, not a volume.** Each repository is a `Repo` custom resource the operator
   reconciles (spec: url, refresh interval; status: per node — synced, generation, last error). A cache agent runs as a
   DaemonSet per Instance over its Sandbox nodes (ADR-0052) with a hostPath directory: it clones a repository onto its
@@ -100,9 +109,8 @@ decision: **what a Machine says about a repository, and what the cluster does wi
   on-demand fetch; every cache speaks git protocol v2, so a fetch advertises only the refs it asks for; and the refresh
   interval carries ±20% jitter, like the Lease, so R Repos on N nodes do not hit a remote on one beat (scaling review
   R13, 2026-09-30). The agent also consolidates a cache's packs without deleting an object (ADR-0004). The
-  Orchestrator's attach then runs unchanged: `git clone --shared` off the mount, worktree beside it. A Sandbox that
-  lands on a cold node pays one clone there, once — the same economics as an image pull, and the reason a Sandbox can
-  run on any node.
+  Orchestrator's attach then runs unchanged: `git clone --shared` off the mount. A Sandbox that lands on a cold node
+  pays one clone there, once — the same economics as an image pull, and the reason a Sandbox can run on any node.
 - **The Orchestrator creates `Repo` CRs; it does not sync them.** At boot it walks its registered Machines and creates
   one CR per bound identity, so a statically known repository is KNOWN before a run can ask: the cache agent on every
   node probes it (`git ls-remote`) as soon as the CR exists, so a wrong url or a credential that does not reach shows in
@@ -123,10 +131,13 @@ decision: **what a Machine says about a repository, and what the cluster does wi
   whose clone Secret `git-clone.json` does not list gets none, and the clone is anonymous; the cache agent reads only
   that Secret, and the operator matches nothing. The Orchestrator writes and reads no git credential (ADR-0068). The
   Secret uses Flux's key names (`username`/`password`; `identity`, `identity.pub`, `known_hosts`), so a Flux or Argo
-  user reuses the Secret they have. **The list is also the fence.** A per-run url — a run input, a ticket field — is
-  otherwise a way to spend the cluster's credential against any host: one that matches no entry is refused at attach,
-  naming the list. A static binding is code the Instance typechecked and deployed, so it is admitted without a match and
-  cloned anonymously; a private one then fails at the cache with git's error. `jr2 init` scaffolds one wildcard entry —
+  user reuses the Secret they have. With a token, the cache agent's helper answers for the Repo's own origin alone
+  (scheme, host and port), and its clone, probe and fetch follow no redirect, so the token never reaches an origin
+  outside the entry. A repository that moved, and that its old url redirects to, is cloned by its new url. **The list is
+  also the fence.** A per-run url — a run input, a ticket field — is otherwise a way to spend the cluster's credential
+  against any host: one that matches no entry is refused at attach, naming the list. A static binding is code the
+  Instance typechecked and deployed, so it is admitted without a match and cloned anonymously; a private one then fails
+  at the cache with git's error. `jr2 init` scaffolds one wildcard entry —
   `{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }`, today's two implicit defaults made visible, with a
   comment saying to narrow it before anything untrusted can start a run, and that it also pushes: a `push()` whose Repo
   Slot url it matches, a per-run url included, spends the same token or key — so the open fence is in the user's file
@@ -198,15 +209,15 @@ decision: **what a Machine says about a repository, and what the cluster does wi
   the kit's first cluster requirement a storage class most small clusters lack.
 - **A Flux-style `GitRepository` serving an artifact over HTTP.** Rejected: an artifact download is a clone per Sandbox
   — the cost the cache exists to avoid.
-- **Urls kept in the spec, not the slot** (the shape before this decision, with a url in place of a name). Rejected: the
-  walk cannot see inside the spec, so a bound repository would be invisible to `jr2 up` and to prewarm, and `customize`
-  would have nothing to bind.
+- **Urls from a per-run function of the `workspace()`, not the slot** (the shape before this decision, with a url in
+  place of a name). Rejected: the walk cannot see inside a function, so a bound repository would be invisible to
+  `jr2 up` and to prewarm, and `customize` would have nothing to bind.
 
 ## Consequences
 
 - The operator becomes git-aware, which ADR-0001 kept it from being: the `Repo` CRD and the cache agent are its. The
-  Sandbox CRD stays free of git semantics beyond a list of identities; clone and worktree remain the Orchestrator's
-  post-`Ready` step (ADR-0004).
+  Sandbox CRD stays free of git semantics beyond a list of identities; the clone remains the Orchestrator's post-`Ready`
+  step, and a Worktree is a Machine's cut (ADR-0004).
 - `workspace()`'s `repos` names at least one slot, or is `open` whole — in which case the `customize` that names the map
   is held to the same rule — or is left out, for a Workspace with no Repo Slot; a Machine that composes no Sandbox has
   no repos to customize, and the data-plane switch ("does this Instance need Sandboxes") is "a registered Machine
@@ -214,12 +225,12 @@ decision: **what a Machine says about a repository, and what the cluster does wi
   Sandboxes, the cache agent and the Sandbox Images; a deployed Orchestrator wires its kube client whatever its current
   Assembly composes, because a publish can bring the first `workspace()` without a roll
   ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)).
-- Every slot gets a branch worktree cut at the run's branch, a reference checkout included. A slot has no read-only
-  mode; that is a decision of its own if it is ever wanted.
+- A slot has no read-only mode, and needs none: a slot in which a Machine cuts nothing holds only `default/`, on the
+  Binding's base.
 - The Console's start form loses the catalog dropdown: a per-run repository is a url field unless the Machine's door
   enumerates its own.
-- The volume paths change: the in-pod source mount is `/repos/<key>` where `<key>` is derived from the identity, and the
-  pod-local layout is `/work/<slot>/{default,<branch>}`. Existing checkouts on a pre-0051 PVC are not migrated.
+- The volume paths change: the in-pod source mount is `/repos/<key>` where `<key>` is the identity's cache key, and the
+  pod-local layout is `/work/<slot>/{default,<name>}`. Existing checkouts on a pre-0051 PVC are not migrated.
 - ADR-0047's deploy-key prompt reads ssh urls off the walk. A per-run ssh url first seen at attach was never prompted
   for; its first attach fails with the key hint, as any unregistered key does.
 - A `customize` of a per-run slot with a static url is legal and makes it bound; a Machine that wants a slot to stay the

package/docs/reference/decisions/0052-a-sandbox-lands-where-an-ordinary-pod-lands-and-the-cache-follows-it.md

@@ -27,6 +27,11 @@ use. **Which nodes are an Instance's Sandbox nodes, and who follows that set** i
   Sandbox node, so a cache is only ever present where a Sandbox can land, and the affinity it feeds only ever names a
   usable node. The build set (ADR-0045) is the union of the nodes an ordinary pod lands on — the Orchestrator
   Deployment's own placement — and the Sandbox nodes, intersected with the supported set as before.
+- **The cache agent also reports Landlock for its node.** It probes Landlock when it starts, and on a node without it
+  the agent is NotReady, with the reason. `jr2 up` reads the DaemonSet's pods and refuses to converge while a Sandbox
+  node lacks Landlock, naming each one ([ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)). This is the
+  one refusal on the node set: Landlock is a fact that each Sandbox node must have, not a set that can be empty. The
+  admin keeps a bad node out with `sandbox.nodeSelector` or a taint.
 - **The Sandbox CR carries the placement.** `Sandbox.spec` gains `nodeSelector` and `tolerations` beside `resources`,
   `initContainers`, and `volumes`; the Orchestrator writes them from its baked config at provision and the operator
   copies them onto the pod, merging nothing. The operator stays config-blind (ADR-0001), and every Instance's placement

package/docs/reference/decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md

@@ -29,8 +29,8 @@ a fetch inside a pod reaches the remote, and who may ask** is one decision.
   Binding's own spelling, the caller's own credential, never the Agent's (ADR-0005).
 
 - **The ask rides the Sandbox CR and reaches the agent through the pod.** The program asks the Custodian on `localhost`
-  (`POST /fetch`, with the Sandbox token's Stand-in — a constant, because the User Container gets no env); the Custodian
-  puts the token it holds in place of the Stand-in and asks the Orchestrator for THIS pod's Sandbox
+  (`POST /fetch`, with the fetch token's Stand-in — a constant, because the User Container gets no env); the Custodian
+  puts the fetch token in place of the Stand-in, on this route alone and asks the Orchestrator for THIS pod's Sandbox
   (`POST /sandboxes/<name>/fetch` — the program cannot name another,
   [ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)); the Orchestrator patches one
   annotation on the Sandbox CR, per Repo key, timestamp value — the Lease's shape, an annotation the Orchestrator
@@ -45,16 +45,28 @@ a fetch inside a pod reaches the remote, and who may ask** is one decision.
   sticky, once per pod life. The Orchestrator's route waits on that entry — a Sandbox watch event, never a poll
   ([ADR-0063](0063-the-orchestrator-watches-the-cluster.md)) — then answers the Custodian, which answers the program.
   One wait, and it is the wait an attach already makes.
-- **The scope is the Sandbox token's scope, and no seat gains a credential.** A Sandbox may ask for the caches it mounts
-  and nothing else; the remote is reached by the cache agent with the Repo CR's `secretRef`, the credential that cloned
-  the cache. The pod holds none before and none after. The Menu is untouched — a fetch is not something the Agent
-  _says_, it is something it _does_ — and no Machine declares anything: the ability is ambient in every Workspace pod,
-  the way Working tools are, and absent on the Instance Harness, which mounts no Repo.
+- **The scope is the fetch token's scope, and no seat gains a credential.** The fetch token is valid on the fetch route
+  alone, and the control token is not valid there
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). A Sandbox may ask for the
+  caches it mounts and nothing else; the remote is reached by the cache agent with the Repo CR's `secretRef`, the
+  credential that cloned the cache. The pod holds none before and none after. The Menu is untouched — a fetch is not
+  something the Agent _says_, it is something it _does_ — and no Machine declares anything: the ability is ambient in
+  every Workspace pod, the way Working tools are, and absent on the Instance Harness, which mounts no Repo.
 - **Freshness degrades, absence does not, and the caller is told.** A remote fetch that fails or outruns the on-demand
   budget lets the program fall through to the objects the cache holds — ADR-0051's stance for attach — and writes one
   line to stderr, which git passes through verbatim:
   `warning: jr2: remote fetch failed (<git's error>); serving the cache as of <lastFetched>`. The budget is the cache
-  agent's one on-demand number; the program's wait is that plus watch slack, and nothing else owns a timeout.
+  agent's one on-demand number; the program's wait is that plus watch slack, and nothing else owns a timeout. A cut
+  reads that line too: its output carries the line in `stale`, and the cut uses what the clone holds. A branch name that
+  the clone does not hold is then `refused`, because the remote cannot confirm that it is new
+  ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)).
+- **One fetch at a time in a clone.** All Worktrees of a clone share `refs/remotes/origin/*`, and git updates a ref only
+  if it still holds the value that the fetch read. So two fetches that overlap on a moved remote can fail with
+  `cannot lock ref`. The failure does no harm, but it costs a Turn. So the program takes a per-clone lock after the ask,
+  so a dead remote does not make coders wait in line. `git upload-pack` can end before the fetch writes its refs: that
+  happens when a pack moves. In a shared clone, git often keeps the connection open to the end. The lock must last to
+  the end of the fetch in both cases, so a small child process that the program leaves watches the fetch and holds the
+  lock. ADR-0075 holds the measurements.
 - **Every seat that holds the checkouts holds the program.** The fetch url lives in the shared `default/.git/config`, so
   a seat without the program has checkouts whose `git fetch` dies. That is ADR-0005's own argument for `/repos` — half
   of one exception, not a second — applied once more: the pod's `/opt/jr2` volume is mounted read-only into the User

package/docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md

@@ -31,48 +31,63 @@ the one part ADR-0049/0051 left a package unable to leave unsaid: **the model.**
   who never reads the file spends money on a model they did not choose, silently, which is the failure class `jr2 up`
   exists to make loud. Rejected: a Machine factory `task({ model })` — ADR-0049 settled that a package exports a Machine
   and retunes with `customize`, and a factory reopens that.
-- **Open widens to an Effect's url, argv and secret, bound once.** A package cannot know the host its `http` Effect
-  calls, the program its `command` runs
+- **Open widens to an Effect's url, argv, MCP server and tool, and secret, bound once.** A package cannot know the host
+  its `http` Effect calls, the program its `command` runs, the MCP server and tool its `mcp` Effect calls
   ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)), or the secret its
   composer spends, so it may leave each Open: `http({ method, url: open, auth, input, request })`,
-  `http({ method: "PUT", url: open, body: file(path) })`, `command(open, { env, pin })`, and `secret(open)` in place of
-  a secret's name. The url, the argv and the secret's name are the Open parts of an Effect that exist; everything else
-  the definition says is the package's as written — the method, the headers, the auth and the secrets they name, the
-  input, `request`, the env, `pin` — and is checked when the Machine is built. `secret(open)` is taken by `bearer`,
-  `basic` (the user or the password), a header's value, and a command's env, as its value or its `.path`; in a url it is
-  refused when the Machine is built ("leave the whole url Open"), since a url that carries a secret is left Open whole
-  (below). An Effect takes one Open secret: a second `secret(open)` in one definition is refused when the Machine is
-  built ("an Effect takes one Open secret"); the one `secret(open)` may stand in several places, a value and its
-  `.path`. An Effect that names an Open secret is placed as one that names a secret is — a credentialed command in the
-  Sandbox Effector, an `http` where its body places it — before the name is known. The composer binds the parts with
-  `customize(machine, { effects: { <slot>: { url } } })`, `{ argv }` or `{ secret }`, and an Effect with an Open url or
-  argv beside an Open secret takes one object with both keys (`{ url, secret }`, `{ argv, secret }`): a url is a string
-  or a `text` with a secret in its path, an argv is the usual list, and a secret is a name that obeys `secret()`'s own
-  rule — it is the secret's file in the Effector's mount (ADR-0068). The type of `effects` is the intersection of the
-  Open parts' bindings, so a binding that leaves one of them unbound is a compile error, as an unbound url is; at run
-  time, a binding that leaves one unbound gives an Effect still Open in it, which a later `customize()` may bind. Each
-  is bound ONCE, to a value: never a mapper over the door, so a host is fixed in the definition or bound before any run,
-  and no run chooses one, nor a secret. Binding builds the Effect again with its constructor, with the bound name in
-  every place `secret(open)` stood, so a bound part meets every rule the constructor checks — a literal host, no secret
-  in a query, a non-empty argv, a secret's name — and the bound Effect is the one the same definition written with that
-  name gives; `jr2 up` reads it as written: the placement, the secrets it names, and the Effector's fence
-  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)) are the bound ones, and the bound secret
-  is placed only in that Effect's Effector, as a named secret is. Only an Open part is offered: a part the author fixed
-  is no key of `effects` and is refused at the call, and a part bound once is fixed from then on, so a second composer
-  cannot move it. `effects` reaches through `workspace()`'s body, `pool()`'s worker and a composed Machine's `actors`,
-  as `agents` does, typed off the slot's logic. An Open argv's slots are the composer's, so the load walk counts every
-  pick param as read by it when the Machine is built, and `customize()` runs the walk's pick-param check again once the
-  argv is bound — a param the bound argv does not read is refused there, and a warning it gives for the bound argv is
-  the bound Machine's, as it is the same Machine's written with that argv: the bound Machine gets a config of its own,
-  which carries those warnings ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)), so a copy
-  `provide()` makes of it — a run's — keeps them, and the Open Machine keeps its own. The compiler's check does not
-  reach a bound argv: an Open argv's input is one string per key, so nothing at build or at `customize()` checks that
-  the invoke supplies each slot the bound argv names, and a slot it does not supply faults when the Effect starts — its
-  state's `onError`, with nothing run. The `jr2 up` walk reports an Open Effect beside Open Repo Slots and Agents and
-  refuses the converge naming the `effects` line — `{ effects: { <slot>: { secret: "<name>" } } }` for an Open secret,
-  one object with both keys for an Effect with two Open parts; the Effect refuses to run while Open, as the second fence
-  — its state's `onError`, with nothing sent and no ledger row. The Open part is the whole url, the whole argv, or the
-  secret's name.
+  `http({ method: "PUT", url: open, body: file(path) })`, `command(open, { env, pin })`,
+  `mcp.call(open, open, { input })`, and `secret(open)` in place of a secret's name. The url, the argv, an `mcp`
+  Effect's server and tool, and the secret's name are the Open parts of an Effect that exist; everything else the
+  definition says is the package's as written — the method, the headers, the auth and the secrets they name, the input,
+  `request`, the env, `pin` — and is checked when the Machine is built. `secret(open)` is taken by `bearer`, `basic`
+  (the user or the password), a header's value, and a command's env, as its value or its `.path`; in a url it is refused
+  when the Machine is built ("leave the whole url Open"), since a url that carries a secret is left Open whole (below).
+  An Effect takes one Open secret: a second `secret(open)` in one definition is refused when the Machine is built ("an
+  Effect takes one Open secret"); the one `secret(open)` may stand in several places, a value and its `.path`. An Effect
+  that names an Open secret is placed as one that names a secret is — a credentialed command in the Sandbox Effector, an
+  `http` where its body places it — before the name is known. The composer binds the parts with
+  `customize(machine, { effects: { <slot>: { url } } })`, `{ argv }`, `{ secret }`, `{ server }` or `{ tool }`, and an
+  Effect with two Open parts takes one object with both keys (`{ url, secret }`, `{ argv, secret }`,
+  `{ server, tool }`): a url is a string or a `text` with a secret in its path, an argv is the usual list, and a secret
+  is a name that obeys `secret()`'s own rule — it is the secret's file in the Effector's mount (ADR-0068) — and a server
+  is a name of the `mcp` block of `jr2.config.ts`, whose secret is the server's own, so an `mcp` Effect takes no
+  `secret(open)`
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). The
+  type of `effects` is the intersection of the Open parts' bindings, so a binding that leaves one of them unbound is a
+  compile error, as an unbound url is; at run time, a binding that leaves one unbound gives an Effect still Open in it,
+  which a later `customize()` may bind. Each is bound ONCE, to a value: never a mapper over the door, so a host is fixed
+  in the definition or bound before any run, and no run chooses one, nor a secret. Binding builds the Effect again with
+  its constructor, with the bound name in every place `secret(open)` stood, so a bound part meets every rule the
+  constructor checks — a literal host, no secret in a query, a non-empty argv, a secret's name — and the bound Effect is
+  the one the same definition written with that name gives; `jr2 up` reads it as written: the placement, the secrets it
+  names, and the Effector's fence ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)) are the
+  bound ones, and the bound secret is placed only in that Effect's Effector, as a named secret is. Only an Open part is
+  offered: a part the author fixed is no key of `effects` and is refused at the call, and a part bound once is fixed
+  from then on, so a second composer cannot move it. `effects` reaches through `workspace()`'s body, `pool()`'s worker
+  and a composed Machine's `actors`, as `agents` does, typed off the slot's logic. An Open argv's slots are the
+  composer's, so the load walk counts every pick param as read by it when the Machine is built, and `customize()` runs
+  the walk's pick-param check again once the argv is bound — a param the bound argv does not read is refused there, and
+  a warning it gives for the bound argv is the bound Machine's, as it is the same Machine's written with that argv: the
+  bound Machine gets a config of its own, which carries those warnings
+  ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)), so a copy `provide()` makes of it — a run's
+  — keeps them, and the Open Machine keeps its own. The compiler's check does not reach a bound argv: an Open argv's
+  input is one string per key, so nothing at build or at `customize()` checks that the invoke supplies each slot the
+  bound argv names, and a slot it does not supply faults when the Effect starts — its state's `onError`, with nothing
+  run. The `jr2 up` walk reports an Open Effect beside Open Repo Slots and Agents and refuses the converge naming the
+  `effects` line — `{ effects: { <slot>: { secret: "<name>" } } }` for an Open secret, one object with both keys for an
+  Effect with two Open parts, `{ effects: { <slot>: { server: "<name>" } } }`, `{ tool: "<tool>" }` or both for an `mcp`
+  Effect, with only its Open keys; the Effect refuses to run while Open, as the second fence — its state's `onError`,
+  with nothing sent and no ledger row. The Open part is the whole url, the whole argv, an MCP server's name or a tool's
+  name, or the secret's name.
+- **Open widens to a hooked Gate's look, which only warns.** A package writes the Hook handlers of its Gate slots for
+  each forge that it supports, because a forge's payload is public, so a handler is never Open. It imports the Hook kind
+  of each forge that it hears, for the payload types, and it has `@jr2/orchestrator`, which holds the kinds, as a peer
+  dependency ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Which Hooks of
+  those kinds exist is the Instance's config. A look needs a url and a token, so a package leaves `look: open`, and the
+  composer binds it once, to a look or `"none"`, with `customize(machine, { gates: { <slot>: { look } } })`, which can
+  also add, replace or remove a handler by kind and event key ([ADR-0011](0011-workflow-defined-events.md)). An Open
+  look that nobody binds is the one Open part that `jr2 up` does not refuse: it warns, as it warns about a hooked Gate
+  with no look, because the Gate still works when a person answers it with `jr2 send`.
 - **The per-run Dial is the escape hatch, not the default.** A shipped Machine's door may carry `model` and
   `thinkingLevel` (ADR-0018's two Dials) and fold them into each invoke's input; the bound definition is what `jr2 up`
   preflights, the door value overrides it for one run's Turns. Nothing in jr2 changes for this — it is the Machine's own

package/docs/reference/decisions/0055-a-release-is-a-pushed-tag-and-the-publish-guard-is-the-credential.md

@@ -16,10 +16,10 @@ version, images, gate, trigger.
   an npmjs credential is the release job, and it holds no token: it publishes with npm trusted publishing (OIDC from
   GitHub Actions), so nothing long-lived exists to leak. A `pnpm -r publish` on a dev box reaches npmjs and fails
   `ENEEDAUTH`, which is the guard — an absence that cannot be edited past, where the manifest line was a presence that
-  had to be. `publishConfig.access: public` stays on all four, because a scoped package's first publish is 402 without
-  it. `scripts/dist-publish.sh` passes `--registry` again, and `publish.test.ts` inverts: it asserts that **no** public
-  manifest names a registry, so the old guard cannot be smuggled back in one package and silently pin a release to
-  localhost.
+  had to be. `publishConfig.access: public` stays on every public package, because a scoped package's first publish is
+  402 without it. `scripts/dist-publish.sh` passes `--registry` again, and `publish.test.ts` inverts: it asserts that
+  **no** public manifest names a registry, so the old guard cannot be smuggled back in one package and silently pin a
+  release to localhost.
 - **Lockstep, and `main` carries the next version.** One number across `packages/*` and `templates/default`, because
   [ADR-0019](0019-one-converging-command-against-the-current-context.md)'s one release train already reads a single
   `KIT_VERSION`, ADR-0043's scaffold pins two packages at one exact number, and `workspace:*` packs to an exact
@@ -50,11 +50,11 @@ version, images, gate, trigger.
   ([ADR-0072](0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md)). It does not wait for the
   npm approval, so the site can be ahead of the live packages until the maintainer approves them.
 - **The job stages; the maintainer approves.** Each trusted publisher is configured for `npm stage publish` only, so the
-  tag produces four staged tarballs and one 2FA approval per package (`npm stage approve`, dependencies first) makes
-  them live. This is the one human act a release keeps, and it is kept on purpose: the job's identity is bound to the
-  repository and the workflow file, so a stolen GitHub session or a bad edit to that file could otherwise publish under
-  the project's name; staged, it can stage and nothing more. It is not a runbook step — nothing has to be remembered in
-  order, the staged tarballs wait.
+  tag produces one staged tarball per public package and one 2FA approval per package (`npm stage approve`, dependencies
+  first) makes them live. This is the one human act a release keeps, and it is kept on purpose: the job's identity is
+  bound to the repository and the workflow file, so a stolen GitHub session or a bad edit to that file could otherwise
+  publish under the project's name; staged, it can stage and nothing more. It is not a runbook step — nothing has to be
+  remembered in order, the staged tarballs wait.
 - **Two executors of one train.** `scripts/publish.sh` is the irreversible half — images, then packages, dependencies
   first, live versions skipped — and the job runs it with `--stage`. A maintainer runs it as `just publish` from the
   pushed tag when a 0.x release cannot wait the job's hour: `npm publish` with a 2FA prompt per package in place of an
@@ -94,14 +94,15 @@ version, images, gate, trigger.
   configuration" no longer holds; the rest of that list does.
 - **Bootstrap, once:** create the `jr2` org on npmjs (a scope is a user or an org), publish the first version by hand
   with a token — npm attaches a trusted publisher only to a package that already exists — then configure the trusted
-  publisher on all four packages and revoke the token. After that no token that publishes on its own exists anywhere:
-  the job's identity stages, a maintainer's login needs its second factor. Likewise once: make the three GHCR packages
-  public after the first push, because GHCR creates them private.
+  publisher on each public package and revoke the token. Each new public package needs the same step once: publish its
+  first version by hand before the first tag that holds it, or that tag's `npm stage publish` of it fails. After that no
+  token that publishes on its own exists anywhere: the job's identity stages, a maintainer's login needs its second
+  factor. Likewise once: make the three GHCR packages public after the first push, because GHCR creates them private.
 - `publish.test.ts` asserts no registry, `access: public`, and `engines`; `dist-publish.sh` drops its manifest read-back
   and passes `--registry`; the `@dist` fixture takes its registry from `JR2_DIST_PORT`'s default rather than the
   manifest; `kit-push.sh`'s cli-vs-orchestrator cross-check widens to every manifest; `just release` is new;
   `.github/workflows/` gains `ci.yml` and `release.yml`.
 - A release costs a runner kind cluster and roughly ten minutes of docker. Accepted: it is the only time the installed
   path must be proven on the exact tree that ships.
-- The four tarballs gain the npm-page fields (`description`, `repository` with `directory`, `homepage`, `bugs`,
+- The public tarballs gain the npm-page fields (`description`, `repository` with `directory`, `homepage`, `bugs`,
   `keywords`) and a README each; the root README's "only scaffolding exists" line goes.