@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/guides/cut-a-worktree.md

@@ -0,0 +1,560 @@
+---
+title: Cut a Worktree
+description: Make a Worktree with worktree(), choose what a cut refuses, and remove a Worktree.
+---
+
+# Cut a Worktree
+
+Make each [Worktree](../reference/glossary.md#worktree) that your [Machine](../reference/glossary.md#machine) needs,
+with the [`worktree()`](../reference/authoring-surface/worktree.md) [Effect](../reference/glossary.md#effect).
+
+A [Workspace](../reference/glossary.md#workspace) only clones each [Repo](../reference/glossary.md#repo). The body of
+the Workspace does a [Cut](../reference/glossary.md#cut) of each Worktree in a state of its own. In this
+[Workflow](../reference/glossary.md#workflow), a coder [Agent](../reference/glossary.md#agent) works on a new branch. A
+reviewer reads the coder's commit in a second Worktree, with no branch. Then the Machine removes the review Worktree,
+and pushes the commit that the reviewer read. Save the file as `workflows/fix-a-bug.ts` in your
+[Instance](../reference/glossary.md#instance):
+
+**Anthropic**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import {
+  agent,
+  arg,
+  branchName,
+  command,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  readyOf,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when you committed the fix.",
+  input: z.object({}),
+});
+const pass = defineEvent({ name: "pass", description: "Call this when the commit is correct.", input: z.object({}) });
+const revise = defineEvent({
+  name: "revise",
+  description: "Call this when the commit is not correct. Say what to change.",
+  input: z.object({ notes: z.string() }),
+});
+
+// The run input. `branchName` refuses a name that the cut and the push refuse.
+const runInput = z.object({ prompt: z.string(), branch: branchName });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+type Context = BodyInput & { reviewed?: string };
+
+// Your Machine names each folder. So it knows each path before the cut.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+const cloneTree = (context: BodyInput) => `${context.workspace.repos.app}/default` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: Context },
+  events: [finished, pass, revise],
+  actors: {
+    coder: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You fix the bug. You commit the fix." }),
+    reviewer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      workspace: "read",
+      instructions: "You review one commit. You change nothing.",
+    }),
+    // Each run gets a new branch: the cut refuses a branch that exists.
+    cut: worktree({ expect: "new" }),
+    // No `--force`: git refuses a Worktree with changes, and the output holds its exit code.
+    // The state below goes on with either result: a Worktree that stays does no harm here.
+    remove: command(["git", "worktree", "remove", arg("path")], { timeout: "1m" }),
+    publish: push({ pin: true }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix-a-bug",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: context.prompt, cwd: coderTree(context), continue: true }),
+      },
+      on: { finished: "reading" },
+    },
+    // A cut of the same path reads the Worktree. `head` is the tip of the branch, whatever HEAD the coder left.
+    reading: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [
+          {
+            guard: ({ event }) => isReady(event.output),
+            target: "detaching",
+            actions: assign({ reviewed: ({ event }) => readyOf(event.output).head }),
+          },
+          { target: "notCut" },
+        ],
+      },
+    },
+    // Each round forces this folder to the commit, and cleans it.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review ${context.reviewed}.`, cwd: reviewTree(context) }),
+      },
+      on: {
+        pass: "removing",
+        revise: {
+          target: "coding",
+          actions: assign({ prompt: ({ event }) => `Change the fix as the review asks:\n\n${event.notes}` }),
+        },
+      },
+    },
+    // The clone is not the Worktree that goes, so the command runs there.
+    removing: {
+      invoke: {
+        src: "remove",
+        input: ({ context }) => ({ path: reviewTree(context), worktree: cloneTree(context) }),
+        onDone: "publishing",
+      },
+    },
+    // The input names the Worktree and the commit. jr2 reads the branch from the cut of that path.
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: coderTree(context), sha: context.reviewed! }),
+        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" } } },
+    notPushed: { invoke: { src: "fail", input: { reason: "the push did not succeed" } } },
+    failed: { invoke: { src: "fail", input: { reason: "an Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/<you>/app.git" },
+});
+```
+
+**Local**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import {
+  agent,
+  arg,
+  branchName,
+  command,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  readyOf,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when you committed the fix.",
+  input: z.object({}),
+});
+const pass = defineEvent({ name: "pass", description: "Call this when the commit is correct.", input: z.object({}) });
+const revise = defineEvent({
+  name: "revise",
+  description: "Call this when the commit is not correct. Say what to change.",
+  input: z.object({ notes: z.string() }),
+});
+
+// The run input. `branchName` refuses a name that the cut and the push refuse.
+const runInput = z.object({ prompt: z.string(), branch: branchName });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+type Context = BodyInput & { reviewed?: string };
+
+// Your Machine names each folder. So it knows each path before the cut.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+const cloneTree = (context: BodyInput) => `${context.workspace.repos.app}/default` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: Context },
+  events: [finished, pass, revise],
+  actors: {
+    coder: agent({ model: "local/qwen3.6-35b-a3b", instructions: "You fix the bug. You commit the fix." }),
+    reviewer: agent({
+      model: "local/qwen3.6-35b-a3b",
+      workspace: "read",
+      instructions: "You review one commit. You change nothing.",
+    }),
+    // Each run gets a new branch: the cut refuses a branch that exists.
+    cut: worktree({ expect: "new" }),
+    // No `--force`: git refuses a Worktree with changes, and the output holds its exit code.
+    // The state below goes on with either result: a Worktree that stays does no harm here.
+    remove: command(["git", "worktree", "remove", arg("path")], { timeout: "1m" }),
+    publish: push({ pin: true }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix-a-bug",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: context.prompt, cwd: coderTree(context), continue: true }),
+      },
+      on: { finished: "reading" },
+    },
+    // A cut of the same path reads the Worktree. `head` is the tip of the branch, whatever HEAD the coder left.
+    reading: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [
+          {
+            guard: ({ event }) => isReady(event.output),
+            target: "detaching",
+            actions: assign({ reviewed: ({ event }) => readyOf(event.output).head }),
+          },
+          { target: "notCut" },
+        ],
+      },
+    },
+    // Each round forces this folder to the commit, and cleans it.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review ${context.reviewed}.`, cwd: reviewTree(context) }),
+      },
+      on: {
+        pass: "removing",
+        revise: {
+          target: "coding",
+          actions: assign({ prompt: ({ event }) => `Change the fix as the review asks:\n\n${event.notes}` }),
+        },
+      },
+    },
+    // The clone is not the Worktree that goes, so the command runs there.
+    removing: {
+      invoke: {
+        src: "remove",
+        input: ({ context }) => ({ path: reviewTree(context), worktree: cloneTree(context) }),
+        onDone: "publishing",
+      },
+    },
+    // The input names the Worktree and the commit. jr2 reads the branch from the cut of that path.
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: coderTree(context), sha: context.reviewed! }),
+        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" } } },
+    notPushed: { invoke: { src: "fail", input: { reason: "the push did not succeed" } } },
+    failed: { invoke: { src: "fail", input: { reason: "an Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/<you>/app.git" },
+});
+```
+
+Write your GitHub user name in place of `<you>`. The Agents use the model of the tab.
+[Push and sign a branch](push-and-sign-a-branch.md) tells how to give the push a credential.
+
+## Name the path
+
+The path of a Worktree is exactly `/work/<slot>/<name>`. `<slot>` is a [Repo Slot](../reference/glossary.md#repo-slot).
+`<name>` is one folder name that you choose. It is not `default`, and it starts with neither `.` nor `-`. It does not
+change with the name of the branch.
+
+Make the path from `context.workspace.repos`, and add `as const`. Then the compiler can read the slot, and it refuses a
+slot that the Workspace does not have:
+
+```ts
+// Your Machine names each folder. So it knows each path before the cut.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+const cloneTree = (context: BodyInput) => `${context.workspace.repos.app}/default` as const;
+```
+
+The check of the compiler is a help. It sees only a literal path under `jr2Setup`. jr2 also checks each path when the
+run gets to it.
+
+## Cut a branch
+
+Invoke the Effect with `{ path, branch }`. `branch` is required, unless you give `detach`. The Machine names the branch,
+so jr2 never reads it from the folder or from `HEAD`.
+
+```ts
+cutting: {
+  invoke: {
+    src: "cut",
+    input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+    // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+    onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+  },
+},
+```
+
+The cut fetches, then finds the branch in this order:
+
+1. A local branch.
+2. `origin/<branch>`. The new local branch tracks it.
+3. A new branch, with no upstream. It starts from `from`, or from the base of the
+   [Binding](../reference/glossary.md#binding) when the input has no `from`.
+
+The output is `ready`, `refused` or `unknown`. Each Effect outcome is open, so give the last arm of `onDone` no guard.
+[`isReady`](../reference/authoring-surface/isready.md) is the guard for `ready`.
+
+| The field of `ready` | What it holds                                                                |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `slot`, `path`       | The Repo Slot and the path of the Worktree.                                  |
+| `branch`             | The branch of the cut, or `null` for a detached cut.                         |
+| `head`               | The tip of the branch, or the commit of a detached cut. It is never `HEAD`.  |
+| `found`              | How the cut found it: `local`, `remote`, `none`, `held` or `commit`.         |
+| `stale`              | The warning of git when the fetch failed. The cut used what the clone holds. |
+
+`held` means that a cut made this path before, so the Worktree holds earlier work. No fetch happens, and the cut does
+not check `expect` again. Thus a cut of the same path also reads a Worktree:
+
+```ts
+// A cut of the same path reads the Worktree. `head` is the tip of the branch, whatever HEAD the coder left.
+reading: {
+  invoke: {
+    src: "cut",
+    input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+    onDone: [
+      {
+        guard: ({ event }) => isReady(event.output),
+        target: "detaching",
+        actions: assign({ reviewed: ({ event }) => readyOf(event.output).head }),
+      },
+      { target: "notCut" },
+    ],
+  },
+},
+```
+
+[`readyOf`](../reference/authoring-surface/readyof.md) gives the `ready` output to an action, because xstate does not
+carry the guard to the action.
+
+## Choose what a cut refuses
+
+`expect` says if the branch can exist. It is an option of `worktree()`, so a run cannot change it:
+
+- `worktree()`: use a local branch, then a branch of the remote, then make a new branch.
+- `worktree({ expect: "new" })`: refuse a branch that exists, local or on the remote. Use it for a name that a planner
+  or a run input chooses for new work. A name that collides is then a refusal, and not the branch of a different person.
+- `worktree({ expect: "existing" })`: refuse a branch that does not exist, and make nothing. Use it when a run must
+  continue a branch that exists.
+
+The example gives the coder a new branch for each run:
+
+```ts
+// Each run gets a new branch: the cut refuses a branch that exists.
+cut: worktree({ expect: "new" }),
+```
+
+A pick param or a run input that names a branch can use the schema
+[`branchName`](../reference/authoring-surface/branchname.md). It is the rule of the cut and of the push. Thus jr2
+refuses a bad name at the [Menu](../reference/glossary.md#menu) or at the door, before the cut.
+
+## Read a commit with no branch
+
+Invoke the Effect with `{ path, detach }` to hold one commit, with no branch. The example gives this Worktree to a
+reviewer. Each cut forces the folder to the commit, and cleans it. Ignored files stay, so that a reviewer can run the
+tests:
+
+```ts
+// Each round forces this folder to the commit, and cleans it.
+detaching: {
+  invoke: {
+    src: "cut",
+    input: ({ context }) => ({ path: reviewTree(context), detach: context.reviewed! }),
+    onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+  },
+},
+```
+
+`expect` applies only to a branch. A slot with `expect` can thus also make a detached cut, as `cut` does here. A cut
+that you lend to a [Chart](../reference/glossary.md#chart) must state `expect`, so a Chart uses such a slot too.
+
+## Give the Worktree to each step
+
+Each step names its Worktree by its path:
+
+| The step                                | The key of its input |
+| --------------------------------------- | -------------------- |
+| A [Turn](../reference/glossary.md#turn) | `cwd`                |
+| A `command`                             | `worktree`           |
+| A `push`                                | `worktree`           |
+| An `http` Effect with a file            | `worktree`           |
+
+Each key is required under Repo Slots. A Turn that wants the folder above the Repo Slots states `cwd: "/work"`. To read
+a slot that has no Worktree, use `/work/<slot>/default`. A Workspace with no Repo Slot, and an Agent with
+`workspace: "none"`, need no `cwd`.
+
+A Turn of a Working Agent that names a path where no Worktree exists does not start. The
+[Harness](../reference/glossary.md#harness) refuses it, and the Machine gets `agent.fault` with
+``the Turn's `cwd` <path> does not exist: cut the Worktree first``.
+
+A `push` has no branch in its input. jr2 finds the cut of that path, and reads the branch there. An Agent can move
+`HEAD`, and it cannot change that record:
+
+```ts
+// The input names the Worktree and the commit. jr2 reads the branch from the cut of that path.
+publishing: {
+  invoke: {
+    src: "publish",
+    input: ({ context }) => ({ worktree: coderTree(context), sha: context.reviewed! }),
+    onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
+  },
+},
+```
+
+## Run more than one coder
+
+The author chooses how many Agents work in a Workspace. Agents in one Worktree share git, as people in one checkout do.
+Give each coder that needs its own branch a Worktree of its own, with its own path and its own branch. Each Worktree
+uses the one clone. To merge the branches, cut a Worktree for the merge target, and run `git merge` in a `command`
+there. No fetch is necessary, because each branch is in the clone. Then push once.
+
+Cuts of one clone wait for each other, so they do not collide.
+
+## Remove a Worktree
+
+jr2 has no Effect that removes a Worktree. To remove one, run `git worktree remove` in a `command`:
+
+```ts
+// No `--force`: git refuses a Worktree with changes, and the output holds its exit code.
+// The state below goes on with either result: a Worktree that stays does no harm here.
+remove: command(["git", "worktree", "remove", arg("path")], { timeout: "1m" }),
+```
+
+Invoke the `command` in a different Worktree. The clone is always there, so the example names it:
+
+```ts
+// The clone is not the Worktree that goes, so the command runs there.
+removing: {
+  invoke: {
+    src: "remove",
+    input: ({ context }) => ({ path: reviewTree(context), worktree: cloneTree(context) }),
+    onDone: "publishing",
+  },
+},
+```
+
+- The branch stays. Only the folder goes.
+- A Worktree with changes or with untracked files stays too, and git exits with a code that is not 0. Route on `exited`
+  to see it, or add `--force` to the argv to drop those changes. Ignored files do not stop the removal.
+- jr2 keeps its record of the cut. A cut of the same path and the same branch makes the folder again. Its `found` is
+  `local`. A detached cut makes the folder again too.
+- jr2 deletes each Worktree with the [Sandbox](../reference/glossary.md#sandbox). Thus a Machine needs this recipe only
+  to free the disk during a run.
+
+## Rules
+
+These settle as `refused`, and nothing changes. Route them to your last arm:
+
+- a path that is not a Worktree path: `"<path>" is not a Worktree path: /work/<slot>/<name>, with one segment in <name>`
+- the path of the clone: `"<path>" is the clone: it stays as the attach left it; cut a sibling`
+- a name that starts with `.` or `-`: `"<path>": a Worktree's name starts with neither . nor -`
+- a slot that the Workspace does not have:
+  `"<path>" names Repo Slot "<slot>", which its Workspace does not carry (<slots>)`
+- no branch and no commit, or both: ``a cut names a branch, or a commit in `detach` ``
+- `from` on a detached cut: ``a detached cut takes no `from` ``
+- `expect: "new"` on a branch that exists: `<branch> exists, and this cut makes only a new branch`
+- `expect: "existing"` on a branch that does not exist: `<branch> does not exist, and this cut makes nothing`
+- a re-cut that does not agree with the first cut: `<path> was cut for <branch>, not <other>`,
+  `<path> was cut detached, not for <branch>`, or `<path> was cut from <from>, not <other>`
+- a folder that no cut made: `<path> is a folder and no Worktree: a cut removes nothing it did not make`
+- a detached cut of a Worktree that no cut made:
+  `<path> is a Worktree no cut made, and a detached cut forces only its own`
+- a commit that the clone does not hold, also after a fetch: `no commit "<sha>" in this clone`
+- a branch that `default/` or a different Worktree holds: `<path> holds <branch>: read it there, or cut another branch`
+- a name that the clone does not hold, after a fetch that failed:
+  `<branch> is not in this clone, and the remote did not answer, so it may exist there: <warning>`
+- a `from` on a branch that exists:
+  ``<branch> exists, and it is not at `from` "<from>": `from` starts a new branch and moves no branch``
+
+A name that git or the push refuses also settles `refused`. The `reason` says why, for example
+`"<name>" is not a branch name`.
+
+These are not `refused`, because no word of a run can cause them:
+
+- `createMachine` refuses an Effect's `onDone` with a guard on its last arm:
+  `machine "<id>": state "<state>" (Effect "<slot>") has an onDone with no unguarded last arm — … (ADR-0075)`
+- `jr2 up` refuses a `worktree()` in a Workspace with no Repo Slot:
+  `workflow "<workflow>": worktree "<slot>" runs in Workspace of workflow "<workflow>", which has no Repo Slot: a cut makes a Worktree of a Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`
+- when a `worktree()` starts, it refuses the same Workspace:
+  `worktree "<slot>" runs under a Workspace with no Repo Slot: a cut makes a Worktree of a Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`
+- a Repo Slot name that starts with `.`, because `/work/.jr2/` is reserved for jr2. See
+  [Bind a shipped Machine's Open parts](bind-open-parts.md).
+
+## Read next
+
+- [Workspaces](../concepts/workspaces.md): the clone, the folders, and what names a Worktree.
+- [Effects](../concepts/effects.md): where a cut runs, and what a restart does to it.
+- [Push and sign a branch](push-and-sign-a-branch.md): the `push` Effect.
+- [Set an Agent's access and Dials](set-an-agents-access-and-dials.md): a reviewer in a detached Worktree.
+- [Let an Agent write a Chart](let-an-agent-write-a-chart.md): a cut that you lend to a Chart.
+- Reference: [`worktree`](../reference/authoring-surface/worktree.md),
+  [`WorktreeOptions`](../reference/authoring-surface/type-worktreeoptions.md),
+  [`WorktreeInput`](../reference/authoring-surface/type-worktreeinput.md),
+  [`WorktreeOutput`](../reference/authoring-surface/type-worktreeoutput.md) and
+  [`branchName`](../reference/authoring-surface/branchname.md).
+- [ADR-0075](../reference/decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md): a Machine cuts a
+  Worktree, and the Workspace only clones.

package/docs/guides/fix-a-failed-converge.md

@@ -308,14 +308,23 @@ refusals of a push and of the [Effector](../reference/glossary.md#effector) imag
 
   The check has a limit. The check pod has labels of its own, so a NetworkPolicy that selects the Harness pods by label
   does not select the check pod. When such a policy closes the egress of the Harness pods, the check can pass while a
-  Turn fails.
+  Turn fails. The egress policy of jr2, which closes the cloud metadata addresses, selects the check pod too.
 
   A check can fail when the model works, for example a model that loads for longer than the check waits. When you know
   that the models work, run `jr2 up --skip-provider-preflight`. No check pod runs, and the converge goes on. `jr2 up`
   writes one line:
-  `warning: provider: preflight skipped (--skip-provider-preflight) — these models were not checked: <model>, …`. A
-  model that does not work then fails in a run, as `agent.fault`, and not at the converge. Remove the flag when the
-  check works again.
+  `warning: provider: preflight skipped (--skip-provider-preflight) — these models were not checked: <model>, …`. When
+  an Agent names a remote MCP server, the line ends with
+  `; these MCP servers' tool lists were not checked: <server>, …`. A model that does not work then fails in a run, as
+  `agent.fault`, and not at the converge. Remove the flag when the check works again.
+
+- When an Agent names a remote MCP server, the check pod also asks the server for its tools, through its Custodian. Each
+  name in an allowlist must be a tool of the server:
+  `error: mcp: workflow "<workflow>": Agent "<slot>" allowlists the tool "<tool>", which "<server>" does not list — it lists: <tools> (ADR-0079)`.
+  A server that refuses the token (a 401 or a 403) is an error too:
+  `error: mcp: "<server>" at <url> refused the request from a pod on <where> (HTTP <status>) — a wrong or expired value of <NAME>, or a binding of it (hosts, headers, paths) that does not let its Stand-in through to the url; every call of an Agent that names it would fail (ADR-0079)`.
+  A server that does not answer is a warning. [Give an Agent MCP tools](give-an-agent-mcp-tools.md#rules) gives each
+  text.
 
 - Each rollout must complete. The error starts with
   `error: <part>: rollout did not complete in namespace <namespace> — the pods say:`. See
@@ -330,9 +339,12 @@ refusals of a push and of the [Effector](../reference/glossary.md#effector) imag
   ``error: <layer>: rollout reported success, but the running pod carries <images> — expected <image>. The cluster is serving code this converge did not deploy; `kubectl -n <namespace> rollout restart deploy` and re-run `jr2 up` to resolve it.``
 - When the rollout completes but no pod matches, `jr2 up` cannot check the image. It continues:
   `<layer>: WARNING — rollout succeeded but no pod matched <selector> (nothing verified)`
-- Before the publish, the Orchestrator must read the image map that `jr2 up` wrote. When it does not read it in time,
-  `jr2 up` publishes nothing:
-  ``refusing: after <seconds>s the Orchestrator still reads an older <maps> from its mount — the kubelet has not refreshed it; nothing was published, and the previous Assembly is still current. Run `jr2 up` again``
+- Before the publish, the Orchestrator must read the maps that `jr2 up` wrote, and the digests of the Caller tokens and
+  the Hook secrets. With no publish, `jr2 up` waits for the digests only. When the Orchestrator does not read them in
+  time, `jr2 up` stops with exit code 1:
+  ``refusing: after <seconds>s the Orchestrator still reads an older <names> from its mount — the kubelet has not refreshed it; <what this means>. Run `jr2 up` again``
+  `<what this means>` is `nothing was published, and the previous Assembly is still current`, or
+  `a Caller token or Hook secret that this converge wrote does not work yet`, or both.
 - The Orchestrator checks the Assembly again before it makes it current. It loads each Workflow and `jr2.config.ts`. It
   refuses an [Open](../reference/glossary.md#open) part that nobody bound, a secret that the config does not declare, a
   Kit version that is not its own, and a zod `input` that no door reads (a Machine that `jr2Setup` did not make). The