@jr2/orchestrator 0.5.1 → 0.7.0

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 a7a8fc26-851f-4459-9efb-845389acfda9 (task) — attached
+run 79b90360-cdbf-4538-8611-d52da1b8b914 (task) — attached
   → active "placing"
   → active "provisioning"
   → active "attaching"
@@ -183,10 +183,13 @@ jr2 status <run id>
 ```
 
 The status is one line of JSON. While the coder works, `gates` is `[]`. When the run waits at `review`, `gates` holds
-the Gate. Its `gate` is `body.review`, and the line ends with its `meta`:
+the Gate. Its `gate` is `body.review`, and the line ends with its `meta`. After the JSON, `jr2 status` prints one line
+for each Worktree that the run cut:
 
 ```text
-…"gate":"body.review",…,"meta":{"summary":"Fixed the \"trims the name\" test failure in docs/site/tutorial/greet. The bug was that the name wasn't being trimmed before constructing the greeting output. Added `.trim()` to the name extraction in src/greet.js, changing `args.find(...) ?? \"world\"` to `(args.find(...) ?? \"world\").trim()`. All 6 tests now pass.","branch":"jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16","worktree":"/work/target/jr2-task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16"}}]}
+…"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.
@@ -196,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 `d8f59a0c-9ea1-43fc-8d0c-b153caf70f16`,
+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`.
@@ -206,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-a7a8fc26-x-38-oakg23   Ready   http://ws-a7a8fc26-x-38-oakg23.my-instance.svc:8080   5m10s
+…
+→ 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-a7a8fc26-x-38-oakg23` 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:
@@ -237,12 +243,12 @@ node --test
 ```
 
 ```text
-✔ greets the world by default (1.172165ms)
-✔ greets a name (0.138615ms)
-✔ shouts (0.117168ms)
-✔ trims the name (0.067037ms)
-✔ prints help (0.642445ms)
-✔ refuses an unknown flag (0.281559ms)
+✔ 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
@@ -250,18 +256,18 @@ node --test
 ℹ cancelled 0
 ℹ skipped 0
 ℹ todo 0
-ℹ duration_ms 55.318206
+ℹ 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
-1a84393 Fix: trim the name before using it in greet output
+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
@@ -283,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 a7a8fc26-851f-4459-9efb-845389acfda9
+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
@@ -292,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:
@@ -312,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-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16 -> jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16
+ * [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
@@ -337,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 a7a8fc26-851f-4459-9efb-845389acfda9
+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:
@@ -346,33 +352,38 @@ In the first terminal, `jr2 run` prints the end of the run, then the final statu
 …
   → active "teardown"
   → done "done"
-{"runId":"a7a8fc26-851f-4459-9efb-845389acfda9","workflow":"task",…,"output":{"branch":"jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16"}}
+{"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
-  branch from the release tag, in a Worktree in `/work/target/`. See [Workspaces](../concepts/workspaces.md).
+  branch from the release tag, in the Worktree `/work/target/task`. See [Workspaces](../concepts/workspaces.md).
 - `task` left its Repo Slots and the model of its coder Open. `customize()` bound them where you registered the
   Workflow, and `jr2 up` refuses a Workflow with an Open part. See [Composition](../concepts/composition.md) and
   [ADR-0054](../reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md).
 - 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
 ```

package/docs/get-started/create-an-instance.md

@@ -86,7 +86,7 @@ jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
 typecheck: tsc --noEmit (the instance's own compiler)
 agents: (none) (carried by 1 workflow machine(s))
 assembly: staging
-assembly: ba71fa27f37f (kit v<version>; 1 workflow(s): ping)
+assembly: 50e6f81e3bfb (kit v<version>; 1 workflow(s): ping)
 kubernetes: v1.36.1 (floor 1.35, ADR-0037)
 first contact: deploy instance "my-instance" to context kind-jr2 (create namespace "my-instance")? [y/N] y
 platforms: linux/amd64 (from 1 schedulable node(s))
@@ -94,14 +94,15 @@ images: installed kit — the published v<version> Harness, operator and Orchest
 …
 orchestrator: waiting for rollout
 orchestrator: verified — 1 pod(s) running ghcr.io/snapwich/jr2-orchestrator:<version>
-instance effector: none (no Effect is placed there)
-assembly: publishing ba71fa27f37f (no current Assembly)
-assembly: ba71fa27f37f is current — workflows: ping
+instance effector: none (no Effect is placed there, and no Hook needs it)
+assembly: publishing 50e6f81e3bfb (no current Assembly)
+assembly: 50e6f81e3bfb is current — workflows: ping
 swept nothing — every labeled image is named by a live root
+…
 converged — `jr2 run <workflow>` when ready
 ```
 
-`<version>` is the Kit version, such as `0.4.1`. `ba71fa27f37f` is the hash of the
+`<version>` is the Kit version, such as `0.4.1`. `50e6f81e3bfb` is the hash of the
 [Assembly](../reference/glossary.md#assembly) of your Instance: your Workflows and your config. Your hash can be
 different. It changes each time that your Workflows or your config change.
 
@@ -122,9 +123,9 @@ JSON:
 
 ```text
 → context kind-jr2 / namespace my-instance
-run a256ff8a-f99f-42f5-975c-4f93a5008c56 (ping) — attached
+run db1fd16f-166f-4575-b8fb-60cd80321308 (ping) — attached
   → done "done"
-{"runId":"a256ff8a-f99f-42f5-975c-4f93a5008c56","workflow":"ping","instanceId":"0e82cc83-7c15-426f-86ff-e7354873a429","status":"done","value":"done","context":{"message":"hi","reply":"pong: hi"},"children":[],"waiting":[],"held":[],"assembly":"ba71fa27f37f"}
+{"runId":"db1fd16f-166f-4575-b8fb-60cd80321308","workflow":"ping","instanceId":"71af068c-e150-4802-8b1c-6d07d3bb4a08","startedAt":"2026-11-06T19:15:47.436Z","status":"done","value":"done","context":{"message":"hi","reply":"pong: hi"},"children":[],"waiting":[],"held":[],"assembly":"50e6f81e3bfb","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}
 ```
 
 Your run id and your [Instance ID](../reference/glossary.md#instance-id) are not the same as the ones here. The run is
@@ -155,16 +156,17 @@ Click `ping`. The center shows its Machine, with the states `responding` and `do
 ## Unlock the Console
 
 Without a token, you can look at the runs in the Console, but you cannot start a run or answer a
-[Gate](../reference/glossary.md#gate). For these, you need the Instance token. In the first terminal, run:
+[Gate](../reference/glossary.md#gate). For these, you need the token of a Caller with a scope. Here, use the Instance
+token. In the first terminal, run:
 
 ```sh
 kubectl -n my-instance get secret jr2-instance -o jsonpath='{.data.JR2_INSTANCE_TOKEN}' | base64 -d
 ```
 
-The command prints the token, 48 hexadecimal characters, with no newline after it. Paste the token in the
-`instance token` box in the Console nav. Push Enter. The Console checks the token. Then the badge after the box shows
-`live`, and a `start` button shows next to `ping`. The browser tab keeps the token until you close the tab. `jr2 up`
-keeps the same token each time that it runs.
+The command prints the token, 48 hexadecimal characters, with no newline after it. Paste the token in the `Caller token`
+box in the Console nav. Push Enter. The Console checks the token. Then the badge after the box shows `live`, the nav
+shows `as token/instance`, and a `start` button shows next to `ping`. The browser tab keeps the token until you close
+the tab. `jr2 up` keeps the same token each time that it runs.
 
 Keep the port forward open. The next pages use the Console. [Open the Console](../guides/open-the-console.md) gives more
 about the Console.
@@ -181,8 +183,9 @@ each time that you change the folder. [Converge](../concepts/converge.md) explai
 it. [Machines and Workflows](../concepts/machines-and-workflows.md) explains the two words.
 
 The Console is a page that the Orchestrator serves, at [`GET /`](../reference/http-api.md#get). Anyone who can reach it
-can see the runs. Only the holder of the Instance token can start a run or answer a Gate
-([ADR-0032](../reference/decisions/0032-the-console-unlocks-with-the-instance-token.md)).
+can see the runs. Only a [Caller](../reference/glossary.md#caller) with a scope, such as the holder of the Instance
+token, can start a run or answer a Gate
+([ADR-0032](../reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md)).
 
 `jr2 init` wrote `AGENTS.md` for your Assistant. It points to the docs that the Kit installs in
 `node_modules/@jr2/orchestrator/docs/`. These are the docs of your Kit version