@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/concepts/effects.md

@@ -7,9 +7,10 @@ description: How a Machine runs a command, calls a URL, pushes a branch or start
 
 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 Workspace's branch, and `dispatch` starts a run of a
-[Workflow](../reference/glossary.md#workflow). You write an Effect as an actor slot, beside the
-[Agents](../reference/glossary.md#agent) of the Machine.
+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
 
@@ -26,8 +27,8 @@ two times. A plain [xstate](https://xstate.js.org) promise has no such record.
 
 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, and it can ask for a test run with the pick `run_tests`. When the Agent picks `finished`, the Machine pushes
-the branch:
+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**
 
@@ -39,9 +40,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -61,6 +64,9 @@ const finished = defineEvent({
 const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the coder, 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({
@@ -71,7 +77,8 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer. You commit your work on the branch.",
     }),
-    // Two Effects. Each is an actor slot, beside the Agent.
+    // Three Effects. Each is an actor slot, beside the Agent.
+    cut: worktree(),
     tests: command(["node", "--test"], { timeout: "5m" }),
     publish: push(),
     fail: fail(),
@@ -80,12 +87,20 @@ const body = jr2Setup({
   id: "test-and-push",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: 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: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: appTree(context) }),
       },
       on: { finished: "publishing" },
       initial: "ready",
@@ -94,6 +109,7 @@ const body = jr2Setup({
         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.
@@ -110,10 +126,12 @@ const body = jr2Setup({
     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" } } },
@@ -125,7 +143,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -139,9 +156,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -161,6 +180,9 @@ const finished = defineEvent({
 const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the coder, 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({
@@ -171,7 +193,8 @@ const body = jr2Setup({
       model: "local/qwen3.6-35b-a3b",
       instructions: "You are a careful engineer. You commit your work on the branch.",
     }),
-    // Two Effects. Each is an actor slot, beside the Agent.
+    // Three Effects. Each is an actor slot, beside the Agent.
+    cut: worktree(),
     tests: command(["node", "--test"], { timeout: "5m" }),
     publish: push(),
     fail: fail(),
@@ -180,12 +203,20 @@ const body = jr2Setup({
   id: "test-and-push",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: 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: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: appTree(context) }),
       },
       on: { finished: "publishing" },
       initial: "ready",
@@ -194,6 +225,7 @@ const body = jr2Setup({
         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.
@@ -210,10 +242,12 @@ const body = jr2Setup({
     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" } } },
@@ -225,7 +259,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -242,6 +275,7 @@ 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
 ```
@@ -253,6 +287,7 @@ 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
@@ -268,10 +303,9 @@ argument that the input of the Effect fills. Thus an Agent's text cannot become
 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.
 
-A `command` uses the [Worktree](../reference/glossary.md#worktree) of one
-[Repo Slot](../reference/glossary.md#repo-slot): the only slot, or the slot that its `slot` option names. 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.
+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`
 
@@ -413,15 +447,18 @@ export const machine = jr2Setup({
 });
 ```
 
-The body can also be a file of the Worktree: `body: file(path)` (see [`file`](../reference/authoring-surface/file.md)).
-The default timeout of an `http` Effect is 30 seconds.
+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 Workspace's branch to the
-[Binding](../reference/glossary.md#binding) of its Repo Slot. 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:
+[`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.
@@ -429,11 +466,18 @@ credential. These options change what a push publishes:
 - `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 gives `{ sha }`. With `squash`, it gives `{ message }`.
+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
@@ -467,6 +511,7 @@ 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                                                                |
@@ -475,17 +520,18 @@ commands in it:
 | 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). It has the
-same [Stand-ins](../reference/glossary.md#stand-in) as the Agent's shell, and no credential of its own.
+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 `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.
+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
 
@@ -493,6 +539,7 @@ An Effect gives each outcome to `onDone`, a failure too. Route on the `outcome`
 
 | 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)         |
@@ -502,6 +549,11 @@ A test that fails is `exited` with a code that is not 0. A program that the cont
 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
@@ -521,6 +573,7 @@ jr2 records its output. After an Orchestrator restart, jr2 reads the record:
 | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 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.                       |
@@ -569,8 +622,10 @@ pick waits for its answer.
 ## Rules
 
 - An Effect is a key of `actors`. `createMachine` refuses an Effect that you write directly in an `invoke`.
-- A `command`, 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 `command`, a `push` and a file body name their slot.
+- 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.

package/docs/concepts/machines-and-workflows.md

@@ -143,6 +143,13 @@ has a door of its own. It does not use the door of the Machine inside it, becaus
 item. Thus the wrapper declares the door, with its `input` option. `workspace()` refuses a body that has a zod `input`,
 also a body that `setup()` made.
 
+A `workspace()` that a parent Machine invokes parses its door too, before it makes a pod. When the parent passes less
+than the door requires, the invoke fails with `workspace input invalid, before any pod: <zod message>`, and the parent's
+`onError` takes it. This is a defect of the parent, so no pod is spent on it. The body gets the parsed value, as it does
+on a root run: defaults are applied and unknown keys are removed. A `pool()` with a door does the same, and its error
+starts `pool input invalid, before any worker`. The door of a plain child Machine is a type, and nothing parses it at
+run time.
+
 ## The Vocabulary
 
 The Vocabulary of a Machine is the list of the workflow events that it takes. Each event comes from
@@ -253,6 +260,8 @@ moves a Machine.
 - A payload schema is a flat `z.object`, and it has no `sender` field. jr2 writes `sender` on each event that a party
   sends.
 - When a Machine declares a door, the Orchestrator refuses a start whose input does not agree with it.
+- A `workspace()` or a `pool()` under a parent parses its door before it makes a pod. An input that does not agree fails
+  the invoke.
 - The body of a `workspace()` declares no door. `workspace()` refuses a body that declares one.
 - The output of a run is the root `output` of its Machine. jr2 refuses an `output` on a final state directly below the
   root when the root has no `output`.

package/docs/concepts/pools-and-sources.md

@@ -31,7 +31,7 @@ example runs with no model. A worker is usually a Machine with an [Agent](../ref
 ```ts
 import { assign, fromPromise } from "xstate";
 import { z } from "zod";
-import { defineEvent, jr2Setup, pool, source } from "@jr2/orchestrator";
+import { defineEvent, jr2Setup, pool, source, type PoolNextInput } from "@jr2/orchestrator";
 
 type Ticket = { id: string; title: string; needs: string[] };
 
@@ -50,7 +50,7 @@ const claimed = new Set<string>();
 
 // The Source: give the next ready ticket, or say how many tickets are not ready.
 const tickets = source<Ticket>({
-  next: fromPromise(async ({ input }: { input: { active: string[] } }) => {
+  next: fromPromise(async ({ input }: { input: PoolNextInput }) => {
     const done = (id: string) => claimed.has(id) && !input.active.includes(id);
     const waiting = backlog.filter((t) => !claimed.has(t.id));
     const ready = waiting.find((t) => t.needs.every(done));
@@ -180,8 +180,9 @@ A Pool is a Machine. It can be the root of a Workflow, or a different Machine ca
 [`source(spec)`](../reference/authoring-surface/source.md) declares where a Pool gets its items. A Source has three
 parts ([`SourceSpec`](../reference/authoring-surface/type-sourcespec.md)):
 
-- `next`: an [xstate](https://xstate.js.org) promise actor that claims the next ready item. Its input is `{ active }`,
-  the ids of the items that workers have now.
+- `next`: an [xstate](https://xstate.js.org) promise actor that claims the next ready item. Its input is
+  `{ active, settled, input }`: the ids of the items that workers have now, the ids of the finished and failed items,
+  and the input of the Pool. Thus a Source can fan out over a plan with no state of its own.
 - `wake`: an optional event, made with [`defineEvent`](../reference/authoring-surface/defineevent.md), that tells the
   Pool that new work is ready.
 - `pollEvery`: an optional time in milliseconds. While the Pool waits, it calls `next` again at this interval.
@@ -211,8 +212,7 @@ the issue tracker.
 
 - `itemId` gives each item an id of its own, and the same id each time. The Pool uses it as the id of the worker and as
   the key in `items`.
-- `next` must not give an item that a worker has now, or an item that a worker finished. The Pool gives `next` the
-  active ids only. Your Source keeps the finished items.
+- `next` must not give an item in `active` or in `settled`.
 - `cap` is a number, or a function of the run input. Without `cap`, one worker runs at a time.
 - `onDrained` takes only `"final"`: the run ends.
 - The Pool calls `next` again on `wake` or after `pollEvery` only while it waits: workers run and no item is ready.