@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/concepts/effects.md

@@ -0,0 +1,658 @@
+---
+title: Effects
+description: How a Machine runs a command, calls a URL, pushes a branch or starts a run, at most once.
+---
+
+# Effects
+
+An [Effect](../reference/glossary.md#effect) is work that a [Machine](../reference/glossary.md#machine) does outside
+itself. jr2 has four kinds: `command` runs a program in the [Workspace](../reference/glossary.md#workspace), `http`
+calls a URL, `push` pushes the branch of a [Worktree](../reference/glossary.md#worktree), and `dispatch` starts a run of
+a [Workflow](../reference/glossary.md#workflow). The Kit also gives
+[`worktree()`](../reference/authoring-surface/worktree.md), an Effect on the `command` machinery that cuts a Worktree.
+You write an Effect as an actor slot, beside the [Agents](../reference/glossary.md#agent) of the Machine.
+
+## Why Effects exist
+
+A Machine often needs a fact from the world: do the tests pass, did the call succeed, is the branch on the remote.
+Without an Effect, the Machine can only ask an Agent to do the work. Then the Machine must trust what the Agent says. An
+Effect gives the Machine its own result, and the Machine routes on it.
+
+An Effect also keeps a credential away from the Agent. A `push` uses a push credential, and an `http` call uses an
+[Effect secret](../reference/glossary.md#effect-secret). The Agent never reads either one. jr2 also records each Effect
+before it starts, so that a restart of the [Orchestrator](../reference/glossary.md#orchestrator) does not do the work
+two times. A plain [xstate](https://xstate.js.org) promise has no such record.
+
+## An Effect is an actor slot
+
+Put an Effect under `actors` in [`jr2Setup`](../reference/authoring-surface/jr2setup.md). Invoke it by its key from a
+state. The state's `onDone` gets the output of the Effect. This example is a Workflow with a Workspace. An Agent fixes
+the code in a Worktree that the Machine cuts first. It can ask for a test run with the pick `run_tests`. When the Agent
+picks `finished`, the Machine pushes the branch:
+
+**Anthropic**
+
+```ts
+import { z } from "zod";
+import {
+  agent,
+  answer,
+  command,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  workspace,
+  worktree,
+  type CommandOutput,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+// The two picks of the Agent.
+const runTests = defineEvent({
+  name: "run_tests",
+  description: "Run the tests. The result is the answer to this call.",
+  input: z.object({}),
+});
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when the tests pass and your fix is committed.",
+  input: z.object({}),
+});
+
+const runInput = z.object({ prompt: z.string(), branch: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+// The Worktree that the coder, the tests and the push all name.
+const appTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
+const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
+
+const body = jr2Setup({
+  types: {} as { context: BodyInput; input: BodyInput },
+  events: [runTests, finished],
+  actors: {
+    coder: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You are a careful engineer. You commit your work on the branch.",
+    }),
+    // Three Effects. Each is an actor slot, beside the Agent.
+    cut: worktree(),
+    tests: command(["node", "--test"], { timeout: "5m" }),
+    publish: push(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "test-and-push",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: appTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: context.prompt, cwd: appTree(context) }),
+      },
+      on: { finished: "publishing" },
+      initial: "ready",
+      states: {
+        ready: { on: { run_tests: "testing" } },
+        testing: {
+          invoke: {
+            src: "tests",
+            input: ({ context }) => ({ worktree: appTree(context) }),
+            onDone: {
+              target: "ready",
+              // The Agent reads this text as the answer to its run_tests pick.
+              actions: answer(({ event }) =>
+                passed(event.output)
+                  ? "The tests pass."
+                  : `The tests fail:\n${"tail" in event.output ? event.output.tail : event.output.reason}`,
+              ),
+            },
+          },
+        },
+      },
+    },
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: appTree(context) }),
+        onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    // A Failure ends the body, and jr2 deletes the Sandbox with its commits. To keep them, wait at
+    // a Gate before this state.
+    notPushed: { invoke: { src: "fail", input: { reason: "the push did not publish the fix" } } },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+**Local**
+
+```ts
+import { z } from "zod";
+import {
+  agent,
+  answer,
+  command,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  workspace,
+  worktree,
+  type CommandOutput,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+// The two picks of the Agent.
+const runTests = defineEvent({
+  name: "run_tests",
+  description: "Run the tests. The result is the answer to this call.",
+  input: z.object({}),
+});
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when the tests pass and your fix is committed.",
+  input: z.object({}),
+});
+
+const runInput = z.object({ prompt: z.string(), branch: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+// The Worktree that the coder, the tests and the push all name.
+const appTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
+const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
+
+const body = jr2Setup({
+  types: {} as { context: BodyInput; input: BodyInput },
+  events: [runTests, finished],
+  actors: {
+    coder: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You are a careful engineer. You commit your work on the branch.",
+    }),
+    // Three Effects. Each is an actor slot, beside the Agent.
+    cut: worktree(),
+    tests: command(["node", "--test"], { timeout: "5m" }),
+    publish: push(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "test-and-push",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: appTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: context.prompt, cwd: appTree(context) }),
+      },
+      on: { finished: "publishing" },
+      initial: "ready",
+      states: {
+        ready: { on: { run_tests: "testing" } },
+        testing: {
+          invoke: {
+            src: "tests",
+            input: ({ context }) => ({ worktree: appTree(context) }),
+            onDone: {
+              target: "ready",
+              // The Agent reads this text as the answer to its run_tests pick.
+              actions: answer(({ event }) =>
+                passed(event.output)
+                  ? "The tests pass."
+                  : `The tests fail:\n${"tail" in event.output ? event.output.tail : event.output.reason}`,
+              ),
+            },
+          },
+        },
+      },
+    },
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: appTree(context) }),
+        onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    // A Failure ends the body, and jr2 deletes the Sandbox with its commits. To keep them, wait at
+    // a Gate before this state.
+    notPushed: { invoke: { src: "fail", input: { reason: "the push did not publish the fix" } } },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+[Agents and Turns](agents-and-turns.md) tells how to define an Agent.
+
+The Effect has the life of the state that invokes it. It starts when the run enters the state, and it stops when the run
+leaves the state. Its input goes into the run's snapshot. A typo in `src` is a compile error.
+[`customize()`](../reference/authoring-surface/customize.md) binds an [Open](../reference/glossary.md#open) part of the
+Effect by its slot key (see [Composition](composition.md)).
+
+[`jr2 up`](../reference/cli.md#up) reads each Effect slot without running it, and prints what it found. For each
+Workflow, it lists each Effect with its kind, its argv or its method and host, its timeout, and where it runs. For the
+example above, `jr2 up` prints these lines:
+
+```text
+effects: workflow "test-and-push" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
+  tests: command ["node","--test"] — 300s, in the Harness
+  publish: push — 300s, in the Sandbox Effector
+```
+
+The first line gives the name of the Workflow. Each next line gives the slot of one Effect.
+
+`jr2 up` also lists each state that invokes [`fail`](../reference/authoring-surface/fail.md), because each one ends the
+run `failed`:
+
+```text
+failures: workflow "test-and-push" — the states that fail the run (ADR-0073)
+  test-and-push.notCut: invokes fail
+  test-and-push.notPushed: invokes fail
+  test-and-push.failed: invokes fail
+  test-and-push.lost: invokes fail
+```
+
+## The four kinds
+
+### `command`
+
+[`command`](../reference/authoring-surface/command.md) runs one program. Its argv is a list, and each entry is one
+argument. jr2 starts `argv[0]` with no shell. An [`arg("name")`](../reference/authoring-surface/arg.md) entry is one
+argument that the input of the Effect fills. Thus an Agent's text cannot become shell syntax. To use a shell, write it
+in the argv: `["sh", "-c", "…"]`. Then the result is the result of your script. The Agent can change the files that the
+script runs, so do not trust its result more than the Agent.
+
+Under [Repo Slots](../reference/glossary.md#repo-slot), the input of a `command` names its Worktree: `{ worktree }`, a
+Worktree that a cut made, or `/work/<slot>/default`. Its default timeout is 10 minutes. Its output keeps the end of what
+the program wrote: 4096 characters by default (the `tail` option). The full output goes to the run's feed.
+
+### `http`
+
+[`http`](../reference/authoring-surface/http.md) calls a URL. The definition fixes the method, the URL, the headers and
+the auth. The scheme and the host of the URL are literal text. An Effect secret can be in the path of the URL, in a
+header or in the auth, but never in the host. A `request` function makes the part that changes for each run: path
+segments, and a JSON or text body. Thus a value from the run can change a path segment or the body, but not where the
+call goes.
+
+In the second example, an Agent with `workspace: "none"` writes one comment, and the Machine posts it on a ticket. This
+Agent has no [Sandbox](../reference/glossary.md#sandbox). The `jira` Effect secret must be in the
+[`secrets`](../reference/config.md#secrets) list of `jr2.config.ts`:
+
+**Anthropic**
+
+```ts
+import { z } from "zod";
+import { agent, bearer, defineEvent, fail, fromPick, http, jr2Setup, secret } from "@jr2/orchestrator";
+
+const postComment = defineEvent({
+  name: "post_comment",
+  description: "Post one comment on the ticket.",
+  input: z.object({ body: z.string() }),
+});
+
+// The host is fixed here. No input can change it.
+const comment = http({
+  method: "POST",
+  url: "https://jira.example.com/rest/api/2/issue",
+  auth: bearer(secret("jira")),
+  input: z.object({ ticket: z.string(), body: z.string() }),
+  request: ({ ticket, body }) => ({ path: [ticket, "comment"], json: { body } }),
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: { ticket: string }; input: { ticket: string } },
+  events: [postComment],
+  actors: {
+    triager: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You triage tickets.",
+      workspace: "none",
+    }),
+    comment,
+    fail: fail(),
+  },
+}).createMachine({
+  id: "comment",
+  input: z.object({ ticket: z.string() }),
+  context: ({ input }) => input,
+  on: { "agent.fault": ".failed" },
+  initial: "triaging",
+  states: {
+    triaging: {
+      invoke: {
+        src: "triager",
+        input: ({ context }) => ({ prompt: `Write one comment for ticket ${context.ticket}.` }),
+      },
+      initial: "ready",
+      states: {
+        ready: { on: { post_comment: "posting" } },
+        posting: {
+          invoke: {
+            src: "comment",
+            // The Agent gives `body`. The Machine gives `ticket`.
+            input: fromPick(postComment, ({ context }) => ({ ticket: context.ticket })),
+            onDone: "#done",
+          },
+        },
+      },
+    },
+    done: { id: "done", type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**Local**
+
+```ts
+import { z } from "zod";
+import { agent, bearer, defineEvent, fail, fromPick, http, jr2Setup, secret } from "@jr2/orchestrator";
+
+const postComment = defineEvent({
+  name: "post_comment",
+  description: "Post one comment on the ticket.",
+  input: z.object({ body: z.string() }),
+});
+
+// The host is fixed here. No input can change it.
+const comment = http({
+  method: "POST",
+  url: "https://jira.example.com/rest/api/2/issue",
+  auth: bearer(secret("jira")),
+  input: z.object({ ticket: z.string(), body: z.string() }),
+  request: ({ ticket, body }) => ({ path: [ticket, "comment"], json: { body } }),
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: { ticket: string }; input: { ticket: string } },
+  events: [postComment],
+  actors: {
+    triager: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You triage tickets.",
+      workspace: "none",
+    }),
+    comment,
+    fail: fail(),
+  },
+}).createMachine({
+  id: "comment",
+  input: z.object({ ticket: z.string() }),
+  context: ({ input }) => input,
+  on: { "agent.fault": ".failed" },
+  initial: "triaging",
+  states: {
+    triaging: {
+      invoke: {
+        src: "triager",
+        input: ({ context }) => ({ prompt: `Write one comment for ticket ${context.ticket}.` }),
+      },
+      initial: "ready",
+      states: {
+        ready: { on: { post_comment: "posting" } },
+        posting: {
+          invoke: {
+            src: "comment",
+            // The Agent gives `body`. The Machine gives `ticket`.
+            input: fromPick(postComment, ({ context }) => ({ ticket: context.ticket })),
+            onDone: "#done",
+          },
+        },
+      },
+    },
+    done: { id: "done", type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+The body can also be a file of a Worktree: `body: file(path)` (see [`file`](../reference/authoring-surface/file.md)).
+The input then names the Worktree, `{ worktree }`, and a cut must have made it. A path alone does not name the target of
+a credential. The default timeout of an `http` Effect is 30 seconds.
+
+### `push`
+
+[`push`](../reference/authoring-surface/push.md) pushes the branch of a Worktree to the
+[Binding](../reference/glossary.md#binding) of its Repo Slot. Its input names the Worktree, `{ worktree }`, and has no
+branch. jr2 reads the branch from the cut of that path, so an Agent that moves `HEAD` does not change what jr2 pushes.
+It uses the push credential of the `git.credentials` entry that the URL matches (see
+[`git.credentials`](../reference/config.md#git-credentials)). The Agent never reads that credential. These options
+change what a push publishes:
+
+- `pin`: push the commit that the input names, such as a commit that a [Gate](../reference/glossary.md#gate) approved.
+  Without `pin`, jr2 pushes the tip of the Agent's branch when the Effect starts.
+- `sign`: push signed copies of the commits.
+- `squash`: push one commit that holds all the changes, with the message that the input gives.
+- `force`: replace what the remote branch holds.
+
+With `pin`, the input also gives `{ sha }`. With `squash`, it also gives `{ message }`.
+
+After a signed or a squashed push, the commits on the remote are not the Agent's own commits. Then jr2 moves the Agent's
+branch to the published commits. The Agent's files, index and stash do not change. The default timeout is 5 minutes.
+
+### `worktree`
+
+[`worktree()`](../reference/authoring-surface/worktree.md) cuts a Worktree, or reads the one that a cut made at that
+path. Its outcomes are `ready`, `refused` and `unknown`. It runs in the Harness container, and it is idempotent. Each
+thing that an Agent's word can cause is `refused`, and nothing changes. [Workspaces](workspaces.md) tells what a
+Worktree is, and [Cut a Worktree](../guides/cut-a-worktree.md) tells how to use it.
+
+### `dispatch`
+
+[`dispatch`](../reference/authoring-surface/dispatch.md) starts a run of a Workflow. The new run is a run of its own: it
+has its own line in [`jr2 runs`](../reference/cli.md#runs), its own Workspaces and its own `CANCEL`. Its record names
+the run that started it: it is **dispatched by** that run. Use `dispatch` when a Machine waits for work, for example at
+a [Gate](../reference/glossary.md#gate) that a webhook answers, and each item of work needs a run of a Workflow that you
+have. To use a Machine as a part of one run, invoke it in the run instead (see [Composition](composition.md)).
+
+- The name of the Workflow is a constant of the definition, as `jr2 run` writes it: `"triage"`, or `"<wrapper>/<name>"`
+  for a named [Chart](../reference/glossary.md#chart). An Agent cannot choose it.
+- The `input` of the invoke is the run input of the new run: the same JSON that `jr2 run --input` sends. The `input`
+  option of the definition is a zod schema of that run input. It types the invoke, and `jr2 up` compares it with the
+  input that the Workflow declares.
+- By default, the Effect ends when the Orchestrator accepts the new run. With `wait: true`, the Effect ends when the new
+  run ends, and its output holds the status and the output of that run. The default timeout is 30 seconds, and 10
+  minutes with `wait`.
+- With no `target`, the new run starts in the same Orchestrator. With
+  `target: { url: "https://<host>", token: secret("<name>") }`, it starts on a different Orchestrator. `url` is the
+  origin of that Orchestrator, and the secret holds its Instance token.
+- The new run starts under the current [Assembly](../reference/glossary.md#assembly), as a run of `jr2 run` does.
+
+The two runs are independent. A `CANCEL` of one run does not cancel the other. When the run that dispatched ends, the
+new run continues.
+
+## Where an Effect runs
+
+You do not choose where an Effect runs. The kind, and what the Effect names, decide it. Each
+[Effector](../reference/glossary.md#effector) is a container that runs jr2's own process, and the Agent cannot run
+commands in it:
+
+| The Effect                              | Where it runs                                                                       |
+| --------------------------------------- | ----------------------------------------------------------------------------------- |
+| A `command` that names no Effect secret | The [Harness](../reference/glossary.md#harness) container of the Sandbox            |
+| A `worktree()`                          | The Harness container of the Sandbox                                                |
+| A `command` that names an Effect secret | The [Sandbox Effector](../reference/glossary.md#sandbox-effector), against a commit |
+| An `http` Effect                        | The [Instance Effector](../reference/glossary.md#instance-effector)                 |
+| An `http` Effect with a Worktree file   | The Sandbox Effector                                                                |
+| A `push`                                | The Sandbox Effector                                                                |
+| A `dispatch` with no `target`           | The Orchestrator, in its own process                                                |
+| A `dispatch` with a `target`            | The Instance Effector                                                               |
+
+A `command` that names no Effect secret runs beside the Agent's [Working tools](../reference/glossary.md#working-tools).
+It runs as the Agent's user, with the tools of the [Sandbox Image](../reference/glossary.md#sandbox-image). The Harness
+confines it with Landlock, as it confines the Agent's shell. It has the same
+[Stand-ins](../reference/glossary.md#stand-in) as the Agent's shell, and no credential of its own.
+
+A `command` that names an Effect secret in its `env` runs in the Sandbox Effector, a container in which the Agent runs
+nothing. It does not run in the live Worktree. It runs against one commit: the tip of the branch when it starts, or with
+`pin`, the commit that its input names. When the Worktree held changes that the command did not see, its output has
+`dirty: true`.
+
+A `command`, a `worktree()`, a `push` and an `http` Effect with a file body need a Workspace. Invoke them from the body
+of a [`workspace()`](../reference/authoring-surface/workspace.md). [Architecture](architecture.md) tells what each
+Effector is, and [Secrets and trust](secrets-and-trust.md) tells how an Effector holds the Effect secrets.
+
+## Every outcome is output
+
+An Effect gives each outcome to `onDone`, a failure too. Route on the `outcome` field:
+
+| Kind       | The outcomes                                              | The output type                                                           |
+| ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `worktree` | `ready`, `refused`, `unknown`                             | [`WorktreeOutput`](../reference/authoring-surface/type-worktreeoutput.md) |
+| `command`  | `exited`, `timeout`, `killed`, `unknown`                  | [`CommandOutput`](../reference/authoring-surface/type-commandoutput.md)   |
+| `http`     | `response`, `unreachable`, `refused`, `unknown`           | [`HttpOutput`](../reference/authoring-surface/type-httpoutput.md)         |
+| `push`     | `pushed`, `rejected`, `diverged`, `unknown`               | [`PushOutput`](../reference/authoring-surface/type-pushoutput.md)         |
+| `dispatch` | `started`, `settled`, `refused`, `unreachable`, `unknown` | [`DispatchOutput`](../reference/authoring-surface/type-dispatchoutput.md) |
+
+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. An HTTP 4xx or 5xx status is a `response`. A Workflow that refuses the run input of a `dispatch` is `refused`,
+with the status code and the report of the refusal. `unknown` means that jr2 cannot tell what the Effect did.
+
+Each union is open: it holds a stand-in member, `LaterOutcome`, so a later release can add an outcome and your Machine
+still works. Route on what you know, and give the rest a last arm with no guard. With no match, the run stays in that
+state and shows no fault. So `createMachine`, `jr2 check`, `jr2 up` and the Chart door refuse an `onDone` with a guard
+on its last arm. An invoke with no `onDone` is legal: the Effect settles, and the state stays.
+
+The `onError` route of an Effect is only for a defect in the Machine or in the config. For example, the Effect is not in
+a Workspace, or an `arg()` has no value, or an Open part has no binding. An outcome that means that the work did not
+succeed goes to a state that invokes [`fail`](../reference/authoring-surface/fail.md). Then the run ends `failed`, with
+a reason (see [How a run ends](machines-and-workflows.md#how-a-run-ends)). Do not throw to fail: a throw is a defect,
+and the run ends `error`.
+
+## At most once
+
+jr2 writes a record of each Effect before the Effect starts, and saves it with the run's snapshot. When the Effect ends,
+jr2 records its output. After an Orchestrator restart, jr2 reads the record:
+
+- An Effect that ended gives its output. jr2 does not run it again.
+- An Effect that did not start, starts.
+- An Effect that started follows the rule of its kind.
+
+| Kind                                    | After a restart, when the Effect started                                                                                                                     |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A `command` that names no Effect secret | jr2 attaches to it again. When the Harness does not know it, the outcome is `unknown`. It never runs again.                                                  |
+| A `command` that names an Effect secret | jr2 follows it. When the Sandbox Effector lost it, jr2 runs it again against the same commit. With no commit recorded, the outcome is `unknown`.             |
+| A `worktree()`                          | jr2 attaches to it again. When the Harness does not know it, jr2 sends it again: a cut is idempotent.                                                        |
+| A `push`                                | jr2 follows it. When the Sandbox Effector lost it, jr2 pushes the same commit again, and no other commit. With no commit recorded, the outcome is `unknown`. |
+| An `http` Effect                        | jr2 follows it. When no Effector holds it, jr2 sends it again only if it is `idempotent`. Else the outcome is `unknown`.                                     |
+| A `dispatch`                            | jr2 sends the start again, with the same key. The Orchestrator answers with the run that the key started, and it starts no second run.                       |
+
+A `command` that names no Effect secret runs the code of the Worktree, and that code can spend a Stand-in. Thus jr2 does
+not run it two times. A `push`, and a `command` that names an Effect secret, run against a commit that jr2 records. Thus
+jr2 can send them again with that commit.
+
+To try again, write it in the Machine: a route from the outcome back into the state. Mark an `http` Effect `idempotent`
+only when a second call is safe: the call has its own idempotency key, or it only reads.
+
+## When the state exits
+
+When the run leaves the state, the Effect stops:
+
+- jr2 kills the process group of a `command` that names no Effect secret.
+- The Sandbox Effector stops a `command` that names an Effect secret. It sends `SIGTERM`, waits 5 seconds, then sends
+  `SIGKILL`.
+- An `http` Effect and a `push` have no stop. jr2 stops waiting for the output, but the Effector can still finish the
+  work.
+- A `dispatch` with `wait` stops its wait. The run that it started continues.
+
+jr2 records the stop, and the Machine gets no output. There is no "finally" in a Machine: cleanup is a state. Put an
+Effect that must not stop in a state of its own. The only exit of that state is its `onDone`. That state handles the
+events of the states above it.
+
+## From a pick to an Effect
+
+An Agent can start an Effect with a pick. The pick moves the run into a state that invokes the Effect. Three names help
+you write that state. Each one is optional.
+
+- [`fromPick(def, fill)`](../reference/authoring-surface/frompick.md) is the `input` of the state. The params of the
+  pick go into the Effect's input, by name. `fill` gives only the keys that the Machine adds. In `comment.ts`, the Agent
+  gives `body`, and the Machine gives `ticket`. Thus the Agent cannot post on a different ticket. TypeScript checks the
+  sum against the input type of the Effect.
+- [`paramsOf(event, def)`](../reference/authoring-surface/paramsof.md) reads the same params in a plain `input` mapper.
+  Use it when the Machine changes a param before the Effect gets it.
+- [`answer(fn)`](../reference/authoring-surface/answer.md) sets what the Agent reads when jr2 answers its pick. In
+  `test-and-push.ts`, the Agent reads one line, or the end of the test output. Without `answer`, it reads the
+  `CommandOutput` of the command, as JSON. [The Menu](the-menu.md) tells more about `answer`.
+
+While the Effect runs below the Agent's state, the Agent's pick is [outstanding](../reference/glossary.md#outstanding).
+The state is not at [Rest](../reference/glossary.md#rest) until the Effect ends. [The Menu](the-menu.md) tells how a
+pick waits for its answer.
+
+## Rules
+
+- An Effect is a key of `actors`. `createMachine` refuses an Effect that you write directly in an `invoke`.
+- The last arm of an Effect's `onDone` has no guard. `createMachine` refuses one that has:
+  `machine "<id>": state "<state>" (Effect "<slot>") has an onDone with no unguarded last arm — … (ADR-0075)`.
+- A `command`, a `worktree()`, a `push` and an `http` Effect with a file body run only inside a `workspace()`.
+- Under a Workspace with more than one Repo Slot, a `push` names its `slot`.
+- The host of an `http` URL is literal. An Effect secret never goes in the host, the query or the fragment of a URL.
+- Each Effect secret that an Effect names is in the `secrets` list of `jr2.config.ts`, with a value of 8 characters or
+  more. `jr2 up` refuses a name that is not in the list, and a value that is shorter.
+- A `push` with `sign` needs a `sign` field on its `git.credentials` entry. A `squash` without `sign` needs a `sign` or
+  a `committer` field there.
+- Each param of a pick that enters an Effect's state has a reader: the Effect's input, `fill`, a guard or an `assign`.
+  `createMachine` refuses a param that nothing reads, and a `fill` key that is also a param.
+- A packaged Machine can leave an `http` URL, a `command` argv, one Effect secret name or the `target` of a `dispatch`
+  Open. The composer binds it one time with `customize()`. `jr2 up` refuses an Open part that nobody bound.
+- A `dispatch` with no `target` names a Workflow that the Assembly has. `jr2 up` refuses a name that it does not have,
+  and an `input` schema that the input of that Workflow does not take.
+- The `url` of a `dispatch` target is an origin only: a scheme, a host and a port, with no path, no query and no user.
+
+The guides give the refusal text of each rule.
+
+## Read next
+
+- [Run a command or call a URL with an Effect](../guides/run-a-command-or-call-a-url.md)
+- [Push and sign a branch](../guides/push-and-sign-a-branch.md)
+- [Start a run from a run](../guides/start-a-run-from-a-run.md)
+- [Workspaces](workspaces.md), [The Menu](the-menu.md), [Secrets and trust](secrets-and-trust.md)
+- Reference: [`command`](../reference/authoring-surface/command.md), [`http`](../reference/authoring-surface/http.md),
+  [`push`](../reference/authoring-surface/push.md), [`dispatch`](../reference/authoring-surface/dispatch.md),
+  [`fromPick`](../reference/authoring-surface/frompick.md), [`answer`](../reference/authoring-surface/answer.md)
+- [ADR-0067](../reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md):
+  an Effect is an actor slot, and runs at most once unless marked idempotent
+- [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md): an Effector holds
+  an Effect's secrets and signs its wire
+- [ADR-0071](../reference/decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md): a run starts a run through a
+  `dispatch` Effect