@jr2/orchestrator 0.4.1 → 0.6.0

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

@@ -0,0 +1,304 @@
+---
+title: Answer a Gate
+description: Send an event to an open Gate of a run, from the CLI, the Console, a webhook handler or a CI job.
+---
+
+# Answer a Gate
+
+Send an event to an open [Gate](../reference/glossary.md#gate) of a run from the CLI, the
+[Console](../reference/glossary.md#console), a webhook handler or a CI job.
+
+A run waits at a Gate until a person or a different system answers it. The Gate is open while the run is in the state
+that invokes it, and it closes when the run leaves that state. An open Gate has an id, its events, and the input schema
+of each event. Its `meta` is the data that the [Machine](../reference/glossary.md#machine) shows to the person or the
+system that answers.
+
+The examples on this page use the [Workflow](../reference/glossary.md#workflow) `release`. Its Gate `review` takes
+`approve`, with no input, and `reject`, with a `reason`. The Workflow has no [Agent](../reference/glossary.md#agent), so
+you can try the steps with no model. Save the file as `workflows/release.ts` in your
+[Instance](../reference/glossary.md#instance). Then run `jr2 up`:
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { defineEvent, fail, jr2Setup } from "@jr2/orchestrator";
+
+// The two answers that the Gate takes. A person, a script or a CI job sends one of them.
+const approve = defineEvent({
+  name: "approve",
+  description: "Release this version.",
+  input: z.object({}),
+});
+const reject = defineEvent({
+  name: "reject",
+  description: "Do not release this version. Say why.",
+  input: z.object({ reason: z.string().min(1) }),
+});
+
+type Context = { version: string; reason?: string };
+
+export const machine = jr2Setup({
+  types: {} as { input: { version: string }; context: Context },
+  events: [approve, reject],
+  actors: { fail: fail() },
+}).createMachine({
+  id: "release",
+  // jr2 checks each run input against this schema before the run starts.
+  input: z.object({ version: z.string() }),
+  context: ({ input }) => ({ version: input.version }),
+  initial: "review",
+  states: {
+    review: {
+      // The Gate is open while the run is in this state. Its id is the state key, "review".
+      // It takes the events of this state: approve and reject.
+      invoke: { src: "gate", input: ({ context }) => ({ meta: { version: context.version } }) },
+      on: {
+        approve: "released",
+        reject: { target: "rejected", actions: assign({ reason: ({ event }) => event.reason }) },
+      },
+    },
+    released: { type: "final" },
+    // A person stopped the release, and the run ends here. Not a final state: the run ends
+    // `failed`, with the person's reason.
+    rejected: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.reason! }) } },
+  },
+});
+```
+
+In the commands, replace these values:
+
+- `<namespace>`: the namespace of your Instance. It is the [`name`](../reference/config.md#name) in `jr2.config.ts`.
+  When `jr2.config.ts` sets no `name`, it is the name of the Instance folder.
+- `<run id>`: the run id, or its first 4 characters or more. `jr2 run` prints the run id in the line
+  `run <run id> (<workflow>) — attached`.
+
+Give each `jr2` command in the Instance folder.
+
+## Start a run that waits
+
+Start a run in one terminal. `jr2 run` stays attached while the run waits at the Gate:
+
+```sh
+jr2 run release --input '{"version":"1.4.0"}'
+```
+
+```text
+→ context <context> / namespace <namespace>
+run 2319932e-02c1-4f9d-98db-3c5a410395da (release) — attached
+  → active "review"
+```
+
+Your run id is different, and so are the instance id and the `assembly` hash in the next steps. Give the commands in the
+next steps in a second terminal. [Start a run](start-a-run.md) gives the other ways to start a run.
+
+## Find the open Gate
+
+Run [`jr2 status`](../reference/cli.md#status) with the run id:
+
+```sh
+jr2 status 2319
+```
+
+```text
+→ context <context> / namespace <namespace>
+{"runId":"2319932e-02c1-4f9d-98db-3c5a410395da","workflow":"release","instanceId":"c898d8c7-e48b-4a56-8101-7148905b6aed","status":"active","value":"review","context":{"version":"1.4.0"},"children":[],"waiting":[],"held":[],"assembly":"83858e28b054","gates":[{"gate":"review","path":["review"],"accepts":[{"name":"approve","description":"Release this version.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"reject","description":"Do not release this version. Say why.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"],"additionalProperties":false}}],"acceptsNow":["approve","reject"],"meta":{"version":"1.4.0"}}]}
+```
+
+`gates` holds each open Gate of the run, as a [`GateView`](../reference/http-api.md#type-gateview):
+
+- `gate` is the id of the Gate. Give it in `--gate`. When the Machine gives the Gate no id, jr2 makes the id from the
+  path of the Gate's state. Here it is `review`, the key of the state.
+- `accepts` holds each event that the Gate accepts: its `name`, its `description`, and its `input` as JSON Schema.
+- `acceptsNow` holds the events that the run takes now. A guard on a transition can remove an event from this list.
+- `meta` holds the data that the Machine gives to the Gate.
+
+A run that has no open Gate has `"gates":[]`.
+
+## Answer from the CLI
+
+Run [`jr2 send`](../reference/cli.md#send). Give the Gate in `--gate`, the event in `--event`, and the input of the
+event as a JSON object in `--input`:
+
+```sh
+jr2 send 2319 --gate review --event reject --input '{"reason":"The changelog is not ready."}'
+```
+
+```text
+→ context <context> / namespace <namespace>
+delivered reject to gate "review" on 2319932e-02c1-4f9d-98db-3c5a410395da
+```
+
+`jr2 send` prints `delivered` only when the run took the event. In the first terminal, the run ends. A `reject` ends the
+release, so the `rejected` state invokes [`fail`](../reference/authoring-surface/fail.md) with the reason, and the run
+ends `failed`. Its output is the [Failure](../reference/glossary.md#failure), and `jr2 run` exits with `1`:
+
+```text
+  → active "rejected"
+  → failed "rejected"
+failed: The changelog is not ready.
+{"runId":"2319932e-02c1-4f9d-98db-3c5a410395da","workflow":"release","instanceId":"c898d8c7-e48b-4a56-8101-7148905b6aed","status":"failed","value":"rejected","context":{"version":"1.4.0","reason":"The changelog is not ready."},"children":[],"waiting":[],"held":[],"assembly":"83858e28b054","output":{"reason":"The changelog is not ready."}}
+```
+
+The run ended, so its Gate closed. Each example below answers a run that waits. Before each example, start a new run in
+the first terminal:
+
+```sh
+jr2 run release --input '{"version":"1.4.0"}'
+```
+
+For an event with no input, such as `approve`, do not give `--input`:
+
+```sh
+jr2 send <run id> --gate review --event approve
+```
+
+```text
+→ context <context> / namespace <namespace>
+delivered approve to gate "review" on c099e2dc-6dd2-45da-9358-0723c8b83c68
+```
+
+`jr2 send` prints the full run id, also when you give a prefix.
+
+## Answer from the Console
+
+You need the Instance token to answer a Gate from the Console. [Open the Console](open-the-console.md) tells how to open
+it and how to get the token.
+
+1. Open the Console.
+2. Type the Instance token in the `instance token` box in the nav.
+3. Push Enter. The badge beside the box shows `…`, then `live`.
+4. Click the `Attention` tab in the drawer on the right. It shows a card for each open Gate of the Workflow that you
+   selected. To see the Gates of all the Workflows, select `all workflows`. When you select no Workflow, it shows them
+   all.
+5. Find the card. Its top line shows `⚑` and the id of the Gate at the left. At the right, it shows the Workflow and the
+   first 8 characters of the run id. Below it, the card shows the `meta` of the Gate.
+6. The card has a form for each event that the Gate accepts. Fill in the form of the event that you send. A field that
+   has `*` after its name is necessary.
+7. Click `send` in that form.
+
+When the run takes the event, the card goes away. When the [Orchestrator](../reference/glossary.md#orchestrator) refuses
+the event, the form shows the refusal text below the `send` button.
+
+The `⚑` badge in the nav gives the number of open Gates in all the Workflows. Click it to open the `Attention` tab.
+
+## Answer from a webhook or CI
+
+A webhook handler or a CI job answers a Gate with
+[`POST /runs/:runId/gates/:gate/events`](../reference/http-api.md#post-runs-runid-gates-gate-events) and the Instance
+token. jr2 has no webhook receiver of its own. Your handler or job reads its own event, finds the run and the Gate, and
+sends the call. The body is the event: `type` is the name of the event, and the other properties are its input.
+
+`jr2 up` makes the Service `jr2-orchestrator` on port 4000, with no address outside the cluster. Thus a caller outside
+the cluster uses a port forward, or an address that you make for the Service.
+
+In a new terminal, forward a port to the Orchestrator. Keep this command open:
+
+```sh
+kubectl -n <namespace> port-forward svc/jr2-orchestrator 4000:4000
+```
+
+In a different terminal, get the Instance token into a variable:
+
+```sh
+TOKEN=$(kubectl -n <namespace> get secret jr2-instance -o jsonpath='{.data.JR2_INSTANCE_TOKEN}' | base64 -d)
+```
+
+Send the event. Use the full run id, because the route does not accept a prefix:
+
+```sh
+curl -s -X POST http://localhost:4000/runs/<run id>/gates/review/events \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"type":"approve"}'
+```
+
+```text
+{"ok":true}
+```
+
+A webhook handler often knows a fact, such as a version, but not the run id. It can find the run from the `meta` of the
+Gate. [`GET /runs`](../reference/http-api.md#get-runs) gives the live runs, and
+[`GET /runs/:runId`](../reference/http-api.md#get-runs-runid) gives the open Gates of one run. This script approves the
+`release` run that waits for one version. It needs `curl` and `jq`. Save it as `approve-release.sh`:
+
+```sh
+#!/bin/sh
+# Approve the release run that waits at its review Gate for one version.
+# Set JR2_URL, JR2_TOKEN and VERSION before you run this script. It needs curl and jq.
+set -eu
+
+auth="Authorization: Bearer $JR2_TOKEN"
+
+# The live runs of the release Workflow.
+for run in $(curl -fsS -H "$auth" "$JR2_URL/runs" | jq -r '.[] | select(.workflow == "release") | .runId'); do
+  # The open Gates of the run, with their meta.
+  version=$(curl -fsS -H "$auth" "$JR2_URL/runs/$run" | jq -r '.gates[] | select(.gate == "review") | .meta.version')
+  if [ "$version" = "$VERSION" ]; then
+    curl -fsS -X POST -H "$auth" -H "Content-Type: application/json" \
+      -d '{"type":"approve"}' "$JR2_URL/runs/$run/gates/review/events"
+    echo
+  fi
+done
+```
+
+```sh
+JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN VERSION=1.4.0 sh approve-release.sh
+```
+
+```text
+{"ok":true}
+```
+
+A CI job can also run `jr2 send`. With `JR2_URL` and `JR2_TOKEN`, `jr2 send` needs no Instance folder and no kubectl
+context, and it accepts a prefix of the run id:
+
+```sh
+JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN jr2 send <run id> --gate review --event approve
+```
+
+```text
+→ http://localhost:4000
+delivered approve to gate "review" on c44c6e49-452d-4150-8ce4-4d036363d2a0
+```
+
+## Rules
+
+- The Orchestrator refuses a Gate that is not open on the run, with the status code `404`:
+  `no open gate "<gate>" on run "<run id>" (open: <gates>)`. The part `(open: <gates>)` shows only when the run has an
+  open Gate. When an event takes the run out of the state of the Gate, the Gate closes. Thus a second answer gets this
+  refusal.
+- The Orchestrator refuses an event that the Gate does not accept, with the status code `400`:
+  `"<gate>" does not accept "<event>" (accepts: <events>)`
+- The Orchestrator refuses an input that does not agree with the schema of the event, with the status code `400`:
+  `invalid "<event>" payload: <issues>`. `<issues>` is the list of the problems as JSON.
+- The Orchestrator refuses an event that the run does not take now, with the status code `409`, and delivers nothing:
+  `gate "<gate>" is open, and the run does not take "<event>" now: <why> — not delivered (takes now: <events>)`. The
+  body also holds `acceptsNow`.
+- The Orchestrator refuses a body with no `type`, with the status code `400`:
+  `event body must carry a string "type" (one of the gate's accepted names)`
+- The Orchestrator refuses a body that holds `sender`, with the status code `400`:
+  `` `sender` is written by the Orchestrator on every delivered event; a caller cannot send it ``
+- The Orchestrator refuses an event without the Instance token, with the status code `401`: `unauthorized`.
+- The Orchestrator refuses an event with the token of a [Sandbox](../reference/glossary.md#sandbox), with the status
+  code `403`: `a Sandbox token cannot deliver to a gate — gates are not on the Agent's surface`. Thus an Agent cannot
+  answer a Gate.
+- `jr2 send` prints each refusal of the Orchestrator as `error: <refusal>`, and exits with `1`. After a `404` refusal,
+  it also prints the version of the Instance in one more line:
+  ``instance: <version> (<hash>) — if it predates this CLI, `jr2 up` converges the cluster to this kit``. `<hash>` is
+  the hash of the current [Assembly](../reference/glossary.md#assembly).
+- `jr2 send` without `--gate` sends run control, and run control accepts only `CANCEL`. For a different event, it exits
+  with `2`: `jr2 send: unknown event "<event>" (run control accepts: CANCEL; workflow events need --gate)`
+- With `--gate`, `jr2 send` sends nothing when `--input` is not valid JSON. It exits with `2`:
+  `jr2 send: --input is not valid JSON`
+- `jr2 send` with no run id or no `--event` sends nothing. It prints its help and exits with `2`.
+
+## Read next
+
+- [Gates](../concepts/gates.md)
+- [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): a Gate, its events, and its `meta`.
+- [ADR-0013](../reference/decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md): why an
+  Agent cannot answer a Gate, and why a refused event is not delivered.
+- [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-the-instance-token.md): the Instance token in the
+  Console.
+- [Start a run](start-a-run.md)
+- [Watch a run](watch-a-run.md)

package/docs/guides/bind-open-parts.md

@@ -0,0 +1,224 @@
+---
+title: "Bind a shipped Machine's Open parts"
+description: Register a Machine from a package as a Workflow, and bind the parts that it leaves Open with customize().
+---
+
+# Bind a shipped Machine's Open parts
+
+Register a [Machine](../reference/glossary.md#machine) from a package as a
+[Workflow](../reference/glossary.md#workflow), and bind the parts that it leaves [Open](../reference/glossary.md#open)
+with [`customize()`](../reference/authoring-surface/customize.md).
+
+A package does not know your [Repo](../reference/glossary.md#repo), and it cannot pay for your model. Thus a Machine in
+a package marks these parts with [`open`](../reference/authoring-surface/open.md), and you bind them on the line that
+registers it. [`jr2 up`](../reference/cli.md#up) refuses a Workflow with an Open part that nobody bound.
+
+The examples on this page register [`task`](../reference/machines.md#task), the Machine that `@jr2/machines` ships.
+`task` leaves two parts Open: its whole [Repo Slot](../reference/glossary.md#repo-slot) map, and the model of its
+[Agent](../reference/glossary.md#agent) `coder`.
+
+## Install the package
+
+Install `@jr2/machines` at the [Kit version](../reference/glossary.md#kit-version) of your
+[Instance](../reference/glossary.md#instance). `<version>` is the version of `@jr2/orchestrator` in your `package.json`:
+
+```sh
+npm install --save-exact @jr2/machines@<version>
+```
+
+## Find the Open parts
+
+Register the Machine as it is. Save this file as `workflows/fix-app.ts`:
+
+```ts
+import { task } from "@jr2/machines";
+
+// The Machine as it is, with no part bound. jr2 up refuses this file, and prints the line that binds one part.
+export const machine = task;
+```
+
+Then run `jr2 up`. It stops before it changes the cluster. For each Open part, it prints the `customize()` line that
+binds the part:
+
+```sh
+jr2 up
+```
+
+```text
+jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
+typecheck: tsc --noEmit (the instance's own compiler)
+refusing: workflow "fix-app" leaves its Repo Slots open — bind it where the Machine is registered: export const machine = customize(<import>, { repos: { <slot>: "<url>" } })  (ADR-0051)
+refusing: workflow "fix-app" leaves Agent "coder" open — bind it where the Machine is registered: export const machine = customize(<import>, { agents: { coder: { model: "<provider>/<model>" } } })  (ADR-0054)
+```
+
+[The Reference of `@jr2/machines`](../reference/machines.md) also gives the Open parts of each Machine.
+
+## Bind the Open parts
+
+Replace the file with one `customize()` call that binds the two parts. The coder works in the Repo `app`. It can read
+the Repo `handbook`.
+
+**Anthropic**
+
+```ts
+import { customize } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const model = "anthropic/claude-haiku-5-5";
+
+// `task` leaves two parts Open: its Repo Slots and the model of its coder. Bind the two here.
+// The file name gives the Workflow its name: fix-app.
+export const machine = customize(task, {
+  repos: {
+    // The first Repo Slot is the Repo that the coder works in. Its branch starts from `main`.
+    app: { url: "https://github.com/<you>/app.git", ref: "main" },
+    // The coder can read each Repo Slot after the first. A url alone uses the default branch.
+    handbook: "https://github.com/<you>/handbook.git",
+  },
+  // `{ model }` changes only the model. The coder keeps the instructions of `task`.
+  agents: { coder: { model } },
+});
+```
+
+**Local**
+
+```ts
+import { customize } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const model = "local/qwen3.6-35b-a3b";
+
+// `task` leaves two parts Open: its Repo Slots and the model of its coder. Bind the two here.
+// The file name gives the Workflow its name: fix-app.
+export const machine = customize(task, {
+  repos: {
+    // The first Repo Slot is the Repo that the coder works in. Its branch starts from `main`.
+    app: { url: "https://github.com/<you>/app.git", ref: "main" },
+    // The coder can read each Repo Slot after the first. A url alone uses the default branch.
+    handbook: "https://github.com/<you>/handbook.git",
+  },
+  // `{ model }` changes only the model. The coder keeps the instructions of `task`.
+  agents: { coder: { model } },
+});
+```
+
+Write the owner of your Repos in place of `<you>`. A private Repo needs a git credential in the cluster.
+[Give the cluster git credentials](give-the-cluster-git-credentials.md) tells how.
+
+The coder uses the model of the tab. Connect that model in `jr2.config.ts` and `.env` before you run `jr2 up`.
+[Connect a model](../get-started/connect-a-model.md) tells how. Run `jr2 up` again. It converges. Then start a run with
+a prompt:
+
+```sh
+jr2 run fix-app --input '{"prompt":"Make the failing test in test/greet.test.ts pass."}'
+```
+
+[An Agent in a Sandbox](../get-started/an-agent-in-a-sandbox.md) gives a full run of `task`, with the `review`
+[Gate](../reference/glossary.md#gate).
+
+### A Repo Slot
+
+The key of each Repo Slot is the name of the slot, and the directory `/work/<slot>` in the
+[Sandbox](../reference/glossary.md#sandbox). The value is one of these:
+
+- a url: `"https://github.com/<you>/handbook.git"`. The clone stays on the default branch of the Repo, and a new
+  [Worktree](../reference/glossary.md#worktree) branch starts from it.
+- a [Binding](../reference/glossary.md#binding): `{ url, ref }`. The clone stays on `ref`, a branch, a tag or a commit,
+  and a new branch starts from it.
+- a function of the run input: `({ input }) => url`, or `({ input }) => ({ url, ref })`. Each run chooses its Repo. The
+  url must agree with an entry of [`git.credentials`](../reference/config.md#git-credentials) in `jr2.config.ts`.
+- `open`, to leave the slot Open for the Instance that registers your Machine.
+
+`task` leaves the whole map Open. Thus you name every slot, and you name one slot or more. The order has the meaning
+that the Machine gives it. For `task`, the first slot is the Repo that the coder works in, and the coder can read the
+others. A Machine that names its slots, such as `repos: { app: open }`, takes only those keys.
+
+### An Agent
+
+`agents` takes the fields of the definition of an Agent, by slot. Each field goes over the field that the author wrote.
+Thus `{ model }` changes only the model, and the coder keeps the instructions of `task`. You can also change other
+fields, such as `thinkingLevel` or `instructions`.
+[`AgentDefinition`](../reference/authoring-surface/type-agentdefinition.md) gives the fields.
+
+## Bind the parts of a Machine that you compose
+
+When your Machine invokes a packaged Machine as a child, the Open parts of the child are Open in your Machine too. Bind
+them in one of two ways:
+
+- Bind them on the import, before you put it under `actors`: `const coding = customize(task, { repos, agents })`. Then
+  use `coding` as the child. [Composition](../concepts/composition.md) has an example.
+- Bind them on your Machine, through the slot of the child:
+  `customize(yours, { actors: { <slot>: { repos, agents } } })`.
+
+`jr2 up` names the child in the refusal, and it prints the line with `actors`. For example, a Machine `outer` puts
+`task` under `actors` as `coding`, and binds nothing:
+
+```text
+…
+refusing: workflow "outer" leaves its Repo Slots open (on the Machine composed as "coding") — bind it where the Machine is registered: export const machine = customize(<import>, { actors: { coding: { repos: { <slot>: "<url>" } } } })  (ADR-0051)
+refusing: workflow "outer" leaves Agent "coder" open (on the Machine composed as "coding") — bind it where the Machine is registered: export const machine = customize(<import>, { actors: { coding: { agents: { coder: { model: "<provider>/<model>" } } } } })  (ADR-0054)
+```
+
+When `task` is a child of your Machine, give it `branch` in its input. Only the root Machine of a run gets the id that
+`task` makes a branch name from.
+
+## Bind the Open parts of an Effect
+
+A packaged Machine can leave the url of an `http` [Effect](../reference/glossary.md#effect), the argv of a `command`, or
+the name of a secret Open. Bind them with `effects`, by the slot of the Effect:
+`customize(machine, { effects: { notify: { url } } })`. One object binds all the Open parts of one Effect. You bind each
+part one time, to a value. No run chooses it. [`EffectBinding`](../reference/authoring-surface/type-effectbinding.md)
+gives the values, and [Run a command or call a URL with an Effect](run-a-command-or-call-a-url.md) shows an Effect.
+
+## Rules
+
+- `jr2 up` refuses a registered Machine that leaves a part Open. It changes nothing in the cluster:
+  `refusing: workflow "<name>" leaves <part> open — bind it where the Machine is registered: export const machine = customize(<import>, <binding>)  (<adr>)`.
+  `<part>` is one of `its Repo Slots`, `Repo Slot "<slot>"`, `Agent "<slot>"`, or `the <parts> of Effect "<slot>"`,
+  where `<parts>` is such as `url` or `url and secret`. For a child Machine, `(on the Machine composed as "<slot>")`
+  comes after `open`.
+- `jr2 up` refuses an Open part on a Machine that a state writes in its `invoke.src`, because no `customize()` gets to
+  it. Put that Machine under `actors`:
+  `refusing: workflow "<name>" leaves <part> open on a Machine invoked inline — no customize() reaches an actor without a slot key; declare that Machine under setup({ actors }) and bind it there  (ADR-0049, <adr>)`
+- The compiler refuses a key for a part that the Machine does not declare, such as an Agent slot that it does not have.
+  The text of the compiler is:
+  `Object literal may only specify known properties, and '<slot>' does not exist in type '<type>'.` Then `jr2 up` prints
+  `refusing: this instance does not typecheck — nothing was built and nothing was applied`.
+- `customize()` refuses a slot that the compiler did not see. `jr2 up` prints the refusal as `error: <refusal>`:
+  - `customize(): machine "<id>" carries no Agent slot "<slot>" — its Agents are: <slots> (ADR-0049). Only declared parts can be retuned; a Machine that needs another Agent is a new Machine.`
+  - `customize(): machine "<id>" composes no Machine under "<slot>" — the Machines it composes are: <slots> (ADR-0049).`
+  - `customize(): machine "<id>" declares no Repo Slot "<slot>" — its slots are: <slots> (ADR-0051)`
+  - `customize(): machine "<id>" carries no Effect slot "<slot>" — its Effects are: <slots> (ADR-0067). Only declared parts can be bound.`
+- `customize()` refuses an Open map that you bind with no slot:
+  ``customize(): machine "<id>" declares its Repo Slots open as a map — name at least one: `repos: { app: "https://…" }` (ADR-0051).``
+- `customize()` refuses a Repo Slot key that is not a directory name. The key becomes `/work/<slot>`:
+  ``customize(): Repo Slot key "<slot>" is not a directory name — a slot becomes `/work/<slot>`, `/work/.jr2/` is reserved for jr2, and its order matters, so it starts with a letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051, ADR-0075).``
+- `customize()` refuses an empty url:
+  ``customize(): Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot is `open`, a url, `{ url, ref? }`, or a mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
+  For an empty `ref`, the text says `bound with an empty ref`.
+- `customize()` refuses a url that names no Repo, such as a relative path:
+  `customize(): Repo Slot "<slot>" binds "<url>", which names no Repo — <reason> (ADR-0051).`
+- `customize()` refuses `open` or a function as the value of an Effect's part:
+  ``customize(): the <kind> Effect "<slot>"'s <part> is bound once, to a value — not `open` again: no run chooses an Effect's <part> (ADR-0054)``.
+  For a function, the text says `a function of the run` in place of `` `open` again ``.
+- An Agent does not start a [Turn](../reference/glossary.md#turn) while its model is Open:
+  ``agent "<slot>" has an Open model — nobody bound it; bind it where the Machine is registered (`customize(<machine>, { agents: { <slot>: { model: "<provider>/<model>" } } })`), because a packaged Machine cannot pick a model on your behalf (ADR-0054)``.
+  `jr2 up` refuses this case first.
+- `task` inside a different Machine refuses to start without `branch` in its input:
+  ``task: no `branch` on the door and no Instance ID to derive one from — `jr2/task-<instance id>` needs the id the host injects beside the door of the ROOT machine (ADR-0033), and this run of `task` was started by a parent Machine instead. Pass `branch` in the run input.``
+
+## Read next
+
+- [Composition](../concepts/composition.md)
+- [ADR-0054](../reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md): the kit
+  ships Machines, and a shipped Machine leaves its parts Open.
+- [ADR-0049](../reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md): a Machine carries its
+  parts, and `customize()` changes them.
+- [ADR-0051](../reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md): a Repo is a slot
+  on the `workspace()`.
+- [Workspaces](../concepts/workspaces.md)
+- [Publish a Machine as an npm package](publish-a-machine-as-an-npm-package.md), to leave parts Open in a Machine of
+  your own.
+- Reference: [`customize()`](../reference/authoring-surface/customize.md),
+  [`Customize`](../reference/authoring-surface/type-customize.md), [`open`](../reference/authoring-surface/open.md),
+  [`RepoSlot`](../reference/authoring-surface/type-reposlot.md), [`task`](../reference/machines.md#task)