@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/config.md

@@ -15,7 +15,7 @@ Sandbox Image: a Machine names those itself.
 Every field is optional, and an Instance can run with no `jr2.config.ts`. Write the file as
 `export default defineConfig({ … })`. When the config loads, a file with no default export is
 refused: `` <file> has no default export (use `export default defineConfig({…})`) ``. The load also
-checks the shape of `git.credentials`, `secrets`, `harness.catalog` and `priorityClasses`. It
+checks the shape of `git.credentials`, `secrets`, `harness.catalog`, `priorityClasses` and `mcp`. It
 checks that `sandbox` is an object, and checks its `resources`. Each refusal names the field.
 `jr2 up` checks the rest.
 
@@ -42,7 +42,7 @@ export default defineConfig({ name: "my-instance", harness });
 - [Secrets and trust](../concepts/secrets-and-trust.md)
 - [ADR-0050: What code names, config declares; what the CLI names, discovery finds](decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)
 
-Fields: [`name`](#name), [`secrets`](#secrets), [`git`](#git), [`harness`](#harness), [`sandbox`](#sandbox), [`priorityClasses`](#priorityclasses), [`registry`](#registry), [`kitRegistry`](#kitregistry), [`platforms`](#platforms), [`operator`](#operator).
+Fields: [`name`](#name), [`secrets`](#secrets), [`git`](#git), [`harness`](#harness), [`sandbox`](#sandbox), [`priorityClasses`](#priorityclasses), [`callers`](#callers), [`cors`](#cors), [`hooks`](#hooks), [`mcp`](#mcp), [`runs`](#runs), [`registry`](#registry), [`kitRegistry`](#kitregistry), [`platforms`](#platforms), [`operator`](#operator).
 
 <a id="name"></a>
 
@@ -76,8 +76,9 @@ config loads: `<file> at secrets[<i>]<path>: <problem>`, followed by the shape o
 - Type: `string`
 - Required: yes
 
-As a Held secret, the name of the env var that the Harness container sees, which holds the
-Stand-in. As an Effect secret, the name that `secret("<name>")` names, and the name of the
+As a Held secret, the name of its Stand-in: the file the Harness reads it from, the env var
+that the engine reads a model key from, and the env var of the Agent's programs when the
+`workspace()` lists it under `secrets`. As an Effect secret, the name that `secret("<name>")` names, and the name of the
 Effector's file. For a Held secret, it must match `[A-Z_][A-Z0-9_]*`:
 `secrets[<i>].name "<name>" is not an env var name ([A-Z_][A-Z0-9_]*)`. It must not start with
 `JR2_` and must not be a proxy or trust variable of the kit:
@@ -377,7 +378,7 @@ checks from inside the cluster that the endpoint answers.
 
 The API key, when the endpoint needs one. Read it from `process.env`. It is a Held secret,
 `JR2_PROVIDER_API_KEY`: `jr2 up` gives the value to the Custodian only, bound to the host of
-`baseUrl`, and the Harness container holds only its Stand-in. Thus `baseUrl` must be
+`baseUrl`, and the Harness process holds only its secret Stand-in. Thus `baseUrl` must be
 `https://` when you set it:
 `harness.provider.apiKey is set, and harness.provider.baseUrl is not https://`.
 
@@ -467,6 +468,11 @@ deployments, so read it from `process.env` (`.env`).
 
 Env vars for the Harness container. The Agent can read every one of them, so do not put a
 credential here. A known model key is refused here. Put it in the top-level `secrets` list.
+The Harness process gets each one, except a name that loads code from a path, such as
+`NODE_OPTIONS` or `LD_PRELOAD`, and `HOME`, which is its own; the Agent's programs get each
+one. A name that starts with `JR2_` is jr2's own, and is refused. A credential file that the
+Harness process reads, such as `AWS_CONFIG_FILE`, is refused in a folder that the Agent's code
+writes (`/work`, `/tmp`, `/home/jr2`), and gives a warning anywhere else.
 See `HarnessEnvVar`.
 
 <a id="harness-env-name"></a>
@@ -508,7 +514,10 @@ pod as it is. A reference to a Secret of the kit is refused:
 - Required: no
 
 Secrets and ConfigMaps that you manage, whose keys all become env vars of the Harness
-container. See `HarnessEnvFromSource`.
+process and of the Agent's programs, as `env` does. In the container's spec each key has the
+prefix `JR2_ENVFROM_`, so that the Harness can tell jr2's names from the image's; the Harness
+removes it. A key that starts with `JR2_` is refused: `jr2 up` refuses it, and the Harness does
+not start with one. See `HarnessEnvFromSource`.
 
 <a id="harness-envfrom-prefix"></a>
 
@@ -692,6 +701,239 @@ An existing PriorityClass for the Orchestrator, the operator and the Repo cache
 
 An existing PriorityClass for the Sandboxes and the Instance Harness.
 
+<a id="callers"></a>
+
+## `callers`
+
+- Type: `CallersConfig`
+- Required: no
+- Default: none; only the Instance token acts
+
+The Callers that act on the Instance with a credential of their own, and what each may do.
+See `CallersConfig`.
+
+<a id="callers-tokens"></a>
+
+### `callers.tokens`
+
+- Type: `Readonly<Record<string, CallerToken>>`
+- Required: no
+
+The named Caller tokens, by name. A name is lowercase letters, digits and `-`, at most 40
+characters, from a letter to a letter or digit. The config load refuses `instance`, the
+Instance token's name. A name that the config no longer declares stops working at the next
+`jr2 up`.
+
+<a id="callers-tokens-name-may"></a>
+
+### `callers.tokens.<name>.may`
+
+- Type: `Scopes`
+- Required: yes
+
+What the token may do. See `Scopes`.
+
+<a id="callers-tokens-name-may-start"></a>
+
+### `callers.tokens.<name>.may.start`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Start a run.
+
+<a id="callers-tokens-name-may-answer"></a>
+
+### `callers.tokens.<name>.may.answer`
+
+- Type: `AnswerGrant`
+- Required: no
+
+Answer a Gate, and read a run's open Gates without its context. A list item
+`{ workflow, gates }` opens only the Gates that it names, by invoke id (see `GateGrant`).
+
+<a id="callers-tokens-name-may-cancel"></a>
+
+### `callers.tokens.<name>.may.cancel`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Cancel a run.
+
+<a id="callers-tokens-name-may-read"></a>
+
+### `callers.tokens.<name>.may.read`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Read a run's state: its status, its context and its feed.
+
+<a id="callers-tokens-name-may-steer"></a>
+
+### `callers.tokens.<name>.may.steer`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Send a Steering message to an Agent of a run.
+
+<a id="callers-issuers"></a>
+
+### `callers.issuers`
+
+- Type: `readonly JwtIssuer[]`
+- Required: no
+
+The identity providers whose JWTs are Callers. See `JwtIssuer`. Two entries with one
+`issuer` are refused.
+
+<a id="callers-issuers-issuer"></a>
+
+### `callers.issuers[].issuer`
+
+- Type: `string`
+- Required: yes
+
+The issuer's URL, exactly as the `iss` claim gives it, such as `https://dex.example.com`.
+
+<a id="callers-issuers-audience"></a>
+
+### `callers.issuers[].audience`
+
+- Type: `string`
+- Required: yes
+
+The audience that a JWT must name in its `aud` claim: for a login, the client id.
+
+<a id="callers-issuers-jwks"></a>
+
+### `callers.issuers[].jwks`
+
+- Type: `string`
+- Required: no
+- Default: the `jwks_uri` of the issuer's `/.well-known/openid-configuration`
+
+The URL of the issuer's public keys (a JWKS).
+
+<a id="callers-issuers-claims"></a>
+
+### `callers.issuers[].claims`
+
+- Type: `object`
+- Required: no
+- Default: `{ name: "sub", shown: "email", groups: "groups" }`
+
+The claims to read.
+
+<a id="callers-issuers-claims-name"></a>
+
+### `callers.issuers[].claims.name`
+
+- Type: `string`
+- Required: no
+
+The claim that is the Caller's name. Use a claim that the provider never reassigns.
+
+<a id="callers-issuers-claims-shown"></a>
+
+### `callers.issuers[].claims.shown`
+
+- Type: `string`
+- Required: no
+
+The claim that is the name that jr2 shows.
+
+<a id="callers-issuers-claims-groups"></a>
+
+### `callers.issuers[].claims.groups`
+
+- Type: `string`
+- Required: no
+
+The claim that holds the list of groups or roles that `groups` maps to scopes.
+
+<a id="callers-issuers-groups"></a>
+
+### `callers.issuers[].groups`
+
+- Type: `Readonly<Record<string, Scopes>>`
+- Required: yes
+
+The scopes that each value of the groups claim gives, such as
+`{ "jr2-ops": { start: "all", answer: "all" } }`. A JWT with more than one value gets the scopes
+of each, joined. A value that is not here gives nothing.
+
+<a id="callers-issuers-login"></a>
+
+### `callers.issuers[].login`
+
+- Type: `boolean`
+- Required: no
+- Default: `false`, because an issuer for machines (a CI provider's tokens) has no login page
+
+The Console offers a login against this issuer ([ADR-0032](decisions/0032-the-console-unlocks-with-a-callers-credential.md)): OIDC, the authorization code flow
+with PKCE, as a public client, with `audience` as the client id. Register the client as public
+(no secret), with the Console's root (`https://<console>/`) as its redirect URI. The Console
+reads the issuer and the client id before the login, from the open route
+`GET /console/config`: both are public values. A login needs the Console on https or on
+localhost, and the issuer must let the Console's origin call its discovery document and its
+token endpoint (CORS).
+
+<a id="cors"></a>
+
+## `cors`
+
+- Type: `readonly string[]`
+- Required: no
+- Default: none
+
+The origins from which a browser app may call the Instance's HTTP API, such as
+`https://ops.example.com`. Each entry is an origin alone: a scheme, a host and an optional port,
+with no path. The Console is served from the Orchestrator's own origin, so it
+needs no entry. The config load refuses an entry that is not an origin:
+`<file> at cors[<i>]: <entry> is not an origin — scheme://host[:port], with no path`.
+
+<a id="hooks"></a>
+
+## `hooks`
+
+- Type: `Readonly<Record<string, Hook>>`
+- Required: no
+- Default: none
+
+The Hooks of the Instance, by name: each one is a door, `POST /hooks/<name>`, for one outside
+service. A Hook's value comes from its kind's constructor, which the config imports:
+`github({ secret: secret("GH_HOOK") })`, `gitlab({ secret: secret("GL_HOOK"), may })`,
+`discord({ publicKey: "…" })`. `may.answer` names the Workflows whose Gates the Hook may answer,
+every Workflow by default. A Hook never starts a run. A name has the rule of a Caller token's
+name. When the config loads, a bad entry is refused: `<file> at hooks.<name>: <problem>`.
+
+<a id="mcp"></a>
+
+## `mcp`
+
+- Type: `Readonly<Record<string, McpServer>>`
+- Required: no
+- Default: none
+
+The MCP servers, by a name of yours: `[a-z][a-z0-9-]*`, not `jr2`. A remote server has a
+`url` (`https://` with a secret), a `secret` (a name of the `secrets` list; with no `hosts`, it
+is bound to the url's host) and a `timeout` (default `"60s"`). A stdio server has a `command`
+of the Sandbox Image, its `args` and a `timeout`. An Agent names a server in its `mcp` list.
+See [`McpServer`](authoring-surface/type-mcpserver.md).
+
+<a id="runs"></a>
+
+## `runs`
+
+- Type: [`RunsConfig`](authoring-surface/type-runsconfig.md)
+- Required: no
+- Default: `{ retain: "30d", volume: "5Gi" }`
+
+How long ended runs are kept, and the volume size.
+
 <a id="registry"></a>
 
 ## `registry`

package/docs/reference/decisions/0001-operator-owned-generic-sandbox.md

@@ -34,7 +34,7 @@ Sandbox will run must be in the spec at spin-up.
 
 One Harness **image** serves many **Agents** — the Harness resolves model, instructions, and its Menu at runtime without
 a rebuild, reading the definition each admission carries (ADR-0018, ADR-0049) and reading the Menu through the Custodian
-per turn (ADR-0013). So the Orchestrator injects a fixed Harness image plus **config** (env + the prepared worktree),
+per turn (ADR-0013). So the Orchestrator injects a fixed Harness image plus **config** (env + the prepared clones),
 never a per-Agent image build. The HTTP prompt body itself carries only `{message, images}`, so anything persona-shaping
 is set at provision time, not per request.
 
@@ -91,14 +91,15 @@ one keeps the name and the endpoint and costs no node anything. Deferred until a
 These are accepted gaps in the current operator, recorded so they aren't silently forgotten. Each is a deliberate
 deferral.
 
-- **Egress is not restricted.** The pod is hardened at the host boundary — `automountServiceAccountToken: false`,
-  pod/container `securityContext` (`runAsNonRoot`, `allowPrivilegeEscalation: false`, drop `ALL`, seccomp
-  `RuntimeDefault`) — and its _ingress_ is the Orchestrator's alone: `jr2 up` converges a NetworkPolicy that admits no
-  other pod to a Sandbox ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)), which kind's `kindnet`
-  enforces. Nothing yet restricts _egress_: an untrusted Agent can still reach the cluster's API server IP (it holds no
-  credential there) and the internet. A default-deny egress policy with an allowlist is the next layer, and ADR-0058
-  records it open. The ADR-0013 boundary does not depend on either: only the token bounds what a pod may _do_;
-  NetworkPolicy bounds where it may _talk_.
+- **Egress is open.** The pod is hardened at the host boundary — `automountServiceAccountToken: false`, pod/container
+  `securityContext` (`runAsNonRoot`, `allowPrivilegeEscalation: false`, drop `ALL`, seccomp `RuntimeDefault`) — and its
+  _ingress_ is the Orchestrator's alone: `jr2 up` converges a NetworkPolicy that admits no other pod to a Sandbox
+  ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)), which kind's `kindnet` enforces. _Egress_ is open
+  except for the cloud metadata addresses, which no Harness pod reaches
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)): an untrusted Agent can
+  still reach the cluster's API server IP (it holds no credential there) and the internet. A default-deny egress policy
+  with an allowlist is the next layer, and ADR-0058 records it open. The ADR-0013 boundary does not depend on either:
+  only the token bounds what a pod may _do_; NetworkPolicy bounds where it may _talk_.
 - **Sidecars are plain containers, not native sidecars.** They are scheduled as ordinary `containers`, not Kubernetes
   ≥1.29 native sidecars (`initContainers` with `restartPolicy: Always`). There is no start-ordering or
   termination-ordering guarantee between the Harness and its sidecars — the Harness may begin serving before the

package/docs/reference/decisions/0002-duplex-streaming-actor.md

@@ -16,21 +16,88 @@ action observably occurred only post-approval.
 
 The split-channel model:
 
-| Direction | Kind                                                      | Mechanism                                |
-| --------- | --------------------------------------------------------- | ---------------------------------------- |
-| up        | control / decision (the workflow's events, ADR-0011)      | Menu tool call → Custodian → delivery    |
-| up        | progress / telemetry (tokens, attempts, "still working")  | Harness stream (lossy, observation-only) |
-| down      | the next turn's prompt (feedback, steering at a boundary) | a new submission on the same iid         |
-| down      | the Turn part, restated (the Allowed picks changed)       | the Harness's read at each step boundary |
-| down      | interrupts (deliberate terminal cancel)                   | `abort` on the wire                      |
-
-Tool calls are Agent-initiated, so the Machine speaks inside a Turn only as an answer. The one exception is the
-**restated Turn part**: when something other than the Agent's own pick changes its Allowed picks — a Gate's answer, an
-outside event — the Harness learns it by reading the surface at each step boundary and appends the new list
+| Direction | Kind                                                           | Mechanism                                     |
+| --------- | -------------------------------------------------------------- | --------------------------------------------- |
+| up        | control / decision (the workflow's events, ADR-0011)           | Menu tool call → Custodian → delivery         |
+| up        | progress / telemetry (tokens, attempts, "still working")       | Harness stream (lossy, observation-only)      |
+| down      | the next turn's prompt (feedback, steering at a boundary)      | a new submission on the same iid              |
+| down      | the Turn part, restated (the Allowed picks changed)            | the Harness's read at each step boundary      |
+| down      | a jr2 notice (a memory kill, ADR-0062), typed, to its audience | the same step-boundary read, per conversation |
+| down      | a Steering message (a Caller's or the Machine's free text)     | the same step-boundary read, per Agent slot   |
+| down      | interrupts (deliberate terminal cancel)                        | `abort` on the wire                           |
+
+Tool calls are Agent-initiated, so the Machine answers a pick only when the Agent makes one. Inside a Turn, three other
+things reach the Agent, and each one at a step boundary. The first is the **restated Turn part**: when something other
+than the Agent's own pick changes its Allowed picks — a Gate's answer, an outside event — the Harness learns it by
+reading the surface at each step boundary and appends the new list
 ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). It is a pull, not a push:
-nothing new reaches the Harness, and what is restated is fixed text plus Menu names. The residual hard case is
-**unsolicited mid-turn steering** — free text from the Machine to an Agent that has not asked. That remains unsolved,
-and it is the only behavior in that bucket, not a dependency of the whole control plane.
+the Harness asks at a step boundary, and nothing reaches it that it did not ask for. What is restated is fixed text plus
+Menu names. The second is jr2's own **typed notices**, which ride that same step-boundary read: the read of an open Turn
+returns its conversation's pending notices, the Harness appends them, and its acknowledgment of the append delivers
+them. So a running Agent hears a fact the mechanism knows — a memory kill above all — without an interrupt. A notice is
+typed data, and the Harness words it ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). The third
+is a **Steering message**: free text to an Agent that has not asked for it, on the same read (below). Each is a pull at
+a step boundary, never an interrupt.
+
+## Steering messages
+
+- **Two senders.** A Caller ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md))
+  sends one with `POST /runs/:runId/steering { agent, text }` or `jr2 steer <run> <agent> "<text>"`, and needs the
+  `steer` scope for the run's Workflow. A text above 16 KiB of UTF-8 is 413, and an empty one 400. The route answers 202
+  `{ id, agent, open }`: `open` says whether a Turn of the slot was open when the message came. The message names the
+  Caller by the name that jr2 shows (a JWT's `email`, else its name), with its `via` and its `onBehalfOf` claim. The
+  Machine sends one with the authoring action `steer(<agent>, text, { from? })` in a transition, to an Agent of the
+  Machine that runs the action; `from` is the Sender whose words it carries. The action cuts a text above 16 KiB and
+  says so in the text, because a relayed payload is not the author's to bound, and a refusal there would fail the
+  transition.
+- **Addressed by Agent slot.** `agent` names an Agent slot of the run, as the run's slot list names it. The list,
+  `{ agent, open, steerable }` for each slot at `GET /runs/:runId/agents`, is open to a Caller with `steer`, so a Caller
+  can see where a message would go. It lists each Agent that each live Machine instance carries in its `actors`, with or
+  without an open Turn, and `jr2 steer <run>` prints it. An Instance ID is not the address: jr2 computes it, a Caller
+  cannot know it, and a fresh Turn gets a new one. A slot is the name that the author gave, and the walk lets at most
+  one state of a Machine instance hold it at a time ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)), so it
+  names one conversation at a time.
+- **Delivery.** When the slot has an open Turn, its Harness appends the message at the Turn's next step boundary, on the
+  same read as a notice. A pick that ends the Turn skips that read. Thus a message that comes while the Turn's last
+  model request runs is held for the slot's next Turn, as when no Turn is open, and `jr2 steer` says that both can
+  occur. Otherwise the message is held for the slot's next Turn of the same Machine instance, and that Turn's admission
+  carries it. A held message belongs to the Machine instance that was live when it was sent: when that instance ends,
+  the message retires, and the run records it "not delivered". A Machine instance ends when it leaves its parent's
+  children, when it reaches `done` or `error`, and when the run ends; a host that stops parks the run, and ends nothing.
+  An instance below one that ended ends with it. When no live Machine instance holds the slot — it has ended, or it
+  never was — the route answers 409 with the run's slots, because the Orchestrator cannot tell a slot that ended from
+  one that never was; an unknown run is 404, and a run that is not live is 409. The Agent hears each message once, by
+  the rules of a notice (ADR-0062). The run records each message with its author, its text, when it was sent and its
+  outcome (`held`, `heard`, `not-delivered`), in the run's persisted state; the record keeps the newest 100 and each one
+  still held. The run's status carries it as `steering`, behind `read` like `context` (ADR-0014): a message is a
+  Caller's working text, never the open band's.
+- **Never a Machine event.** A Steering message is in no Vocabulary, no Gate takes it, and no guard reads it. The Agent
+  decides what to do with it, and acts on the workflow only by its picks.
+- **Agents message each other only through the Machine.** An Agent's Menu offers a pick that the author declared; the
+  Machine's transition relays its payload with `steer(<agent>, …)`. jr2 gives no built-in message tool.
+- **The Harness frames the message by its author** (ADR-0062). A Caller's message is an instruction from outside the
+  run, with the Caller's name. A message that the Machine relays from another Agent is information from a peer, and the
+  frame says that it is not an instruction. A Machine's message that relays no one is the workflow's own text.
+- **`steerable: false` on an Agent definition refuses Callers only** (403). The Machine can still steer that Agent: the
+  author wrote both. The admission strips it from the definition, because the model never reads it.
+- **What a model reads changes, so two `@model` claims are owed**
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)): `steer-follow`, an
+  Agent follows a Caller's Steering message that comes in its open Turn, and `peer-not-order`, an Agent does not obey a
+  peer's relayed word as an order. Their floors were set before a measured run, as `chart-refusal`'s was: `steer-follow`
+  9 of 10, a list read last's floor, because the message is the newest text that the model read; and `peer-not-order` 7
+  of 10, because there the peer's word comes after the workflow's text, and ADR-0029 measured how much the text read
+  last pulls.
+
+Considered and rejected: address a message by conversation (an Instance ID), which a Caller cannot know and which
+changes at a fresh Turn; a built-in tool with which an Agent messages another Agent, which goes around the Machine that
+the author wrote; and a Steering message as a Machine event, which makes free text control.
+
+Considered and not chosen now: a held message turns back a pick that ends the Turn. The Harness would refuse that pick
+while a message waits for the slot, and the model would read the message and pick again, so a message always reaches the
+Turn that was open when it came. It costs a new refusal that the model reads (an `@model` claim), one more model request
+in that case, and a pick that a Caller's message can undo, where today a pick is final. The case is one model request
+wide, and a Gate or the Machine can still send the Agent back. Look at it again if Callers need a message to reach the
+Turn that was open.
 
 ## Durability: the admission is the handle
 

package/docs/reference/decisions/0004-worktree-provisioning-model.md

@@ -91,34 +91,40 @@ fast setup.
 
 ## Where setup runs
 
-Worktree provisioning is a post-`Ready` step owned by the Orchestrator: the Sandbox CRD names repositories by identity
-so the operator can place and mount them, but it knows nothing about clones or worktrees (ADR-0001, ADR-0051).
-`workspace()`'s attach is one idempotent in-pod script the Harness runs on `POST /attach` (ADR-0012,
-[ADR-0063](0063-the-orchestrator-watches-the-cluster.md)), once `Ready` says every cache is present and fetched.
+The clone is a post-`Ready` step owned by the Orchestrator: the Sandbox CRD names repositories by identity so the
+operator can place and mount them, but it knows nothing about clones or worktrees (ADR-0001, ADR-0051). `workspace()`'s
+attach is one idempotent in-pod script the Harness runs on `POST /attach` (ADR-0012,
+[ADR-0063](0063-the-orchestrator-watches-the-cluster.md)), once `Ready` says every cache is present and fetched. The
+attach only clones. A Machine cuts each Worktree with the kit Effect `worktree()`
+([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)).
 
 ## In-Sandbox layout: worktrees off the per-Sandbox clone (gwtmux convention)
 
 "Not a shared worktree" above means _not a worktree off a fleet-shared `.git`_. **Inside** a Sandbox, worktrees are the
-intended ergonomic — taken off the Sandbox's **own** clone. The per-Sandbox clone _is_ the `default/`, and branch
-working trees are its siblings, matching the layout [gwtmux](https://github.com/snapwich/gwtmux) already expects, under
-the slot the Machine gave the repository (ADR-0051):
+intended ergonomic — taken off the Sandbox's **own** clone. The per-Sandbox clone _is_ the `default/`, and the Worktrees
+are its siblings, matching the layout [gwtmux](https://github.com/snapwich/gwtmux) already expects, under the slot the
+Machine gave the repository (ADR-0051):
 
 ```
-/work/<slot>/default/        the per-Sandbox `git clone --shared` (holds the pod-local .git; the default branch checked out)
-/work/<slot>/<branch>/        `git worktree add` siblings, one per branch worked
+/work/<slot>/default/        the per-Sandbox `git clone --shared` (holds the pod-local .git; stays on the Binding's base)
+/work/<slot>/<name>/         `git worktree add` siblings: folders a Machine cuts, each with one branch or one commit
 ```
 
 Because the layout is identical to the one used outside the cluster, existing worktree tooling works **unchanged** when
-you exec into a Sandbox. Object resolution falls through: a branch worktree shares the per-Sandbox `default/.git`, whose
+you exec into a Sandbox. Object resolution falls through: a Worktree shares the per-Sandbox `default/.git`, whose
 alternates point at the read-only cache — existing objects are read from the cache, new commits land in the pod-local
-`.git`. `default/` is a checkout of the Repo's default branch, as gwtmux's `default/` is outside the cluster: work
-happens in the branch worktrees, and `default/` is the reference tree a human or a tool finds where it expects one. Not
-`--no-checkout`: an empty working tree reads as every tracked file deleted to `git status`, which misleads an Agent that
-looks. The branch name `default` is refused by the spec guard: the branch Worktree is a sibling of that directory, never
-it. `origin`'s push url is the binding's own spelling, so a Machine that bound over ssh pushes over ssh even when the
-cache was cloned over https.
-
-This does **not** reintroduce jr's contention: the shared `.git` here is _per-Sandbox_, and it is accessed serially
-under the standing invariant that **one Agent runs at a time per Workspace** — structural since ADR-0012 (one sequential
-body per workspace). A Machine that runs concurrent Agents in one Sandbox, or an Agent that spawns parallel git-touching
-subagents, reintroduces contention (pod-scoped, not fleet-wide) and must opt into separate Sandboxes instead.
+`.git`. `default/` stays on the Binding's base: a branch is attached, a tag or a commit is detached, and with no base it
+is the Repo's default branch, as gwtmux's `default/` is outside the cluster. No work happens in it: work happens in the
+Worktrees, and `default/` is the reference tree that a human, a tool or an Agent that only reads finds where it expects
+one. Not `--no-checkout`: an empty working tree reads as every tracked file deleted to `git status`, which misleads an
+Agent that looks. A Worktree's folder cannot be named `default`, and a cut of the branch that `default/` holds is
+`refused`, with a reason that names `/work/<slot>/default`. `origin`'s push url is the binding's own spelling, so a
+Machine that bound over ssh pushes over ssh even when the cache was cloned over https.
+
+This does **not** reintroduce jr's contention: the shared `.git` here is _per-Sandbox_, so what contends stays in one
+pod and never crosses the fleet. Inside the pod it is the author's choice. A Machine that runs concurrent Agents in
+Worktrees of one clone, or an Agent that spawns parallel git-touching subagents, takes that contention, and a Machine
+that does not want it uses separate Sandboxes. Two things keep one clone safe to share. The attach sets `gc.auto=0` and
+`maintenance.auto=false` in the clone, because a `gc` beside a cut or a commit can prune what another Worktree needs.
+And all Worktrees of a clone share `refs/remotes/origin/*`, so `jr2-upload-pack` holds a per-clone lock for each fetch
+(ADR-0053, ADR-0075).