@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/concepts/durable-runs.md

@@ -7,7 +7,8 @@ description: How a run survives a restart of the Orchestrator, what ends it, and
 
 A run is durable. The [Orchestrator](../reference/glossary.md#orchestrator) saves each run after each transition of its
 [Machine](../reference/glossary.md#machine). When the Orchestrator starts again, it continues each run that did not end,
-from the state that it saved. A run that ended stays readable for one week.
+from the state that it saved. A run that ended stays readable for [`runs.retain`](../reference/config.md#runs), 30 days
+by default.
 
 ## Why runs are durable
 
@@ -78,7 +79,7 @@ A run that the Orchestrator does not continue gets one of these results:
 
 | Result    | When                                                                                                        | What stays                                         |
 | --------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `lost`    | No Workflow has the name of the run's file, or the row holds no snapshot.                                   | The row and the reason, for one week.              |
+| `lost`    | No Workflow has the name of the run's file, or the row holds no snapshot.                                   | The row and the reason, for `runs.retain`.         |
 | `drifted` | The Orchestrator cannot read the Assembly of the run, or the Machine of the Workflow has a different shape. | The row and the snapshot.                          |
 | `failed`  | The restore of the run stopped with an error.                                                               | The run stays live. The next start tries it again. |
 
@@ -112,8 +113,9 @@ Orchestrator cannot read the Assembly that the run holds:
 
 The Orchestrator keeps a drifted run, and you can read it. [`jr2 status`](../reference/cli.md#status) shows its status,
 `drifted`, with the reason. The reason names the Workflow and the two digests, or the Assembly and why it cannot load.
-[`jr2 runs`](../reference/cli.md#runs) does not show it, because `jr2 runs` shows only the runs that run now. jr2 cannot
-move a drifted run to a new Machine. Thus, before you change the Kit version, let the runs end, or cancel them.
+By default, [`jr2 runs`](../reference/cli.md#runs) shows only the live runs, so it does not show a drifted run.
+`jr2 runs --status drifted`, `--status ended` or `--status all` shows it with its reason. jr2 cannot move a drifted run
+to a new Machine. Thus, before you change the Kit version, let the runs end, or cancel them.
 
 ## CANCEL and stop
 
@@ -137,18 +139,40 @@ The operator removes them after the same idle timeout. A run that a Machine fail
 
 `jr2 status` shows a cancelled run with the status `cancelled` and the state that it was in.
 
-## One week of history
+## History
 
-jr2 keeps the row of a run that ended for 7 days after its last write. This is true for each status that is not live:
-`done`, `failed`, `error`, `cancelled`, `lost` and `drifted`. The Orchestrator deletes the older rows when it starts,
-and one time each hour after that. A live run stays, whatever its age. A run that waits at a Gate for a month is still
-there.
+jr2 keeps the row of a run that ended for 30 days after its last write. `runs.retain` in `jr2.config.ts` changes this
+time, for example `runs: { retain: "90d" }`. It is a number and `m`, `h`, `d` or `w`, and it is at least `1h`. This is
+true for each status that is not live: `done`, `failed`, `error`, `cancelled`, `lost` and `drifted`. The Orchestrator
+deletes the older rows when it starts, and one time each hour after that. A live run stays, whatever its age. A run that
+waits at a Gate for a month is still there.
 
-You cannot change the 7 days. jr2 is not the record of the results of a run. A Machine sends its results where they
-belong, such as a pull request. `jr2 status` on a run that ended is for debugging. After the 7 days, `jr2 status` says
-that the run does not exist, and a prefix of its id no longer finds it.
+`jr2 runs --status ended` lists the runs that ended, newest first. `--workflow` and `--since` make the list shorter. jr2
+is not the record of the results of a run. A Machine sends its results where they belong, such as a pull request.
+`jr2 status` on a run that ended is for debugging. After `runs.retain`, `jr2 status` says that the run does not exist,
+and a prefix of its id no longer finds it.
 
-The week of a drifted run starts at the restart or the publish that refused it, not at its last transition.
+The time of a drifted run starts at the restart or the publish that refused it, not at its last transition.
+
+The same time applies to the [Conversations](../reference/glossary.md#conversation) of a run and to the log of each
+[Hook](../reference/glossary.md#hook). The Orchestrator keeps each conversation of an Agent while the run is kept, and
+deletes it with the row of the run. Thus `jr2 logs` reads the conversations of a run that ended, also after its
+[Sandbox](../reference/glossary.md#sandbox) is gone. [Read a conversation](../guides/read-a-conversation.md) gives the
+commands.
+
+### The state volume
+
+The Orchestrator keeps the rows of the runs, the conversations, the Assemblies and the
+[Charts](../reference/glossary.md#chart) on its state volume. A new volume claim is `5Gi` by default, and `jr2 up` keeps
+the size of a claim that exists. `runs.volume` in `jr2.config.ts` sets its size, such as `runs: { volume: "20Gi" }`.
+`jr2 up` makes the claim larger when its StorageClass allows expansion, and refuses otherwise. It never makes a claim
+smaller, because Kubernetes cannot.
+
+A space guard keeps the volume from becoming full. When the volume is more than 80% full, the Orchestrator deletes the
+conversations of the runs that ended, the oldest run first, until the volume is less than 80% full. The rows of the runs
+stay, and each one shows that its conversations went for space. The guard never deletes a conversation of a live run.
+When the volume is more than 95% full and no ended run has a conversation left, the Orchestrator keeps no more entries
+of the open conversations. One conversation also has a limit of 8 MiB, after which the Orchestrator keeps no more of it.
 
 [`jr2 down`](../reference/cli.md#down) deletes the namespace of the Instance, and the store with it. The live runs go
 too.
@@ -162,7 +186,9 @@ too.
 - The Orchestrator never continues a drifted run, and never moves it to a new Machine.
 - The Orchestrator never continues a cancelled run.
 - `CANCEL` is the only run event that `jr2 send` sends without `--gate`. `--keep` goes only with `CANCEL`.
-- jr2 keeps a run that ended for 7 days. The hourly sweep never deletes a live run.
+- jr2 keeps a run that ended for `runs.retain`, 30 days by default. The hourly sweep never deletes a live run.
+- jr2 keeps the conversations of a run for as long as it keeps the run, unless the space guard deletes them first. The
+  space guard never deletes a conversation of a live run.
 
 [Cancel a run](../guides/cancel-a-run.md) and [Watch a run](../guides/watch-a-run.md) give the commands and their
 output.
@@ -170,6 +196,7 @@ output.
 ## Read next
 
 - [Watch a run](../guides/watch-a-run.md)
+- [Read a conversation](../guides/read-a-conversation.md)
 - [Cancel a run](../guides/cancel-a-run.md)
 - [Iterate on a Machine on kind](../guides/iterate-on-a-machine-on-kind.md)
 - [Effects](effects.md), [Workspaces](workspaces.md) and [Converge](converge.md)
@@ -183,7 +210,7 @@ output.
 - [ADR-0025](../reference/decisions/0025-cancel-ends-a-run-stop-parks-it.md): `CANCEL` ends a run, and a stop parks it
 - [ADR-0030](../reference/decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md): a snapshot names the
   Machine that wrote it
-- [ADR-0065](../reference/decisions/0065-a-persist-survives-a-crash-and-history-is-a-week.md): a save survives a crash,
-  and jr2 keeps a week of history
+- [ADR-0065](../reference/decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md): a save
+  survives a crash, and jr2 keeps history for `runs.retain`
 - [ADR-0069](../reference/decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md): a
   run holds the Assembly that it started under

package/docs/concepts/effects.md

@@ -1,15 +1,16 @@
 ---
 title: Effects
-description: How a Machine runs a command, calls a URL, pushes a branch or starts a run, at most once.
+description: How a Machine runs a command, calls a URL or an MCP tool, pushes a branch or starts a run.
 ---
 
 # Effects
 
 An [Effect](../reference/glossary.md#effect) is work that a [Machine](../reference/glossary.md#machine) does outside
-itself. jr2 has four kinds: `command` runs a program in the [Workspace](../reference/glossary.md#workspace), `http`
-calls a URL, `push` pushes the Workspace's branch, and `dispatch` starts a run of a
-[Workflow](../reference/glossary.md#workflow). You write an Effect as an actor slot, beside the
-[Agents](../reference/glossary.md#agent) of the Machine.
+itself. jr2 has five kinds: `command` runs a program in the [Workspace](../reference/glossary.md#workspace), `http`
+calls a URL, `push` pushes the branch of a [Worktree](../reference/glossary.md#worktree), `dispatch` starts a run of a
+[Workflow](../reference/glossary.md#workflow), and `mcp` calls a tool of an MCP server. The Kit also gives
+[`worktree()`](../reference/authoring-surface/worktree.md), an Effect on the `command` machinery that cuts a Worktree.
+You write an Effect as an actor slot, beside the [Agents](../reference/glossary.md#agent) of the Machine.
 
 ## Why Effects exist
 
@@ -26,8 +27,8 @@ two times. A plain [xstate](https://xstate.js.org) promise has no such record.
 
 Put an Effect under `actors` in [`jr2Setup`](../reference/authoring-surface/jr2setup.md). Invoke it by its key from a
 state. The state's `onDone` gets the output of the Effect. This example is a Workflow with a Workspace. An Agent fixes
-the code, and it can ask for a test run with the pick `run_tests`. When the Agent picks `finished`, the Machine pushes
-the branch:
+the code in a Worktree that the Machine cuts first. It can ask for a test run with the pick `run_tests`. When the Agent
+picks `finished`, the Machine pushes the branch:
 
 **Anthropic**
 
@@ -39,9 +40,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -61,6 +64,9 @@ const finished = defineEvent({
 const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the coder, the tests and the push all name.
+const appTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
@@ -71,7 +77,8 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer. You commit your work on the branch.",
     }),
-    // Two Effects. Each is an actor slot, beside the Agent.
+    // Three Effects. Each is an actor slot, beside the Agent.
+    cut: worktree(),
     tests: command(["node", "--test"], { timeout: "5m" }),
     publish: push(),
     fail: fail(),
@@ -80,12 +87,20 @@ const body = jr2Setup({
   id: "test-and-push",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: appTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: ({ context }) => ({ prompt: context.prompt, cwd: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: appTree(context) }),
       },
       on: { finished: "publishing" },
       initial: "ready",
@@ -94,6 +109,7 @@ const body = jr2Setup({
         testing: {
           invoke: {
             src: "tests",
+            input: ({ context }) => ({ worktree: appTree(context) }),
             onDone: {
               target: "ready",
               // The Agent reads this text as the answer to its run_tests pick.
@@ -110,10 +126,12 @@ const body = jr2Setup({
     publishing: {
       invoke: {
         src: "publish",
+        input: ({ context }) => ({ worktree: appTree(context) }),
         onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     // A Failure ends the body, and jr2 deletes the Sandbox with its commits. To keep them, wait at
     // a Gate before this state.
     notPushed: { invoke: { src: "fail", input: { reason: "the push did not publish the fix" } } },
@@ -125,7 +143,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -139,9 +156,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -161,6 +180,9 @@ const finished = defineEvent({
 const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the coder, the tests and the push all name.
+const appTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
@@ -171,7 +193,8 @@ const body = jr2Setup({
       model: "local/qwen3.6-35b-a3b",
       instructions: "You are a careful engineer. You commit your work on the branch.",
     }),
-    // Two Effects. Each is an actor slot, beside the Agent.
+    // Three Effects. Each is an actor slot, beside the Agent.
+    cut: worktree(),
     tests: command(["node", "--test"], { timeout: "5m" }),
     publish: push(),
     fail: fail(),
@@ -180,12 +203,20 @@ const body = jr2Setup({
   id: "test-and-push",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: appTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: ({ context }) => ({ prompt: context.prompt, cwd: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: appTree(context) }),
       },
       on: { finished: "publishing" },
       initial: "ready",
@@ -194,6 +225,7 @@ const body = jr2Setup({
         testing: {
           invoke: {
             src: "tests",
+            input: ({ context }) => ({ worktree: appTree(context) }),
             onDone: {
               target: "ready",
               // The Agent reads this text as the answer to its run_tests pick.
@@ -210,10 +242,12 @@ const body = jr2Setup({
     publishing: {
       invoke: {
         src: "publish",
+        input: ({ context }) => ({ worktree: appTree(context) }),
         onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     // A Failure ends the body, and jr2 deletes the Sandbox with its commits. To keep them, wait at
     // a Gate before this state.
     notPushed: { invoke: { src: "fail", input: { reason: "the push did not publish the fix" } } },
@@ -225,7 +259,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -242,6 +275,7 @@ example above, `jr2 up` prints these lines:
 
 ```text
 effects: workflow "test-and-push" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
   tests: command ["node","--test"] — 300s, in the Harness
   publish: push — 300s, in the Sandbox Effector
 ```
@@ -253,12 +287,13 @@ run `failed`:
 
 ```text
 failures: workflow "test-and-push" — the states that fail the run (ADR-0073)
+  test-and-push.notCut: invokes fail
   test-and-push.notPushed: invokes fail
   test-and-push.failed: invokes fail
   test-and-push.lost: invokes fail
 ```
 
-## The four kinds
+## The five kinds
 
 ### `command`
 
@@ -268,10 +303,9 @@ argument that the input of the Effect fills. Thus an Agent's text cannot become
 in the argv: `["sh", "-c", "…"]`. Then the result is the result of your script. The Agent can change the files that the
 script runs, so do not trust its result more than the Agent.
 
-A `command` uses the [Worktree](../reference/glossary.md#worktree) of one
-[Repo Slot](../reference/glossary.md#repo-slot): the only slot, or the slot that its `slot` option names. Its default
-timeout is 10 minutes. Its output keeps the end of what the program wrote: 4096 characters by default (the `tail`
-option). The full output goes to the run's feed.
+Under [Repo Slots](../reference/glossary.md#repo-slot), the input of a `command` names its Worktree: `{ worktree }`, a
+Worktree that a cut made, or `/work/<slot>/default`. Its default timeout is 10 minutes. Its output keeps the end of what
+the program wrote: 4096 characters by default (the `tail` option). The full output goes to the run's feed.
 
 ### `http`
 
@@ -413,15 +447,18 @@ export const machine = jr2Setup({
 });
 ```
 
-The body can also be a file of the Worktree: `body: file(path)` (see [`file`](../reference/authoring-surface/file.md)).
-The default timeout of an `http` Effect is 30 seconds.
+The body can also be a file of a Worktree: `body: file(path)` (see [`file`](../reference/authoring-surface/file.md)).
+The input then names the Worktree, `{ worktree }`, and a cut must have made it. A path alone does not name the target of
+a credential. The default timeout of an `http` Effect is 30 seconds.
 
 ### `push`
 
-[`push`](../reference/authoring-surface/push.md) pushes the Workspace's branch to the
-[Binding](../reference/glossary.md#binding) of its Repo Slot. It uses the push credential of the `git.credentials` entry
-that the URL matches (see [`git.credentials`](../reference/config.md#git-credentials)). The Agent never reads that
-credential. These options change what a push publishes:
+[`push`](../reference/authoring-surface/push.md) pushes the branch of a Worktree to the
+[Binding](../reference/glossary.md#binding) of its Repo Slot. Its input names the Worktree, `{ worktree }`, and has no
+branch. jr2 reads the branch from the cut of that path, so an Agent that moves `HEAD` does not change what jr2 pushes.
+It uses the push credential of the `git.credentials` entry that the URL matches (see
+[`git.credentials`](../reference/config.md#git-credentials)). The Agent never reads that credential. These options
+change what a push publishes:
 
 - `pin`: push the commit that the input names, such as a commit that a [Gate](../reference/glossary.md#gate) approved.
   Without `pin`, jr2 pushes the tip of the Agent's branch when the Effect starts.
@@ -429,18 +466,26 @@ credential. These options change what a push publishes:
 - `squash`: push one commit that holds all the changes, with the message that the input gives.
 - `force`: replace what the remote branch holds.
 
-With `pin`, the input gives `{ sha }`. With `squash`, it gives `{ message }`.
+With `pin`, the input also gives `{ sha }`. With `squash`, it also gives `{ message }`.
 
 After a signed or a squashed push, the commits on the remote are not the Agent's own commits. Then jr2 moves the Agent's
 branch to the published commits. The Agent's files, index and stash do not change. The default timeout is 5 minutes.
 
+### `worktree`
+
+[`worktree()`](../reference/authoring-surface/worktree.md) cuts a Worktree, or reads the one that a cut made at that
+path. Its outcomes are `ready`, `refused` and `unknown`. It runs in the Harness container, and it is idempotent. Each
+thing that an Agent's word can cause is `refused`, and nothing changes. [Workspaces](workspaces.md) tells what a
+Worktree is, and [Cut a Worktree](../guides/cut-a-worktree.md) tells how to use it.
+
 ### `dispatch`
 
 [`dispatch`](../reference/authoring-surface/dispatch.md) starts a run of a Workflow. The new run is a run of its own: it
 has its own line in [`jr2 runs`](../reference/cli.md#runs), its own Workspaces and its own `CANCEL`. Its record names
 the run that started it: it is **dispatched by** that run. Use `dispatch` when a Machine waits for work, for example at
-a [Gate](../reference/glossary.md#gate) that a webhook answers, and each item of work needs a run of a Workflow that you
-have. To use a Machine as a part of one run, invoke it in the run instead (see [Composition](composition.md)).
+a [Gate](../reference/glossary.md#gate) that a [Hook](../reference/glossary.md#hook) answers, and each item of work
+needs a run of a Workflow that you have. To use a Machine as a part of one run, invoke it in the run instead (see
+[Composition](composition.md)).
 
 - The name of the Workflow is a constant of the definition, as `jr2 run` writes it: `"triage"`, or `"<wrapper>/<name>"`
   for a named [Chart](../reference/glossary.md#chart). An Agent cannot choose it.
@@ -452,12 +497,27 @@ have. To use a Machine as a part of one run, invoke it in the run instead (see [
   minutes with `wait`.
 - With no `target`, the new run starts in the same Orchestrator. With
   `target: { url: "https://<host>", token: secret("<name>") }`, it starts on a different Orchestrator. `url` is the
-  origin of that Orchestrator, and the secret holds its Instance token.
+  origin of that Orchestrator, and the secret holds the token of a [Caller](../reference/glossary.md#caller) of that
+  Orchestrator with the `start` scope for the Workflow, and also `read` when `wait` is `true`.
 - The new run starts under the current [Assembly](../reference/glossary.md#assembly), as a run of `jr2 run` does.
 
 The two runs are independent. A `CANCEL` of one run does not cancel the other. When the run that dispatched ends, the
 new run continues.
 
+### `mcp`
+
+[`mcp`](../reference/authoring-surface/mcp.md) calls an MCP server: `mcp.call(server, tool, { input })` calls a tool,
+`mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a prompt. `server` is a name of
+the [`mcp`](../reference/config.md#mcp) block of `jr2.config.ts`, which holds the URL and the secret of the server. Thus
+the definition holds no URL and no credential, and an Agent's word can reach only the arguments, through the input.
+
+An Agent can also hold the tools of a server as [MCP tools](../reference/glossary.md#mcp-tools), and call them in its
+Turn with no approval (see [Agents and Turns](agents-and-turns.md#the-mcp-tools)). Use an `mcp` Effect when the call
+needs the approval of a person, or when the Machine makes the call with no model. The Agent picks, a Gate waits for the
+approval, and the Effect calls the tool. The output of the Effect is the answer to the pick. Thus the approval is in the
+record of the run, and the Machine routes on it. The default timeout is the `timeout` of the server: 60 seconds when it
+sets none. [Call an MCP tool from a Machine](../guides/call-an-mcp-tool-from-a-machine.md) has an example.
+
 ## Where an Effect runs
 
 You do not choose where an Effect runs. The kind, and what the Effect names, decide it. Each
@@ -467,40 +527,51 @@ commands in it:
 | The Effect                              | Where it runs                                                                       |
 | --------------------------------------- | ----------------------------------------------------------------------------------- |
 | A `command` that names no Effect secret | The [Harness](../reference/glossary.md#harness) container of the Sandbox            |
+| A `worktree()`                          | The Harness container of the Sandbox                                                |
 | A `command` that names an Effect secret | The [Sandbox Effector](../reference/glossary.md#sandbox-effector), against a commit |
 | An `http` Effect                        | The [Instance Effector](../reference/glossary.md#instance-effector)                 |
 | An `http` Effect with a Worktree file   | The Sandbox Effector                                                                |
 | A `push`                                | The Sandbox Effector                                                                |
 | A `dispatch` with no `target`           | The Orchestrator, in its own process                                                |
 | A `dispatch` with a `target`            | The Instance Effector                                                               |
+| An `mcp` Effect                         | The Instance Effector                                                               |
 
 A `command` that names no Effect secret runs beside the Agent's [Working tools](../reference/glossary.md#working-tools).
-It runs as the Agent's user, with the tools of the [Sandbox Image](../reference/glossary.md#sandbox-image). It has the
-same [Stand-ins](../reference/glossary.md#stand-in) as the Agent's shell, and no credential of its own.
+It runs as the Agent's user, with the tools of the [Sandbox Image](../reference/glossary.md#sandbox-image). The Harness
+confines it with Landlock, as it confines the Agent's shell. It has the same
+[Stand-ins](../reference/glossary.md#stand-in) as the Agent's shell, and no credential of its own.
 
 A `command` that names an Effect secret in its `env` runs in the Sandbox Effector, a container in which the Agent runs
 nothing. It does not run in the live Worktree. It runs against one commit: the tip of the branch when it starts, or with
 `pin`, the commit that its input names. When the Worktree held changes that the command did not see, its output has
 `dirty: true`.
 
-A `command`, a `push` and an `http` Effect with a file body need a Workspace. Invoke them from the body of a
-[`workspace()`](../reference/authoring-surface/workspace.md). [Architecture](architecture.md) tells what each Effector
-is, and [Secrets and trust](secrets-and-trust.md) tells how an Effector holds the Effect secrets.
+A `command`, a `worktree()`, a `push` and an `http` Effect with a file body need a Workspace. Invoke them from the body
+of a [`workspace()`](../reference/authoring-surface/workspace.md). [Architecture](architecture.md) tells what each
+Effector is, and [Secrets and trust](secrets-and-trust.md) tells how an Effector holds the Effect secrets.
 
 ## Every outcome is output
 
 An Effect gives each outcome to `onDone`, a failure too. Route on the `outcome` field:
 
-| Kind       | The outcomes                                              | The output type                                                           |
-| ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `command`  | `exited`, `timeout`, `killed`, `unknown`                  | [`CommandOutput`](../reference/authoring-surface/type-commandoutput.md)   |
-| `http`     | `response`, `unreachable`, `refused`, `unknown`           | [`HttpOutput`](../reference/authoring-surface/type-httpoutput.md)         |
-| `push`     | `pushed`, `rejected`, `diverged`, `unknown`               | [`PushOutput`](../reference/authoring-surface/type-pushoutput.md)         |
-| `dispatch` | `started`, `settled`, `refused`, `unreachable`, `unknown` | [`DispatchOutput`](../reference/authoring-surface/type-dispatchoutput.md) |
+| Kind       | The outcomes                                                      | The output type                                                           |
+| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `worktree` | `ready`, `refused`, `unknown`                                     | [`WorktreeOutput`](../reference/authoring-surface/type-worktreeoutput.md) |
+| `command`  | `exited`, `timeout`, `killed`, `unknown`                          | [`CommandOutput`](../reference/authoring-surface/type-commandoutput.md)   |
+| `http`     | `response`, `unreachable`, `refused`, `unknown`                   | [`HttpOutput`](../reference/authoring-surface/type-httpoutput.md)         |
+| `push`     | `pushed`, `rejected`, `diverged`, `unknown`                       | [`PushOutput`](../reference/authoring-surface/type-pushoutput.md)         |
+| `dispatch` | `started`, `settled`, `refused`, `unreachable`, `unknown`         | [`DispatchOutput`](../reference/authoring-surface/type-dispatchoutput.md) |
+| `mcp`      | `returned`, `refused`, `unreachable`, `input-required`, `unknown` | [`McpCallOutput`](../reference/authoring-surface/type-mcpcalloutput.md)   |
 
 A test that fails is `exited` with a code that is not 0. A program that the container does not have is `exited` with
 code 127. An HTTP 4xx or 5xx status is a `response`. A Workflow that refuses the run input of a `dispatch` is `refused`,
-with the status code and the report of the refusal. `unknown` means that jr2 cannot tell what the Effect did.
+with the status code and the report of the refusal. A tool of an `mcp` Effect that ran and failed is `returned` with
+`isError: true`. `unknown` means that jr2 cannot tell what the Effect did.
+
+Each union is open: it holds a stand-in member, `LaterOutcome`, so a later release can add an outcome and your Machine
+still works. Route on what you know, and give the rest a last arm with no guard. With no match, the run stays in that
+state and shows no fault. So `createMachine`, `jr2 check`, `jr2 up` and the Chart door refuse an `onDone` with a guard
+on its last arm. An invoke with no `onDone` is legal: the Effect settles, and the state stays.
 
 The `onError` route of an Effect is only for a defect in the Machine or in the config. For example, the Effect is not in
 a Workspace, or an `arg()` has no value, or an Open part has no binding. An outcome that means that the work did not
@@ -521,8 +592,10 @@ jr2 records its output. After an Orchestrator restart, jr2 reads the record:
 | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | A `command` that names no Effect secret | jr2 attaches to it again. When the Harness does not know it, the outcome is `unknown`. It never runs again.                                                  |
 | A `command` that names an Effect secret | jr2 follows it. When the Sandbox Effector lost it, jr2 runs it again against the same commit. With no commit recorded, the outcome is `unknown`.             |
+| A `worktree()`                          | jr2 attaches to it again. When the Harness does not know it, jr2 sends it again: a cut is idempotent.                                                        |
 | A `push`                                | jr2 follows it. When the Sandbox Effector lost it, jr2 pushes the same commit again, and no other commit. With no commit recorded, the outcome is `unknown`. |
 | An `http` Effect                        | jr2 follows it. When no Effector holds it, jr2 sends it again only if it is `idempotent`. Else the outcome is `unknown`.                                     |
+| An `mcp` Effect                         | As an `http` Effect. jr2 does not read the `idempotentHint` of a tool: only your `idempotent` mark counts.                                                   |
 | A `dispatch`                            | jr2 sends the start again, with the same key. The Orchestrator answers with the run that the key started, and it starts no second run.                       |
 
 A `command` that names no Effect secret runs the code of the Worktree, and that code can spend a Stand-in. Thus jr2 does
@@ -530,7 +603,8 @@ not run it two times. A `push`, and a `command` that names an Effect secret, run
 jr2 can send them again with that commit.
 
 To try again, write it in the Machine: a route from the outcome back into the state. Mark an `http` Effect `idempotent`
-only when a second call is safe: the call has its own idempotency key, or it only reads.
+only when a second call is safe: the call has its own idempotency key, or it only reads. The same rule is true for an
+`mcp` Effect.
 
 ## When the state exits
 
@@ -539,8 +613,8 @@ When the run leaves the state, the Effect stops:
 - jr2 kills the process group of a `command` that names no Effect secret.
 - The Sandbox Effector stops a `command` that names an Effect secret. It sends `SIGTERM`, waits 5 seconds, then sends
   `SIGKILL`.
-- An `http` Effect and a `push` have no stop. jr2 stops waiting for the output, but the Effector can still finish the
-  work.
+- An `http` Effect, an `mcp` Effect and a `push` have no stop. jr2 stops waiting for the output, but the Effector can
+  still finish the work.
 - A `dispatch` with `wait` stops its wait. The run that it started continues.
 
 jr2 records the stop, and the Machine gets no output. There is no "finally" in a Machine: cleanup is a state. Put an
@@ -569,8 +643,10 @@ pick waits for its answer.
 ## Rules
 
 - An Effect is a key of `actors`. `createMachine` refuses an Effect that you write directly in an `invoke`.
-- A `command`, a `push` and an `http` Effect with a file body run only inside a `workspace()`.
-- Under a Workspace with more than one Repo Slot, a `command`, a `push` and a file body name their slot.
+- The last arm of an Effect's `onDone` has no guard. `createMachine` refuses one that has:
+  `machine "<id>": state "<state>" (Effect "<slot>") has an onDone with no unguarded last arm — … (ADR-0075)`.
+- A `command`, a `worktree()`, a `push` and an `http` Effect with a file body run only inside a `workspace()`.
+- Under a Workspace with more than one Repo Slot, a `push` names its `slot`.
 - The host of an `http` URL is literal. An Effect secret never goes in the host, the query or the fragment of a URL.
 - Each Effect secret that an Effect names is in the `secrets` list of `jr2.config.ts`, with a value of 8 characters or
   more. `jr2 up` refuses a name that is not in the list, and a value that is shorter.
@@ -578,11 +654,14 @@ pick waits for its answer.
   a `committer` field there.
 - Each param of a pick that enters an Effect's state has a reader: the Effect's input, `fill`, a guard or an `assign`.
   `createMachine` refuses a param that nothing reads, and a `fill` key that is also a param.
-- A packaged Machine can leave an `http` URL, a `command` argv, one Effect secret name or the `target` of a `dispatch`
-  Open. The composer binds it one time with `customize()`. `jr2 up` refuses an Open part that nobody bound.
+- A packaged Machine can leave an `http` URL, a `command` argv, one Effect secret name, the `target` of a `dispatch`, or
+  the server and the tool of an `mcp` Effect Open. The composer binds it one time with `customize()`. `jr2 up` refuses
+  an Open part that nobody bound.
 - A `dispatch` with no `target` names a Workflow that the Assembly has. `jr2 up` refuses a name that it does not have,
   and an `input` schema that the input of that Workflow does not take.
 - The `url` of a `dispatch` target is an origin only: a scheme, a host and a port, with no path, no query and no user.
+- An `mcp` Effect names a remote server that the `mcp` block declares. `jr2 up` refuses a server that the block does not
+  declare, and a stdio server.
 
 The guides give the refusal text of each rule.
 
@@ -591,13 +670,17 @@ The guides give the refusal text of each rule.
 - [Run a command or call a URL with an Effect](../guides/run-a-command-or-call-a-url.md)
 - [Push and sign a branch](../guides/push-and-sign-a-branch.md)
 - [Start a run from a run](../guides/start-a-run-from-a-run.md)
+- [Call an MCP tool from a Machine](../guides/call-an-mcp-tool-from-a-machine.md)
 - [Workspaces](workspaces.md), [The Menu](the-menu.md), [Secrets and trust](secrets-and-trust.md)
 - Reference: [`command`](../reference/authoring-surface/command.md), [`http`](../reference/authoring-surface/http.md),
   [`push`](../reference/authoring-surface/push.md), [`dispatch`](../reference/authoring-surface/dispatch.md),
-  [`fromPick`](../reference/authoring-surface/frompick.md), [`answer`](../reference/authoring-surface/answer.md)
+  [`mcp`](../reference/authoring-surface/mcp.md), [`fromPick`](../reference/authoring-surface/frompick.md),
+  [`answer`](../reference/authoring-surface/answer.md)
 - [ADR-0067](../reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md):
   an Effect is an actor slot, and runs at most once unless marked idempotent
 - [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md): an Effector holds
   an Effect's secrets and signs its wire
 - [ADR-0071](../reference/decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md): a run starts a run through a
   `dispatch` Effect
+- [ADR-0079](../reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md):
+  a Machine calls an MCP server as an Effect, and the Machine is the approval