@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/concepts/secrets-and-trust.md

@@ -51,10 +51,15 @@ export default defineConfig({
 ```
 
 - A pod claims a Held secret when its [`workspace()`](../reference/authoring-surface/workspace.md) lists the name under
-  `secrets`. A pod also claims the key of each provider that an Agent in that pod uses.
+  `secrets`. A pod also claims the key of each provider that an Agent in that pod uses, and the `secret` of each MCP
+  server that an Agent in that pod names.
 - The [Instance Harness](../reference/glossary.md#instance-harness) claims only the model keys of the Menu-only Agents
-  that it hosts.
-- An Effect claims an Effect secret when it names it with [`secret()`](../reference/authoring-surface/secret.md).
+  that it hosts, and the secrets of the MCP servers that they name.
+- An Effect claims an Effect secret when it names it with [`secret()`](../reference/authoring-surface/secret.md). An
+  `mcp` Effect claims the `secret` of its server for the
+  [Instance Effector](../reference/glossary.md#instance-effector).
+- A [Hook](../reference/glossary.md#hook) that checks a signature with a shared secret (`mac`) claims that secret for
+  the Instance Effector, as an Effect does.
 - One entry can be a Held secret and an Effect secret at the same time. The placement is a fact of each place that names
   it, not of the entry.
 - An entry that nothing names goes nowhere, and [`jr2 up`](../reference/cli.md#up) warns about it.
@@ -81,13 +86,17 @@ these things:
 2. It replaces the Stand-in with the value, in the headers that the entry names.
 3. It opens its own TLS connection to the host, and verifies the certificate of the host.
 
-The Custodian sends the traffic to each other host with no change. It refuses a loopback, link-local or unspecified
-address. A request to a bound host that has no Stand-in in its headers does not leave the pod.
+Two Held secrets can go to one host in one header, such as the tokens of two MCP servers of one service. The Custodian
+chooses the value by the Stand-in that the header holds. The Custodian sends the traffic to each other host with no
+change. It refuses a loopback, link-local or unspecified address. A request to a bound host that has no Stand-in in its
+headers does not leave the pod.
 
 These fields of an entry bind a Held secret. They do not place it:
 
 - [`hosts`](../reference/config.md#secrets-hosts): the hosts that the value can go to. A known model key with one
-  default host, such as `ANTHROPIC_API_KEY`, can leave it out. It then goes only to the host of its provider.
+  default host, such as `ANTHROPIC_API_KEY`, can leave it out. It then goes only to the host of its provider. The
+  `secret` of an MCP server can leave it out too. It then goes only to the host of the server's URL, in the header
+  `authorization`.
 - [`headers`](../reference/config.md#secrets-headers): the headers in which the Custodian replaces the Stand-in.
 - [`paths`](../reference/config.md#secrets-paths): the path prefixes that the value can go to.
 
@@ -128,9 +137,9 @@ The Instance Harness has a token of its own for the Menu. It runs no program of
 The Harness runs the [Turns](../reference/glossary.md#turn) of each Agent of the Sandbox. The Harness process itself
 runs only jr2's code. Each other process in the Harness container runs confined with Landlock: each command of the
 Agent's shell, and so the tests, the builds, git and its hooks; the search tools; the I/O of the read, write and edit
-tools; jr2's own git; and each `command` Effect that names no Effect secret. Code that one Agent writes in `/work` can
-run in a program of a different Agent, for example when a reviewer runs the tests of a coder. Thus jr2 confines each
-such program, and not only the programs of one Agent.
+tools; jr2's own git; each stdio MCP server; and each `command` Effect that names no Effect secret. Code that one Agent
+writes in `/work` can run in a program of a different Agent, for example when a reviewer runs the tests of a coder. Thus
+jr2 confines each such program, and not only the programs of one Agent.
 
 All these programs are in one Landlock domain. They can see, signal and trace each other, as the programs of one user on
 a computer can. Thus a later shell command can find and stop a server that an earlier command started. When the process
@@ -212,46 +221,71 @@ make the Sandbox. [Give the cluster git credentials](../guides/give-the-cluster-
 ## The tokens
 
 jr2 makes its own tokens. `jr2 up` makes the Instance token and the signing key the first time, and keeps them in the
-`jr2-instance` Secret. Each other token comes from the signing key, so the Orchestrator stores no token for each pod.
+`jr2-instance` Secret. Each token of a pod comes from the signing key, so the Orchestrator stores no token for each pod.
 
-| Token          | Who holds it                                                                                         | What it lets the holder do                                                                                  |
-| -------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Instance token | You, the CLI, the [Console](../reference/glossary.md#console) when you type it, and a webhook client | Everything: start a run, read its full state, answer a Gate, cancel a run.                                  |
-| Control token  | The Custodian of one Sandbox, as a file                                                              | Read the Menu and send the picks of the Agents in that Sandbox, for the Agent that the Harness names.       |
-| Fetch token    | The Custodian of one Sandbox, as a file                                                              | Ask for a fetch of a Repo that the Sandbox mounts.                                                          |
-| Harness bearer | The Orchestrator. The Harness holds only its SHA-256 digest.                                         | Call the Harness in one pod: start a Turn, read it, stop it, set up a Worktree, and run a `command` Effect. |
-| Effector key   | The Orchestrator, and the Effector of one placement                                                  | Sign a request to that Effector, and sign its answer.                                                       |
+| Token              | Who holds it                                                                                    | What it lets the holder do                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Instance token     | You and the CLI, through the Kubernetes API                                                     | Everything: start a run, read its full state, answer a Gate, cancel a run, and the routes that no scope opens. |
+| Named Caller token | A [Caller](../reference/glossary.md#caller) that has no access to the cluster, such as a CI job | The scopes that `callers.tokens` gives its name, for the Workflows that each scope names.                      |
+| Control token      | The Custodian of one Sandbox, as a file                                                         | Read the Menu and send the picks of the Agents in that Sandbox, for the Agent that the Harness names.          |
+| Fetch token        | The Custodian of one Sandbox, as a file                                                         | Ask for a fetch of a Repo that the Sandbox mounts.                                                             |
+| Harness bearer     | The Orchestrator. The Harness holds only its SHA-256 digest.                                    | Call the Harness in one pod: start a Turn, read it, stop it, set up a Worktree, and run a `command` Effect.    |
+| Effector key       | The Orchestrator, and the Effector of one placement                                             | Sign a request to that Effector, and sign its answer.                                                          |
 
 - The Instance token enters no Harness pod. The CLI reads it from the `jr2-instance` Secret over the Kubernetes API.
-  Thus Kubernetes RBAC decides who holds it.
+  Thus Kubernetes RBAC decides who holds it. The CLI is the Caller `token/instance`. It also sends the name of your
+  Kubernetes user, and the run records it as the party that the Caller acts for.
+- [`callers.tokens`](../reference/config.md#callers-tokens) declares each named Caller token. `jr2 up` makes its value
+  one time, in a Secret of its own, `jr2-caller-<name>`. The Orchestrator holds only the SHA-256 digest of each value,
+  in the `jr2-caller-digests` Secret, which it mounts. `jr2 caller token <name>` prints the value, which it reads over
+  the Kubernetes API.
+- `jr2 caller rotate <name>` makes a new value. The Orchestrator reads the digests again when the mount changes. The
+  kubelet updates the mount in about one minute, and `jr2 caller rotate` waits for it. When it returns, the old value no
+  longer works. No pod restarts.
+- When `callers.tokens` no longer declares a name, the next `jr2 up` deletes its Secret, and its value stops working.
 - A control token or a fetch token cannot answer a Gate, and cannot speak for a different pod. The Orchestrator accepts
   each one only on its own routes. Thus an Agent cannot approve its own work, and a Sandbox cannot send a pick for an
-  Agent in a different Sandbox.
+  Agent in a different Sandbox. No token of a pod is a Caller.
 - A Harness can check its bearer, but it cannot make a bearer. Thus an Agent cannot drive a conversation in a different
   pod.
 
+[Callers and Hooks](callers-and-hooks.md) tells how jr2 knows a Caller, and what each scope opens.
+[Give a Caller a scope](../guides/give-a-caller-a-scope.md) declares a named Caller token and uses it.
+
 ## Open observation, guarded control
 
-Each route of the [HTTP API](../reference/http-api.md) is in one of three access bands:
+Each route of the [HTTP API](../reference/http-api.md) is in one of these access bands:
 
 - [**Open**](../reference/http-api.md#band-open), with no token: the [Workflows](../reference/glossary.md#workflow), the
   structure of each Machine, and the live runs of a Workflow with their states. An open route shows no context of a run,
   and an [Emit](../reference/glossary.md#emit) shows only its type.
 - [**Authenticated**](../reference/http-api.md#band-authenticated), with the Instance token or a token of a Sandbox: the
   routes of the Agent's Menu and the fetch. A token of a Sandbox reaches only its own routes, in its own pod.
-- [**Instance token only**](../reference/http-api.md#band-instanceonly): the start of a run, the full state of a run,
-  the Gates, and cancel.
-
-Thus the Console shows the Machines and the runs without a token. When you type the Instance token in the Console, it
-can also start runs and answer Gates. The Console keeps the token in the session storage of the browser tab, and forgets
-it when you close the tab.
+- [**A Caller with a scope**](../reference/http-api.md#band-guarded): the start of a run, the full state of a run, the
+  Gates, and cancel. Each route needs one scope of a Caller (`start`, `read`, `answer`, `cancel` or `steer`) for the
+  Workflow of the run. The Instance token has each scope for each Workflow. A named Caller token has the scopes that its
+  entry gives it. A token of a Sandbox is not a Caller.
+- [**Instance token only**](../reference/http-api.md#band-instanceonly): the routes that no scope opens, such as a
+  runtime Chart, the report of the Repos and the log of a Hook (`GET /hooks/:name`).
+- [**A Hook's verifier**](../reference/http-api.md#band-hook), with no bearer token: `POST /hooks/:name`. The verifier
+  of the Hook checks each delivery.
+
+Thus the Console shows the Machines and the runs without a token. When you type a Caller's token in the Console, or log
+in at an issuer that the Instance declares, the Console also shows the controls that the Caller's scopes open: start,
+the Gates, cancel and steer. The Console keeps the credential in the session storage of the browser tab, and forgets it
+when you close the tab. [Open the Console](../guides/open-the-console.md) tells how.
 
 "Open" means open to each caller that can reach the Service of the Orchestrator: a port forward, a pod in the cluster,
 or an ingress. The names of the states and the types of the Emits are open.
 
 The Harness writes each Agent's conversation to its container log. The log has the prompts, the model's text and
-thinking, its tool calls and the answers to its picks. It does not write the results of the Working tools. Each person
-who can read the pod logs of the namespace can read these conversations.
+thinking, its tool calls and the answers to its picks. It does not write the results of the Working tools or of the MCP
+tools. Each person who can read the pod logs of the namespace can read these conversations.
+
+The Orchestrator also keeps each conversation, with the same cut, for `runs.retain` (30 days by default). Thus the kept
+copy has the same residual as the log: an answer to a pick can carry a held value that an upstream wrote into a
+`command` output, or a secret in a form that the scrub does not catch. A Caller with `read` on the Workflow can read the
+kept copy with `GET /runs/:runId/conversations`.
 
 ## Rules
 
@@ -264,7 +298,10 @@ who can read the pod logs of the namespace can read these conversations.
 - A file that the Harness process reads, such as the one that `AWS_CONFIG_FILE` or `GOOGLE_APPLICATION_CREDENTIALS`
   names in `harness.env`, cannot be in `/work`, `/tmp`, `/dev/shm` or `/home/jr2`: `jr2 up` refuses it. In another
   folder, `jr2 up` gives a warning: make sure that the user of the Sandbox cannot write the file.
-- A Held secret must name its `hosts`, unless it is a known model key with one default host.
+- A Held secret must name its `hosts`, unless it is a known model key with one default host, or the `secret` of an MCP
+  server.
+- An MCP server with a `secret` has an `https://` URL. When an entry sets `hosts`, `headers` or `paths`, they must let
+  the Stand-in through to the URL of each server that names the entry.
 - A name that a `workspace()` lists must be in the `secrets` list. A name that an Effect gives to `secret()` must be in
   it too.
 - An Effect secret has 8 characters or more.
@@ -285,22 +322,25 @@ who can read the pod logs of the namespace can read these conversations.
 
 ## Read next
 
+- [Give a Caller a scope](../guides/give-a-caller-a-scope.md)
 - [Use a local model](../guides/use-a-local-model.md)
 - [Use a hosted provider or a gateway](../guides/use-a-hosted-provider.md)
 - [Give the cluster git credentials](../guides/give-the-cluster-git-credentials.md)
 - [Run a command or call a URL with an Effect](../guides/run-a-command-or-call-a-url.md)
+- [Give an Agent MCP tools](../guides/give-an-agent-mcp-tools.md)
 - [Open the Console](../guides/open-the-console.md)
-- [Architecture](architecture.md) and [Effects](effects.md)
+- [Callers and Hooks](callers-and-hooks.md), [Architecture](architecture.md) and [Effects](effects.md)
 - The [`secrets`](../reference/config.md#secrets), [`git`](../reference/config.md#git) and
   [`harness`](../reference/config.md#harness) fields of `jr2.config.ts`,
   [`secret()`](../reference/authoring-surface/secret.md), and the [HTTP API](../reference/http-api.md)
 - [ADR-0013](../reference/decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md),
   [ADR-0014](../reference/decisions/0014-observation-is-open-run-state-is-not.md),
   [ADR-0023](../reference/decisions/0023-the-harness-prints-the-conversation.md),
-  [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-the-instance-token.md),
+  [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md),
   [ADR-0051](../reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md),
   [ADR-0058](../reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md),
   [ADR-0059](../reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md),
   [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md),
-  [ADR-0076](../reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md) and
-  [ADR-0077](../reference/decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md)
+  [ADR-0076](../reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md),
+  [ADR-0077](../reference/decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md) and
+  [ADR-0079](../reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)

package/docs/concepts/the-menu.md

@@ -21,6 +21,11 @@ and the tools block is first in it. A change to the tools block makes the provid
 Thus jr2 keeps the Menu the same, and tells each [Turn](../reference/glossary.md#turn) which part of it the Turn can
 pick now.
 
+The Menu is the last part of the tools block. The [Working tools](../reference/glossary.md#working-tools) come first,
+then the [MCP tools](../reference/glossary.md#mcp-tools), then the Menu. The model reads a Menu tool as
+`mcp__jr2__<event>`, and an MCP tool as `mcp__<server>__<tool>`, where `<server>` is never `jr2`. Only a call of a Menu
+tool is a pick. A call of an MCP tool acts on a service outside the Machine, and the Turn goes on after it.
+
 ## Where the Menu comes from
 
 You do not write the Menu. `jr2Setup` makes the Menu from the Machine when you call `createMachine`:
@@ -336,6 +341,11 @@ Each event that a party sends carries its [Sender](../reference/glossary.md#send
 [`Sender`](../reference/authoring-surface/type-sender.md)). The [Orchestrator](../reference/glossary.md#orchestrator)
 writes it on each event that a party delivers. An event that the Machine sends to itself has no Sender.
 
+A Gate's event also carries the [Caller](../reference/glossary.md#caller) that answered it: `via`, `name`, and
+`onBehalfOf` when the Caller says that it acts for a person or a service. `checked` names the fields that jr2 verified.
+jr2 always verifies `via` and `name`. It does not verify `onBehalfOf`, except for a Hook, whose signature covers it. So
+do not use an unchecked `onBehalfOf` to decide who may do something.
+
 Use the Sender when two parties can send the same event to one state. The guard
 [`sentBy(id)`](../reference/authoring-surface/sentby.md) is true for an event from that party, and for an event with no
 Sender. It is false for an event from a different party, so xstate tries the next transition. `sentBy` can only make a
@@ -344,6 +354,7 @@ transition refuse other senders. It never gives an event to a party. The positio
 ## Rules
 
 - jr2 refuses a pick that is not on the Menu.
+- A call of an MCP tool is not a pick. It does not move the Machine, and it does not end the Turn.
 - A pick that is on the Menu but not in the Allowed picks moves nothing. Its answer gives the Allowed picks.
 - While a pick is outstanding, or while the Agent's state is not at Rest, jr2 refuses each pick and delivers nothing.
   This includes a pick that would end the Turn.

package/docs/concepts/workspaces.md

@@ -583,7 +583,8 @@ In a Workspace with no Repo:
 - A `worktree()` needs a Repo Slot, a `push` needs a branch, and a `command` with an Effect secret runs on a commit.
   Thus `jr2 up` refuses all three.
 
-jr2 deletes `/work` with the Sandbox. Send what must stay before the body ends, as the example does with `upload`. A
+jr2 deletes `/work` with the Sandbox. Send what must stay before the body ends, as the example does with `upload`. The
+secret `files` that `upload` names is an entry of the `secrets` list of `jr2.config.ts`, as each Effect secret is. A
 Lost Sandbox has lost all of its work, because no commit was pushed.
 
 ## The pod
@@ -600,10 +601,10 @@ A Sandbox pod has two containers, and two more when the Machine needs them:
 ### The Sandbox Image
 
 The [Sandbox Image](../reference/glossary.md#sandbox-image) is the image of the Harness container. It holds the tools
-that an Agent's Working tools can use, and the shell that you get when you run `kubectl exec` into the pod. The image is
-yours. Its floor is glibc, git and a writable `HOME`. [Add tools to the Sandbox](../guides/add-tools-to-the-sandbox.md)
-gives the full list. jr2 adds nothing to the image. It mounts its own runtime into the pod at `/opt/jr2`, and starts the
-Harness from there. Thus the `ENTRYPOINT` and the `CMD` of the image do not run.
+that an Agent's Working tools can use, and the shell that you get with `jr2 workspace shell`. The image is yours. Its
+floor is glibc, git and a writable `HOME`. [Add tools to the Sandbox](../guides/add-tools-to-the-sandbox.md) gives the
+full list. jr2 adds nothing to the image. It mounts its own runtime into the pod at `/opt/jr2`, and starts the Harness
+from there. Thus the `ENTRYPOINT` and the `CMD` of the image do not run.
 
 `image` names it in one of two forms:
 

package/docs/get-started/a-model-decides.md

@@ -406,8 +406,7 @@ there:
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run 8fecb896-2100-4ee6-88d6-788eaf0d7244 (triage) — attached
-  → active "triaging"
+run f40a189e-b554-4310-b6e5-3b92c74e414e (triage) — attached
   → active "triaging"
   → active "clarify"
 ```
@@ -427,10 +426,10 @@ can show the same state. `jr2 run` does not return while the run waits. Keep it
 > ```text
 > …
 > → context kind-jr2 / namespace my-instance
-> run 89cc6ea5-9e2d-4f8a-8d02-18a6e47f2a5c (triage) — attached
+> run 4eafe1a5-b45d-4613-8ae3-4c85b26eeb0c (triage) — attached
 >   → active "triaging"
 >   → done "accepted"
-> {"runId":"89cc6ea5-9e2d-4f8a-8d02-18a6e47f2a5c","workflow":"triage","instanceId":"fac049b9-9dd2-4ba5-aca8-0b3ebe619701","status":"done","value":"accepted","context":{"request":"Add a --version flag to the CLI. It prints the installed version and exits.","exchange":[],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"assembly":"3eb6cd4d61bf","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
+> {"runId":"4eafe1a5-b45d-4613-8ae3-4c85b26eeb0c","workflow":"triage","instanceId":"d4daa575-f8ac-4ba9-af2e-406084adbd89","startedAt":"2026-11-06T19:24:22.161Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"done","value":"accepted","context":{"request":"Add a --version flag to the CLI. It prints the installed version and exits.","exchange":[],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"assembly":"9ff0a4d3c5da","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
 > ```
 >
 > Your run id and your [Instance ID](../reference/glossary.md#instance-id) are different, and so is the `summary`, the
@@ -444,14 +443,15 @@ The Gate holds the question of the Agent in its `meta`. In the send terminal, ru
 jr2 status <run id>
 ```
 
-`<run id>` is the run id that `jr2 run` printed. You can give its first 4 characters or more, such as `8fecb896`.
+`<run id>` is the run id that `jr2 run` printed. You can give its first 4 characters or more, such as `f40a189e`.
 [`jr2 status`](../reference/cli.md#status) prints the status of the run as one line of JSON. The Gate is in `gates`, at
 the end:
 
 ```text
 …
 → context kind-jr2 / namespace my-instance
-{"runId":"8fecb896-2100-4ee6-88d6-788eaf0d7244","workflow":"triage","instanceId":"a814d943-9b27-410c-a790-2c4225aa05ba","status":"active","value":"clarify","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where specifically should the version number be displayed (e.g., CLI flag, About screen, or help output), and what exact user action should trigger it?"}]},"children":[],"waiting":[],"held":[],"assembly":"3eb6cd4d61bf","gates":[{"gate":"clarify","path":["clarify"],"accepts":[{"name":"answer","description":"Answer the triager's question. It triages the request again with the answer in hand.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"info":{"type":"string","description":"The answer, in prose."}},"required":["info"],"additionalProperties":false}}],"acceptsNow":["answer"],"meta":{"question":"Where specifically should the version number be displayed (e.g., CLI flag, About screen, or help output), and what exact user action should trigger it?"}}]}
+{"runId":"f40a189e-b554-4310-b6e5-3b92c74e414e","workflow":"triage","instanceId":"6a6fb1c4-d6d8-4867-a51b-693c0772cc7b","startedAt":"2026-11-06T19:23:30.814Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"active","value":"clarify","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where should the version number be displayed to users (e.g., a specific command like `--version`, an 'About' screen, or a startup log message)?"}]},"children":[],"waiting":[],"held":[],"assembly":"9ff0a4d3c5da","gates":[{"gate":"clarify","path":["clarify"],"accepts":[{"name":"answer","description":"Answer the triager's question. It triages the request again with the answer in hand.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"info":{"type":"string","description":"The answer, in prose."}},"required":["info"],"additionalProperties":false}}],"acceptsNow":["answer"],"meta":{"question":"Where should the version number be displayed to users (e.g., a specific command like `--version`, an 'About' screen, or a startup log message)?"}}]}
+started by: token/instance on behalf of kubernetes-admin
 ```
 
 The `question` is in the words of the model, so your question is different. Your instance id is different too. The Gate
@@ -470,7 +470,7 @@ jr2 send <run id> --gate clarify --event answer --input '{"info":"Add a --versio
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered answer to gate "clarify" on 8fecb896-2100-4ee6-88d6-788eaf0d7244
+delivered answer to gate "clarify" on f40a189e-b554-4310-b6e5-3b92c74e414e
 ```
 
 The run goes back to `triaging`, and the Agent reads your answer. Look at the first terminal. When the Agent picks
@@ -481,7 +481,7 @@ The run goes back to `triaging`, and the Agent reads your answer. Look at the fi
   → active "triaging"
   → active "triaging"
   → done "accepted"
-{"runId":"8fecb896-2100-4ee6-88d6-788eaf0d7244","workflow":"triage","instanceId":"a814d943-9b27-410c-a790-2c4225aa05ba","status":"done","value":"accepted","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where specifically should the version number be displayed (e.g., CLI flag, About screen, or help output), and what exact user action should trigger it?","info":"Add a --version flag to the CLI. It prints the installed version and exits."}],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"assembly":"3eb6cd4d61bf","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
+{"runId":"f40a189e-b554-4310-b6e5-3b92c74e414e","workflow":"triage","instanceId":"6a6fb1c4-d6d8-4867-a51b-693c0772cc7b","startedAt":"2026-11-06T19:23:30.814Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"done","value":"accepted","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where should the version number be displayed to users (e.g., a specific command like `--version`, an 'About' screen, or a startup log message)?","info":"Add a --version flag to the CLI. It prints the installed version and exits."}],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"answers":[{"gate":"clarify","type":"answer","at":"2026-11-06T19:24:02.957Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}],"assembly":"9ff0a4d3c5da","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
 ```
 
 `summary` is the request as the model wrote it again, in one sentence. Your summary is different. The `output` of the
@@ -502,24 +502,25 @@ This request does not say what is wrong. The run goes to `clarify` and waits, as
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run 84079cb2-3cdd-4b9a-ae39-51ab873c5f3c (triage) — attached
+run 7e6c9deb-ca65-4103-b517-abf6b0028aff (triage) — attached
   → active "triaging"
   → active "clarify"
 ```
 
-`84079cb2-3cdd-4b9a-ae39-51ab873c5f3c` is the id of the second run. Your run id is different. If the Agent picks
+`7e6c9deb-ca65-4103-b517-abf6b0028aff` is the id of the second run. Your run id is different. If the Agent picks
 `accept` or `reject`, start the run again.
 
 ## Answer from the Console
 
-Open `http://localhost:4000` in your browser. If the badge after the `instance token` box shows `live`, go to the next
-step. If the box is empty, get the token. In the send terminal, run:
+Open `http://localhost:4000` in your browser. If the nav shows `as token/instance` and the badge `live`, go to the next
+step. If the nav shows the `Caller token` box, get the token. In the send terminal, run:
 
 ```sh
 kubectl -n my-instance get secret jr2-instance -o jsonpath='{.data.JR2_INSTANCE_TOKEN}' | base64 -d
 ```
 
-Type the token in the `instance token` box. Push Enter. The badge after the box shows `live`.
+Type the token in the `Caller token` box. Push Enter. The badge after the box shows `live`, and the nav shows
+`as token/instance`.
 
 Click `triage` in the Fleet rail on the left. The center shows the Machine of `triage`, with its states and transitions.
 Click the run in the rail. The Console lights the state of the run, `clarify`.

package/docs/get-started/an-agent-in-a-sandbox.md

@@ -137,7 +137,7 @@ seats: workflow "task" — who may send what, per state (ADR-0015)
   task.working agent:coder: [finish]
   task.review gate: [approve, request_changes]
 …
-sandbox image "default": building jr2-sandbox-my-instance-default:6389bdf72d50-amd64
+sandbox image "default": building jr2-sandbox-my-instance-default:5e601a543032-amd64
   no USER declared — the pod's uid-1000 fallback applies
   kind load → cluster "jr2"
 …
@@ -161,7 +161,7 @@ jr2 run task --input '{"prompt":"In docs/site/tutorial/greet, one test fails. Fi
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run 290b4be9-1e24-46a2-8cb5-27fabb3bbd3c (task) — attached
+run 79b90360-cdbf-4538-8611-d52da1b8b914 (task) — attached
   → active "placing"
   → active "provisioning"
   → active "attaching"
@@ -187,8 +187,9 @@ the Gate. Its `gate` is `body.review`, and the line ends with its `meta`. After
 for each Worktree that the run cut:
 
 ```text
-…"gate":"body.review",…,"meta":{"summary":"Fixed a bug in docs/site/tutorial/greet/src/greet.js where the name argument wasn't being trimmed. The test \"trims the name\" failed because input like \" ada \" produced \"hello,  ada \" instead of \"hello, ada\". Added `.trim()` to the name extraction so whitespace is stripped before constructing the greeting. All 6 tests now pass.","branch":"jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd","worktree":"/work/target/task"}}]}
-worktree: /work/target/task (target), branch jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd
+…"gate":"body.review",…,"meta":{"summary":"Fixed the failing \"trims the name\" test in docs/site/tutorial/greet. The bug was in src/greet.js where the name argument wasn't being trimmed, causing `greet([\" ada \"])` to output `'hello,  ada '` instead of `'hello, ada'`. Added `.trim()` to the name extraction line. All 6 tests now pass.","branch":"jr2/task-1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b","worktree":"/work/target/task"}}]}
+started by: token/instance on behalf of kubernetes-admin
+worktree: /work/target/task (target), branch jr2/task-1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b
 ```
 
 Run the command again until `gates` holds the Gate.
@@ -198,7 +199,7 @@ Run the command again until `gates` holds the Gate.
 - `worktree` is the folder in the Sandbox that holds the branch. It is
   [the Worktree](../reference/glossary.md#worktree).
 
-Copy `branch` and `worktree` from your output. The part after `jr2/task-`, here `1f34eef3-5749-4d7c-a16b-488c56ec88cd`,
+Copy `branch` and `worktree` from your output. The part after `jr2/task-`, here `1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b`,
 is the [Instance ID](../reference/glossary.md#instance-id) of the run. `jr2 status` prints it as `instanceId`. It is not
 the run id. Do not make the branch name from the run id. With the Instance token, the drawer of the
 [Console](../reference/glossary.md#console) shows the same `meta`.
@@ -208,27 +209,30 @@ If `meta` has a `reason` and no `summary`, the [Turn](../reference/glossary.md#t
 
 ## Find the Sandbox
 
-The label `jr2.dev/run` on the Sandbox holds the full run id. A prefix does not work here. Copy the full run id from the
-line `run <run id> (task) — attached` in the first terminal:
+List the Workspaces of the run with [`jr2 workspace ls`](../reference/cli.md#workspace-ls):
 
 ```sh
-kubectl -n my-instance get sandboxes -l jr2.dev/run=<run id>
+jr2 workspace ls <run id>
 ```
 
 ```text
-NAME                      PHASE   ENDPOINT                                              AGE
-ws-290b4be9-x-0-19gh8ze   Ready   http://ws-290b4be9-x-0-19gh8ze.my-instance.svc:8080   5m25s
+…
+→ context kind-jr2 / namespace my-instance
+WORKSPACE      SANDBOX                   WORKFLOW  PHASE  AGE  RUN
+79b90360/x:23  ws-79b90360-x-23-1gex8om  task      Ready  81s  held
 ```
 
-`ws-290b4be9-x-0-19gh8ze` is the name of the Sandbox. Your Sandbox has a different name. It starts with `ws-` and the
-first 8 characters of the run id. The pod of the Sandbox has the same name. The commands below write it as `<sandbox>`.
+`79b90360/x:23` is the handle of the Workspace: the first 8 characters of the run id, then the path of the Workspace in
+the run. `ws-79b90360-x-23-1gex8om` is the name of the Sandbox. The name of the Sandbox is a handle too. Your values are
+different. The commands below write the handle as `<workspace>`. `held` tells that the run holds the Sandbox.
 
 ## Look inside the Sandbox
 
-Go into the `harness` container of the pod. The Agent's tools run in this container:
+Open a shell in the Sandbox with [`jr2 workspace shell`](../reference/cli.md#workspace-shell). The shell runs as the
+Agent's tools run: in the same container, with the same files and the same limits:
 
 ```sh
-kubectl -n my-instance exec -it <sandbox> -c harness -- bash
+jr2 workspace shell <workspace>
 ```
 
 In the Sandbox, go to the fixture in the Worktree. Then run its tests. `<worktree>` is the `worktree` that you copied:
@@ -239,12 +243,12 @@ node --test
 ```
 
 ```text
-✔ greets the world by default (1.0597ms)
-✔ greets a name (0.162102ms)
-✔ shouts (0.08266ms)
-✔ trims the name (0.057171ms)
-✔ prints help (3.806196ms)
-✔ refuses an unknown flag (0.222015ms)
+✔ greets the world by default (1.208079ms)
+✔ greets a name (0.113673ms)
+✔ shouts (0.070218ms)
+✔ trims the name (0.054069ms)
+✔ prints help (0.712678ms)
+✔ refuses an unknown flag (0.242712ms)
 ℹ tests 6
 ℹ suites 0
 ℹ pass 6
@@ -252,18 +256,18 @@ node --test
 ℹ cancelled 0
 ℹ skipped 0
 ℹ todo 0
-ℹ duration_ms 53.312932
+ℹ duration_ms 49.489997
 ```
 
 Your times are different. Read the commits of the coder. The branch starts at the release tag, so the commits after the
 tag are the commits of the coder:
 
 ```sh
-git log --oneline v<version>..HEAD
+git --no-pager log --oneline v<version>..HEAD
 ```
 
 ```text
-e467788 fix: trim name in greet.js to handle leading/trailing whitespace
+8afef7d (HEAD -> jr2/task-1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b) fix: trim name in greet to handle leading/trailing whitespace
 ```
 
 Each line is one commit. The commit ids and the messages come from the model. The author of each commit is
@@ -285,7 +289,7 @@ jr2 send <run id> --gate body.review --event request_changes --input '{"notes":"
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered request_changes to gate "body.review" on 290b4be9-1e24-46a2-8cb5-27fabb3bbd3c
+delivered request_changes to gate "body.review" on 79b90360-cdbf-4538-8611-d52da1b8b914
 ```
 
 The coder continues the same conversation, with your notes as its next prompt. The Sandbox and the branch stay. Run
@@ -294,10 +298,10 @@ The coder continues the same conversation, with your notes as its next prompt. T
 ## Push the branch
 
 `task` does not push, and the Agent has no credential to push with. While the run waits at `review`, you push the branch
-from the Sandbox. Go into the Sandbox again:
+from the Sandbox. Open a shell in the Sandbox again:
 
 ```sh
-kubectl -n my-instance exec -it <sandbox> -c harness -- bash
+jr2 workspace shell <workspace>
 ```
 
 In the Sandbox, go to the Worktree. Then push the branch. `<branch>` is the `branch` that you copied:
@@ -314,7 +318,7 @@ Username for 'https://github.com': <you>
 Password for 'https://<you>@github.com':
 …
 To https://github.com/<you>/jr2.git
- * [new branch]      jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd -> jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd
+ * [new branch]      jr2/task-1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b -> jr2/task-1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b
 ```
 
 `origin` fetches through the Repo cache of the node, and pushes to your fork. Open your fork on GitHub to see the
@@ -339,7 +343,7 @@ jr2 send <run id> --gate body.review --event approve
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered approve to gate "body.review" on 290b4be9-1e24-46a2-8cb5-27fabb3bbd3c
+delivered approve to gate "body.review" on 79b90360-cdbf-4538-8611-d52da1b8b914
 ```
 
 In the first terminal, `jr2 run` prints the end of the run, then the final status as one line of JSON, and stops:
@@ -348,21 +352,25 @@ In the first terminal, `jr2 run` prints the end of the run, then the final statu
 …
   → active "teardown"
   → done "done"
-{"runId":"290b4be9-1e24-46a2-8cb5-27fabb3bbd3c","workflow":"task",…,"output":{"branch":"jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd"},"worktrees":[{"slot":"target","path":"/work/target/task","branch":"jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd"}]}
+{"runId":"79b90360-cdbf-4538-8611-d52da1b8b914","workflow":"task",…,"output":{"branch":"jr2/task-1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b"},"worktrees":[{"slot":"target","path":"/work/target/task","branch":"jr2/task-1e805d38-68ac-4ec9-acc8-fc5ce6a68f6b"}]}
 ```
 
 ## Make sure that the Sandbox is gone
 
-Use the full run id again:
+List the Workspaces of the run again:
 
 ```sh
-kubectl -n my-instance get sandboxes -l jr2.dev/run=<run id>
+jr2 workspace ls <run id>
 ```
 
 ```text
-No resources found in my-instance namespace.
+…
+→ context kind-jr2 / namespace my-instance
+WORKSPACE  SANDBOX  WORKFLOW  PHASE  AGE  RUN
 ```
 
+The list has no row, because the run removed its Sandbox.
+
 ## What happened
 
 - `task` is a Machine in a Workspace. The run made a Sandbox for the Workspace and cloned your fork into it. It cut the
@@ -373,8 +381,9 @@ No resources found in my-instance namespace.
 - The `review` Gate kept the Sandbox while the run waited. `request_changes` sent the coder back to the same
   conversation. `approve` ended the run, and the end of the Workspace removed the Sandbox. See
   [Gates](../concepts/gates.md) and [ADR-0012](../reference/decisions/0012-workspace-wrapper-machine.md).
-- You used `kubectl exec` to go into the Sandbox. The guide [Look inside a Sandbox](../guides/look-inside-a-sandbox.md)
-  gives the same commands.
+- You used `jr2 workspace shell` to go into the Sandbox. The shell runs as the Agent runs, so it cannot read the
+  credential of the Agent. The guide [Look inside a Sandbox](../guides/look-inside-a-sandbox.md) gives the same
+  commands.
 - You pushed by hand, because `task` does not push. On the next page, a Machine pushes the branch with an
   [Effect](../reference/glossary.md#effect).
 

package/docs/get-started/connect-a-model.md

@@ -183,7 +183,7 @@ jr2 up
 → .env: ANTHROPIC_API_KEY
 jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
 …
-warning: secrets[0] (ANTHROPIC_API_KEY) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider reads it, and no Effect names it (ADR-0059, ADR-0068)
+warning: secrets[0] (ANTHROPIC_API_KEY) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider reads it, and no Effect or Hook names it (ADR-0059, ADR-0068)
 …
 converged — `jr2 run <workflow>` when ready
 ```