@jr2/orchestrator 0.5.1 → 0.6.0

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/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md

@@ -22,24 +22,24 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
   default: `agent({ model, instructions, workspace?, thinkingLevel?, description? })`.
 
 - **The Frame is `prompt` and `cwd`: what this Turn is about and where it works.** Neither identity nor a Dial. A
-  worktree path is per run by nature — `/work/<slot>/<branch>` exists only once a run has a branch — so no definition
-  can name it, and a directory is not a property of a persona any more than a prompt is. `cwd` leaves `AgentDefinition`.
-  The Harness roots the Working tools at the Frame's `cwd`, which rides the admit body beside the prompt and the Dials.
+  worktree path is per run by nature — `/work/<slot>/<name>` exists only once a run cuts it — so no definition can name
+  it, and a directory is not a property of a persona any more than a prompt is. `cwd` leaves `AgentDefinition`. The
+  Harness roots the Working tools at the Frame's `cwd`, which rides the admit body beside the prompt and the Dials.
 
 - **The Briefing is not the Frame.** jr2's Turn part
   ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)) follows the prompt — the resolved working
   directory, the Allowed picks and any notices — in a block of its own. The prompt stays the Machine state's words
   alone; jr2 never writes into it.
 
-- **Under a Workspace, an absent `cwd` resolves to the only Repo Slot's Worktree, and is refused when there is more than
-  one.** With one slot there is no choice, so no convention is being smuggled in (ADR-0051: the kit gives no slot a
-  meaning). With two or more, the state must say which — `cwd: context.workspace.repos.target` — and the actor refuses
-  the Turn before admission, naming the slots and the line to add. The trap is accepted with open eyes: a composer who
-  adds a second slot on the `customize` line can make a Machine that ran yesterday refuse today, in a file the Machine's
-  author never sees. The refusal is explicit, at the first Turn, before any pod is spent; `jr2 up` cannot see it because
-  the invoke's input is a function. A `workspace: "none"` Agent has no Working tools and no `cwd` (ADR-0028); a
-  stub-Harness run with no Workspace keeps `/work`. `task` always passes its `cwd`, because "the first slot is the one
-  the coder edits" is its convention and a convention is stated, not defaulted.
+- **Under Repo Slots, `cwd` is required.** A Workspace that only clones has no Worktree for a default to name
+  ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), and `/work` is the wrong default: an
+  Agent's search hits `default/`, and a relative write lands outside each Worktree, which is the incident above. So the
+  state says where — `cwd: "/work/target/fix"` — and the actor refuses the Turn before admission, naming the slots and
+  the line to add; `jr2 up` cannot see it because the invoke's input is a function. A Turn that wants `/work` states it.
+  A Workspace with no Repo Slot needs no `cwd`: its Turns work in `/work` (ADR-0051). A `workspace: "none"` Agent has no
+  Working tools and no `cwd` (ADR-0028); a stub-Harness run with no Workspace keeps `/work`. `task` passes its `cwd` as
+  any Machine does: "the first slot is the one the coder edits" is its convention, and a convention is stated, not
+  defaulted.
 
 - **`continue: true` is the whole continuation surface.** Absent, every invocation is a fresh conversation — jr's lossy
   handoff, ADR-0016's default, unchanged. Present, the Turn lands on **this Agent's one conversation in this Machine
@@ -112,11 +112,11 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
   that is wrong under every `workspace()` is not a default.
 - **`cwd` as a third Dial.** Rejected on the word: Dials say how hard to run. A directory says where, which is the same
   kind of fact as the prompt — hence Frame.
-- **Default `cwd` to the first Repo Slot.** Rejected: reverses ADR-0051 ("there is no `workdir`"). The single-slot
-  default is not the same thing — with one slot there is nothing to privilege.
-- **Refuse an absent `cwd` under every Workspace.** The safer twin of the single-slot default: one line per invoke, no
-  composition trap. Not taken: the trap's failure is explicit and early, and the line is noise for the common
-  single-repo Machine.
+- **Default `cwd` to the first Repo Slot.** Rejected: reverses ADR-0051 ("there is no `workdir`").
+- **Default `cwd` to the only Repo Slot's Worktree.** Rejected: a Workspace that only clones has no such Worktree. And a
+  refusal under every Workspace with Repo Slots has no composition trap: with a default, a composer who adds a second
+  slot on the `customize` line makes a Machine that ran yesterday refuse today, in a file the Machine's author never
+  sees. The cost is one line per invoke.
 - **A caller-chosen conversation key (`conversation: "coder"`).** Rejected: it either restates the structure or
   contradicts it. Path-scoping the key was proposed and made the key redundant — once the id is
   `<run>/<machine path>/<agent>`, the author has nothing left to name.
@@ -133,19 +133,19 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
 - `AgentTurnInput` is `{ prompt, cwd?, continue?, model?, thinkingLevel? }`; `AgentDefinition` loses `cwd`. The Harness
   admit body gains the Frame's `cwd`; `ResolvedDefinition.cwd` resolves from it, not the definition; the Harness stops
   validating `description`, which the Orchestrator strips before admission (it is Console material).
-- **A Frame's `cwd` is absolute or the admission is refused**, naming the Frame. Absent is the one silent case, and it
-  says `/work` — a stated default. A relative path has no such answer: it would resolve against whatever directory the
-  Harness process sits in, which is the silent wrong directory this ADR was written for, one level further from the
-  author. The refusal is a 400 at admission, before a pod is spent.
-- `task` passes `cwd: worktreeOf(context).path` and `continue: true`, and drops `generation` (and its `scope`). It keeps
-  `turns`, reset on `agent.fault`, because re-briefing is prompt policy.
+- **A Frame's `cwd` is absolute or the admission is refused**, naming the Frame. Absent is the one silent case, it
+  reaches a Harness only where no Repo Slot is, and it says `/work` — a stated default. A relative path has no such
+  answer: it would resolve against whatever directory the Harness process sits in, which is the silent wrong directory
+  this ADR was written for, one level further from the author. The refusal is a 400 at admission, before a pod is spent.
+- `task` passes the path of the Worktree it cuts as `cwd`, and `continue: true`, and drops `generation` (and its
+  `scope`). It keeps `turns`, reset on `agent.fault`, because re-briefing is prompt policy.
 - The ledger record for a continued conversation carries its epoch; the input mapper reads it at mint time, so the
   minted id persists with the input and restore re-attaches the same conversation (ADR-0016's mapper rule holds — the
   fresh suffix is still the random component).
 - The `@kind` fixtures drop `tools:` and `instanceId:`; the steps compute the continued id from the actor path, as they
   already computed today's pin.
 - A regression scenario for the silent success: a `task` whose model uses relative paths must produce its file inside
-  the worktree, and a multi-slot Machine with no `cwd` must be refused with the slots named.
+  the worktree, and a Machine under Repo Slots with no `cwd` must be refused with the slots named.
 - GLOSSARY.md: **Frame** enters; **Dials** loses `cwd`; **Instance ID** states the `continue` scope and that a faulted
   conversation is not continued. ADR-0016 (continuation), ADR-0018 (identity line), ADR-0031 (placement scenario),
   ADR-0035 (reroll gate wording), ADR-0049 (persona hazard), and ADR-0054 (`task`'s continuation) are edited to state

package/docs/reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md

@@ -93,9 +93,11 @@ and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harne
   `harness.env` or in an `envFrom` Secret.
 - **Open gaps, recorded here and not fixed:**
   - **Sandbox egress.** An Agent with bash can reach the internet and send out anything it can read — which no longer
-    includes a held key: a client that goes around the Custodian carries only Stand-ins. A default-deny egress policy
-    needs an allowlist: DNS, the Orchestrator, the model provider, and whatever the work needs (package registries, for
-    example). That needs a config surface and cluster CIDRs, so it is a separate decision.
+    includes a held key: a client that goes around the Custodian carries only Stand-ins. One exception: no Harness pod
+    reaches a cloud metadata address
+    ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). A default-deny egress
+    policy needs an allowlist: DNS, the Orchestrator, the model provider, and whatever the work needs (package
+    registries, for example). That needs a config surface and cluster CIDRs, so it is a separate decision.
   - **A held key can be spent.** The Agent can use a key through the Custodian while its pod lives, and a SigV4 or ADC
     credential cannot be held at all ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)).
   - **The Orchestrator's Secret writes are namespace-wide.** Its Role may create and patch every Secret, and may not get