@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/guides/set-an-agents-access-and-dials.md

@@ -19,7 +19,7 @@ the file as `workflows/review.ts` in your [Instance](../reference/glossary.md#in
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const approve = defineEvent({
   name: "approve",
@@ -42,6 +42,10 @@ const runInput = z.object({ branch: z.string(), sha: z.string(), model: z.string
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { notes: string; summary: string };
 
+// Two Worktrees of one clone: the coder's branch, and the commit that the reviewer reads.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/work` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [approve, requestChanges, finished],
@@ -64,21 +68,38 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "review",
   context: ({ input }) => ({ ...input, notes: "", summary: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "reviewing",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "detaching" }, { target: "notCut" }],
+      },
+    },
+    // The second cut has no branch: the Worktree holds the commit, detached.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
     reviewing: {
       invoke: {
         src: "reviewer",
         input: ({ context }) => ({
           prompt: `Review commit ${context.sha}.`,
-          // The review Worktree holds the commit of `reviewSha`, detached from the branch.
-          cwd: context.workspace.review?.app ?? context.workspace.repos.app,
+          // The review Worktree holds the commit, detached from the branch.
+          cwd: reviewTree(context),
           // A Dial: this Turn thinks harder than the default of the model.
           thinkingLevel: "high",
         }),
@@ -93,7 +114,7 @@ const body = jr2Setup({
         src: "coder",
         input: ({ context }) => ({
           prompt: `Change the code on the branch as the review asks:\n\n${context.notes}`,
-          cwd: context.workspace.repos.app,
+          cwd: coderTree(context),
           // Each Turn of the coder continues the same conversation.
           continue: true,
           // A Dial: the model of this Turn, from the run input. Absent, the model of the definition.
@@ -115,6 +136,7 @@ const body = jr2Setup({
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -123,7 +145,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch, reviewSha: input.sha }),
 });
 ```
 
@@ -132,7 +153,7 @@ export const machine = workspace(body, {
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const approve = defineEvent({
   name: "approve",
@@ -155,6 +176,10 @@ const runInput = z.object({ branch: z.string(), sha: z.string(), model: z.string
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { notes: string; summary: string };
 
+// Two Worktrees of one clone: the coder's branch, and the commit that the reviewer reads.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/work` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [approve, requestChanges, finished],
@@ -177,21 +202,38 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "review",
   context: ({ input }) => ({ ...input, notes: "", summary: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "reviewing",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "detaching" }, { target: "notCut" }],
+      },
+    },
+    // The second cut has no branch: the Worktree holds the commit, detached.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
     reviewing: {
       invoke: {
         src: "reviewer",
         input: ({ context }) => ({
           prompt: `Review commit ${context.sha}.`,
-          // The review Worktree holds the commit of `reviewSha`, detached from the branch.
-          cwd: context.workspace.review?.app ?? context.workspace.repos.app,
+          // The review Worktree holds the commit, detached from the branch.
+          cwd: reviewTree(context),
           // A Dial: this Turn thinks harder than the default of the model.
           thinkingLevel: "high",
         }),
@@ -206,7 +248,7 @@ const body = jr2Setup({
         src: "coder",
         input: ({ context }) => ({
           prompt: `Change the code on the branch as the review asks:\n\n${context.notes}`,
-          cwd: context.workspace.repos.app,
+          cwd: coderTree(context),
           // Each Turn of the coder continues the same conversation.
           continue: true,
           // A Dial: the model of this Turn, from the run input. Absent, the model of the definition.
@@ -228,6 +270,7 @@ const body = jr2Setup({
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -236,7 +279,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch, reviewSha: input.sha }),
 });
 ```
 
@@ -259,13 +301,13 @@ prompt and picks from its [Menu](../reference/glossary.md#menu). You can invoke
 the example does, or in a [Machine](../reference/glossary.md#machine) with no Workspace.
 
 A `"read"` Agent keeps bash, so a command can still change a file or the branch. To keep a reviewer away from the
-branch, give its Turn the review [Worktree](../reference/glossary.md#worktree):
+branch, give its Turn a detached [Worktree](../reference/glossary.md#worktree):
 
-1. In the `spec` of the `workspace()`, set `reviewSha` to the commit to review.
-2. In the Turn, set `cwd` to `context.workspace.review?.<slot>`.
+1. Cut the Worktree with [`worktree()`](../reference/authoring-surface/worktree.md), with `{ path, detach }`.
+2. In the Turn, set `cwd` to that path.
 
-The review Worktree is `/work/<slot>/<branch>-review`, with each `/` in the branch changed to `-`. It holds the commit
-of `reviewSha`, detached from the branch. In the example, `<slot>` is `app`, and the commit comes from the run input.
+The Worktree holds the commit, with no branch. In the example, the path is `/work/app/review`, and the commit comes from
+the run input. [Cut a Worktree](cut-a-worktree.md) tells more.
 
 The access is a part of the identity of the Agent. Only the definition sets it. A Turn cannot change it.
 
@@ -290,7 +332,7 @@ Run [`jr2 up`](../reference/cli.md#up) to converge the new Workflow:
 jr2 up
 ```
 
-`jr2 up` prints no line that is special to this Workflow. The `seats:` lines show the picks of the three Agents.
+The `effects:` lines show the cut. The `seats:` lines show the picks of the three Agents.
 
 To give a model to the coder's Turns, add `model` to the run input:
 
@@ -318,6 +360,8 @@ Dial. Thus:
 - `jr2 up` gives each pod the model key of the providers that the definitions of its Agents name. For an Agent in a
   Sandbox, use a Dial model of a provider that a definition in that Sandbox names. For a Menu-only Agent, use a provider
   that a Menu-only definition of the Instance names.
+- In the same way, `jr2 up` gives each pod the secret of each MCP server that the definitions of its Agents name. The
+  [MCP tools](../reference/glossary.md#mcp-tools) of an Agent come from its definition only. A Turn cannot change them.
 
 ## Continue a conversation
 
@@ -337,9 +381,11 @@ task, also on a Turn that continues. In the example, each `fixing` prompt gives
 - jr2 refuses a Turn whose `input` has a key that a Turn does not have, such as `instructions` or `workspace`. Only the
   definition sets those two. `<keys>` is each key that is not correct, in backticks, with a comma between them:
   ``agent "<slot>": the Turn's input carries <keys>, which a Turn has no use for — its input is its Frame (`prompt`, `cwd`), its Dials (`model`, `thinkingLevel`), and `continue` (ADR-0057)``
-- Under a Workspace with more than one [Repo Slot](../reference/glossary.md#repo-slot), jr2 refuses a Turn of an Agent
-  with Working tools that sets no `cwd`:
-  ``turn <id>: agent "<slot>" works under a Workspace carrying more than one Repo Slot (<slots>) and its Turn framed no `cwd` — say which Worktree it works in (`cwd: context.workspace.repos.<slot>`, one of those), because the kit gives no slot a meaning (ADR-0051) and a Turn's Frame is where it works (ADR-0057)``
+- Under a Workspace with [Repo Slots](../reference/glossary.md#repo-slot), jr2 refuses a Turn of an Agent with Working
+  tools that sets no `cwd`:
+  ``turn <id>: agent "<slot>" works under a Workspace with Repo Slots (<slots>) and its Turn framed no `cwd`: say where it works, a Worktree, or `cwd: "/work"` above them (ADR-0057)``
+- `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)``
 - The Harness refuses a `cwd` that is not an absolute path. The run gets `agent.fault`, with this reason:
   ``harness admission failed (400): agent "<slot>": the Turn's Frame carries a `cwd` that is not an absolute path — the Frame says WHERE this Turn works (ADR-0057), and a Turn rooted anywhere else would work in the wrong directory silently``
 - The Harness refuses a model that is not in its catalog and not a model of the custom provider. The run gets
@@ -359,7 +405,8 @@ task, also on a Turn that continues. In the example, each `fixing` prompt gives
 ## Read next
 
 - [Agents and Turns](../concepts/agents-and-turns.md): the definition, the Frame, the Dials and `continue`.
-- [Workspaces](../concepts/workspaces.md): the Worktrees and the review Worktree.
+- [Workspaces](../concepts/workspaces.md): the Worktrees.
+- [Cut a Worktree](cut-a-worktree.md): a detached Worktree for a reviewer.
 - [The Menu](../concepts/the-menu.md): the picks of an Agent.
 - [Bind a shipped Machine's Open parts](bind-open-parts.md): bind an Open model.
 - Reference: [`agent`](../reference/authoring-surface/agent.md),

package/docs/guides/size-a-workspace.md

@@ -14,26 +14,39 @@ it on a node, so the Sandbox always has it. Write it in the `resources` option o
 
 ```ts
 import { z } from "zod";
-import { command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { command, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const runInput = z.object({ branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the tests run in.
+const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
+
 const body = jr2Setup({
-  types: {} as { input: BodyInput },
+  types: {} as { input: BodyInput; context: BodyInput },
   actors: {
+    cut: worktree(),
     // JR2_CPUS holds the cpu limit of the container. Playwright does not read that limit.
     e2e: command(["sh", "-c", "npx playwright test --workers=$JR2_CPUS"], { timeout: "30m" }),
     fail: fail(),
   },
 }).createMachine({
   id: "e2e",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "testing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
     testing: {
       invoke: {
         src: "e2e",
+        input: ({ context }) => ({ worktree: testTree(context) }),
         onDone: [
           {
             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -46,6 +59,7 @@ const body = jr2Setup({
     passed: { type: "final" },
     // Not final states: each one fails the run, and the run ends `failed`.
     failed: { invoke: { src: "fail", input: { reason: "the Playwright tests did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
   },
 });
@@ -55,7 +69,6 @@ export const machine = workspace(body, {
   // The Size of the whole Sandbox: 4 GiB of memory and 2 cpus. jr2 reserves all of it on a node.
   resources: { limits: { memory: "4Gi", cpu: "2" } },
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -160,8 +173,8 @@ The Harness can miss a fast increase. Then the kernel stops the whole container,
 memory limit (OOMKilled, limit <memory>): the Workspace's processes passed the Harness container's memory limit and the kernel killed the container, the conversation with it. Use fewer workers, or give the Workspace a larger Size (ADR-0060, ADR-0061).
 ```
 
-The next Agent in the Workspace gets a notice of the kill. When you see either text again and again, state a larger
-Size.
+Each conversation that was in the Workspace at the kill gets a notice of it one time, and so does the next Turn of the
+Agent whose Turn the kill cut. When you see either text again and again, state a larger Size.
 
 ## Rules
 

package/docs/guides/start-a-run-for-each-alert.md

@@ -0,0 +1,290 @@
+---
+title: Start a run for each alert
+description: Make a standing Pool that starts one run for each alert that an outside service sends to a Hook.
+---
+
+# Start a run for each alert
+
+Start one run of a [Workflow](../reference/glossary.md#workflow) for each alert that an alert service sends to a
+[Hook](../reference/glossary.md#hook).
+
+The example has three Workflows and one Hook. The alert service sends each new issue to the Hook `sentry`. The Workflow
+`alerts` is a standing [Pool](../reference/glossary.md#pool) of runs: its push Source holds each alert, and the Pool
+starts one run of `triage` for each alert, with at most 8 live at one time. A `triage` run waits until a person takes
+the alert or dismisses it.
+
+`@jr2/orchestrator/hooks/webhook` has `webhook()`, which makes the kind of a service that jr2 ships no kind for. It is
+part of `@jr2/orchestrator`, so your [Instance](../reference/glossary.md#instance) installs nothing more.
+
+## Write the kind of the service
+
+The alert service signs the raw body with a shared secret, and puts the HMAC-SHA256 in hex in the header
+`sentry-hook-signature`. The header `sentry-hook-resource` and the field `action` give the event key, such as
+`issue.created`. The header `request-id` is the id of the delivery. Save the kind as `hooks/sentry.ts`, beside
+`workflows/`, because it is not a Workflow:
+
+```ts
+import { z } from "zod";
+import { webhook } from "@jr2/orchestrator/hooks/webhook";
+
+// An alert service that jr2 ships no kind for. The service signs the raw body with a shared secret
+// (sha256, hex) in the header sentry-hook-signature. The event key is the resource and its action,
+// such as issue.created. The module is in `hooks/`, not in `workflows/`, because it is not a Workflow.
+export const sentry = webhook({
+  id: "sentry",
+  events: {
+    "issue.created": z.looseObject({
+      data: z.looseObject({
+        issue: z.looseObject({ id: z.string(), title: z.string(), level: z.string() }),
+      }),
+    }),
+  },
+  verify: { mac: { header: "sentry-hook-signature" } },
+  key: { name: { header: "sentry-hook-resource" }, action: { json: "action" } },
+  delivery: { header: "request-id" },
+});
+
+declare module "@jr2/orchestrator/hooks" {
+  interface HookKinds {
+    sentry: typeof sentry;
+  }
+}
+```
+
+The `declare module` block adds the kind to the types of the handlers. A handler for an event key that the kind does not
+give does not compile.
+
+## Write the Workflow of one alert
+
+Save `workflows/triage.ts`. Its door takes the issue id and the title of one alert:
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { defineEvent, jr2Setup } from "@jr2/orchestrator";
+
+// The two answers of the person on call.
+const take = defineEvent({
+  name: "take",
+  description: "I take this alert.",
+  input: z.object({ who: z.string().min(1) }),
+});
+const dismiss = defineEvent({
+  name: "dismiss",
+  description: "This alert needs no work. Say why.",
+  input: z.object({ reason: z.string().min(1) }),
+});
+
+type Context = { issue: string; title: string; who?: string };
+
+// One run for each alert. The run waits until a person takes the alert or dismisses it.
+export const machine = jr2Setup({
+  types: {} as { input: { issue: string; title: string }; context: Context },
+  events: [take, dismiss],
+}).createMachine({
+  id: "triage",
+  // The door: the alerts Pool sends this input for each alert.
+  input: z.object({ issue: z.string(), title: z.string() }),
+  context: ({ input }) => ({ issue: input.issue, title: input.title }),
+  initial: "waiting",
+  states: {
+    waiting: {
+      invoke: {
+        src: "gate",
+        input: ({ context }) => ({ meta: { issue: context.issue, title: context.title } }),
+      },
+      on: {
+        take: { target: "taken", actions: assign({ who: ({ event }) => event.who }) },
+        dismiss: "dismissed",
+      },
+    },
+    taken: { type: "final" },
+    dismissed: { type: "final" },
+  },
+});
+```
+
+## Write the standing Pool
+
+Save `workflows/alerts.ts`:
+
+```ts
+import { z } from "zod";
+import { carry, dispatch, pool, skip, source } from "@jr2/orchestrator";
+import type {} from "../hooks/sentry.ts";
+
+// The door of the triage Workflow: each alert is one run of it.
+const triageDoor = z.object({ issue: z.string(), title: z.string() });
+
+// A push Source: each Hook delivery carries an alert, and the Pool holds it until a slot is free.
+const alerts = source({
+  item: z.object({ issue: z.string(), title: z.string(), level: z.string() }),
+  hooks: {
+    sentry: {
+      "issue.created": ({ payload }) => {
+        const issue = payload.data.issue;
+        if (issue.level !== "error" && issue.level !== "fatal") return skip(`level is ${issue.level}`);
+        return carry({ issue: issue.id, title: issue.title, level: issue.level });
+      },
+    },
+  },
+});
+
+// A standing Pool of runs: one triage run for each alert, at most 8 live at once.
+export const machine = pool(dispatch("triage", { input: triageDoor, wait: true }), {
+  id: "alerts",
+  standing: true,
+  source: alerts,
+  itemId: (alert) => `sentry-${alert.issue}`,
+  cap: 8,
+  itemInput: (alert) => ({ issue: alert.issue, title: alert.title }),
+});
+```
+
+- The Source has `item` and `hooks`, and no read: it is a push Source. Its handler gives `carry(item)` for an alert of
+  the level `error` or `fatal`, and `skip(reason)` for the other levels.
+- The worker is `dispatch("triage", { input, wait: true })`, so each alert is a run of its own of `triage`.
+- `itemId` is the key of the run. A second delivery of the same alert finds the run of the first one, and starts no
+  second run.
+- `standing: true`: jr2 starts the run of the Pool, and keeps one live run of it.
+
+## Declare the Hook
+
+Add the Hook to `jr2.config.ts`, and its secret to the `secrets` list:
+
+```ts
+import { defineConfig, secret } from "@jr2/orchestrator";
+import { sentry } from "./hooks/sentry.ts";
+
+export default defineConfig({
+  // The Hook's secret is an entry of the list. jr2 up places SENTRY_HOOK in the Instance Effector.
+  secrets: [{ name: "SENTRY_HOOK", value: process.env.SENTRY_HOOK }],
+  hooks: {
+    // POST /hooks/sentry: the alert service signs each delivery with SENTRY_HOOK. The Hook brings
+    // items to the Pool of the alerts Workflow, through its source Gate, and to nothing more.
+    sentry: sentry({ secret: secret("SENTRY_HOOK"), may: { answer: ["alerts"] } }),
+  },
+});
+```
+
+`may.answer` names `alerts`, because the Hook brings items to the Pool through the Pool's `source` Gate. Put the secret
+in `.env`:
+
+```sh
+SENTRY_HOOK=<secret>
+```
+
+`<secret>` is a long random value. Give the alert service the same value.
+
+## Converge
+
+```sh
+jr2 up
+```
+
+```text
+…
+standing: sentry → alerts → triage
+…
+secret SENTRY_HOOK: an Effect secret in the Instance Effector (hook sentry)
+the Instance Effector: holds SENTRY_HOOK
+…
+standing alerts → triage: live, run 0d08bbbc-d34e-47fb-9b4b-8e788e328eb4, 0 held items
+…
+```
+
+`jr2 up` puts the secret in the [Instance Effector](../reference/glossary.md#instance-effector) only, which checks each
+signature. jr2 starts the run of `alerts` at this publish. Your run id is different.
+
+## Set up the alert service
+
+The address of the Hook is `POST /hooks/sentry` on the Orchestrator. `jr2 up` makes the Service `jr2-orchestrator` on
+port 4000, with no address outside the cluster. Give the Service an address that the alert service can reach, such as an
+ingress. Then give the service the URL `https://<host>/hooks/sentry` and the secret.
+
+## Send a test delivery
+
+You can sign a delivery yourself. Forward a port to the Orchestrator, and keep this command open:
+
+```sh
+kubectl -n <namespace> port-forward svc/jr2-orchestrator 4000:4000
+```
+
+In a second terminal, sign a body with the secret and send it:
+
+```sh
+BODY='{"action":"created","data":{"issue":{"id":"4505","title":"TypeError in checkout","level":"error"}}}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SENTRY_HOOK" | sed 's/^.* //')
+curl -s -X POST http://localhost:4000/hooks/sentry \
+  -H "Content-Type: application/json" \
+  -H "sentry-hook-resource: issue" \
+  -H "request-id: test-1" \
+  -H "sentry-hook-signature: $SIG" \
+  -d "$BODY"
+```
+
+```text
+{"delivery":"test-1","seen":false,"delivered":[],"refused":[],"ignored":0,"sources":[{"pool":"0d08bbbc-d34e-47fb-9b4b-8e788e328eb4","workflow":"alerts","source":"source","verdict":"held","key":"sentry-4505"}]}
+```
+
+The Pool holds the alert, and starts a run of `triage` for it when a slot is free. Send the same command again. The
+answer has `"seen":true`, because the Hook got the id `test-1` before, and the Pool starts no second run.
+
+## Follow the alerts
+
+[`jr2 runs`](../reference/cli.md#runs) lists the run of `triage` for the alert.
+[`jr2 status <run id>`](../reference/cli.md#status) of that run prints, in its `dispatched by:` line, the run of the
+Pool, the key `sentry-4505`, and the Hook delivery that carried the alert. The person on call answers its Gate:
+
+```sh
+jr2 send <run id> --gate waiting --event take --input '{"who":"<you>"}'
+```
+
+`<run id>` is the id of the `triage` run, and `<you>` is your name. To see what the door of the Hook did with each
+delivery that jr2 keeps (`runs.retain`, 30 days by default), print its log:
+
+```sh
+jr2 hooks sentry
+```
+
+To stop the alerts for a time, cancel the run of `alerts`. A cancel of a standing Pool is a pause: the Hook's answer has
+the verdict `paused`, and the Pool holds nothing. [`jr2 run alerts`](../reference/cli.md#run) resumes it.
+
+## Rules
+
+- `pool()` refuses a Pool of runs that does not stand:
+  ``pool("<id>"): a Pool of runs stands: give it `standing: true`. A Pool of runs that a Caller starts and that ends is not offered: its itemId is a key that lives for runs.retain past the run, so a second batch in that time does no work (ADR-0017)``
+- `pool()` refuses a `dispatch` slot without `wait: true`:
+  ``pool("<id>"): its dispatch slot for "<workflow>" has no `wait: true` — with `started` alone, the Pool cannot know when a run ends, and `cap` counts nothing (ADR-0017)``
+- `pool()` refuses a `dispatch` slot with a `target`:
+  ``pool("<id>"): its dispatch slot for "<workflow>" has a `target` — a Pool of runs on another Orchestrator is not designed: remove the target (ADR-0017)``
+- `pool()` refuses a Pool of runs without `cap`:
+  ``pool("<id>"): a Pool of runs states its `cap`, a whole number above 0: the most live runs at once (ADR-0017)``
+- `pool()` refuses a push Source on a Pool that does not stand:
+  `pool("<id>"): a push Source needs a standing Pool of runs: a Pool that ends when it drains would end at once (ADR-0017)`
+- `jr2 up` refuses a standing Pool that is not the top Machine of its Workflow:
+  `refusing: workflow "<workflow>": machine "<machine>" composes the standing Pool "<id>" — a standing Pool is the top Machine of its Workflow, because jr2 keeps one run of each standing Workflow: move the Pool to a file of its own in workflows/ (ADR-0017)`
+- `jr2 up` warns when two standing Pools dispatch to one Workflow:
+  ``warning: the standing Pools "<pool>" and "<pool>" each dispatch to "<workflow>": `cap` is for each Pool, so one item that two Sources carry can take a slot in each, and the caps add (ADR-0017)``
+- The Orchestrator refuses `jr2 run` of a standing Workflow whose run is live, with the status code `409`:
+  ``"<workflow>" is a standing Workflow, and its run <run id> is live: jr2 keeps its run, and `jr2 run` only resumes a paused one (ADR-0017)``
+- The Orchestrator refuses a `dispatch` to a standing Workflow:
+  `"<workflow>" is a standing Workflow: jr2 starts its run, and a dispatch cannot (ADR-0017)`
+- When the Pool holds `hold` items (1000 by default), the door answers 429 with the verdict `hold-full`, and the service
+  can send the delivery again.
+- While the Pool waits for the back-off of a hand-over, it has no live run, and the door answers 503.
+- A Hook whose `may.answer` does not name the Workflow of the Pool brings it nothing.
+
+## Read next
+
+- [Pools and Sources](../concepts/pools-and-sources.md)
+- [Callers and Hooks](../concepts/callers-and-hooks.md)
+- [Write a Hook kind](write-a-hook-kind.md), for a service that `webhook()` cannot read
+- [Start a run from a run](start-a-run-from-a-run.md)
+- Reference: [`pool()`](../reference/authoring-surface/pool.md), [`source()`](../reference/authoring-surface/source.md),
+  [`carry()`](../reference/authoring-surface/carry.md), [`skip()`](../reference/authoring-surface/skip.md),
+  [`dispatch()`](../reference/authoring-surface/dispatch.md) and [`webhook()`](../reference/hooks.md#webhook)
+- [ADR-0017](../reference/decisions/0017-pool-over-a-source-port.md): a standing Pool, and a Hook that brings items to
+  it
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): a
+  Hook, and `webhook()`