@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/guides/run-a-command-or-call-a-url.md

@@ -10,8 +10,9 @@ Run a program in the [Workspace](../reference/glossary.md#workspace), or call a
 
 Put the Effect under `actors` in [`jr2Setup`](../reference/authoring-surface/jr2setup.md), beside the
 [Agents](../reference/glossary.md#agent). Then invoke it by its key from a state, and route on its output in `onDone`.
-In this [Workflow](../reference/glossary.md#workflow), a coder fixes the tests. It picks `run_test` to run one test file
-with a [`command`](../reference/authoring-surface/command.md) Effect. When it picks `finished`, an
+In this [Workflow](../reference/glossary.md#workflow), the Machine cuts a [Worktree](../reference/glossary.md#worktree),
+and a coder fixes the tests there. It picks `run_test` to run one test file with a
+[`command`](../reference/authoring-surface/command.md) Effect. When it picks `finished`, an
 [`http`](../reference/authoring-surface/http.md) Effect posts its summary to a URL. Save the file as
 `workflows/fix-and-report.ts` in your [Instance](../reference/glossary.md#instance):
 
@@ -29,9 +30,11 @@ import {
   fail,
   fromPick,
   http,
+  isReady,
   jr2Setup,
   secret,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -50,6 +53,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 and the command name.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
@@ -60,6 +66,8 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You fix failing tests. You change no test. You commit the fix.",
     }),
+    // Cut the Worktree: an Effect too.
+    cut: worktree(),
     // One program, with no shell. arg("file") is one argument, from the input of the Effect.
     test: command(["node", "--test", arg("file")], { timeout: "5m" }),
     // A call to a fixed URL. The Effector puts the value of the secret in the header.
@@ -77,12 +85,20 @@ const body = jr2Setup({
   id: "fix-and-report",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  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: fixTree(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: fixTree(context) }),
       },
       on: {
         finished: "reporting",
@@ -95,8 +111,8 @@ const body = jr2Setup({
         testing: {
           invoke: {
             src: "test",
-            // The `file` of the pick goes to the arg("file") of the command.
-            input: fromPick(runTest),
+            // The `file` of the pick goes to the arg("file") of the command. The Machine gives `worktree`.
+            input: fromPick(runTest, ({ context }) => ({ worktree: fixTree(context) })),
             onDone: {
               target: "ready",
               // The Agent reads this text as the answer to its run_test pick.
@@ -114,7 +130,7 @@ const body = jr2Setup({
       invoke: {
         src: "report",
         // The Agent gives `summary`. The Machine gives `branch`.
-        input: fromPick(finished, ({ context }) => ({ branch: context.workspace.branch })),
+        input: fromPick(finished, ({ context }) => ({ branch: context.branch })),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "response" && event.output.status < 300, target: "done" },
           { target: "notReported" },
@@ -123,6 +139,7 @@ const body = jr2Setup({
     },
     done: { type: "final" },
     // Not final states: a final state means `done`. Each one fails the run, and the run ends `failed`.
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     notReported: { invoke: { src: "fail", input: { reason: "the report did not go out" } } },
     failed: { invoke: { src: "fail", input: { reason: "the coder could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
@@ -132,7 +149,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -150,9 +166,11 @@ import {
   fail,
   fromPick,
   http,
+  isReady,
   jr2Setup,
   secret,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -171,6 +189,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 and the command name.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
@@ -181,6 +202,8 @@ const body = jr2Setup({
       model: "local/qwen3.6-35b-a3b",
       instructions: "You fix failing tests. You change no test. You commit the fix.",
     }),
+    // Cut the Worktree: an Effect too.
+    cut: worktree(),
     // One program, with no shell. arg("file") is one argument, from the input of the Effect.
     test: command(["node", "--test", arg("file")], { timeout: "5m" }),
     // A call to a fixed URL. The Effector puts the value of the secret in the header.
@@ -198,12 +221,20 @@ const body = jr2Setup({
   id: "fix-and-report",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  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: fixTree(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: fixTree(context) }),
       },
       on: {
         finished: "reporting",
@@ -216,8 +247,8 @@ const body = jr2Setup({
         testing: {
           invoke: {
             src: "test",
-            // The `file` of the pick goes to the arg("file") of the command.
-            input: fromPick(runTest),
+            // The `file` of the pick goes to the arg("file") of the command. The Machine gives `worktree`.
+            input: fromPick(runTest, ({ context }) => ({ worktree: fixTree(context) })),
             onDone: {
               target: "ready",
               // The Agent reads this text as the answer to its run_test pick.
@@ -235,7 +266,7 @@ const body = jr2Setup({
       invoke: {
         src: "report",
         // The Agent gives `summary`. The Machine gives `branch`.
-        input: fromPick(finished, ({ context }) => ({ branch: context.workspace.branch })),
+        input: fromPick(finished, ({ context }) => ({ branch: context.branch })),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "response" && event.output.status < 300, target: "done" },
           { target: "notReported" },
@@ -244,6 +275,7 @@ const body = jr2Setup({
     },
     done: { type: "final" },
     // Not final states: a final state means `done`. Each one fails the run, and the run ends `failed`.
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     notReported: { invoke: { src: "fail", input: { reason: "the report did not go out" } } },
     failed: { invoke: { src: "fail", input: { reason: "the coder could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
@@ -253,7 +285,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -261,7 +292,7 @@ The `coding` state routes [`agent.fault`](../reference/mechanism-events.md#agent
 Turn of the coder fails with no pick. Each state that invokes an Agent has a route for it, on the state or on a state
 above it: `jr2 check` refuses a Machine without one. When no transition takes the event, the run ends `error`.
 
-`failed`, `notReported` and `lost` are not final states. Each one invokes
+`notCut`, `failed`, `notReported` and `lost` are not final states. Each one invokes
 [`fail`](../reference/authoring-surface/fail.md), and the run ends `failed` with its reason: a final state means `done`.
 Do not throw from a promise to fail, because a throw is a defect, and the run ends `error`.
 
@@ -301,25 +332,24 @@ The options:
 - `timeout`: how long the program can run, such as `"90s"`, `"10m"` or `"1h"`. The default is `"10m"`. After it, jr2
   kills the process group, and the outcome is `timeout`.
 - `tail`: how many characters of the end of the output the Machine gets. The default is 4096.
-- `slot`: the [Repo Slot](../reference/glossary.md#repo-slot) whose [Worktree](../reference/glossary.md#worktree) the
-  program runs in. Write it only when the Workspace has more than one Repo Slot.
 
-The program starts in the root of the Worktree. In a Workspace with no Repo Slot, it starts in `/work`, the folder that
-the steps of the Workspace share (see [Workspaces](../concepts/workspaces.md#a-workspace-with-no-repo)). To run it in a
-subfolder, give the path as an argument, such as `["node", "--test", "<dir>/test/*.test.js"]`, or write
-`["sh", "-c", "cd <dir> && <program>"]`.
+The input of the Effect says where the program runs. Under [Repo Slots](../reference/glossary.md#repo-slot), `worktree`
+is required: the path of a Worktree that a cut made, or `/work/<slot>/default`. The program starts in the root of that
+folder. In a Workspace with no Repo Slot, it starts in `/work`, the folder that the steps of the Workspace share (see
+[Workspaces](../concepts/workspaces.md#a-workspace-with-no-repo)). To run it in a subfolder, give the path as an
+argument, such as `["node", "--test", "<dir>/test/*.test.js"]`, or write `["sh", "-c", "cd <dir> && <program>"]`.
 
 A `command` with no Effect secret runs in the [Harness](../reference/glossary.md#harness) container of the
-[Sandbox](../reference/glossary.md#sandbox), in the Worktree, beside the
-[Working tools](../reference/glossary.md#working-tools) of the Agent. It uses the tools of the
-[Sandbox Image](../reference/glossary.md#sandbox-image). Thus invoke it in the body of a
+[Sandbox](../reference/glossary.md#sandbox), beside the [Working tools](../reference/glossary.md#working-tools) of the
+Agent. It uses the tools of the [Sandbox Image](../reference/glossary.md#sandbox-image). Thus invoke it in the body of a
 [`workspace()`](../reference/authoring-surface/workspace.md).
 
 Each outcome is output for `onDone`, also a failure. Route on `outcome`
 ([`CommandOutput`](../reference/authoring-surface/type-commandoutput.md)):
 
 - `exited`, with `code` and `tail`. 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.
+  container does not have is `exited` with code 127. A bad `worktree` is `exited` with code 127 too, and `tail` gives
+  the reason. A bad path does not add an outcome.
 - `timeout`, with `tail`.
 - `killed`, with `signal` and `tail`.
 - `unknown`, with `reason`: jr2 cannot tell what the program did. jr2 does not run it again.
@@ -332,13 +362,14 @@ the value. `secret("<name>").path` gives the path of a file that holds the value
 list of `jr2.config.ts`, as for `hook-token`.
 
 A `command` with an Effect secret in `env` does not run beside the Agent. It runs in the
-[Sandbox Effector](../reference/glossary.md#sandbox-effector), a container that the Agent cannot reach. It runs against
-one commit of the branch, not against the live Worktree:
+[Sandbox Effector](../reference/glossary.md#sandbox-effector), a container that the Agent cannot reach. Its `worktree`
+must be a branch Worktree that a cut made in this Sandbox, because a path alone does not name the target of a
+credential. It runs against one commit of that branch, not against the live Worktree:
 
 - By default, the commit is the tip of the branch when the Effect starts. When the Worktree holds changes that the
   program did not see, its output has `dirty: true`.
-- With `pin: true`, the commit is the `sha` of the input of the Effect: `{ sha: "<full commit id>" }`. Use it for a
-  commit that a [Gate](../reference/glossary.md#gate) approved.
+- With `pin: true`, the commit is the `sha` of the input of the Effect: `{ worktree, sha: "<full commit id>" }`. Use it
+  for a commit that a [Gate](../reference/glossary.md#gate) approved.
 
 The Sandbox Effector runs in the Sandbox Image, or in the image of the `effector` option of `workspace()`. Thus that
 image must hold the program.
@@ -362,8 +393,10 @@ image must hold the program.
 - `maxBody`: how many bytes of a text body the output keeps. The default is 65536.
 - `idempotent`: `true` when a second call is safe. The default is `false`. See [Effects](../concepts/effects.md).
 
-To send a file of the Worktree as the body, use [`file(path)`](../reference/authoring-surface/file.md) as `body`. In a
-Workspace with no Repo Slot, the path is relative to `/work`. jr2 sends a file body only with `PUT`, `POST` or `PATCH`.
+To send a file of a Worktree as the body, use [`file(path)`](../reference/authoring-surface/file.md) as `body`. The
+input of the Effect names the Worktree, `{ worktree }`, and a cut in this Sandbox must have made it. The path is
+relative to that Worktree. In a Workspace with no Repo Slot, the input has no `worktree`, and the path is relative to
+`/work`. jr2 sends a file body only with `PUT`, `POST` or `PATCH`.
 
 An `http` Effect runs in the [Instance Effector](../reference/glossary.md#instance-effector). The
 [Effector](../reference/glossary.md#effector) puts the value of each Effect secret into the call. The Agent never reads
@@ -414,9 +447,12 @@ jr2 up
 ```text
 …
 effects: workflow "fix-and-report" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
   test: command ["node","--test","<file>"] — 300s, in the Harness
   report: http POST https://hooks.example.com — 30s, in the Instance Effector, secrets "hook-token"
+…
 failures: workflow "fix-and-report" — the states that fail the run (ADR-0073)
+  fix-and-report.notCut: invokes fail
   fix-and-report.notReported: invokes fail
   fix-and-report.failed: invokes fail
   fix-and-report.lost: invokes fail
@@ -440,20 +476,19 @@ When you call `command()`, it refuses:
 - `pin: true` with no Effect secret in `env`:
   ``command(argv, { pin: true }) names no secret in its env: `pin` chooses the commit a credentialed command runs against in the Sandbox Effector, and a command that names no secret runs in the live Worktree (ADR-0067) — name its secret, command(argv, { env: { NAME: secret("x") }, pin: true }), or drop `pin` ``
 
+`workspace()` refuses a body with an invoke that does not say where it works, when it can read the input:
+``workspace(): state "<state>": "<slot>" names no `<key>`, and a Workspace with Repo Slots says where each Turn and Effect works: a Worktree, or `cwd: "/work"` for a Turn (ADR-0057)``
+
 When a `command` starts, it refuses:
 
 - a state outside a `workspace()`. With no Effect secret in `env`:
   `command "<slot>" runs in the Harness container of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`.
   With one:
   `command "<slot>" runs in the Sandbox Effector of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
-- no `slot` under a Workspace with more than one Repo Slot:
-  `command "<slot>" runs under a Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`.
-  With an Effect secret in `env`, the text is
-  `command "<slot>" runs under a Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" } (ADR-0051)`
+- no `worktree` under Repo Slots, with no Effect secret in `env`:
+  ``command "<slot>" runs under a Workspace with Repo Slots (<slots>) and its input names no `worktree`: say which, a Worktree that a cut gave or `<slot>/default` ``
 - with an Effect secret in `env`, a Workspace with no Repo Slot:
   `command "<slot>" runs under a Workspace with no Repo Slot: a command with an Effect secret runs against one commit of a Repo Slot's branch, and there is none — declare a Repo Slot, or name no secret in its env, and it runs in /work beside the Agent (ADR-0051)`
-- a `slot` that the Workspace does not have:
-  `command "<slot>" names Repo Slot "<name>", which its Workspace does not carry (<slots>)`
 - an `arg()` with no string in the input. The angle brackets around the name are in the text, and `<type>` is `nothing`
   when the input has no such key:
   `command "<slot>": argv slot <<name>> has no string value in its input (got <type>) — map it in the invoke's input`
@@ -477,7 +512,7 @@ When you call `http()`, it refuses:
 - a file body with a method other than `PUT`, `POST` or `PATCH`:
   `http({ method: "<method>", body: file(...) }): a file body is sent with PUT, POST, PATCH (ADR-0068)`
 - a `body` that is not `file()`:
-  ``http({ body }): a body is file(path, { slot?, segments?, contentType? }) — json and text come from `request` ``
+  ``http({ body }): a body is file(path, { segments?, contentType? }) — json and text come from `request` ``
 - a `content-type` header beside the `contentType` of `file()`:
   `http({ headers, body: file(path, { contentType }) }): "content-type" is set by file()'s contentType — write one of them (ADR-0067)`
 - a `request` with a file body:
@@ -489,9 +524,16 @@ When an `http` Effect starts, it refuses an input that its `input` schema does n
 `http "<slot>": its input does not match the definition's input schema — <path>: <message>`. With a file body, the text
 ends after `input schema`.
 
-An `http` Effect with a file body runs in the Sandbox Effector. When it starts, it refuses a state outside a
-`workspace()`:
-`http "<slot>" runs in the Sandbox Effector of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
+An `http` Effect with a file body runs in the Sandbox Effector. When it starts, it refuses:
+
+- a state outside a `workspace()`:
+  `http "<slot>" runs in the Sandbox Effector of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
+- no `worktree` under Repo Slots:
+  ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its input names no `worktree` ``
+
+A bad `worktree` is output, because a word of a run can cause it. An `http` Effect with a file body settles `refused`. A
+`command` settles `exited` with code 127, with the reason in `tail`. A credentialed `command` and a file body need a
+cut: `no cut made <path> in this Sandbox: cut it with worktree()`
 
 When you call `secret()`, `bearer()` or `text`, they refuse:
 
@@ -534,6 +576,7 @@ When you call `secret()`, `bearer()` or `text`, they refuse:
 - [Secrets and trust](../concepts/secrets-and-trust.md): who holds an Effect secret.
 - [The Menu](../concepts/the-menu.md): how a pick waits for its answer.
 - [Push and sign a branch](push-and-sign-a-branch.md): the `push` Effect.
+- [Cut a Worktree](cut-a-worktree.md): the Worktree that a `command` runs in, and the removal of a Worktree.
 - Reference: [`command`](../reference/authoring-surface/command.md),
   [`CommandOptions`](../reference/authoring-surface/type-commandoptions.md),
   [`http`](../reference/authoring-surface/http.md), [`secret`](../reference/authoring-surface/secret.md),

package/docs/guides/run-one-worker-per-item.md

@@ -31,7 +31,7 @@ The imports:
 ```ts
 import { fromPromise } from "xstate";
 import { z } from "zod";
-import { customize, defineEvent, pool, source } from "@jr2/orchestrator";
+import { customize, defineEvent, pool, source, type PoolNextInput } from "@jr2/orchestrator";
 import { task } from "@jr2/machines";
 ```
 
@@ -59,13 +59,9 @@ type Issue = { number: number; title: string; body: string };
 // because the request has no token.
 const ISSUES = "https://api.github.com/repos/you/app/issues?labels=jr2&state=open&per_page=100";
 
-// The issues that this Source gave to a worker. A worker has each one now, or it finished it.
-// The set is in the memory of the Orchestrator, and a restart empties it.
-const claimed = new Set<number>();
-
 // The Source: give the next open issue that no worker has had.
 const issues = source<Issue>({
-  next: fromPromise<Issue | null, { active: string[] }>(async ({ input }) => {
+  next: fromPromise<Issue | null, PoolNextInput>(async ({ input }) => {
     const res = await fetch(ISSUES, { headers: { accept: "application/vnd.github+json" } }).catch(() => undefined);
     if (!res?.ok) {
       // While workers run, look again later. With no worker, stop the run with the error.
@@ -78,12 +74,11 @@ const issues = source<Issue>({
       body: string | null;
       pull_request?: unknown;
     }>;
-    // The issues API also lists pull requests. Skip them, and skip each issue that a worker has now.
-    const issue = open.find(
-      (i) => i.pull_request === undefined && !claimed.has(i.number) && !input.active.includes(`issue-${i.number}`),
-    );
+    // The issues API also lists pull requests. Skip them, and skip each issue that a worker has now
+    // or that a worker finished.
+    const taken = [...input.active, ...input.settled];
+    const issue = open.find((i) => i.pull_request === undefined && !taken.includes(`issue-${i.number}`));
     if (!issue) return null;
-    claimed.add(issue.number);
     return { number: issue.number, title: issue.title, body: issue.body ?? "" };
   }),
   // Send this event to the `source` Gate when you add the label to an issue.
@@ -129,10 +124,10 @@ The file has five parts:
   When no issue is ready, it gives `null`. The request has no token, so the Repo must be public. Without a token, GitHub
   allows 60 requests in each hour. The example reads only the first page of issues: at most 100. When the request fails
   while workers run, `next` gives `null` in place of the error, so that the failure does not stop the run.
-- **The record of the Source.** `next` keeps each issue that it gives in the `Set` `claimed`, and skips the issues in
-  `active`. The `Set` is in the memory of the [Orchestrator](../reference/glossary.md#orchestrator), and each run of the
-  Workflow uses the same `Set`. A restart of the Orchestrator empties it. Then `next` can give a finished issue again,
-  but never an issue that a worker of this run has now.
+- **The record of the Source.** The Source keeps no record of its own. `next` skips each issue in `active` and in
+  `settled`. The Pool holds both, so they stay across a restart of the
+  [Orchestrator](../reference/glossary.md#orchestrator). Each run of the Workflow has its own lists, so a new run can
+  give an issue that is still open.
 - **The worker.** `fixer` is `task` with its two [Open](../reference/glossary.md#open) parts bound: the Repo and the
   model of the coder. [Bind a shipped Machine's Open parts](bind-open-parts.md) tells more.
 - **The run input.** `door` is the run input of the Pool. `cap` reads `workers` from it. A worker never gets it.
@@ -149,15 +144,21 @@ jr2 up
 …
 jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
 typecheck: tsc --noEmit (the instance's own compiler)
+…
+effects: workflow "issues" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
+…
 failures: workflow "issues" — the states that fail the run (ADR-0073)
   issues.failing: invokes fail
+  task.noBranch: invokes fail
+  task.notCut: invokes fail
   task.lost: invokes fail
 …
 seats: workflow "issues" — who may send what, per state (ADR-0015)
   task.working agent:coder: [finish]
   task.review gate: [approve, request_changes]
 …
-agents: coder, triager (carried by 4 workflow machine(s))
+agents: coder, triager (carried by 5 workflow machine(s))
 …
 sandbox nodes: jr2-control-plane
 …
@@ -180,7 +181,7 @@ jr2 run issues --input '{"workers":2}'
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run e1effd33-9bf6-4137-ae70-3aa504910784 (issues) — attached
+run 7c248a11-445a-4123-8ce2-834cb57706d7 (issues) — attached
   → active "discovering"
   → active "discovering"
   → active "discovering"
@@ -205,7 +206,8 @@ jr2 status <run id>
 ```text
 …
 → context kind-jr2 / namespace my-instance
-{"runId":"e1effd33-9bf6-4137-ae70-3aa504910784","workflow":"issues",…,"gates":[{"gate":"source",…},{"gate":"issue-3.body.review",…},{"gate":"issue-2.body.review",…}]}
+{"runId":"7c248a11-445a-4123-8ce2-834cb57706d7","workflow":"issues",…,"gates":[{"gate":"source",…},{"gate":"issue-3.body.review",…},{"gate":"issue-2.body.review",…}]}
+…
 ```
 
 In the JSON that it prints, `gates` holds each open Gate of the run:
@@ -233,7 +235,7 @@ jr2 send <run id> --gate issue-2.body.review --event approve
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered approve to gate "issue-2.body.review" on e1effd33-9bf6-4137-ae70-3aa504910784
+delivered approve to gate "issue-2.body.review" on 7c248a11-445a-4123-8ce2-834cb57706d7
 ```
 
 The Pool then calls `next` again, and starts a worker for the next issue.
@@ -254,12 +256,18 @@ jr2 send <run id> --gate source --event issues_changed
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered issues_changed to gate "source" on e1effd33-9bf6-4137-ae70-3aa504910784
+delivered issues_changed to gate "source" on 7c248a11-445a-4123-8ce2-834cb57706d7
 ```
 
-Without the event, the Pool calls `next` again when a worker finishes, or after `pollEvery`. A webhook can send the same
+Without the event, the Pool calls `next` again when a worker finishes, or after `pollEvery`. A script can send the same
 event with [`POST /runs/:runId/gates/:gate/events`](../reference/http-api.md#post-runs-runid-gates-gate-events).
 
+A [Hook](../reference/glossary.md#hook) can tell the Pool too. Give the Source a `hooks` handler for the forge's event,
+for example `github` and `issues.labeled`, that gives [`reread()`](../reference/authoring-surface/reread.md), or
+[`skip(reason)`](../reference/authoring-surface/skip.md) for a label that is not `jr2`. Then each delivery of the Hook
+makes the Pool call `next` at once. [Pools and Sources](../concepts/pools-and-sources.md#a-hook-reaches-a-source) tells
+how.
+
 ## The end of the run
 
 When the last worker finishes and no issue is ready, the run ends. In the first terminal, `jr2 run` prints the last
@@ -269,7 +277,7 @@ state of the Pool, then the status of the run as JSON:
 …
   → active "discovering"
   → done "drained"
-{"runId":"e1effd33-9bf6-4137-ae70-3aa504910784","workflow":"issues","instanceId":"db9712c8-7c19-4d18-8fb1-8c01d326808f","status":"done","value":"drained","context":{"runInput":{"workers":2,"instanceId":"db9712c8-7c19-4d18-8fb1-8c01d326808f"},"cap":2,"active":[],"items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{},"status":"drained"},"children":[],"waiting":[],"held":[],"assembly":"ca3b0e760c85","output":{"status":"drained","items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{}}}
+{"runId":"7c248a11-445a-4123-8ce2-834cb57706d7","workflow":"issues","instanceId":"1d3090c8-645b-4e22-b343-68d548aab5f4","startedAt":"2026-11-06T19:20:02.886Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"done","value":"drained","context":{"runInput":{"workers":2,"instanceId":"1d3090c8-645b-4e22-b343-68d548aab5f4"},"cap":2,"active":[],"items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{},"held":[],"ready":[],"claimed":{},"again":[],"latch":false,"taken":3,"carried":[],"refused":[],"status":"drained"},"children":[],"waiting":[],"held":[],"answers":[{"gate":"issue-2.body.review","type":"approve","at":"2026-11-06T19:21:49.638Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}},{"gate":"source","type":"issues_changed","at":"2026-11-06T19:21:57.842Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}},{"gate":"issue-3.body.review","type":"approve","at":"2026-11-06T19:22:03.493Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}},{"gate":"issue-1.body.review","type":"approve","at":"2026-11-06T19:22:33.752Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}],"assembly":"f5bb024883b4","output":{"status":"drained","items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{}},"worktrees":[{"slot":"app","path":"/work/app/task","branch":"jr2/issue-3"},{"slot":"app","path":"/work/app/task","branch":"jr2/issue-2"},{"slot":"app","path":"/work/app/task","branch":"jr2/issue-1"}]}
 ```
 
 In the JSON, `context.items` holds the output of each worker that finished, by item id. `context.failures` holds the
@@ -286,8 +294,8 @@ In the JSON, `context.items` holds the output of each worker that finished, by i
   workers register the same Gate or [Agent](../reference/glossary.md#agent), the run stops with the status `error`, and
   its `fault` is `registration address "<address>" is already live (two concurrent registrations share an id)`. For
   `task`, `<address>` is `gate/<run id>/<item id>.body.review` or `agent/<run id>/<item id>.body/coder`.
-- `next` gets only `active`: the ids of the items that workers have now. To not give a finished item again, the Source
-  must keep the items that it gave.
+- `next` gets `active`, the ids of the items that workers have now, and `settled`, the ids of the finished and failed
+  items. It also gets `input`, the input of the Pool. To not give a finished item again, skip each id in `settled`.
 - When a worker fails, for example when the Sandbox of a `task` is lost, the Pool keeps the Failure in `failures` and
   goes on. Only the Sandbox of that worker is deleted. The other workers, and the work in their Sandboxes, stay. A
   defect in a worker is different: the run stops with the status `error`.
@@ -305,9 +313,8 @@ In the JSON, `context.items` holds the output of each worker that finished, by i
   starts with ``task: no `branch` on the door and no Instance ID to derive one from``.
 - Without `cap`, one worker runs at a time. Each `task` worker has its own
   [Workspace](../reference/glossary.md#workspace). Thus the run has `cap` Sandboxes or fewer at one time.
-- The Pool takes the `wake` event only while it waits: workers run, and no item is ready. At other times,
-  [`jr2 send`](../reference/cli.md#send) refuses it:
-  `error: gate "source" is open, and the run does not take "<event>" now: no writing of it would move the run with this payload — not delivered (takes now: nothing)`.
+- The Pool takes the `wake` event at any time while the run is open. While it waits, it calls `next` at once. While
+  `next` runs, it calls `next` once more after that call, so that the change is not lost.
 - `onDrained` takes only `"final"`: the run ends.
 
 ## Read next