@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/get-started/create-an-instance.md

@@ -86,7 +86,7 @@ jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
 typecheck: tsc --noEmit (the instance's own compiler)
 agents: (none) (carried by 1 workflow machine(s))
 assembly: staging
-assembly: ba71fa27f37f (kit v<version>; 1 workflow(s): ping)
+assembly: 50e6f81e3bfb (kit v<version>; 1 workflow(s): ping)
 kubernetes: v1.36.1 (floor 1.35, ADR-0037)
 first contact: deploy instance "my-instance" to context kind-jr2 (create namespace "my-instance")? [y/N] y
 platforms: linux/amd64 (from 1 schedulable node(s))
@@ -94,14 +94,15 @@ images: installed kit — the published v<version> Harness, operator and Orchest
 …
 orchestrator: waiting for rollout
 orchestrator: verified — 1 pod(s) running ghcr.io/snapwich/jr2-orchestrator:<version>
-instance effector: none (no Effect is placed there)
-assembly: publishing ba71fa27f37f (no current Assembly)
-assembly: ba71fa27f37f is current — workflows: ping
+instance effector: none (no Effect is placed there, and no Hook needs it)
+assembly: publishing 50e6f81e3bfb (no current Assembly)
+assembly: 50e6f81e3bfb is current — workflows: ping
 swept nothing — every labeled image is named by a live root
+…
 converged — `jr2 run <workflow>` when ready
 ```
 
-`<version>` is the Kit version, such as `0.4.1`. `ba71fa27f37f` is the hash of the
+`<version>` is the Kit version, such as `0.4.1`. `50e6f81e3bfb` is the hash of the
 [Assembly](../reference/glossary.md#assembly) of your Instance: your Workflows and your config. Your hash can be
 different. It changes each time that your Workflows or your config change.
 
@@ -122,9 +123,9 @@ JSON:
 
 ```text
 → context kind-jr2 / namespace my-instance
-run a256ff8a-f99f-42f5-975c-4f93a5008c56 (ping) — attached
+run db1fd16f-166f-4575-b8fb-60cd80321308 (ping) — attached
   → done "done"
-{"runId":"a256ff8a-f99f-42f5-975c-4f93a5008c56","workflow":"ping","instanceId":"0e82cc83-7c15-426f-86ff-e7354873a429","status":"done","value":"done","context":{"message":"hi","reply":"pong: hi"},"children":[],"waiting":[],"held":[],"assembly":"ba71fa27f37f"}
+{"runId":"db1fd16f-166f-4575-b8fb-60cd80321308","workflow":"ping","instanceId":"71af068c-e150-4802-8b1c-6d07d3bb4a08","startedAt":"2026-11-06T19:15:47.436Z","status":"done","value":"done","context":{"message":"hi","reply":"pong: hi"},"children":[],"waiting":[],"held":[],"assembly":"50e6f81e3bfb","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}
 ```
 
 Your run id and your [Instance ID](../reference/glossary.md#instance-id) are not the same as the ones here. The run is
@@ -155,16 +156,17 @@ Click `ping`. The center shows its Machine, with the states `responding` and `do
 ## Unlock the Console
 
 Without a token, you can look at the runs in the Console, but you cannot start a run or answer a
-[Gate](../reference/glossary.md#gate). For these, you need the Instance token. In the first terminal, run:
+[Gate](../reference/glossary.md#gate). For these, you need the token of a Caller with a scope. Here, use the Instance
+token. In the first terminal, run:
 
 ```sh
 kubectl -n my-instance get secret jr2-instance -o jsonpath='{.data.JR2_INSTANCE_TOKEN}' | base64 -d
 ```
 
-The command prints the token, 48 hexadecimal characters, with no newline after it. Paste the token in the
-`instance token` box in the Console nav. Push Enter. The Console checks the token. Then the badge after the box shows
-`live`, and a `start` button shows next to `ping`. The browser tab keeps the token until you close the tab. `jr2 up`
-keeps the same token each time that it runs.
+The command prints the token, 48 hexadecimal characters, with no newline after it. Paste the token in the `Caller token`
+box in the Console nav. Push Enter. The Console checks the token. Then the badge after the box shows `live`, the nav
+shows `as token/instance`, and a `start` button shows next to `ping`. The browser tab keeps the token until you close
+the tab. `jr2 up` keeps the same token each time that it runs.
 
 Keep the port forward open. The next pages use the Console. [Open the Console](../guides/open-the-console.md) gives more
 about the Console.
@@ -181,8 +183,9 @@ each time that you change the folder. [Converge](../concepts/converge.md) explai
 it. [Machines and Workflows](../concepts/machines-and-workflows.md) explains the two words.
 
 The Console is a page that the Orchestrator serves, at [`GET /`](../reference/http-api.md#get). Anyone who can reach it
-can see the runs. Only the holder of the Instance token can start a run or answer a Gate
-([ADR-0032](../reference/decisions/0032-the-console-unlocks-with-the-instance-token.md)).
+can see the runs. Only a [Caller](../reference/glossary.md#caller) with a scope, such as the holder of the Instance
+token, can start a run or answer a Gate
+([ADR-0032](../reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md)).
 
 `jr2 init` wrote `AGENTS.md` for your Assistant. It points to the docs that the Kit installs in
 `node_modules/@jr2/orchestrator/docs/`. These are the docs of your Kit version

package/docs/guides/add-tools-to-the-sandbox.md

@@ -12,16 +12,17 @@ Put the programs that your [Agents](../reference/glossary.md#agent) and
 A [Workspace](../reference/glossary.md#workspace) runs its body in a [Sandbox](../reference/glossary.md#sandbox): a pod
 of its own. The Sandbox Image is the image of the pod's `harness` container. The Agent's
 [Working tools](../reference/glossary.md#working-tools) run in that container, and so do the `command` Effects and the
-shell that you get with `kubectl exec`. Thus a program that is in the image is a program that they can run.
+shell that you get with `jr2 workspace shell`. Thus a program that is in the image is a program that they can run.
 
 Use this table to choose:
 
-| You want                                       | Do this                                                                                                        |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| The same tools for each Workspace              | Change `images/default/Dockerfile`.                                                                            |
-| Different tools for the Workspaces of one file | Put a docker context beside the workflow module, and name it in the `image` option.                            |
-| An image that you build and push yourself      | Write its registry ref in the `image` option.                                                                  |
-| A service that runs beside the Agent           | Name its image in the `user` option. It runs in the [User Container](../reference/glossary.md#user-container). |
+| You want                                       | Do this                                                                                                                                   |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| The same tools for each Workspace              | Change `images/default/Dockerfile`.                                                                                                       |
+| Different tools for the Workspaces of one file | Put a docker context beside the workflow module, and name it in the `image` option.                                                       |
+| An image that you build and push yourself      | Write its registry ref in the `image` option.                                                                                             |
+| A service that runs beside the Agent           | Name its image in the `user` option. It runs in the [User Container](../reference/glossary.md#user-container).                            |
+| A tool that the model calls by name            | Put an MCP server in the image, and declare it in `jr2.config.ts`. See [Write a tool as an MCP server](write-a-tool-as-an-mcp-server.md). |
 
 ## Add a tool to the default image
 
@@ -239,17 +240,23 @@ RUN apk add --no-cache git
 # The Worktrees under /work belong to a different user. Tell git to trust them.
 RUN git config --system --add safe.directory '*'
 
-# jr2 does not replace this command. It must keep running: when it ends, the pod is not ready.
+# jr2 does not replace this command. It must keep running: when it ends, Kubernetes starts the container again.
 CMD ["sh", "-c", "while true; do sleep 3600; done"]
 ```
 
 Save it as `workflows/shell/Dockerfile`. Name it in the `workspace()` options with
 `user: import.meta.resolve("./shell")`. `user` takes the same two forms as `image`, and `jr2 up` builds a `file:`
-context in the same way. Open the shell with `kubectl -n <namespace> exec -it <sandbox> -c user -- sh`.
+context in the same way. Open the shell with [`jr2 workspace shell`](../reference/cli.md#workspace-shell) and `--user`.
+[Look inside a Sandbox](look-inside-a-sandbox.md#find-the-sandbox) tells how to find `<workspace>`:
+
+```sh
+jr2 workspace shell <workspace> --user
+```
 
 The User Container is not a second Sandbox Image:
 
-- Its own `ENTRYPOINT` and `CMD` run. Its process must keep running: when it ends, the pod is not ready.
+- Its own `ENTRYPOINT` and `CMD` run. Its process must keep running. When it ends, Kubernetes starts the container
+  again, so a `CMD` that ends at once restarts again and again.
 - jr2 gives it `/work`, which it can write, and `/repos` and `/opt/jr2`, which it can only read. jr2 gives it no other
   mount, no environment variable and no command.
 - It has no floor: an Alpine base is correct here. It runs as the `USER` of its image, and root is permitted.
@@ -266,6 +273,42 @@ container, the [Sandbox Effector](../reference/glossary.md#sandbox-effector). By
 [Run a command or call a URL with an Effect](run-a-command-or-call-a-url.md) and
 [Push and sign a branch](push-and-sign-a-branch.md).
 
+### Reach a service in the User Container
+
+No Service of the cluster goes to the User Container. To reach a port in the Sandbox pod, run
+[`jr2 workspace forward`](../reference/cli.md#workspace-forward). It forwards a port on your computer to the port in the
+pod, through the API server of the cluster, until you push Ctrl-C:
+
+```sh
+jr2 workspace forward <workspace> 3000
+```
+
+```text
+→ context <context> / namespace <namespace>
+127.0.0.1:36779
+forwarding 127.0.0.1:36779 → 7a0e8b50/x:0:3000 — Ctrl-C ends it
+```
+
+The address on stdout is the local address. The port changes on each run.
+
+When the User Container runs an sshd on port `22`, `ssh` can go through `jr2 workspace forward --stdio`. Add this entry
+to `~/.ssh/config`. Replace `<namespace>` with the namespace of your Instance:
+
+```text
+Host *.jr2
+  ProxyCommand jr2 workspace forward %h 22 --stdio -n <namespace>
+```
+
+Then connect with the name of the Sandbox, which `jr2 workspace ls` prints, and `.jr2`:
+
+```sh
+ssh <sandbox>.jr2
+```
+
+With `-n`, `jr2 workspace forward` needs no Instance folder, so `ssh` can run it from each folder. The sshd and its keys
+are yours: jr2 gives the User Container no key. With `ssh -A`, your `ssh-agent` goes only to the User Container, and the
+Agent runs nothing there.
+
 ## Rules
 
 - `workspace()` refuses an `image` that is empty or not a string:
@@ -303,6 +346,7 @@ container, the [Sandbox Effector](../reference/glossary.md#sandbox-effector). By
   [`UserContainer`](../reference/authoring-surface/type-usercontainer.md), [`jr2 up`](../reference/cli.md#up)
 - [ADR-0037](../reference/decisions/0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md): the Instance
   builds its Sandbox Images, and jr2 injects the Harness.
-- [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md): the containers of the Sandbox pod.
+- [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md): the containers of the Sandbox pod, and how you
+  reach the User Container.
 - [ADR-0049](../reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md): a Machine carries its
   images.

package/docs/guides/answer-a-gate-from-a-forge.md

@@ -0,0 +1,304 @@
+---
+title: Answer a Gate from a forge
+description: Make a Gate that a review on GitHub or GitLab answers, and that looks for the review it waits for.
+---
+
+# Answer a Gate from a forge
+
+Make a [Gate](../reference/glossary.md#gate) that a review on a forge, such as GitHub, answers through a
+[Hook](../reference/glossary.md#hook), and that looks for the review when no delivery comes.
+
+A Gate slot is a Gate that hears a Hook. You declare it with `gate({ … })` in `actors`, and a state invokes it by its
+key. It is the same Gate as `src: "gate"`: it has the same id, the same events, the same card in the
+[Console](../reference/glossary.md#console), and `jr2 send` can answer it too. It adds four parts:
+
+- `meta`: a zod object of the data that the state gives the Gate. The Gate checks the data when it opens.
+- `delivers`: the events that the Gate can give from a delivery or from its look.
+- `hooks`: a handler for each [Hook kind](../reference/glossary.md#hook-kind) and event key. A handler reads the payload
+  of a delivery, and gives one event of `delivers`, or `undefined` when the delivery is not for this Gate.
+- `look`: a read of the fact that the Gate waits for, with an `http` Effect that is marked `idempotent: true`.
+
+The example is the [Workflow](../reference/glossary.md#workflow) `review`. A run waits for a review of one commit of one
+pull request. The `github` kind is `@jr2/orchestrator/hooks/github`, so your
+[Instance](../reference/glossary.md#instance) installs nothing more.
+
+Save the file as `workflows/review.ts`:
+
+```ts
+// workflows/review.ts: a run that waits for a review of one pull request on GitHub. A review on
+// GitHub answers the Gate, through a Hook of the `github` kind. The look reads the reviews of the
+// pull request, so a review that came before the Gate opened, or while the Orchestrator was down,
+// also answers it.
+
+import { z } from "zod";
+import type {} from "@jr2/orchestrator/hooks/github";
+import { bearer, defineEvent, gate, http, jr2Setup, secret, type HttpOutput } from "@jr2/orchestrator";
+
+const approve = defineEvent({
+  name: "approve",
+  description: "A reviewer approved the commit.",
+  input: z.object({ by: z.string() }),
+});
+const changes = defineEvent({
+  name: "changes",
+  description: "A reviewer asked for changes.",
+  input: z.object({ by: z.string(), notes: z.string() }),
+});
+
+type Meta = { owner: string; repo: string; pr: number; url: string; sha: string };
+
+// The reviews of the pull request, from the GitHub API. The look reads them again, so the call is
+// marked idempotent.
+const reviews = http({
+  method: "GET",
+  url: "https://api.github.com",
+  auth: bearer(secret("github-token")),
+  headers: { accept: "application/vnd.github+json" },
+  idempotent: true,
+  input: z.object({ owner: z.string(), repo: z.string(), pr: z.number() }),
+  request: ({ owner, repo, pr }) => ({ path: ["repos", owner, repo, "pulls", String(pr), "reviews"] }),
+});
+
+/** The last verdict on the commit, from the API's answer. */
+function verdictOf(output: HttpOutput, meta: Meta) {
+  if (output.outcome !== "response" || output.status !== 200 || output.body === undefined) return undefined;
+  const list = JSON.parse(output.body) as Array<{
+    state: string;
+    commit_id: string;
+    body: string | null;
+    user: { login: string };
+  }>;
+  const last = list.filter((r) => r.commit_id === meta.sha && r.state !== "COMMENTED").at(-1);
+  if (last?.state === "APPROVED") return { type: "approve" as const, by: last.user.login };
+  if (last?.state === "CHANGES_REQUESTED")
+    return { type: "changes" as const, by: last.user.login, notes: last.body ?? "" };
+  return undefined;
+}
+
+const review = gate({
+  meta: z.object({ owner: z.string(), repo: z.string(), pr: z.number(), url: z.string(), sha: z.string() }),
+  delivers: [approve, changes],
+  hooks: {
+    github: {
+      "pull_request_review.submitted": ({ payload, meta }) => {
+        // A review of another pull request, or of an older commit, is not for this Gate.
+        if (payload.pull_request.html_url !== meta.url || payload.review.commit_id !== meta.sha) return undefined;
+        if (payload.review.state === "approved") return { type: "approve", by: payload.review.user.login };
+        if (payload.review.state === "changes_requested") {
+          return { type: "changes", by: payload.review.user.login, notes: payload.review.body ?? "" };
+        }
+        return undefined;
+      },
+    },
+  },
+  look: {
+    read: reviews,
+    input: (meta) => ({ owner: meta.owner, repo: meta.repo, pr: meta.pr }),
+    every: "10m",
+    until: verdictOf,
+  },
+});
+
+type Input = Meta;
+
+export const machine = jr2Setup({
+  types: {} as { context: Input & { notes?: string }; input: Input },
+  events: [approve, changes],
+  actors: { review },
+}).createMachine({
+  id: "review",
+  input: z.object({ owner: z.string(), repo: z.string(), pr: z.number(), url: z.string(), sha: z.string() }),
+  context: ({ input }) => input,
+  initial: "inReview",
+  states: {
+    inReview: {
+      invoke: {
+        src: "review",
+        input: ({ context }) => ({
+          meta: { owner: context.owner, repo: context.repo, pr: context.pr, url: context.url, sha: context.sha },
+        }),
+      },
+      on: { approve: "approved", changes: "changesAsked" },
+    },
+    approved: { type: "final" },
+    changesAsked: { type: "final" },
+  },
+});
+```
+
+The `import type {} from "@jr2/orchestrator/hooks/github"` line gives the handlers their types: the event key
+`pull_request_review.submitted` and its payload. A key that no kind in scope gives does not compile. A handler reads
+only the fields that the kind's schema names.
+
+## The handler
+
+A delivery of the kind and the event key goes to each open Gate whose handlers hear them. Thus each handler compares the
+payload with the Gate's `meta`. In the example, the handler gives `undefined` for a review of another pull request or of
+an older commit. A handler is pure and synchronous: it does no I/O and reads no clock.
+
+The event of a handler has the Gate as its [Sender](../reference/glossary.md#sender), with the Hook as its
+[Caller](../reference/glossary.md#caller). The run takes the event only when it takes it from this Gate now, as for
+`jr2 send`.
+
+## The look
+
+A delivery can come before the Gate opens, or it can be lost while the
+[Orchestrator](../reference/glossary.md#orchestrator) is down. The look reads the fact, so these cases come to the same
+read:
+
+- The look reads once after the Gate opens, again after each restart of the Orchestrator, and every `every` while the
+  Gate is open. The default `every` is `"10m"`.
+- `until` gives one event of `delivers` from the read's output, or `undefined` for "not yet".
+- When the run takes the event, the look stops until the Gate opens again. The run's feed shows `looked`. A looked event
+  has the Gate as its Sender and no Caller.
+- The `http` Effect of the look is an Effect, so the secret that it names is an entry of the `secrets` list, as
+  `github-token` is in the example's `jr2.config.ts`. Put its value in `.env` as `GITHUB_TOKEN`.
+
+A state that goes back to its own Gate must change the `meta`, for example to a new `sha`. If not, the look reads the
+same verdict again.
+
+Give `look: "none"` to a Gate that hears a command, such as a `/retry` comment. A command is not a fact that a read can
+find, so a lost delivery of a command stays lost.
+
+## The Hook
+
+The Gate hears a delivery only when the [Instance](../reference/glossary.md#instance) declares a Hook of its kind. Each
+Hook is a name in the `hooks` block of `jr2.config.ts`, and its address is `POST /hooks/<name>`. Set up the service with
+this address one time:
+
+```ts
+import { defineConfig, secret } from "@jr2/orchestrator";
+import { github } from "@jr2/orchestrator/hooks/github";
+import { gitlab } from "@jr2/orchestrator/hooks/gitlab";
+
+export default defineConfig({
+  // Each Hook's secret is an entry of the list. jr2 up places GH_HOOK in the Instance Effector, and
+  // gives the Orchestrator only the sha-256 of GL_HOOK.
+  secrets: [
+    { name: "GH_HOOK", value: process.env.GH_HOOK },
+    { name: "GL_HOOK", value: process.env.GL_HOOK },
+    // The look of review reads the reviews with this token. jr2 up places it in the Instance Effector.
+    { name: "github-token", value: process.env.GITHUB_TOKEN },
+  ],
+  hooks: {
+    // POST /hooks/forge: GitHub signs each delivery with the secret GH_HOOK. The Hook may answer
+    // the Gates of review alone.
+    forge: github({ secret: secret("GH_HOOK"), may: { answer: ["review"] } }),
+    // POST /hooks/lab: GitLab sends the secret GL_HOOK as a token in a header.
+    lab: gitlab({ secret: secret("GL_HOOK"), may: { answer: ["review"] } }),
+  },
+});
+```
+
+A Hook takes a credential and `may.answer`. `may.answer` is the list of Workflows whose Gates the Hook can answer. The
+default is every Workflow. A Hook never starts a run. The kind tells how the service signs:
+
+- `github` and `slack` sign with a shared secret (`mac`). The
+  [Instance Effector](../reference/glossary.md#instance-effector) holds the secret and checks the signature. The
+  Orchestrator does not hold the secret.
+- `gitlab` sends a shared token in a header (`token`). The Orchestrator keeps only the sha-256 of the token, and removes
+  the header before the kind reads the delivery.
+- `discord` signs with a key pair (`ed25519`). The config holds the public key, which cannot sign.
+
+Each secret that a Hook names is an entry of the `secrets` list. For a `mac` Hook, [`jr2 up`](../reference/cli.md#up)
+places the secret in the Instance Effector alone, as it places an
+[Effect secret](../reference/glossary.md#effect-secret), and it converges the Instance Effector for the Hook. For a
+`token` Hook, `jr2 up` writes the sha-256 of the secret into the Secret `jr2-hook-digests`, which the Orchestrator
+mounts. The Orchestrator reads it again when it changes, so a new value needs no restart. The kubelet updates the mount
+in about one minute, and `jr2 up` waits for it before it says `converged`. A kind that posts a follow-up, such as the
+reply to a Slack click, declares the hosts of the post. `jr2 up` adds these hosts to the Instance Effector's list of
+targets, with no secret. The output of `jr2 up` names the Hook as `hook forge`, in the line of the secret and in the
+line of the Instance Effector.
+
+When a delivery comes, the door does these steps in this sequence:
+
+1. The door refuses a body that is larger than 2 MiB. It reads no more of the body than this limit.
+2. The verifier checks the delivery. A signed time that is more than 300 seconds from the Orchestrator's clock fails the
+   check.
+3. The kind reads the delivery. A handshake (a GitHub `ping`, a Discord `PING`, a Slack `url_verification`) gets the
+   kind's answer and goes to no Gate.
+4. The kind's schema parses the payload.
+5. The door looks for a repeat: a delivery whose id or body this Hook got before.
+6. The delivery goes to each open Gate, in each live run of a Workflow that the Hook may answer, whose handlers hear its
+   kind and event key.
+
+The answer is the outcome:
+`{ delivery, seen, delivered: [{ run, workflow, gate, event }], refused: [{ run, gate, event?, reason }], ignored, sources }`.
+`ignored` counts the open Gates whose handler gave `undefined`. A Gate whose handler throws, or gives an event that the
+run does not take now, is in `refused`, and the run's feed shows `hook-refused`. The run continues.
+
+To see what the door did, print the Hook's log. It keeps each delivery for `runs.retain` (30 days by default), newest
+first:
+
+```sh
+jr2 hooks forge
+```
+
+## A Gate in a package
+
+A [packaged Machine](publish-a-machine-as-an-npm-package.md) writes its handlers, because a forge's payload is public.
+It leaves its look `open`, because the look needs a url and a token. The composer binds the look with `customize()`, and
+can add, replace or remove a handler by kind and event key, where `null` removes one:
+`customize(machine, { gates: { review: { look, hooks: { gitlab: { "note.MergeRequest": null } } } } })`.
+
+## Rules
+
+- The door refuses a delivery that fails the verifier, or whose signed time is more than 300 seconds from the
+  Orchestrator's clock, with 401. Nothing else occurs, and the Hook's log keeps no line.
+- The door refuses a body that is larger than 2 MiB with 413, before the verifier:
+  `the delivery's body is larger than 2097152 bytes, the most the door reads` The Hook's log keeps a `too-large` line,
+  which does not claim the delivery's id.
+- The door refuses a name that the config does not declare with 404:
+  `no Hook named "<name>" in the current Assembly's config`
+- With no current Assembly, the door answers 503:
+  `the Orchestrator has no current Assembly, so no Hook is declared now — ask again`
+- `jr2 up` refuses a `mac` Hook whose secret is not in the `secrets` list:
+  ``hooks.<name> names secret("<NAME>"), which the `secrets` list does not hold — add it: secrets: [{ name: "<NAME>", value: process.env.<NAME> }] (ADR-0068)``
+  It refuses a `token` Hook whose secret is not in the list with the same text, which ends with `(ADR-0078)`.
+- `jr2 up` names the secret of a `token` Hook: `secret <NAME>: a digest in the Orchestrator (hook <name>)`
+- A `mac` Hook whose check the Instance Effector cannot answer gets 503:
+  `the Hook's signature cannot be checked now: no Instance Effector (ADR-0068)`
+- A request that the kind cannot read gets 400: `the <kind> kind cannot read the delivery: <error>`
+- A payload that the kind's schema refuses gets 200, with `payloadRefused: { kind, key, issues }`. It goes to no Gate.
+  When the service sends it again, the door parses it again.
+- A delivery whose id or body the Hook got before gets 200 with `seen: true`, and goes to no Gate.
+- The config load refuses a Hook's name that is not lowercase letters, digits and `-`, at most 40 characters:
+  `<file> at hooks.<name>: a Hook's name is lowercase letters, digits and -, at most 40, starts with a letter and ends with a letter or digit (ADR-0078)`
+- The config load refuses a value that no kind made:
+  `<file> at hooks.<name>: not a Hook — make it with its kind, such as github({ secret: secret("GH_HOOK") }) (ADR-0078)`
+- `jr2 hooks <name>` needs the Instance token.
+
+- `gate()` refuses a part that it does not know:
+  `gate(): "<key>" is not a part of a Gate slot (meta, delivers, hooks, look, reply) (ADR-0011)`
+- `gate()` refuses an empty `delivers`: `gate(): its delivers lists at least one event that defineEvent made (ADR-0011)`
+- `gate()` refuses a look whose read is a different Effect:
+  ``gate(): its look reads with <an http Effect that is not marked idempotent: true | a <kind> Effect> — a look reads again after each restore and every `every`, so its read is an http Effect marked idempotent: true, or a promise (ADR-0067) (ADR-0011)``
+- `gate()` refuses an `every` that is not a duration:
+  `gate(): its look's every "<every>" is not a positive duration (like "90s", "10m", "2h") (ADR-0011)`
+- `createMachine` refuses an event of `delivers` that the Machine does not declare:
+  `machine "<id>": Gate slot "<slot>" delivers "<event>", which no def in jr2Setup({ events }) declares (declared: <events>) — list it in events (ADR-0011)`
+- `createMachine` refuses an event of `delivers` that the Gate does not take at the state that invokes it:
+  `machine "<id>": state "<state>" invokes Gate slot "<slot>", which delivers "<event>", and its Gate does not accept it (accepts: <events>) — no handler or look could deliver it: handle it on that state, a state above it or a plain child, or drop it from delivers (ADR-0011)`
+- The Gate does not open when its `meta` does not agree with the schema, and the invoke fails:
+  `gate "<gate>": its meta does not match the Gate slot's meta schema — <path>: <message>`
+- `customize()` refuses a slot that holds no Gate slot:
+  `customize(): machine "<id>" carries no Gate slot "<slot>" — its Gate slots are: <slots> (ADR-0011). Only declared parts can be bound.`
+- `customize()` refuses `open` as a look:
+  ``customize(): Gate slot "<slot>"'s look is bound once, to a look or "none" — not `open` again (ADR-0054)``
+- The Chart door refuses a Chart that invokes a lent Gate slot whose `delivers` holds an event that is not in the
+  Chart's `events`:
+  ``<path>: the Gate slot "<slot>" delivers "<event>", which is not in the Chart's `events` (events: <events>); declare it in `events` and handle it on this state``
+- `jr2 up` and `jr2 check` warn, and do not refuse, about a Gate slot that hears a Hook and has no look and no `after`
+  on its state:
+  ``warning: workflow "<workflow>": Gate slot "<slot>" on "<state>" hears a Hook and has no look and no `after` on its state — a delivery lost in an outage stops the run until a person answers the Gate: give it a look, or look: "none" for a Gate that hears a command (ADR-0011)``
+- `jr2 up` and `jr2 check` warn about a look that a package left `open` and that nobody bound:
+  `warning: workflow "<workflow>": Gate slot "<slot>" on "<state>" leaves its look open — a delivery lost in an outage stops the run until a person answers the Gate: bind it with customize(machine, { gates: { <slot>: { look } } }), or give it look: "none" (ADR-0011, ADR-0054)`
+
+## Read next
+
+- [Gates](../concepts/gates.md) and [Callers and Hooks](../concepts/callers-and-hooks.md)
+- [Write a Hook kind](write-a-hook-kind.md), for a service that jr2 ships no kind for
+- [Answer a Gate](answer-a-gate.md) and [Bind Open parts](bind-open-parts.md)
+- [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): a Gate hears a Hook, and looks before it waits
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): a
+  Hook is a Caller that can only answer a Gate or bring items to a Source