@jr2/orchestrator 0.3.0 → 0.5.1

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

@@ -0,0 +1,227 @@
+# 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
+(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
+volume of `default/` checkouts, which on a multi-node cluster pins every Sandbox to the node holding it. The two are one
+decision: **what a Machine says about a repository, and what the cluster does with that.**
+
+## Decision
+
+- **A Repo is a slot on the `workspace()`**, beside `image` and `user`, keyed by the Machine's own word for it:
+
+  ```ts
+  export const codeReview = workspace(body, {
+    input,
+    image: import.meta.resolve("./image"),
+    repos: {
+      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.
+
+- **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.
+
+- **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
+  repository" where the body claims nothing. So the map is the Open part, one level up from a slot: the composer names
+  every slot with `customize`, in the order the Machine documents. The body's handles are typed `Workspaced<…, string>`,
+  which is its statement that it names no slot; `workspace()` refuses a body that names one under an Open map, since the
+  composer may never write that word. The walk reports an Open map as one Open part with no slot, and `jr2 up` refuses
+  it by the same route, with `<slot>` left in the line for the composer to fill. Rejected: `customize` adding keys to a
+  declared map — a slot a Machine never declared is a compile error on purpose (a typo cannot mint a clone), and a body
+  that named `target` could say nothing about a `reference` it never knew of; the map-level Open says what the body
+  actually knows. Rejected: a second Machine of the consumer's own, wrapping the exported body with more slots —
+  composition is the right act for a different BODY, but the same body with more checkouts beside it is a binding, and
+  `customize` is where bindings go.
+
+- **A Workspace with no Repo Slot leaves `repos` out.** A Workspace is a Sandbox bound to one unit of work, and a
+  repository is something it may attach, not what makes it one. Some work has no repository: fetch data, write a report,
+  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
+  "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.
+
+- **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
+  accepted, so a consumer can also bind a mapper over the child's door. A slot the Machine does not declare is a compile
+  error (a phantom on the wrapper type, read through `pool()`'s `worker` and `workspace()`'s `body` as the image is). A
+  registered Machine with an open slot nobody bound is refused by `jr2 up`'s walk, before it builds anything, naming the
+  Machine, the slot, and the `customize` line that fixes it. That is the one check that is converge-time and not
+  compile-time: a `workflows/` export has no type to hang it on (ADR-0050).
+- **The url is the identity.** There is no repo name. `jr2.config.ts` loses `repos`; `Register`, `RepoName`,
+  `repoNames()`, and the `const` on `defineConfig` retire. ADR-0050's rule holds vacuously: the string a Machine writes
+  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 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
+  node the first time a Sandbox there needs it, fetches in place on the interval and on demand before an attach, and
+  pins gc exactly as ADR-0004 requires. The Sandbox CR names the repositories it needs by identity; the operator mounts
+  each node cache read-only, sets a soft node affinity toward nodes whose status holds them, and reports `Ready` only
+  once every one is present and has been fetched since the CR asked. The agent works per Repo, four at once on a node (a
+  kit value; a fetch is network and CPU beside the Sandboxes it serves), so one Repo's cold clone never holds another's
+  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.
+- **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
+  `jr2 status` right after converge, not at the first run. Known is not warm: the clone happens on a node the first time
+  a Sandbox there needs the repository, never on every node at boot — cloning a large repository onto every node that
+  may never run a Sandbox for it is the cost the image-pull economics above exist to avoid. A per-run url creates its CR
+  at first attach, and every later attach anywhere finds it. The boot restates a bound CR's url and `secretRef` at every
+  deploy; an attach restates the `secretRef` of a CR nothing binds, since no boot will — so a `git.credentials` entry
+  fixed after a failed clone reaches the cache at the next run either way. Only an attach moves the eviction clock: a
+  boot is not an attach.
+- **Credentials are matched by prefix and carried by the CR, the Argo and Flux shape.** `jr2.config.ts` holds
+  `git.credentials`, a list of `{ match, token?, sshKey? }`: `match` is a prefix on the identity (`github.com/ourorg/`,
+  or `*`), `token` names an env var whose value `jr2 up` writes into that entry's own clone Secret,
+  `jr2-git-<hash of match>` (labelled, and deleted when the entry no longer has one; an unset variable writes none),
+  listing the Secrets it wrote in `git-clone.json` in `jr2-held`, names only; `sshKey` names a Secret holding a deploy
+  key; the url's scheme picks which field applies, and the longest match wins. When the Orchestrator creates a `Repo` CR
+  it resolves the entry and writes a `secretRef`, the name of a Secret `jr2 up` wrote or the user made — a token entry
+  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 —
+  `{ 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
+  and commit, never implied.
+- **An entry may carry a push credential and a signing key** (ADR-0067), checked by shape when the config loads:
+  `push?: { sshKey } | { token }`, the credential a `push()` to a Binding under the entry spends — absent, the clone
+  credential pushes, and an entry with no credential admits a clone, never a push; a token goes Basic over https through
+  a credential helper only, which answers for the Binding's own host alone, and the push follows no redirect, so the
+  token never reaches an origin outside the entry. `sign?: { sshKey, name, email } | { gpgKey, name, email }`, the key a
+  `push({ sign: true })` signs with and the committer it signs as — explicit, so an auth key is never reused as a
+  signing key; an ssh key is the default format, a GPG key is a Secret with `private.asc` and no passphrase. `name` and
+  `email` are required: the Effector re-creates the commits, and a forge verifies a signature only when the committer
+  email belongs to the account that holds the key. The author line stays the Agent's. `committer?: { name, email }`, who
+  an unsigned `push({ squash: true })` is committed by, at the Effector's clock (ADR-0067): a squash is a new commit,
+  and without `sign` no signer names its committer; `jr2 up` refuses an unsigned squash whose entry has neither `sign`
+  nor `committer`.
+- **The pod's maker places the push credential, by reference, when the url is known.** When a registered Machine pushes,
+  `jr2 up` writes each entry's push and sign credentials into that entry's own Secret, `jr2-git-push-<hash of match>`
+  (labelled, and deleted when the entry no longer has one), never per Workspace: the token from `.env` in Flux's key
+  names (`username`, `password`); the keys of the Secret its ssh key names, copied as data and never decoded
+  (`identity`, `identity.pub`, `known_hosts`); the signing key as `sign.identity` or `sign.private.asc`; and
+  `entry.json`, what the entry is (its match, what it pushes with, the committer it signs as). An entry with no `push`
+  field pushes with its clone credentials, each over its own scheme, so the scaffold's wildcard holds both. An entry
+  with nothing it can place — its token unset, its key's Secret absent — gets no Secret, and `jr2 up` says why. It
+  writes `git-push.json` in `jr2-held` beside them: which entries have a Secret and what each can spend, names only. At
+  provision the Orchestrator matches each pushed slot's url — static, per-run or `customize()`-bound, one path — against
+  the fence (longest prefix, the attach match), and the Sandbox CR carries the matched entry's Secret name
+  (`gitCredentials`, the `secretRef` shape); the operator projects it into the Sandbox Effector alone (ADR-0005). The
+  Orchestrator reads no value. The Effector holds only the entries named there and matches a push's url as the fence
+  does, longest match first, and refuses a url outside the entry.
+- **A push is refused with a fix that works, at `jr2 up` for a static Binding and at provision for any url.** One rule
+  (`pushRefusal`), and the fix each refusal names is one the same rule then accepts: a url no entry matches (the entry
+  to add, its `match` the url's host and directories, so always a prefix of the url); a local path (git's local
+  transport runs that repository's config and hooks) or `git://`; an `http://` url — a push credential goes over https
+  or ssh only: a token over http is the token in the clear, and no ssh key is spent over http — told the url its entry
+  can push to (https for a token, ssh for an ssh key) or, when no entry or no credential is there, the https url and the
+  token to add; an entry that holds no credential the url's scheme can spend (a token over https, an ssh key over ssh):
+  the clone field to add when it holds a clone credential and no `push` field, since a `push` field would replace that
+  credential, the `push` field when it holds none, and the other scheme's url when its `push` field already names the
+  other credential, since a `push` field names one; and `sign: true` on an entry with no `sign` field (the field to
+  add). `jr2 up` reads a static Binding's entry as written, then refuses an https Binding whose entry's token variable
+  is unset. A key's Secret, or a signing key's, that is absent at `jr2 up` is a warning, not a refusal: it may be
+  written after (ADR-0047's prompt, a human); the entry's Secret is written without that key, and the provision refuses
+  the push that needs it, naming the Secret to create and `jr2 up` to run again. The provision reads the same entry as
+  `jr2 up` placed it, so a per-run url is refused at attach for the same reasons, as a url outside the fence is, before
+  anything is written. Accepted costs: `jr2 up`'s report is exact for a static Binding and says "the entry its url
+  matches" for a per-run slot; a wildcard entry gives a per-run push the catch-all credential, the fence's existing
+  choice.
+- **Freshness degrades, absence does not.** A fetch that fails on a warm cache lets the attach proceed on the objects it
+  has, announced as stale with git's own error. A stale attach is stale until the next fetch anyone inside the pod runs:
+  the worktree's `origin` asks the cache, and the cache asks the remote (ADR-0053) — no container the Agent executes in
+  holds a credential (ADR-0005), and the same failure lets that fetch fall through to the cache's objects with a warning
+  on stderr. A clone that fails on a cold node fails that provision pointedly, naming the repository and the error, and
+  the CR status carries it for `jr2 status` (ADR-0048's pattern).
+- **Eviction is reachability plus age.** `jr2 gc` deletes a `Repo` CR that no Machine of a held Assembly binds (the
+  current one's, and every one a live run holds,
+  [ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)) and no run has attached
+  within its TTL; the cache agent removes the node copy on CR deletion, once no pod on that node mounts it.
+
+## Considered options
+
+- **Image volumes** (each repository generation packed as an OCI artifact, mounted by kubelet): gives per-node cache,
+  scheduling, and GC for free, and immutability makes the gc invariant structural. Rejected: a refresh is a new layer
+  per fetch, so packs accumulate until a repack, and a repack is a full re-upload and a full re-pull on every node — the
+  re-clone cost a mutable bare repo never pays. Immutability bought only what gc pinning already buys.
+- **A per-repo PersistentVolume.** Rejected: an RWO volume still binds to one node at a time; it changes nothing about
+  pinning, only the number of volumes.
+- **Keep the shared PVC, require RWX storage for multi-node.** Rejected: scales the storage, not the fetch, and makes
+  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.
+
+## 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).
+- `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
+  composes a Sandbox", read off the walk, not "config has repos". That switch decides what `jr2 up` DEPLOYS for
+  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.
+- 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.
+- 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
+  run's declares it per-run and the consumer leaves it alone. Which slots a consumer may fix is the package author's
+  call, expressed by the slot's state.

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

@@ -0,0 +1,81 @@
+# A Sandbox lands where an ordinary pod lands, and the cache follows it
+
+[ADR-0051](0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md) made a Sandbox schedulable on any node and
+put a Repo cache agent on every node as a DaemonSet that tolerates every taint. The grill of 2026-09-13 found the two
+halves disagreeing about which nodes matter: the Sandbox pod carries no tolerations and no selector, so it lands only
+where an ordinary pod lands, while the cache agent probes and clones on control-plane and GPU nodes no Sandbox can reach
+— and a `present` cache there scores a node the scheduler cannot use. Meanwhile
+[ADR-0045](0045-the-platform-joins-the-image-address-and-the-cluster-chooses-it.md) read a third set (every node not
+cordoned) to choose build platforms, and nothing in `jr2.config.ts` could say which nodes an Instance's Sandboxes may
+use. **Which nodes are an Instance's Sandbox nodes, and who follows that set** is one decision.
+
+## Decision
+
+- **A Sandbox node is where an ordinary pod lands. There is no jr2 node label.** A node is a Sandbox node when it is not
+  cordoned, matches the Instance's `sandbox.nodeSelector`, and carries no taint the Instance's `sandbox.tolerations` do
+  not tolerate. With no config that is exactly the default scheduler's answer: taints already express "not for ordinary
+  work" for every workload on the cluster, so jr2 reads them instead of asking for a second, jr2-only opt-in that every
+  kind cluster and every fresh pool would have to perform before `jr2 up` could work.
+- **The override is Instance-level and raw Kubernetes**: `sandbox: { nodeSelector?, tolerations? }` in `jr2.config.ts`,
+  pod-spec shapes verbatim, the stance `harness.env` takes for `EnvVar`. A node label or taint is a deployment fact a
+  Machine cannot know (ADR-0050), so it lives in the file that holds deployment facts. No `affinity` key: the operator
+  owns the Sandbox's affinity (the soft preference toward nodes holding its Repo caches), and a user preference beside
+  it would need a merge rule for a case no cluster has asked for. A requirement (`nodeSelector`) never conflicts with a
+  preference, so the two sit side by side untouched.
+- **One predicate, three readers.** The Sandbox pod, the cache-agent DaemonSet, and `jr2 up`'s summary all use the same
+  `nodeSelector` and `tolerations`. The DaemonSet loses its blanket `operator: Exists` toleration: one cache agent per
+  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 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
+  is its own: the CR is namespaced, the DaemonSet is per Instance with a per-namespace hostPath, and the shared operator
+  holds no placement state. Version skew is ADR-0019's contract: an older operator would place a pod without the new
+  fields, and the `jr2 up` that introduces them is the one that upgrades the operator.
+- **An empty set warns; it never refuses.** `jr2 up` prints the Sandbox nodes it sees, and when there are none names
+  each node with the taint or selector that excluded it and the `sandbox.*` line that would admit it — then converges.
+  The set moves: a pool autoscales from zero, a node is cordoned mid-converge, a GPU box joins tomorrow. A refusal would
+  turn `jr2 up` into a point-in-time check of a moving set. The run-time truth is the operator's: a `Pending` Sandbox
+  reports the scheduler's own `FailedScheduling` message through its condition, so `jr2 status` shows the taint or
+  selector while the run waits (ADR-0048's pattern).
+- **A Machine says nothing about placement — for now.** A packaged `workspace()` that needs a GPU cannot write the
+  consumer's label (the encapsulation gap ADR-0049/0051 closed for Agents and Repos). The extension, when a Machine
+  needs it, is a named class: `workspace(body, { node: "gpu" })` and
+  `sandbox: { classes: { gpu: { nodeSelector, tolerations } } }`, refused by `jr2 up`'s walk when unmapped — the Repo
+  Slot pattern. `sandbox.nodeSelector` and `sandbox.tolerations` are that shape's default class, so the extension adds
+  `classes` beside them and renames nothing; and because placement rides the CR, a per-Machine class needs no new
+  plumbing. A class is placement only: how big a Sandbox is belongs to the Machine, not the cluster, and rides the
+  `workspace()` as its Size ([ADR-0060](0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)).
+  `sandbox.resources` sits beside `nodeSelector` and `tolerations` as the Instance's default Size, for a Workspace that
+  states none.
+
+## Considered options
+
+- **A jr2 label** (`jr2.dev/sandbox=true` on nodes that opt in). Rejected: every cluster pays a labeling step before the
+  first `jr2 up`, a single-node kind cluster included, and a labeled node is a candidate for every Sandbox — a GPU node
+  labeled for one Machine hosts all of them. Taints already say what the label would, for every workload at once.
+- **A jr2 vocabulary** (`sandbox.nodes: ["node-4"]`, or `pool: "workers"`). Rejected: simpler to type and wrong on the
+  first autoscaled pool, where node names are not stable and "pool" is a cloud provider's word with a different label on
+  each.
+- **The operator reads placement from a per-Instance object** (a ConfigMap, or the DaemonSet's own template) instead of
+  the CR. Rejected: a second read per reconcile and a cross-object dependency the CR does not declare, for no gain — the
+  CR already carries everything else the pod needs.
+- **Refuse `jr2 up` on an empty set**, the ADR-0051 stance for an unbound slot. Rejected: a slot is a static fact of the
+  code; the node set is a fact of the cluster right now.
+- **Keep the DaemonSet on every node.** Rejected: a cache on a node no Sandbox reaches is a clone nobody reads, a probe
+  that fails on a control-plane node's egress rules, and an affinity term the scheduler cannot honor.
+
+## Consequences
+
+- ADR-0045 is rewritten in place: "schedulable nodes" is the union above, and the `platforms` escape hatch's "polluted
+  set" case narrows to an untainted pool of a foreign arch — a tainted GPU pool is no longer counted.
+- ADR-0051 is rewritten in place: the cache agent is a DaemonSet over the Sandbox nodes, not every node.
+- The DaemonSet controller auto-tolerates `node.kubernetes.io/unschedulable`, so a cache agent also sits on a cordoned
+  Sandbox node. Harmless: the scheduler ignores the soft affinity toward a node it cannot use.
+- A Sandbox node of a NEW architecture that joins after a converge meets a Sandbox Image the cluster never built for it
+  and fails with `exec format error` until the next `jr2 up` — as any node did before this ADR; `platforms` is the
+  answer for a pool that autoscales from zero.
+- The Orchestrator and operator Deployments keep their own placement; `sandbox.*` names Sandboxes only.
+- A `NoExecute` taint an Instance tolerates on the Sandbox pod is tolerated verbatim: jr2 adds no `tolerationSeconds`,
+  so a Sandbox stays through the taint for as long as its Lease is renewed (ADR-0021).

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

@@ -0,0 +1,111 @@
+# A fetch inside the pod asks the node cache, and the cache asks the remote
+
+[ADR-0051](0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md) made the node cache the only thing that
+fetches from a remote, and left one consequence standing: stale stays stale from inside the pod until the interval or
+the next attach. The only ask a cache agent understood was a pod's birth — `asked` is the newest pod's creation time,
+and a Sandbox is `Ready` once its caches were fetched after its CR was created. Nothing after birth could ask: no CLI,
+no route out of the pod, no body primitive. The grill of 2026-09-13 took the concrete case — a human pushes a fix to
+`master`, the coder at `request_changes` must rebase onto it now, and the human in the User Container of the same pod
+wants the same commit — and found that a five-minute interval is not a freshness model, it is the absence of one. **How
+a fetch inside a pod reaches the remote, and who may ask** is one decision.
+
+## Decision
+
+- **`origin`'s fetch url is a command, not a path.** The attach sets it to git's built-in `ext::` transport, an absolute
+  program on the runtime volume with the Repo's identity as its argument:
+
+  ```
+  ext::/opt/jr2/bin/jr2-upload-pack %S github.com/acme/app
+  ```
+
+  Git runs the program and bridges stdio, so the program owes no remote-helper protocol: it asks for a fetch, waits for
+  the landing, then execs `git upload-pack /repos/<key>` and gets out of the way. Git speaks its ordinary protocol and
+  prints its ordinary output; refs update once, at the end. What the caller sees is a fetch on a slow handshake, never
+  an early return and never a partial state. `git fetch`, `git pull`, `git ls-remote origin`, and `git fetch --dry-run`
+  all pass through it, so every fetch inside a pod is a fetch of the remote's now. `git archive --remote=origin` is the
+  one other read git asks a remote for, and the program serves it the same way — the same ask, then `git upload-archive`
+  against the same cache — because the path url served it and a decision about fetching may not quietly take it away.
+  Nothing else in git talks to a remote, so `status`, `log`, and `rebase` stay local. The push url is unchanged: the
+  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 /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
+  writes. The operator copies it onto the pod as it copies everything else the pod needs from the CR, and the cache
+  agent's `asked` becomes the later of the pod's creation and its ask for that key. Demand stays read off pods alone.
+  The mark is a coalescer: however many fetches are in flight before one lands, the remote is fetched once, and a fetch
+  that started before the ask does not satisfy it — the agent stamps `lastFetched` with the attempt's start, which is
+  what makes that true.
+- **The landing is reported on the Sandbox, standing and per key.** The verdict the operator already computes on the way
+  to `Ready` — fresh, stale with git's error, or still cloning, per Repo, against the CR's creation — becomes a standing
+  entry on the Sandbox status computed against the later of creation and the ask. `Ready` itself stays as it was:
+  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.
+- **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.
+- **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
+  Container beside `/repos`. `ext::` names the program by absolute path, so the seat needs no PATH and jr2 injects no
+  env; the program is a static binary, the `work-acl` rule (ADR-0037), because it executes on a libc jr2 does not
+  control. A human in the User Container gets the same `git fetch` as the Agent, with no credential of their own; the
+  human `exec`'d into the Harness container already had it.
+- **Names.** `fetch` is what an Agent, a human, and a cache do; `refresh` is what the interval does and stays on
+  `refreshInterval`; an _ask_ is the mark, the word the agent and the operator already use. The url carries the Repo's
+  identity, never the cache key — a key is a derived directory name, never chosen by a human (ADR-0004), and not the
+  name a human should read in `git remote -v`.
+- **What stays.** An attach still fetches before it runs, because a creation is an ask. The interval still runs, so a
+  cold attach and `jr2 status` stay honest without anyone asking. There is no CLI verb: the human who wants the fetch is
+  in the pod, where `git fetch` is the verb, and the mark makes a `jr2` verb additive if a caller outside the pod ever
+  needs one.
+
+## Considered options
+
+- **The run asks** — a body primitive before a Turn, or on `request_changes` re-entry, the way attach asks on entry.
+  Rejected as the only path: it covers what the author foresaw and nothing an Agent discovers mid-Turn. Not foreclosed:
+  the mark is the substrate, and a body primitive that sets it is additive.
+- **A Menu pick** (`need_fresh`, declared with `defineEvent`, a `fetching` state the pick transitions to). Rejected: a
+  Turn boundary per fetch, an author opt-in per state, and a transition for something that moves the Machine nowhere. A
+  fetch is not part of a Machine's Vocabulary.
+- **A named Menu tool** (`mcp__jr2__fetch` beside the Menu's events). Rejected: the model must learn a tool and remember
+  to call it before the verb it already knows, and a human at a shell gets nothing from it.
+- **Shorten the interval.** Rejected: polling per node per Repo, and the latency is still the interval.
+- **The ask on the Repo CR.** Rejected: every node holding the cache fetches, and the wait must then name a node.
+- **The cache agent reads Sandbox CRs.** Rejected: two sources of demand where one exists, and a new RBAC grant for the
+  DaemonSet, to save one copy the operator makes for every other field.
+- **A `jr2::` remote helper found on PATH.** Rejected: PATH is env, the User Container gets none (ADR-0005), and an owed
+  image line where `ext::` costs nothing but a longer line in `git remote -v`.
+- **The human's credentialed fetch pushed into the cache.** Rejected: the cache is read-only in the pod by design, the
+  structural half of the gc invariant (ADR-0004). And moot: with this decision the human's own credential is not needed
+  for a fetch at all.
+- **Fail the fetch when the remote fails.** Rejected: attach chose availability (ADR-0051), and the Agent's `git fetch`
+  would become less reliable than today, where it always succeeds against the cache.
+
+## Consequences
+
+- ADR-0051 is rewritten in place: "stale stays stale from inside the pod" is retired; a stale attach is stale until the
+  next fetch anyone inside the pod runs. ADR-0005 is rewritten in place: "`git fetch origin` reads the node cache" is
+  now "asks the node cache", the User Container mounts `/opt/jr2` read-only beside `/repos`, and "nothing injected"
+  narrows to the seat's process — no env, no command, no probe. ADR-0004's refresh section gains the in-pod ask.
+- The runtime volume carries a second static binary, and so a jr2 program is present in every seat of every Workspace
+  pod, User Container included. It is the natural home for in-pod jr2 functionality that does not yet exist.
+- A fetch inside a pod is a remote round trip through the node agent, seconds rather than milliseconds. Every git
+  command that fetches pays it; none that does not.
+- The Sandbox status grows a standing per-key Repo entry; the Custodian carries one loopback route for it; the
+  Orchestrator gains a Sandbox-token route. No new credential, no new watch in the cache agent, no git knowledge in the
+  operator beyond the timestamp comparison it already makes.
+- The rewind gotcha vanishes: a human who fetched around the cache with their own credential advanced a remote-tracking
+  ref the Agent's next cache fetch forced back. Nobody fetches around the cache now.
+- The Harness `bash` tool's own timeout still bounds a fetch the way it bounds any slow command.

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

@@ -0,0 +1,126 @@
+# The kit ships Machines, and a shipped Machine leaves its parts Open
+
+The kit's only worked Machines lived in `examples/`: two model Instances, one of them (`coding`) four workflows deep,
+written against surfaces three ADRs old, runnable by nobody but the author, and installable by no one — an example is
+copied, never imported. ADR-0049 had already settled that "a package exports a Machine, nothing beside it" and ADR-0019
+that "reusable work is published as npm packages", yet the kit itself shipped none, so the packaged-Machine story had no
+first instance to hold it honest. The grill of 2026-09-14 replaced the examples with a package, and in doing so found
+the one part ADR-0049/0051 left a package unable to leave unsaid: **the model.**
+
+## Decision
+
+- **The kit ships Machines as `@jr2/machines`.** A fourth published package beside
+  `@jr2/{cli,orchestrator,agent-protocol}` (ADR-0043), on the same release train, exporting named Machines from its
+  index: `import { task } from "@jr2/machines"`. It ships Machines and never Workflows — a Workflow is the name an
+  Instance registers a Machine under, and only the Instance's `workflows/` file can do that (GLOSSARY.md, ADR-0009).
+  Rejected: `@jr2/workflows` — it names exactly the thing the kit does not ship, and `workflow` is on Machine's
+  avoid-list for the reason ADR-0049/0050 lean on the distinction.
+- **`@jr2/machines` authors against the consumer's `@jr2/orchestrator`: peer dependencies, no regular ones.** Every part
+  a Machine carries is keyed in maps `@jr2/orchestrator` holds (vocabulary.ts, parts.ts) and in `xstate`'s own `provide`
+  and `isMachine`; a second copy of either is a Machine whose Menus are empty and whose Gates accept nothing, with no
+  error anywhere. `peerDependencies: { "@jr2/orchestrator": <exact kit version>, xstate, zod }` states the fact and is
+  the shape a user's own Machine package copies. Rejected: regular deps at the exact version — dedupe makes it work by
+  the accident of equal versions and installs two copies silently on skew.
+- **A shipped Machine leaves its parts Open, and Open widens from the Repo Slot to the Agent's model.** ADR-0051's
+  `open` sentinel — "a consumer's to bind, with `customize`" — applies unchanged to the one part a package cannot
+  honestly fill: `agent({ model: open, instructions })`. The `jr2 up` walk reports an Open model beside Open Repo Slots
+  and refuses the converge naming the `customize` line that binds it; the Agent actor refuses to admit a Turn whose
+  definition is still Open, as the second fence. `AgentDefinition` stays the wire type with `model: string` — a Symbol
+  does not ride a Turn — and `agent()` takes a declaration whose `model` is `string | typeof open`. The sentinel becomes
+  `Symbol.for("jr2.open")`. Rejected: a stock default model — the kit picks a vendor in a published package, and a user
+  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
+  ([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.
+- **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
+  four lines.
+- **The first Machine is `task`: one prompt, one Workspace, one human says done.** Door
+  `{ prompt, branch?, model?, thinkingLevel? }`, branch defaulting to `jr2/task-<instance id>`, where `<instance id>` is
+  the seed Instance ID of the run (`instanceId` in `jr2 status`), not the run id; the Repo Slots Open as a map
+  (`repos: open`, ADR-0051) — the consumer names them, and the order is `task`'s own convention, since jr2 gives no slot
+  a meaning: the first is where the coder works, any others are checkouts the first Turn frames for the coder to read;
+  one Agent `coder` with an Open model. `working` invokes `coder`; its `finish { summary }` parks at the `review` Gate
+  (meta: summary, branch, worktree), as does a terminal `agent.fault` (meta: reason). `approve` reaches the final state
+  and tears the Workspace down; `request_changes { notes }` **continues the same conversation** (`continue: true`,
+  ADR-0057) — one human steering one Agent wants the Agent to remember what it did, unlike ADR-0049's coder⇄reviewer
+  handoff, which is lossy on purpose. No round cap: the human is the cap. Rejected: a per-run Repo on the door — a
+  packaged door cannot enumerate the Instance's repos, and "a Workflow is a name" reads best when the name means "a
+  prompt against THIS repo". Rejected: a named `target: open` slot — the body reads the first checkout the handles
+  carry, never `repos.target`, so the name claimed a shape the body did not have and shut out the one thing a task
+  commonly wants beside its repository: another checkout to read.
+- **The Machine does not push.** ADR-0005/0053: the Agent holds no credential and the push url is the caller's own
+  spelling with the caller's own credential. The Gate park is the inspection window — exec in, review, push, then
+  `approve`, and unpushed commits go with the pod, as ADR-0012 always said. A credentialed push out of the pod is a
+  decision of its own, not this one.
+- **`examples/` retires; `templates/default` is the one Instance in the checkout.** The scaffold's model moves from
+  `examples/starter` to `templates/default` — the folder documents what an Instance looks like and is what `jr2 init`
+  renders, kept byte-equal to the CLI's inline templates by the existing drift test, since an installed CLI cannot read
+  a repo-root folder (ADR-0043). `templates/` is plural because a later `jr2 init --template <name>` is the obvious next
+  step. The scaffold stays `ping`-only — the `@dist` tier's contract is a fresh instance that runs before any provider
+  or repo exists — and `ping.ts`'s prose shows the `@jr2/machines` move as the next step instead of an inline `agent()`
+  sketch. `examples/coding` is deleted whole, `jr.ts` included;
+  [An Agent in a Sandbox](../../get-started/an-agent-in-a-sandbox.md) shows `task` in its place.
+
+## Consequences
+
+- **Every Machine in `@jr2/machines` ships with a `@kind` scenario.** These are for end users, and the only proof a
+  shipped Machine works in jr2 is the stock Harness driving it in a real Sandbox. `features/kind-instance` registers
+  each one the way a consumer would — `customize(task, { repos, agents })` over the tier's fixture repo and scripted
+  model — and the scenario walks its Gates. The socket-free mechanics test beside the Machine covers the default
+  `pnpm -r test` gate; it does not stand in for the scenario.
+- `@jr2/machines` joins the `PUBLIC` list in `publish.test.ts` and the guard loop in `scripts/dist-publish.sh`; the
+  `@dist` tier publishes it to verdaccio, so its pack and `files:` list execute there even though no `@dist` scenario
+  runs it.
+- GLOSSARY.md gains **Open** as a term, and the Workflow entry says the kit ships Machines. Eleven earlier ADRs cite
+  `examples/`; the citations are retargeted in place.
+- A `customize` that binds a model is now the common consumer line, not the exotic one; `jr2 up`'s refusal for an Open
+  Agent prints it, as it does for an Open Repo Slot and an Open Effect (its `effects` line).
+- No Machine in `@jr2/machines` leaves an Effect Open yet; `task` carries no Effect.
+- Two copies of one Machine spend two teams' secrets: each composer binds the Open secret, or a url that carries one in
+  its path, with its own. A labelled form for two Open secrets in one Effect can be added later without changing the
+  unlabelled one.
+- The `triaged-task` mechanics test went with `examples/coding`, and the cross-Machine conversation pin it exercised
+  went with ADR-0057; the `@kind` `consulted`/`advised` fixtures hold Instance Harness placement.