@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/decisions/0045-the-platform-joins-the-image-address-and-the-cluster-chooses-it.md

@@ -0,0 +1,82 @@
+# The platform joins the image address, and the cluster chooses it
+
+[ADR-0038](0038-jr2-up-builds-every-image-it-deploys.md)'s invariant — every tag is a content address, so "present
+implies current" — hashed the build's **inputs** and nothing else. But the bytes are a function of (inputs × platform),
+and no build passed `--platform`: the daemon default (or a remembered `DOCKER_DEFAULT_PLATFORM`) decided silently. So
+one tag named an amd64 or an arm64 image depending on who built it last, and both skips that rest on tag equality — the
+cluster record and [ADR-0041](0041-a-build-the-host-already-holds-is-not-spent-again.md)'s host-held listing — delivered
+an amd64 Sandbox Image to an arm64-only cluster, surfacing as an opaque rollout timeout (`exec format error`, found only
+by hand). The hole is in ADR-0038's core invariant, and it covers every image `jr2 up` builds — Orchestrator, Sandbox,
+and the checkout-mode kit three. Published Kit images were already immune
+([ADR-0044](0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md): multi-arch manifest lists, mirrored
+whole).
+
+## Decision
+
+- **A tag names (inputs × platform set), and says so visibly**: `<repo>:<hash>-<arch>` —
+  `jr2-sandbox-x-default:4a77b1-arm64`, and `…:4a77b1-amd64-arm64` for a multi-platform build (sorted, joined). In the
+  tag, not the salt: the triggering failure was invisible precisely because the tag did not say, and a self-describing
+  tag is diagnosability applied at the naming layer. Every `docker build` passes `--platform` explicitly — the daemon
+  default and `DOCKER_DEFAULT_PLATFORM` stop being steering, which deletes the manual step whose forgetting was the
+  failure.
+- **The cluster's nodes choose the platform set.** `jr2 up` reads the schedulable nodes' `.status.nodeInfo.architecture`
+  — the union of the nodes an ordinary pod lands on (the Orchestrator's placement) and the Instance's Sandbox nodes
+  (ADR-0052), so a tainted pool no Sandbox reaches is never built for — and intersects with the **supported set** — the
+  platforms the kit releases for (`linux/amd64`, `linux/arm64`), one constant beside `KIT_IMAGES` that `just kit-push`
+  builds from too, so the two cannot drift. A node arch outside the supported set is reported and skipped, never built
+  for: a Sandbox Image for `s390x` is dead weight, since no kit image could sit beside it in the pod. An empty
+  intersection is a loud error. Reading a singleton set is not an assumption; only a non-singleton set involves
+  judgement, and that case builds rather than guesses (next bullet).
+- **A multi-arch node set gets a multi-arch build**: `docker buildx build --platform <set> --push`, the `just kit-push`
+  mechanism. This path only ever runs where it can deliver, **by construction**: a mixed-arch cluster is never kind
+  (kind nodes are containers on one host, one arch), and the non-kind transport branch already requires `registry` — so
+  buildx pushes to the registry that must exist, and `kind load` never meets a manifest list. The singleton set keeps
+  the plain single-`docker build` and the existing transport branch.
+- **`platforms` is the one escape hatch** — a deployment-varying config key (env-carried, like `registry`) holding
+  docker platform strings. **Absolute**: when set, derivation is skipped and the list is the build set — still
+  intersected with the supported set, so `s390x` gets the same named error. It exists for the two cases derivation
+  cannot see: autoscale-from-zero (the target pool has no nodes yet) and set pollution (an UNTAINTED amd64 pool beside
+  arm64 workers costs a needless qemu build; the key trims it — a tainted one is already outside the set, ADR-0052). Not
+  additive/subtractive — cleverness the rare case does not earn.
+- **Foreign-arch builds are preflighted.** When the build set contains a platform the host cannot run natively, `RUN`
+  steps need binfmt emulation; without it docker fails mid-build with the same cryptic `exec format error` this ADR
+  exists to delete. So the converge checks emulation is available before spending any build, and the error names the fix
+  (`docker run --privileged --rm tonistiigi/binfmt --install <arch>`).
+- **The host-held skip is honest again — where it can answer at all.** For singleton builds the tag now names the
+  platform and jr2 always built with an explicit `--platform`, so tag-equality on the daemon once more means "present
+  implies current". A multi-arch ref never lands in the daemon (buildx `--push` goes straight to the registry), so the
+  host skip cannot answer for it and a record-silent mixed-arch converge rebuilds — the accepted cost; ADR-0041's
+  rejection of registry-truth HEAD checks stands.
+- **`imageUser` follows the artifact**: `docker inspect` on the daemon-held singleton build;
+  `docker buildx imagetools inspect` against the registry for a manifest list.
+
+## Considered options
+
+- **Multi-arch by default** (every converge, like `just kit-push`). Rejected: nodes in one cluster are almost always one
+  arch, so every everyday converge would pay a qemu cross-build to serve the rare mixed case — and `kind load` cannot
+  deliver a manifest list from the daemon, so the no-registry path would die or fork the transport branch. Multi-arch
+  survives as the _derived_ answer for the set that actually needs it.
+- **Preflight the mismatch only** (compare built image arch to node arch, then say so). Rejected as the whole fix: it
+  diagnoses instead of prevents, and the tag stays a lie — the ADR-0038 invariant keeps its hole and the stale host-held
+  image still needs `--force` folklore. The comparison survives inside the converge-failure diagnosis (ADR-0046) as
+  belt-and-braces messaging.
+- **Platform in the hash salt, not the tag.** Rejected: honest but invisible — two tags would differ inexplicably, and
+  the class of failure this ADR closes was an invisibility failure.
+- **Explicit-only** (`platforms` required, no derivation). Rejected: taxes every single-arch user — the overwhelming
+  case — with a key they should not need, inverting "the CLI does all the work".
+- **Keep `DOCKER_DEFAULT_PLATFORM` as the steering mechanism.** Rejected: an env var the user must remember is the class
+  of manual step jr2 deletes, and forgetting it was the failure.
+
+## Consequences
+
+- ADR-0038's "every tag is a content address" is **amended**: the address covers (inputs × platform set). All five built
+  image kinds take the suffix — one mechanism, no exceptions.
+- ADR-0041 is **amended**: tag-equality on the host daemon is sound again because the tag names the platform; a
+  multi-arch ref is invisible to the host skip by construction.
+- ADR-0044's consequence — "the cross-build workaround of exporting `DOCKER_DEFAULT_PLATFORM` for checkout-mode
+  converges against a foreign-arch cluster is unaffected" — is **superseded**: the workaround is deleted, `--platform`
+  is derived and explicit.
+- A converge gains one cheap read (`kubectl get nodes`) it mostly already pays in spirit; steady-state skips still spend
+  directory walks and no docker.
+- Old un-suffixed tags never collide with new ones (the suffix is always present), so pre-0045 images age out through
+  ADR-0039's sweep — no migration.

package/docs/reference/decisions/0046-a-converge-failure-carries-its-diagnosis.md

@@ -0,0 +1,34 @@
+# A converge failure carries its diagnosis
+
+The failure that produced [ADR-0045](0045-the-platform-joins-the-image-address-and-the-cluster-chooses-it.md) surfaced
+as `error: timed out waiting for the condition` — kubectl's verdict and nothing else. The cause (`exec format error` in
+a CrashLoopBackOff pod) was found only by hand-running `kubectl get pods` and `kubectl logs`. The repo already holds the
+precedent for what should have happened: `oneShotFailure()` (kube.ts) rethrows a one-shot probe's failure with the pod's
+own output in front of kubectl's verdict, because the line that says WHY is exactly what the verdict drops. The rollout
+wait is the same failure one layer up, and `jr2 up` runs three of them (operator, Orchestrator, Instance Harness), all
+equally blind.
+
+## Decision
+
+- **On rollout failure, the error carries the evidence**: for the deployment's pods — phase, container waiting reasons,
+  the last events, and a container log tail — gathered after the timeout and rethrown in front of kubectl's verdict. One
+  `rolloutFailure()` beside `oneShotFailure()`, used by all three rollout waits, so every layer gets the same eyes.
+- **Named diagnoses annotate the evidence, never replace it.** A small pattern table layered on top names the cause and
+  the way back when it matches: `exec format error` → "image platform X, node platform Y" plus `platforms`/`--force`
+  (belt-and-braces under ADR-0045, and the only trace left for pre-0045 images and registry-ref Sandbox Images jr2 never
+  built); `ImagePullBackOff`/`ErrImagePull` → the ref and the registry it resolved to (the `docker.io/library/`
+  normalization trap); `CrashLoopBackOff` → lead with the log tail, which IS the diagnosis; `CreateContainerConfigError`
+  → name the missing object (already preflighted for `envFrom` Secrets — this catches what slips past). The hard rule
+  that keeps the table honest: a named diagnosis may only interpret evidence that is also printed raw beneath it — a
+  table that swallows evidence turns a wrong match into a lie; one that annotates it costs nothing when wrong.
+- **Scope: the rollout wait only.** A converge that never reaches a rollout (config error, build error, apply error)
+  keeps its existing errors — no general "dump the namespace on any error" reflex. Those failures already name
+  themselves; the rollout timeout was the one that did not.
+
+## Considered options
+
+- **Evidence-only** (no pattern table). Rejected: the user still translates `exec format error` into "platform mismatch"
+  themselves, which is the folklore step this ADR exists to delete. The table is small, bounded, and each entry is a
+  failure someone actually hit.
+- **Diagnosis as a separate command** (`jr2 doctor`-style, run after the failure). Rejected: the moment of failure is
+  when the evidence is fresh and the user is looking; a second command is the by-hand loop with a jr2 badge on it.

package/docs/reference/decisions/0047-the-git-ssh-key-source-is-the-users-choice.md

@@ -0,0 +1,47 @@
+# The git ssh key source is the user's choice
+
+[ADR-0019](0019-one-converging-command-against-the-current-context.md) drew a flat line — "personal keys never enter a
+cluster" — and gave ssh repos exactly one path: `jr2 up` generates an in-cluster deploy keypair and prints the public
+key to register. The line had a cost the flow could not pay: GitHub allows one deploy key on exactly one repo, so a
+multi-repo instance means N registrations, and re-using the printed key across repos is rejected — the flow pushed users
+toward machine accounts or hand-rolled Secrets anyway. A key already registered with the git host makes that friction
+zero. The invariant is demoted to a default: jr2 never lifts a personal key silently, but the user may hand one over,
+warned and on purpose.
+
+## Decision
+
+- **Three sources, one prompt**, when `up`'s walk of the registered Machines finds an ssh url on a bound Repo Slot
+  (ADR-0051) whose matching `git.credentials` entry names an `sshKey` Secret that does not exist (the scaffold's
+  wildcard entry names `jr2-git-ssh`): **generate a fresh in-cluster deploy keypair** (recommended, listed first,
+  today's behavior); **use a local key** (discovered `~/.ssh` candidates plus "other path"); or **paste one on stdin,
+  hidden**. Declining all three bails, as before — the cache agent would only fail on an unauthenticated clone later. A
+  per-run slot's url is not on the walk and is never prompted for: an ssh url first seen at attach fails that attach
+  with the key hint, as any unregistered key does. The scripting escape stays kubectl: create the Secret yourself,
+  `kubectl create secret generic jr2-git-ssh --from-file=identity=…` — the Secret carries Flux's key names
+  ([ADR-0051](0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)), and the cache agent reads no other.
+- **`--yes` means generate.** Non-interactive mode never selects a personal key — the dangerous option is never a
+  default. There is no `--git-ssh-key` flag: a scripted supplied-key path is the kubectl escape.
+- **A passphrase-protected key is refused by name** — the in-cluster clone cannot answer a passphrase — detected with
+  `ssh-keygen -y -P ""` before anything is applied. Decrypting and storing plaintext would silently strip protection the
+  user chose to have.
+- **The supplied-key paths warn at choice time**: the key lands in a namespace Secret, readable by anyone with Secret
+  read there and at rest in etcd — a generated deploy key leaks read access to some repos; a personal key leaks
+  everything it can reach. The public half (`identity.pub`) is derived via `ssh-keygen -y`; output prints the
+  fingerprint, never key material.
+- **The generate path pauses at the moment of truth.** The printed key is useless until registered, and an unregistered
+  key makes the repo sync fail ([ADR-0048](0048-the-orchestrator-boots-without-its-repos.md) keeps that from crashing
+  the boot). So interactively, `up` prints the key and waits: "register this public key with your git host, then press
+  enter to continue" — the wait sits exactly where the user must act anyway. `--yes` proceeds without pausing, and any
+  converge that generated a keypair **ends** by repeating the warning: the key, the repos that will not sync until it is
+  registered, and that the cache agent retries on its own.
+
+## Considered options
+
+- **Keep the invariant, improve the messaging.** Rejected: the multi-repo friction is structural (one deploy key, one
+  repo), not informational — no message makes N registrations cheaper than zero.
+- **Agent forwarding instead of copying** (the ADR-0005 pattern for Sandbox sessions). Rejected here: the cache agent
+  fetches unattended, in-cluster, on a schedule the user is not present for — forwarding authenticates a session, not a
+  daemon.
+- **A `--git-ssh-key <path>` flag.** Rejected: it makes the personal-key path scriptable, which is exactly the silent
+  lift the prompt exists to prevent; the kubectl escape already serves automation, with the user's own tooling holding
+  the key.

package/docs/reference/decisions/0048-the-orchestrator-boots-without-its-repos.md

@@ -0,0 +1,36 @@
+# The Orchestrator boots without its repos
+
+The Orchestrator's boot-time repo sync was awaited before the server served: a repo that could not clone — an
+unregistered deploy key, a wrong url, a git host outage — threw, the container exited, and the kubelet crash-looped the
+Orchestrator. So one unreachable repo killed the daemon that hosts every Workflow, including ones that never touch a
+repo, and a first converge with a freshly generated deploy key
+([ADR-0047](0047-the-git-ssh-key-source-is-the-users-choice.md)) was guaranteed to time out its rollout unless the user
+registered the key inside the wait. The codebase already names the correct blast pattern, four lines below the
+violation: a missing `jr2-images` ConfigMap does not stop the boot — the instance serves, and only a provision fails,
+pointing at `jr2 up`.
+
+## Decision
+
+- **A failed repo sync does not stop the boot.** The Orchestrator boots, serves, and creates the `Repo` resources its
+  Machines bind ([ADR-0051](0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)); it does not sync them.
+  The operator's cache agent clones and fetches each onto its node, retries a failure with backoff, and writes every
+  result — synced, or git's own error — to the resource's status. The same blast pattern as the images ConfigMap —
+  degrade the capability, not the daemon.
+- **A Workspace provision needing an unsynced repo fails pointedly**, naming the repo and the last sync error — the
+  moment the degradation actually bites is the moment it is reported, to the run that owns the consequence. The line is
+  the clone (ADR-0051): a cold node whose clone fails fails the provision; a warm cache whose fetch fails lets the
+  attach proceed on the objects it holds, announced as stale with git's error. The pod cannot heal it — the worktree's
+  `origin` fetches from the cache (ADR-0005) — so stale lasts until the cache agent's next successful fetch, which the
+  Agent's own `git fetch` then picks up in place.
+- **Repo sync state is observable**: it lives on each `Repo` resource's status, per node, and `jr2 status` reports repos
+  that are not synced with their last error — the place ADR-0047's "register the key, the cache agent retries" points
+  at.
+
+## Considered options
+
+- **Fail-fast boot, kept.** Rejected: a boot failure is invisible except as a rollout timeout, reported to whoever
+  converged, not whoever needs the repo — and it takes unrelated Workflows down with it. Fail-fast is right when serving
+  would be wrong; an Orchestrator without one repo serves everything else correctly.
+- **`jr2 up` verifies the clone before finishing.** Rejected: registration is a human act on an external system with no
+  deadline — a converge that waits on it hangs CI and re-runs teach nothing. The converge reports the window (ADR-0047);
+  the cache agent closes it on its own.

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

@@ -0,0 +1,126 @@
+# A Machine carries its parts and composes by invoke
+
+A workflow could not use another workflow's Machine as a child without re-declaring the child's events at its own root
+(the `triaged-task` example documented the workaround), and a Machine had no way to travel: its Agents lived in the
+Instance's roster by name and its Sandbox Image in the Instance's `images/`, so a packaged Machine depended on someone
+else's config holding the right strings. The grill of 2026-09-06/09 settled composition and packaging as one decision,
+because they are one problem: **what a Machine depends on that is not inside it.**
+
+## Decision
+
+- **Composition is Machine composition.** A workflow module imports another module's exported Machine and invokes it as
+  an xstate child (`actors: { deep, quick }`, `invoke: { src: "deep" }`). One run, one snapshot, one run id; the child's
+  Gates list under the parent's run and its emits ride the same feed. There is no sub-run and no
+  invoke-by-registered-name: a nested Machine is reached by `import`, never by the name `jr2 run` uses. Rejected:
+  Temporal-style child workflows with their own run ids — a new actor kind, cross-run correlation, and cancel
+  propagation, for no requirement that needs a second run id. A run that STARTS a run is not composition: it is the
+  `dispatch` Effect ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), by the name `jr2 run` uses, and
+  the two runs are independent. Two uses, two mechanisms.
+- **Everything a Machine depends on rides the Machine, scoped to it.** Vocabulary already did (ADR-0011, per-Machine
+  since this decision). The two remaining dependencies join it:
+  - **An Agent is an actor slot.** `jr2Setup({ actors: { researcher: agent({ model, instructions, … }) } })`, invoked as
+    `src: "researcher"` with `{ prompt, …dials }` as input. `agent(definition)` is `agentRun` closed over one definition
+    and branded with it; `agentRun` and `agent: "name"` leave the authoring surface. The typo check is xstate's own
+    `src` typing — a slot the Machine does not declare is a compile error with nothing added — and Stately shows
+    `researching → invoke researcher` instead of a uniform `agentRun`. Two Machines in one run may both carry a
+    `researcher`; each resolves against its own implementations, and the Instance ID's actor path keeps their
+    conversations apart.
+  - **An Effect is an actor slot too**
+    ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)), and its plain-data
+    parts ride the slot: the kind, where it runs, a `command`'s argv, an `http` Effect's method, fixed host and the
+    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, 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 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`
+  to publish the Assembly again, so the ConfigMap bought nothing a Machine-carried definition loses. Placement
+  (ADR-0031) reads `workspace: "none"` off the slot's definition.
+- **Parts resolve at invoke time through the live actor's logic, never a build-time closure.** `agentRun` finds its
+  definition in the logic it was invoked as; `provision` reads the image off the wrapper's parts map keyed on
+  `machine.config`. This is the one rule that lets xstate's `provide()` and customization coexist, and the same rule
+  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 } }`
+  — 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.
+- **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:
+
+  ```ts
+  export const machine = research;                                                            // as-is
+  export const machine = customize(research, { agents: { researcher: { model } }, image });   // retuned
+  const deep = customize(research, { agents: { researcher: { model: opus } } });              // nested twice,
+  const quick = customize(research, { agents: { researcher: { model: haiku } } });            // differently
+  export const machine = jr2Setup({ events: [route], actors: { triager: agent(triager), deep, quick } }).createMachine(…);
+  ```
+
+  A local `workflows/*.ts` is written exactly the same way; there is no package-side API.
+
+- **The wrapper's body is a named slot** (`invoke: { id: "body", src: "body" }` over `setup({ actors: { body } })`), and
+  `pool()`'s worker likewise. That is what lets `provide`, `customize`, Stately, and the `jr2 up` walk reach it
+  uniformly.
+- **A Part is a key of `actors`.** An `agent()`, an Effect (ADR-0067) or a `workspace()` written inline on an
+  `invoke.src` is refused at build (`jr2Setup.createMachine`) and at load (the walk), with the slot form in the message.
+  xstate gives an inline `src` a generated key (`xstate.invoke.<n>.<state id>`) that moves when a state is renamed, so
+  the ledger, `jr2 up`'s report and the Machine doc would name the Part by a number, and `customize()` — `provide`,
+  keyed on `actors` — could not reach it at all. A plain child Machine written inline is not a Part: the walk descends
+  it, with no `customize()` route below it.
+- **`jr2 up` walks the registered Machines** — `implementations.actors`, descending into child Machines — to collect
+  models to preflight and `file:` image contexts to build. A context is keyed by its content digest (the same digest
+  ADR-0038 tags by), taken over its copy in the staged Assembly, the bytes the Orchestrator holds
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)), so the host at `jr2 up`
+  and the Orchestrator agree without a path table even where staging dropped a `.env` or a `node_modules` the folder
+  holds. Repos are slots on the same walk (ADR-0051): a bound slot's url is collected, so its `Repo` resource is warm
+  before a run asks; an open slot nobody bound is refused, naming the Machine, the slot, and the `customize` line that
+  fixes it; a per-run slot is the run's business and the walk leaves it alone.
+
+## Consequences
+
+- **Agent identity moves from the Instance to the Machine.** GLOSSARY.md's Agent entry restates: an Agent is a part of a
+  Machine, not an Instance-scoped roster entry; `customize` is a definition-level act by the composer, so ADR-0018's
+  identity-vs-Dial line is untouched — a Turn still sets `model`/`thinkingLevel` and nothing else.
+- **A Workflow is a Machine registered under a name.** The "wired to its Agents and config" clause retires: the wiring
+  is inside the Machine.
+- `defineAgent` retires in favor of `agent()`; `AgentTurnInput.agent` goes; `deriveMenus` keys on agent-slot logic
+  instead of `src === "agentRun"`; the unit-test seam becomes `provide({ actors: { researcher: fake } })`.
+- Only declared parts can be customized; none can be added. A consumer who needs a third Agent composes a new Machine. A
+  `workspace()` that declares its Repo Slot map Open (`repos: open`, ADR-0051) has declared every slot as the composer's
+  to name, so the map they write is the declaration, not an addition.
+- **`import.meta.resolve` stays** in any Machine that ships a context; there is no other way for an ES module to name a
+  folder it owns.
+- The ledger records which slot a Turn ran as, not the definition's text. If per-Turn auditability of instructions is
+  ever needed, the admission marker can carry a definition digest.
+- `jr2 dev`'s reload cache-busts the workflow module only; an edit to an imported Machine module is not picked up until
+  the next full reload. Known, unaddressed here.
+- A `workflows/` file that is both discovered and imported by another registers as its own Workflow too; a Machine meant
+  only for composition lives in a `_`-prefixed file or outside `workflows/`.
+- A conversation belongs to one Agent slot in one Machine instance by construction — the continued iid is
+  `<run>/<machine actor path>/<agent>` (ADR-0057) — so no continuation can cross personas. What a continuation does NOT
+  check is that the definition behind the slot is the one that started it: a run whose `instructions` were edited before
+  a redeploy continues, which ADR-0030 deliberately allows (shape decides restorability, not behavior). A definition
+  digest on the ledger record would refuse exactly that, so it is not taken.

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

@@ -0,0 +1,73 @@
+# What code names, config declares; what the CLI names, discovery finds
+
+A Machine names things outside itself by string, and until now the first sign of a wrong string was an invoke-time
+failure mid-run. ADR-0049 moved Agents and Sandbox Images INTO the Machine — actor slots and a `workspace()` option — so
+those names are typed by xstate's own `src` typing and by the Machine's own parts. ADR-0051 moved the last one, the
+**Repo**, the same way: a slot on the `workspace()`, bound by url. What this decision fixes is the rule that says where
+a definition lives, and the gate that enforces it.
+
+## Decision
+
+- **One rule decides where a definition lives.** A thing that **code refers to by name** and that a Machine cannot carry
+  is declared in `jr2.config.ts`, so the type system sees the name. A thing that **only the CLI or HTTP API refers to by
+  name** is discovered from files. Workflows are the latter — `jr2 run` and `POST /workflows/:name/runs` name them, a
+  nested Machine is reached by `import` (ADR-0049) — so `workflows/` stays filename-discovered. Agents, images, and
+  Repos are neither: they ride the Machine (ADR-0049, ADR-0051), and the `agents/` folder, `config.agents`,
+  `config.images`, and `config.repos` all retire. One thing code names and a Machine cannot carry is a secret's value:
+  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`).
+- **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
+  `customize(machine, { repos: { <slot>: url } })` of a slot the Machine does not declare is a compile error, never a
+  silent widening to `string`, and the body's `workspace.repos.<slot>` handle is typed by the same keys. There is no
+  `Register`, no `RepoName`, and no `repoNames()`: the url a Machine writes is the thing, not a reference into someone
+  else's file (ADR-0051). A door that offers a menu of Repos is the Instance's own `z.enum` of urls.
+- **`jr2 up` typechecks the Instance before it builds anything**, and refuses on errors, naming them. The scaffold's
+  `tsc --noEmit` and pinned compiler already exist (ADR-0043's rule for the checker); this makes them a gate instead of
+  a script the user may run. A wrong slot name, a `customize()` of an Agent or a Repo Slot the Machine does not carry:
+  all stop here. One Repo check is converge-time and not compile-time: a registered Machine with an open slot nobody
+  bound. A `workflows/` export has no type to hang it on, so the walk that follows the typecheck refuses it, before it
+  builds anything, naming the Machine, the slot, and the `customize` line that fixes it (ADR-0051).
+- **`jr2 check` runs the gate and the walk with no cluster.** The typecheck and the walk are one function of the CLI,
+  `checkInstance`. `jr2 up` and `jr2 check` both call it, so the two give the same refusals with the same text. The walk
+  loads each registered module. Thus `jr2 check` also gives each refusal that a module throws when it loads. These are
+  refusals of `createMachine`, `defineEvent` and `workspace()`, and `npm run typecheck` cannot give them. `jr2 check`
+  reads no kube context. Thus an Assistant that may not run `jr2 up` can run it before it gives a change to the user. It
+  runs in a kit checkout and in an installed Instance. The name is the verb that a user types for "is this folder
+  correct". The glossary's _check_ of a Check pod is a different noun in a different place: one model call in the
+  provider preflight. Thus the name stays, and the glossary entry tells the two apart.
+
+## Considered options
+
+- **A generated declaration** (`jr2-env.d.ts` written by `init`/`up` from directory discovery), to keep `agents/` and
+  `images/` as folders and still type their names. Rejected: a generated-file class jr2 does not have, an editor
+  staleness window, and — decisive — ADR-0049 removed the need by making the names part of the Machine.
+- **Agents and images as config entries** (`agents: { scribe }`, `images: { default: "./images/default" }`), the shape
+  this ADR first took. Rejected the same day: it typed the names but kept them Instance-scoped, so a packaged Machine
+  still depended on someone else's config holding the right strings, and one run could not hold two Machines each
+  carrying a `coder`.
+- **A Repo catalog in config, typed back through a `Register` interface** (`repos: [{ name, url }]`, a `RepoName`
+  derived from `typeof config`, `z.enum(repoNames(config))` on a door), the shape this ADR took for the one dependency
+  it left in config. Rejected in ADR-0051 by the argument above: a packaged Machine still could not say which repository
+  it works on, and a consumer could bind one only by holding the right NAME. The slot key is the type now.
+
+- **A flag on `jr2 up`** (`jr2 up --check`, or `--dry-run`) in place of a verb. Rejected: `up` reads the kube context
+  first and its flags are converge flags; a flag that stops it after the walk still asks an Assistant to run the
+  converging verb, which a permission rule that forbids `jr2 up` also forbids. A verb is the line a permission rule can
+  allow.
+- **A copy of the walk in `jr2 check`.** Rejected: two walks drift, and then the check passes a folder that `jr2 up`
+  refuses — the failure that `jr2 check` exists to remove.
+- **Stage the Assembly in `jr2 check` too.** Rejected: staging runs a frozen install from the lockfile (ADR-0043), which
+  needs the registry and takes minutes, and its refusals are about the install, not the code an Assistant writes.
+
+## Consequences
+
+- Only Machines the Instance's program typechecks get the compile-time guarantee — those under `workflows/` and what
+  they import. A packaged Machine compiled elsewhere carries its own parts, so its internal names are checked where it
+  was built; the Repo it works on is an open slot the consumer binds with `customize`, typed by the package's own slot
+  keys, or a per-run slot typed by the consumer's mapper over the door.
+- Runtime validation stays: an open slot nobody bound is a `jr2 up` walk refusal, and the attach still refuses a per-run
+  url no `git.credentials` entry matches (ADR-0051). The type error is the earlier check, not the only one.