@jr2/orchestrator 0.4.1 → 0.5.1

package/docs/guides/iterate-on-a-machine-on-kind.md

@@ -0,0 +1,190 @@
+---
+title: Iterate on a Machine on kind
+description: Change a Machine, converge the change into your kind cluster, and run it again.
+---
+
+# Iterate on a Machine on kind
+
+Change a [Machine](../reference/glossary.md#machine), converge the change into your kind cluster, and run it again.
+
+kind runs a Kubernetes cluster on your computer, and jr2 uses it as its local cluster. The loop has three steps: edit
+the file, run [`jr2 up`](../reference/cli.md#up), and run the [Workflow](../reference/glossary.md#workflow). The
+[Orchestrator](../reference/glossary.md#orchestrator) runs only the Machines that the last `jr2 up` gave it. Thus a
+change that you save does nothing until you converge it.
+
+The examples on this page use the kind cluster `jr2` and the [Instance](../reference/glossary.md#instance) `my-instance`
+from [Get started](../get-started/install.md). They change `ping`, the Workflow that `jr2 init` writes. It needs no
+model.
+
+## Change the Machine
+
+Open `workflows/ping.ts`. In the line of the `respond` actor, change `` `pong: ${input.message}` `` to
+`` `pong, again: ${input.message}` ``. Save the file.
+
+To find the errors before you converge, run [`jr2 check`](../reference/cli.md#check). `jr2 up` runs the same check
+first:
+
+```sh
+jr2 check
+```
+
+It typechecks the Instance, loads each Workflow and walks its Machine, with no cluster. It prints the typecheck, the
+`effects:` lines, the `seats:` lines and the `failures:` lines, and then `check: passed`. When it refuses, it gives the
+line that `jr2 up` gives, and exits with `1`. `npm run typecheck` runs only the compiler, so it does not find a refusal
+that occurs when a module loads. The checks of `git.credentials` and of the images need the cluster, so only `jr2 up`
+does them.
+
+## Converge the change
+
+Run `jr2 up` in the Instance folder:
+
+```sh
+jr2 up
+```
+
+For an Instance that has only `ping`, the output is:
+
+```text
+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: 0adf5bff234d (kit v<version>; 1 workflow(s): ping)
+…
+sandbox images: skipped (no registered Machine composes a Sandbox)
+…
+orchestrator: applying (image ghcr.io/snapwich/jr2-orchestrator:<version>)
+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 0adf5bff234d (current is ba71fa27f37f)
+assembly: 0adf5bff234d is current — workflows: ping
+swept nothing — every labeled image is named by a live root
+converged — `jr2 run <workflow>` when ready
+```
+
+`0adf5bff234d` is the hash of the new [Assembly](../reference/glossary.md#assembly), and `ba71fa27f37f` is the hash of
+the Assembly that was current. Your hashes can be different. `<version>` is the
+[Kit version](../reference/glossary.md#kit-version). The hash changed, because the Workflow changed. Thus `jr2 up`
+published the new Assembly to the [Orchestrator](../reference/glossary.md#orchestrator). The image of the Orchestrator
+did not change, so its pod did not start again. Your output has more lines when your Machines use a model, a
+[Sandbox](../reference/glossary.md#sandbox) or an [Effect](../reference/glossary.md#effect).
+
+`jr2 up` says `converged` only when the Orchestrator made the new Assembly current. When it stops with `refusing:`, the
+Assembly that was current stays current. In both cases, fix the cause, then run `jr2 up` again.
+[Fix a failed converge](fix-a-failed-converge.md) gives each refusal and its fix.
+
+## Run it again
+
+Run the Workflow:
+
+```sh
+jr2 run ping --input '{"message":"hi"}'
+```
+
+```text
+→ context kind-jr2 / namespace my-instance
+run 7df09f94-d26d-44c3-ba1e-0279f16ccacb (ping) — attached
+  → done "done"
+{"runId":"7df09f94-d26d-44c3-ba1e-0279f16ccacb","workflow":"ping","instanceId":"b2ec6504-553e-495a-a8be-62715c6d8595","status":"done","value":"done","context":{"message":"hi","reply":"pong, again: hi"},"children":[],"waiting":[],"held":[],"assembly":"0adf5bff234d"}
+```
+
+Your run id and your instance id are different. The `reply` comes from the new Machine, and `assembly` is the hash of
+the new Assembly.
+
+The pod of the Orchestrator did not start again, so the port forward of the [Console](../reference/glossary.md#console)
+stays open. Load the page again. Then the Console draws the new Machine. [Open the Console](open-the-console.md) gives
+the command for the port forward.
+
+## Why a repeated jr2 up is fast
+
+`jr2 up` does the full converge each time, but it builds a Sandbox Image only when its folder changed, and it publishes
+the Assembly only when its hash changed. It never builds a Kit image, such as the image of the Orchestrator: the cluster
+pulls each one at the Kit version. [Converge](../concepts/converge.md#the-images) tells why. You see it in these lines:
+
+- `(fresh — build skipped; --force to rebuild anyway)`: the tag of a
+  [Sandbox Image](../reference/glossary.md#sandbox-image) did not change, so `jr2 up` did not build it.
+- `(host-built — build skipped; --force to rebuild)`: your computer holds the Sandbox Image with that tag, so `jr2 up`
+  did not build it.
+- `(current — publish skipped)`: the Orchestrator already has the Assembly with this hash.
+
+A second `jr2 up` with no change builds nothing and publishes nothing:
+
+```text
+…
+assembly: 0adf5bff234d (current — publish skipped)
+swept nothing — every labeled image is named by a live root
+converged — `jr2 run <workflow>` when ready
+```
+
+To build all the images again, run `jr2 up --force`. It builds an image again also when its tag did not change. It also
+sends the Assembly again, and the Orchestrator answers that the Assembly did not change.
+
+## The runs that are live when you converge
+
+A publish does not start the pod of the Orchestrator again. A run that is live keeps the Assembly that it started under.
+Thus it continues on the old Machine, to its end, also after a restart. A run that waits at a
+[Gate](../reference/glossary.md#gate) still waits there, and its Sandbox stays. A `jr2 run` that is attached stays
+attached. Each new run uses the new Machine.
+
+[`jr2 status`](../reference/cli.md#status), with no run id, shows each Assembly that a live run holds:
+
+```sh
+jr2 status
+```
+
+In this output, a run of the Workflow `rollout` from [Write a Workflow](write-a-workflow.md) waits at its Gate. It
+started before the last `jr2 up`:
+
+```text
+→ context kind-jr2 / namespace my-instance
+assembly: a44731886e21 (kit v<version>, current), 0 live runs hold it
+assembly: 3a3fa3c403f9 (kit v<version>), 1 live run holds it
+data plane: yes
+```
+
+The Orchestrator removes the old Assembly when the last run that holds it ends. `data plane: yes` tells that the
+Orchestrator runs in a cluster, so it can make Sandboxes.
+
+A live run cannot continue when the Orchestrator cannot read its Assembly: the volume lost it, or it is for a different
+Kit version. Then the Orchestrator keeps the run with the status `drifted`, and `jr2 status <run id>` gives the reason.
+[Upgrade the Kit version](upgrade-the-kit-version.md) tells when this occurs.
+
+## Rules
+
+- `jr2 up` changes nothing in the cluster when the Instance does not typecheck:
+  `refusing: this instance does not typecheck — nothing was built and nothing was applied`. The output of the compiler
+  follows, one line for each error.
+- `jr2 up` changes nothing in the cluster when a registered Machine has an [Open](../reference/glossary.md#open) part
+  that nobody bound. It prints the line that binds it:
+  `refusing: workflow "<name>" leaves <part> open — bind it where the Machine is registered: export const machine = customize(<import>, <binding>)  (<adr>)`.
+  [Bind a shipped Machine's Open parts](bind-open-parts.md) tells how.
+- `jr2 up` prints an error in a Workflow module as `error: <message>`, and exits with `1`. It changes nothing in the
+  cluster. [Write a Workflow](write-a-workflow.md) gives each error.
+- `jr2 up` refuses when kubectl has no current context:
+  ``error: no kube context — `kind create cluster` (or point kubectl at one), then re-run `jr2 up` ``
+- `jr2 up` loads the Sandbox Images into the nodes only on a kind cluster: a context whose name starts with `kind-`. For
+  a different context with no [`registry`](../reference/config.md#registry), it builds nothing:
+  ``error: context <context> is not a kind cluster and no `registry` is configured — set `registry` in jr2.config.ts (from env) so the image can be pushed (ADR-0019)``
+- The Orchestrator refuses an Assembly that fails its checks. `jr2 up` prints the reason and the lines of the report,
+  and the Assembly that was current stays current:
+  `refusing: the Orchestrator refused Assembly <hash> (HTTP <status>): <error> — the previous Assembly is still current`
+
+## Read next
+
+- [Converge](../concepts/converge.md)
+- [Durable runs](../concepts/durable-runs.md): the Machine shape and drift.
+- [ADR-0019](../reference/decisions/0019-one-converging-command-against-the-current-context.md): one converging command
+  against the current context.
+- [ADR-0069](../reference/decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md): a
+  publish loads the Assembly with no restart, and a run keeps its Assembly.
+- [ADR-0038](../reference/decisions/0038-jr2-up-builds-every-image-it-deploys.md): `jr2 up` builds each image that the
+  cluster runs, with a content hash as its tag.
+- [ADR-0041](../reference/decisions/0041-a-build-the-host-already-holds-is-not-spent-again.md): a build that your
+  computer holds is not done again.
+- [ADR-0050](../reference/decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md): the
+  typecheck is the first step of `jr2 up`.
+- [Write a Workflow](write-a-workflow.md)
+- [Move from kind to a shared cluster](move-from-kind-to-a-shared-cluster.md)
+- Reference: [`jr2 up`](../reference/cli.md#up), [`jr2 run`](../reference/cli.md#run),
+  [`jr2 status`](../reference/cli.md#status)

package/docs/guides/let-an-agent-write-a-chart.md

@@ -0,0 +1,226 @@
+---
+title: Let an Agent write a Chart
+description: Write a Chart wrapper whose planner Agent writes a Chart, runs it, and corrects it.
+---
+
+# Let an Agent write a Chart
+
+Write a [Chart wrapper](../reference/glossary.md#chart-wrapper) whose planner [Agent](../reference/glossary.md#agent)
+writes a [Chart](../reference/glossary.md#chart) and runs it.
+
+This example is `workflows/plan.ts`. The planner reads the task, and it picks `run_chart` with a Chart. The Chart runs
+in the [Open body](../reference/glossary.md#open-body) `body`. It can use the Agent `writer` and the
+[Gate](../reference/glossary.md#gate), and it can add its own Agents with the model of the tab. When the door refuses
+the Chart, the planner gets the report as the answer to its pick, and it can pick again:
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import {
+  agent,
+  chartSchemaFor,
+  defineEvent,
+  fail,
+  fromPick,
+  jr2Setup,
+  openBody,
+  type OpenBodyDeclaration,
+  type OpenBodyOutput,
+} from "@jr2/orchestrator";
+```
+
+The model of the tab:
+
+**Anthropic**
+
+```ts
+const model = "anthropic/claude-haiku-5-5";
+```
+
+**Local**
+
+```ts
+const model = "local/qwen3.6-35b-a3b";
+```
+
+The Open body and the pick:
+
+```ts
+// What a Chart can use. A Chart names these parts by their slot keys, and nothing else.
+const declaration: OpenBodyDeclaration = {
+  // The Agent `writer`, and the Gate, so that a Chart can ask a person.
+  lends: { agents: ["writer"], gate: true },
+  // A Chart can add its own Agents, with this model and with no Sandbox.
+  allows: { models: [model], workspace: ["none"] },
+  // The limits of one run of a Chart.
+  ceilings: { turns: 12, wallClock: "30m", transitions: 500, fanOut: 2, size: 65536 },
+};
+```
+
+```ts
+// The pick of the planner. Its parameter is a Chart, in the grammar of this Open body.
+const runChart = defineEvent({
+  name: "run_chart",
+  description: "Run this Chart. Its outcome is the answer to this call.",
+  input: z.object({ chart: chartSchemaFor(declaration) }),
+});
+```
+
+The Machine:
+
+```ts
+export const machine = jr2Setup({
+  types: {} as { context: Context; input: Input },
+  events: [runChart],
+  actors: {
+    planner: agent({
+      model,
+      workspace: "none",
+      instructions: "You plan work as a Chart. You write the Chart, and you run it with run_chart.",
+    }),
+    writer: agent({
+      model,
+      workspace: "none",
+      instructions: "You write clear, short text for engineers.",
+    }),
+    body: openBody(declaration),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "plan",
+  input: z.object({ task: z.string() }),
+  context: ({ input }) => ({ task: input.task }),
+  on: { "agent.fault": ".failed" },
+  initial: "planning",
+  states: {
+    planning: {
+      invoke: {
+        src: "planner",
+        input: ({ context }) => ({
+          prompt: `Write a Chart for this task, and pick run_chart with it: ${context.task}`,
+          continue: true,
+        }),
+      },
+      initial: "ready",
+      states: {
+        ready: { on: { run_chart: "running" } },
+        running: {
+          // The Chart of the pick runs here. The task goes into the input of the Chart.
+          invoke: {
+            src: "body",
+            input: fromPick(runChart, ({ context }: { context: Context }) => ({ task: context.task })),
+            onDone: [
+              {
+                guard: ({ event }) => outcome(event.output) === "done",
+                target: "#plan.done",
+                actions: assign({ result: ({ event }) => event.output as OpenBodyOutput }),
+              },
+              // A refusal or a ceiling goes back to the planner, as the answer to its pick.
+              { target: "ready", actions: assign({ result: ({ event }) => event.output as OpenBodyOutput }) },
+            ],
+          },
+        },
+      },
+    },
+    done: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+  output: ({ context }) => context.result,
+});
+```
+
+## Read the example
+
+- [`openBody(declaration)`](../reference/authoring-surface/openbody.md) is the slot that the Chart binds. Its
+  declaration lends the Agent `writer` and the Gate, lets a Chart add Agents with `model` and no Sandbox, and sets the
+  ceilings. [Charts](../concepts/charts.md#the-open-body) tells what each part does.
+- The pick `run_chart` has one parameter, `chart`. Its schema is
+  [`chartSchemaFor(declaration)`](../reference/authoring-surface/chartschemafor.md): the Chart grammar with the names of
+  this Open body. The model gets it as the parameters of its tool.
+- The state `running` is below the state of the planner. Thus the pick is
+  [outstanding](../reference/glossary.md#outstanding) while the Chart runs, and the Turn of the planner stays open.
+- [`fromPick`](../reference/authoring-surface/frompick.md) gives the Chart of the pick to the Open body, and adds
+  `task`. The Chart reads it as `{{input.task}}`.
+- The Open body ends with an [`OpenBodyOutput`](../reference/authoring-surface/type-openbodyoutput.md). `done` goes to
+  the final state. `refused` and `ceiling` go back to `ready`, where jr2 answers the pick with the output. The planner
+  reads the report, and it can pick `run_chart` again.
+
+## Run it
+
+Run [`jr2 up`](../reference/cli.md#up). The planner and `writer` are Menu-only Agents, so `jr2 up` converges the
+[Instance Harness](../reference/glossary.md#instance-harness). It also puts the key of each model in `allows.models` on
+the Instance Harness, because a Chart can add an Agent with that model. Then start a run:
+
+```sh
+jr2 run plan --input '{"task":"Write the release notes for the greet CLI, and ask a person to approve them."}'
+```
+
+Open the run in the [Console](../reference/glossary.md#console). After the planner picks `run_chart`, the Console draws
+the Chart inside `running`. The Chart of each run is different, because the planner writes it.
+
+When the door refuses a Chart, the answer to the pick holds the report. The log of the
+[Instance Harness](../reference/glossary.md#instance-harness) shows each answer. Replace `<namespace>` with the
+namespace of your Instance, and `<run id>` with the full run id. The log holds the lines of each run of a Menu-only
+Agent, and the first `grep` keeps the lines of your run:
+
+```sh
+kubectl -n <namespace> logs statefulset/jr2-instance-harness -c harness | grep -F '[<run id>/' | grep -F '[run_chart answer]'
+```
+
+For example, in one run with the model of each tab, the first Chart of the planner gave a prompt to the Gate. The door
+refused it:
+
+```text
+[planner] [<run id>/root/planner] [run_chart answer] Delivered "run_chart" to the workflow (delivery ede62e99-7596-41fe-bda3-c6dcc194517f). The workflow took it and is back in the state that asked for this turn. Its answer: the output of `body`: {"outcome":"refused","report":["states.approve.invoke.input.prompt: a Gate's input takes gate and meta only; `gate` is the kit's Gate, which waits for an outside answer (a human, a webhook), not an Agent's Turn"]}. Your turn is not over. Allowed now: `mcp__jr2__run_chart`.
+```
+
+The planner writes a different Chart in each run. Thus your report can be different, and the door can accept the first
+Chart. Your delivery id is different. After a refusal, the planner can pick `run_chart` again with a corrected Chart.
+
+When the Chart gets to its Gate, the run waits. `jr2 status <run id>` gives the id of the Gate, such as
+`0.plan.planning.running.approve`, and the events that it takes. [Answer a Gate](answer-a-gate.md) tells how to answer
+it. Then the Chart ends, and the run ends with the status `done`.
+
+## Rules
+
+- [`openBody()`](../reference/authoring-surface/openbody.md) refuses a declaration that is not correct, with one line
+  for each problem. The refusal starts with `openBody: `, then each problem, separated by `; `. For example:
+  - `lends.<kind>: an Open body lends agents, effects, machines, guards, actions, delays, gate and fail only`
+  - `allows.workspace: "<value>" is not a Workspace access (write, read, none)`
+  - `ceilings.<ceiling>: missing; an Open body states every ceiling`
+  - `ceilings.<ceiling>: <value> is not a positive integer`
+  - `ceilings.wallClock: <value> is not a positive duration (like "90s", "10m", "2h")`
+  - `ceilings.size: <value> is more than 1048576 bytes (1 MiB)`
+- `createMachine` refuses a lent name that the Machine does not have. The refusal starts with
+  `machine "<id>": Open body "<slot>": `, then each problem:
+  - `lends.<kind>: "<name>" is no actor slot of this Machine; its actors: <slots>`
+  - `lends.<kind>: "<name>" is not an Agent slot (agent(...))`, or `is not an Effect slot`, or `is not a Machine`
+  - `lends.<kind>: "<name>" is no <guard, action or delay> of this Machine; its <kind>: <names>`
+  - `lends.<kind>: "<name>" is the Open body itself`
+- The door refuses a Chart, and gives one line for each problem. Each line starts with the path in the Chart. For
+  example:
+  - `<path>: "<name>" is not a lent actor or an Agent of this Chart; lent: <names>; kit: <gate, fail or none>; minted: <names>`
+  - `<path>: "<name>" is not a lent guard; lent guards: <names> (and jr2.sentBy with params { id }, and jr2.failure)`
+  - `<path>.type: "<name>" is not a generic or a lent action; generic: set, append, increment, clear; lent: <names>`
+  - ``<path>: <reference> is supplied by nothing: it is not in the initial `context`, and no `set`, `append` or `increment` writes it``,
+    then what a write supplies
+  - `<path>: "<reference>" is not a reference: it starts at context, event or input (a reference is a path, never an expression)`
+- The door then compiles the Chart as the Open body does. A line of this last check starts with `(chart):`, and names a
+  state by its [xstate](https://xstate.js.org) id (for example `body.writing`), not by its path in the Chart.
+- A refusal is output, not an error: the Open body ends with `{ outcome: "refused", report }`. A Chart wrapper that
+  routes `onDone` back to the state of the pick gives the report to the planner.
+- When the Turn of an Agent of the Chart cannot go on, and no transition of the Chart takes
+  [`agent.fault`](../reference/mechanism-events.md#agent-fault), the Open body sends the event, unchanged, to this
+  wrapper. The wrapper's root route takes it, as it takes the fault of `planner`, so the run ends `failed`.
+- A Chart that gets to a ceiling stops, and the Open body ends with `{ outcome: "ceiling", ceiling, detail }`.
+
+## Read next
+
+- [Charts](../concepts/charts.md)
+- [The Menu](../concepts/the-menu.md): how a pick waits for its answer.
+- [Run a Chart by name](run-a-chart-by-name.md)
+- Reference: [`openBody`](../reference/authoring-surface/openbody.md),
+  [`OpenBodyDeclaration`](../reference/authoring-surface/type-openbodydeclaration.md),
+  [`chartSchemaFor`](../reference/authoring-surface/chartschemafor.md),
+  [`fromPick`](../reference/authoring-surface/frompick.md)
+- [ADR-0070](../reference/decisions/0070-a-machine-lends-its-parts-to-a-chart.md): a Machine lends its parts to a Chart.

package/docs/guides/look-inside-a-sandbox.md

@@ -0,0 +1,174 @@
+---
+title: Look inside a Sandbox
+description: Open a shell in the Sandbox of a run, and read the branch that its Agent works on.
+---
+
+# Look inside a Sandbox
+
+Open a shell in the [Sandbox](../reference/glossary.md#sandbox) of a run, and read the branch that its
+[Agent](../reference/glossary.md#agent) works on.
+
+A [Workspace](../reference/glossary.md#workspace) of the run makes the Sandbox, and deletes it when the body of the
+Workspace gets to its final state or fails. The [Rules](#rules) give the cases in which the Sandbox stays. The Sandbox
+is a pod. Its `harness` container runs the [Harness](../reference/glossary.md#harness), and the Agent's
+[Working tools](../reference/glossary.md#working-tools) run in it. When you use `kubectl exec`, you get a shell in the
+same container. An Agent that has only the [Menu](../reference/glossary.md#menu) has no Sandbox. To read its
+conversation, see [Watch a run](watch-a-run.md).
+
+In the commands on this page, replace these values:
+
+- `<namespace>`: the namespace of your [Instance](../reference/glossary.md#instance). It is the
+  [`name`](../reference/config.md#name) in `jr2.config.ts`. When `jr2.config.ts` sets no `name`, it is the name of the
+  Instance folder.
+- `<run id>`: the full run id. [`jr2 run`](../reference/cli.md#run) prints it in the line
+  `run <run id> (<workflow>) — attached`. [`jr2 runs`](../reference/cli.md#runs) prints the `runId` of each live run. A
+  prefix does not work here, because `kubectl` does not know the run ids.
+
+Give each `jr2` command in the Instance folder.
+
+## Find the Sandbox
+
+The label `jr2.dev/run` on each Sandbox holds the full id of its run:
+
+```sh
+kubectl -n <namespace> get sandboxes -l jr2.dev/run=<run id>
+```
+
+```text
+NAME                     PHASE   ENDPOINT                                             AGE
+ws-a1322024-x-2-h8pgwk   Ready   http://ws-a1322024-x-2-h8pgwk.my-instance.svc:8080   16s
+```
+
+- `NAME` is the name of the Sandbox, here `ws-a1322024-x-2-h8pgwk`. Your name is different. It starts with `ws-`, then
+  the first 8 characters of the run id. The pod has the same name. In the commands below, write it in place of
+  `<sandbox>`.
+- A run that has two Workspaces at the same time has two rows.
+- `PHASE` is `Pending` until the pod is ready and its node has a fresh cache of each Repo. Then it is `Ready`. It is
+  `Lost` when the pod is gone, and a `Lost` Sandbox does not get a new pod. A delete removes the Sandbox at once, so you
+  seldom see the phase `Terminating`.
+- When the run has no Sandbox now, `kubectl` prints `No resources found in <namespace> namespace.`
+- When a [Workflow](../reference/glossary.md#workflow) puts `branch` and `worktree` in the `meta` of a
+  [Gate](../reference/glossary.md#gate), as the `review` Gate of [`task`](../reference/machines.md#task) does,
+  [`jr2 status <run id>`](../reference/cli.md#status) prints them in `gates`. Give this command on your computer, not in
+  the Sandbox. Then you can copy the Worktree from the status.
+
+## Open a shell
+
+```sh
+kubectl -n <namespace> exec -it <sandbox> -c harness -- bash
+```
+
+The default [Sandbox Image](../reference/glossary.md#sandbox-image) that [`jr2 init`](../reference/cli.md#init) writes
+starts from `node:24-slim`, which has `bash`. If your Sandbox Image has no `bash`, use `sh`.
+
+## Find the Worktree
+
+Each [Repo Slot](../reference/glossary.md#repo-slot) of the Workspace has a folder in `/work`. In it, `default` is a
+clone of the [Repo](../reference/glossary.md#repo), and the [Worktree](../reference/glossary.md#worktree) of the branch
+is beside it. To show the folders of the Repo Slots, use this command:
+
+```sh
+ls /work
+```
+
+Replace `<Repo Slot>` with the name of a slot, such as `target`:
+
+```sh
+git -C /work/<Repo Slot>/default worktree list
+```
+
+For the slot `target` of a run of `task`, the output is:
+
+```text
+/work/target/default                                        1e40403 [main]
+/work/target/jr2-task-0cbdb607-48dc-4eab-9469-f8e41f2b0025  1e40403 [jr2/task-0cbdb607-48dc-4eab-9469-f8e41f2b0025]
+```
+
+The first line is the clone, on the default branch of the Repo. The second line is the Worktree of the branch. Your
+commits and your instance id are different.
+
+- In the commands below, `<branch>` is the name of the branch, and `<worktree>` is the folder of its Worktree. The
+  folder is the name of the branch, with each `/` changed to `-`. For example, the branch `jr2/task-<instance id>` has
+  the Worktree `/work/target/jr2-task-<instance id>`.
+- A Workspace that has a commit to review has one more Worktree, `/work/<Repo Slot>/<worktree>-review`. It holds that
+  commit, with no branch.
+- The attach makes the folders and the Worktrees after the Sandbox is `Ready`. Until then, `/work` has no folder for the
+  Repo Slot.
+
+## Read the branch
+
+Go into the Worktree:
+
+```sh
+cd /work/<Repo Slot>/<worktree>
+```
+
+Show the files that the Agent changed and did not commit:
+
+```sh
+git status
+```
+
+Show the commits of the branch, newest first. The history of its base comes after them:
+
+```sh
+git log --oneline
+```
+
+Show the changes in the last commit:
+
+```sh
+git show --stat HEAD
+```
+
+You can also give one command, with no shell:
+
+```sh
+kubectl -n <namespace> exec <sandbox> -c harness -- git -C /work/<Repo Slot>/<worktree> log --oneline
+```
+
+## Push the branch
+
+The Agent has no credential to push with. To keep its commits after the Sandbox goes, push the branch from the Worktree.
+Replace `<branch>` with the name of the branch:
+
+```sh
+git push origin <branch>
+```
+
+`origin` fetches through the [Repo cache](../concepts/architecture.md#the-repo-cache) of the node, and pushes to the
+Repo. When the Repo url starts with `https://`, `git push` asks for a user name and a password. Give your user name.
+Give a token that can push to the Repo as the password.
+
+A [Machine](../reference/glossary.md#machine) can also push the branch with an
+[Effect](../reference/glossary.md#effect). See [Push and sign a branch](push-and-sign-a-branch.md).
+
+> **Caution**
+>
+> The Agent works in the same files as your shell, so it sees each change that you make there. When the Sandbox goes, a
+> commit that you did not push goes with it.
+
+## Rules
+
+- The Workspace deletes its Sandbox when its body gets to its final state. When the body of each Workspace of the run
+  has got to its final state, no Sandbox has the label of the run.
+- A run that a Machine fails deletes its Sandboxes, as a final state does. See
+  [Fail the run](write-a-workflow.md#fail-the-run). To keep the work, wait at a [Gate](../reference/glossary.md#gate)
+  before the state that fails.
+- A Workspace that its parent stops after Placing, for example with an `after` on the state that holds it, does not
+  delete its Sandbox. The [operator](../concepts/architecture.md#the-operator) deletes it 30 minutes after the last
+  renewal of its [Lease](../reference/glossary.md#lease).
+- [`jr2 send`](../reference/cli.md#send) `<run id> --event CANCEL` deletes the Sandboxes of the run. To keep them, add
+  `--keep`. See [Cancel a run](cancel-a-run.md).
+- A run that faults keeps its Sandboxes. After a fault, and after a CANCEL with `--keep`, nothing renews the Lease of
+  its Workspace. The operator deletes the Sandbox 30 minutes after the last renewal.
+- A Workspace in [Placing](../reference/glossary.md#placing) deletes its Sandbox at once, also after a fault and after a
+  CANCEL with `--keep`. Its Sandbox has no node yet, so it has nothing to look inside.
+
+## Read next
+
+- [Workspaces](../concepts/workspaces.md)
+- [ADR-0004](../reference/decisions/0004-worktree-provisioning-model.md): the clone and the Worktree.
+- [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md): the containers of a Sandbox.
+- [ADR-0012](../reference/decisions/0012-workspace-wrapper-machine.md): when a Workspace deletes its Sandbox.
+- [Watch a run](watch-a-run.md)