@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/reference/authoring-surface/file.md

@@ -9,21 +9,24 @@ Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/or
 
 ```ts
 function file<S extends z.ZodType | undefined = undefined>(path: FromInput<S, string>, options: {
-  slot?: string;
   segments?: FromInput<S, readonly string[]>;
   contentType?: string;
 } = {}): FileBody<S>
 ```
 
 Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`. The Effect
-then runs in the Sandbox Effector of the Workspace whose body invokes it. That Effector opens the
-file in the Worktree and sends it. In a Workspace with no Repo Slot, the path is relative to
+then runs in the Sandbox Effector of the Workspace whose body invokes it. Under a Workspace with
+Repo Slots, the invoke's input names the Worktree: `input: { worktree: "/work/app/fix" }`. It is a
+Worktree that a cut of this run made. That Effector opens the file in that Worktree and sends it.
+In a Workspace with no Repo Slot, the input names no `worktree`, and the path is relative to
 `/work`, the folder that its steps share. Use it with `PUT`, `POST` or `PATCH`. `path` and
 `segments` can be functions of the input of the Effect.
 
-Some paths and files give the output `refused`, and then nothing is sent. The path has a symlink
-in it, has `..`, or is absolute. Or the file is a FIFO, a directory, or a file with more than one
-link.
+Some inputs, paths and files give the output `refused`, and then nothing is sent. The `worktree`
+has no cut in this Sandbox: `no cut made <path> in this Sandbox: cut it with worktree(); nothing
+was sent`. Or the input names a `worktree` in a Workspace with no Repo Slot. Or the path has a
+symlink in it, has `..`, or is absolute. Or the file is a FIFO, a directory, or a file with more
+than one link.
 
 It refuses, when you call it:
 - a path that is not a string or a function: `file(path): the path is a string, or a function of
@@ -43,16 +46,17 @@ And at `jr2 up`, an Effect that no `workspace()` invokes: `workflow "<workflow>"
 there is no Worktree to read; invoke it from a workspace()'s body, or send a json or text body
 (ADR-0068)`.
 
+And when it starts, under a Workspace with Repo Slots, an input with no `worktree`: ``http
+"<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its input names no
+`worktree` ``.
+
 **Parameters**
 
-- `path` ([`FromInput`](type-frominput.md)): The file, relative to the Worktree of the Repo Slot, or to `/work` in a Workspace
-  with no Repo Slot: a string, or a function of the input of the Effect that gives one.
+- `path` ([`FromInput`](type-frominput.md)): The file, relative to the Worktree that `worktree` of the input names, or to
+  `/work` in a Workspace with no Repo Slot: a string, or a function of the input of the Effect
+  that gives one.
 - `options`: Optional. Each field says what it does.
 
-  - `slot` (optional): `string`
-
-    The Repo Slot whose Worktree holds the file. Write it only when the Workspace has more than
-    one.
   - `segments` (optional): `FromInput<S, readonly string[]>`
 
     Path segments that jr2 adds to the end of the url, as `path` does in `request` for a json or
@@ -73,17 +77,22 @@ import {
   fail,
   file,
   http,
+  isReady,
   jr2Setup,
   secret,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
 type Input = Workspaced<{}, "app">;
 
+const reportTree = (context: Input) => `${context.workspace.repos.app}/report` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   actors: {
+    cut: worktree(),
     build: command(["npm", "run", "report"]),
     upload: http({
       method: "PUT",
@@ -100,18 +109,29 @@ const body = jr2Setup({
   id: "report",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "building",
+  initial: "cutting",
   states: {
-    building: { invoke: { src: "build", onDone: "uploading" } },
-    uploading: { invoke: { src: "upload", onDone: "done" } },
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reportTree(context), branch: "report" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+      },
+    },
+    building: {
+      invoke: { src: "build", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "uploading" },
+    },
+    uploading: {
+      invoke: { src: "upload", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "done" },
+    },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "report" }),
 });
 ```
 

package/docs/reference/authoring-surface/http.md

@@ -7,6 +7,8 @@ description: "Make an `http` Effect: a call to a URL, with Effect secrets that t
 
 Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
 
+## Overload 1
+
 ```ts
 function http<
   S extends z.ZodType | undefined = undefined,
@@ -14,8 +16,8 @@ function http<
   const A extends HttpDefinition<S>["auth"] = undefined,
   const H extends HttpDefinition<S>["headers"] = undefined,
 >(
-  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H },
-): EffectLogic<HttpInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
+  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H; body: FileBody<S> },
+): EffectLogic<HttpFileInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
 ```
 
 Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads. Put it
@@ -23,8 +25,9 @@ in `actors`, and invoke it by its key: `actors: { comment: http({ ... }) }`, the
 src: "comment" }`.
 
 It runs in the Instance Effector, which `jr2 up` deploys when a Machine has an `http` Effect.
-With `body: file(...)`, it runs in the Sandbox Effector of the Workspace whose body invokes it.
-The Effector makes the call. The Orchestrator holds no secret.
+With `body: file(...)`, it runs in the Sandbox Effector of the Workspace whose body invokes it,
+and under Repo Slots its input names the Worktree in `worktree`. The Effector makes the call. The
+Orchestrator holds no secret.
 
 Every outcome is output (`HttpOutput`): `response`, `unreachable`, `refused` or `unknown`. A 4xx
 or 5xx status is output too. jr2 sends the call at most one time, unless you mark it
@@ -91,12 +94,15 @@ customize() share: actors: { <name>: http(...) }, then invoke: { src: "<name>" }
     A function that makes the part of the request that changes for each run, from the input:
     `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
     Effect secret. Do not write it beside `body`.
-  - `body` (optional): `FileBody<S>`
+  - `body`: `FileBody<S>`
 
-    A Worktree file as the body: `file(path, { slot?, segments?, contentType? })`. The Effect then
-    runs in the Sandbox Effector of its Workspace. Do not write `request` beside it: the `segments`
+    A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+    runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+    input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+    it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+    input names no `worktree` ``. Do not write `request` beside it: the `segments`
     of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
-    slot?, segments?, contentType? }) — json and text come from `request` ``.
+    segments?, contentType? }) — json and text come from `request` ``.
   - `timeout` (optional): [`Duration`](type-duration.md)
 
     How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
@@ -157,3 +163,97 @@ export const machine = jr2Setup({
 - [Secrets and trust](../../concepts/secrets-and-trust.md)
 - [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
 - [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)
+
+## Overload 2
+
+```ts
+function http<
+  S extends z.ZodType | undefined = undefined,
+  const U extends HttpDefinition<S>["url"] = string,
+  const A extends HttpDefinition<S>["auth"] = undefined,
+  const H extends HttpDefinition<S>["headers"] = undefined,
+>(
+  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H },
+): EffectLogic<HttpInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
+```
+
+**Parameters**
+
+- `def`
+
+  - `method`: [`HttpMethod`](type-httpmethod.md)
+
+    The HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. It refuses
+    another: `http({ method: "<method>" }): the method is one of GET, HEAD, POST, PUT, PATCH,
+    DELETE, OPTIONS`.
+  - `url`: `string | Text | typeof open`
+
+    The url: `http://` or `https://`, then a literal host. No input, param or Effect secret can
+    change where the call goes. An Effect secret can be only in the path:
+    `` text`https://api.telegram.org/bot${secret("tg")}/sendMessage` ``.
+
+    Or `open`: a packaged Machine that cannot know the host leaves the url Open, and the composer
+    binds it one time with `customize(machine, { effects: { <slot>: { url } } })`.
+
+    It refuses:
+    - a scheme or host that is not literal: `` http({ url }): the url is an http:// or https:// url
+      whose scheme and host are literal — a secret may sit only in its path, after a "/":
+      text`https://api.example.com/bot${secret("tg")}/send` (ADR-0068) ``
+    - an Effect secret after `?` or `#`: `` http({ url }): secret("<name>") sits in the url's query
+      or fragment — a secret may sit only in its path; send it in `auth` or a header instead:
+      headers: { "x-api-key": text`${secret("...")}` } (ADR-0068) ``
+    - a host that is not a host: `http({ url }): "<scheme>://<host>" is not a host`
+    - a user name or password in the url: ``http({ url }): the url carries userinfo — use `auth` ``
+  - `headers` (optional): `Readonly<Record<string, string | Text>>`
+
+    Headers that are the same for each run. Each name is lowercase. A value is a string, or a
+    `text` with an Effect secret.
+
+    It refuses:
+    - a name that is not lowercase, or that frames or routes the request (`host`,
+      `content-length`, `transfer-encoding`, `connection`, `upgrade`, `te`, `trailer`,
+      `keep-alive`, `proxy-*`): `http({ headers }): "<name>" is not a header an Effect sets — a
+      lowercase name that does not frame or route the request (ADR-0068)`
+    - an `authorization` header beside `auth`: ``http({ headers }): "authorization" is set by
+      `auth` — write one of them``
+  - `auth` (optional): `{ readonly bearer: Secret; } | { readonly basic: { user: Text; password: Text; }; } | Text`
+
+    The `Authorization` header: `bearer(secret("x"))`, `basic(user, password)`, or a `text` that
+    is the whole value.
+  - `input` (optional): `S`
+
+    The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+    gives it. jr2 parses the input with it before the call. When it starts, input that does not
+    agree with it makes the Effect fail (its `onError` route): `http "<slot>": its input does not
+    match the definition's input schema — <path>: <message>`, one `<path>: <message>` for each
+    problem, joined by `; `.
+  - `request` (optional): `(input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts`
+
+    A function that makes the part of the request that changes for each run, from the input:
+    `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
+    Effect secret. Do not write it beside `body`.
+  - `body` (optional): `FileBody<S>`
+
+    A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+    runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+    input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+    it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+    input names no `worktree` ``. Do not write `request` beside it: the `segments`
+    of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
+    segments?, contentType? }) — json and text come from `request` ``.
+  - `timeout` (optional): [`Duration`](type-duration.md)
+
+    How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
+    `"30s"`. With no answer in that time, the output is `unknown`. It refuses a value that is not
+    a positive duration: `http: timeout "<timeout>" is not a positive duration (like "30s",
+    "2m")`.
+  - `maxBody` (optional): `number`
+
+    The largest number of bytes of a text response body that the output keeps. Default 65536.
+    When jr2 cuts the body, `truncated` is `true`. It refuses a value that is not a positive whole
+    number: `http({ maxBody }): a positive number of bytes`.
+  - `idempotent` (optional): `boolean`
+
+    `true` when it is safe to send the call two times: it has its own idempotency key, or it only
+    reads. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the call went
+    out. Then it sends an idempotent call again, and gives any other call the output `unknown`.

package/docs/reference/authoring-surface/isready.md

@@ -0,0 +1,14 @@
+---
+title: isReady
+description: Is it `ready`?
+---
+
+# `isReady`
+
+Constant, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+const isReady: <O extends { outcome: string; }>(output: O) => output is Extract<O, { outcome: "ready"; }>
+```
+
+Is it `ready`? For a guard. A Chart's form is the guard `jr2.ready`.

package/docs/reference/authoring-surface/jr2setup.md

@@ -60,7 +60,7 @@ function jr2Setup<
 ): SetupReturn<
   TContext,
   WorkflowEvent<TDefs>,
-  MergedActors<TActors>,
+  MergedActors<BindActors<TActors, TInput, TContext>>,
   {},
   TActions,
   TGuards & SentByGuards,

package/docs/reference/authoring-surface/open.md

@@ -28,7 +28,18 @@ Open part.
 
 ```ts
 import { z } from "zod";
-import { agent, customize, defineEvent, fail, jr2Setup, open, workspace } from "@jr2/orchestrator";
+import {
+  agent,
+  customize,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  open,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 const finish = defineEvent({
   name: "finish",
@@ -36,19 +47,40 @@ const finish = defineEvent({
   input: z.object({}),
 });
 
+type Input = Workspaced<{}, "app">;
+
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
   events: [finish],
-  actors: { coder: agent({ model: open, instructions: "You fix the failing test." }), fail: fail() },
+  actors: {
+    coder: agent({ model: open, instructions: "You fix the failing test." }),
+    cut: worktree(),
+    fail: fail(),
+  },
 }).createMachine({
   id: "fix",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "jr2/fix" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
-      invoke: { src: "coder", input: { prompt: "Make `node --test` pass." } },
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: "Make `node --test` pass.", cwd: fixTree(context) }),
+      },
       on: { finish: "done" },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -57,7 +89,6 @@ const body = jr2Setup({
 // What a package exports: the repository and the model are Open.
 export const fix = workspace(body, {
   repos: { app: open },
-  spec: () => ({ branch: "jr2/fix" }),
 });
 
 // What an Instance's `workflows/fix.ts` exports: the same Machine, its Open parts bound.

package/docs/reference/authoring-surface/paramsof.md

@@ -50,9 +50,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   paramsOf,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
@@ -70,6 +72,8 @@ const finished = defineEvent({
 
 type Input = Workspaced<{}, "app">;
 
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   events: [runTest, finished],
@@ -78,6 +82,7 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer.",
     }),
+    cut: worktree(),
     test: command(["node", "--test", arg("file")]),
     fail: fail(),
   },
@@ -85,12 +90,22 @@ const body = jr2Setup({
   id: "fix-tests",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "fix-tests" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: { prompt: "Make the tests pass. Run the tests of one module at a time." },
+        input: ({ context }) => ({
+          prompt: "Make the tests pass. Run the tests of one module at a time.",
+          cwd: fixTree(context),
+        }),
       },
       on: { finished: "done" },
       initial: "ready",
@@ -100,13 +115,17 @@ const body = jr2Setup({
           invoke: {
             src: "test",
             // A plain mapper: the Machine makes the file name from the pick's `module`.
-            input: ({ event }) => ({ file: `test/${paramsOf(event, runTest).module}.test.js` }),
+            input: ({ context, event }) => ({
+              file: `test/${paramsOf(event, runTest).module}.test.js`,
+              worktree: fixTree(context),
+            }),
             onDone: "ready",
           },
         },
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -114,7 +133,6 @@ const body = jr2Setup({
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "fix-tests" }),
 });
 ```
 

package/docs/reference/authoring-surface/pool.md

@@ -51,7 +51,7 @@ its own.
     The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
     `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
     none, and then their `input` is `unknown`.
-  - `source`: `SourceSpec<T>`
+  - `source`: `SourceSpec<T, TInput> | SourceSpec<T>`
 
     Where the items come from. Make it with [`source`](source.md).
   - `itemId`: `(item: T) => string`
@@ -83,7 +83,7 @@ its own.
 
 ```ts
 import { fromPromise } from "xstate";
-import { customize, pool, source } from "@jr2/orchestrator";
+import { customize, pool, source, type PoolNextInput } from "@jr2/orchestrator";
 import { task } from "@jr2/machines";
 
 type Issue = { id: string; title: string };
@@ -94,7 +94,7 @@ const backlog: Issue[] = [
 ];
 
 const issues = source<Issue>({
-  next: fromPromise(async ({ input }: { input: { active: string[] } }) => {
+  next: fromPromise(async ({ input }: { input: PoolNextInput }) => {
     const issue = backlog.find((i) => !input.active.includes(i.id)) ?? null;
     if (issue) backlog.splice(backlog.indexOf(issue), 1);
     return issue;
@@ -151,7 +151,7 @@ an example.
     The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
     `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
     none, and then their `input` is `unknown`.
-  - `source`: `SourceSpec<T>`
+  - `source`: `SourceSpec<T, TInput> | SourceSpec<T>`
 
     Where the items come from. Make it with [`source`](source.md).
   - `itemId`: `(item: T) => string`

package/docs/reference/authoring-surface/push.md

@@ -1,6 +1,6 @@
 ---
 title: push
-description: "Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot."
+description: "Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot."
 ---
 
 # `push`
@@ -8,17 +8,16 @@ description: "Make a `push` Effect: it pushes the branch of the Workspace to the
 Function, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
 
 ```ts
-function push<
-  const O extends PushOptions,
->(
-  options?: O,
-): EffectLogic<PushInput<O> | void, PushOutput>
+function push<const O extends PushOptions>(options?: O): EffectLogic<PushInput<O>, PushOutput>
 ```
 
-Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
+Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot.
 Put it in `actors`, and invoke it from the body of a `workspace()`: `actors: { publish: push({
 sign: true }) }`.
 
+Its input names the Worktree: `{ worktree }`. It has no branch. jr2 reads the branch from the
+`worktree()` cut of that path, so an Agent that moves `HEAD` does not change what jr2 pushes.
+
 It runs in the Sandbox Effector of the Workspace, with the push credential of the
 `git.credentials` entry that the Binding matches. The Agent never reads that credential. It
 pushes one commit: the tip of the Agent's branch when the Effect starts, or, with `pin`, the
@@ -26,8 +25,10 @@ commit that the input names. After an Orchestrator restart, jr2 pushes only that
 again. With `sign` or `squash`, the commit on the remote is not the Agent's own. Then jr2 moves
 the Agent's branch to it.
 
-Every outcome is output (`PushOutput`): `pushed`, `rejected`, `diverged` or `unknown`. Each
-field of [`PushOptions`](type-pushoptions.md) tells what it refuses. When it starts, it also refuses a push
+Every outcome is output (`PushOutput`): `pushed`, `rejected`, `diverged` or `unknown`. A
+`worktree` that no cut made in this Sandbox, a Worktree of another Repo Slot, and a detached
+Worktree are `rejected` at `stage` `start`, and nothing is pushed. Each field of
+[`PushOptions`](type-pushoptions.md) tells what it refuses. When it starts, it also refuses a push
 outside a Workspace: `push "<slot>" runs in the Sandbox Effector of a Workspace, and its state is
 not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`.
 
@@ -45,9 +46,11 @@ import {
   agent,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
@@ -59,6 +62,8 @@ const committed = defineEvent({
 
 type Input = Workspaced<{}, "app">;
 
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   events: [committed],
@@ -67,6 +72,7 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer.",
     }),
+    cut: worktree(),
     publish: push({ sign: true }),
     fail: fail(),
   },
@@ -74,10 +80,20 @@ const body = jr2Setup({
   id: "fix-test",
   context: ({ input }) => input,
   on: { "workspace.lost": ".failed", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "fix-test" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
-      invoke: { src: "coder", input: { prompt: "Fix the failing test, and commit the fix." } },
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: "Fix the failing test, and commit the fix.", cwd: fixTree(context) }),
+      },
       // The Agent moves the Machine on with a pick. An Agent's actor never ends, so `onDone`
       // never fires.
       on: { committed: "publishing" },
@@ -85,6 +101,8 @@ const body = jr2Setup({
     publishing: {
       invoke: {
         src: "publish",
+        // jr2 reads the branch from the cut of this Worktree.
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "pushed", target: "done" },
           { target: "failed" },
@@ -92,6 +110,7 @@ const body = jr2Setup({
       },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
     failed: { invoke: { src: "fail", input: { reason: "the fix was not pushed" } } },
   },
@@ -99,7 +118,6 @@ const body = jr2Setup({
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "fix-test" }),
 });
 ```
 

package/docs/reference/authoring-surface/readyof.md

@@ -0,0 +1,21 @@
+---
+title: readyOf
+description: The `ready` output of an `onDone` arm that `isReady` guards.
+---
+
+# `readyOf`
+
+Function, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function readyOf<O extends { outcome: string }>(output: O): Extract<O, { outcome: "ready" }>
+```
+
+The `ready` output of an `onDone` arm that `isReady` guards. xstate carries no guard's narrowing
+to its actions, so an `assign` reads the output through this.
+
+**Parameters**
+
+- `output`
+
+  - `outcome`: `string`

package/docs/reference/authoring-surface/secret.md

@@ -56,13 +56,25 @@ And at `jr2 up`:
 **Example**
 
 ```ts
-import { command, fail, jr2Setup, secret, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  command,
+  fail,
+  isReady,
+  jr2Setup,
+  secret,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 type Input = Workspaced<{}, "app">;
 
+const deployTree = (context: Input) => `${context.workspace.repos.app}/deploy` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   actors: {
+    cut: worktree(),
     // The command reads the file at $KUBECONFIG. The Agent never reads the secret.
     deploy: command(["kubectl", "apply", "-f", "k8s/"], {
       env: { KUBECONFIG: secret("kube").path },
@@ -73,17 +85,26 @@ const body = jr2Setup({
   id: "deploy",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "deploying",
+  initial: "cutting",
   states: {
-    deploying: { invoke: { src: "deploy", onDone: "done" } },
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: deployTree(context), branch: "deploy" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "deploying" }, { target: "notCut" }],
+      },
+    },
+    deploying: {
+      invoke: { src: "deploy", input: ({ context }) => ({ worktree: deployTree(context) }), onDone: "done" },
+    },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "deploy" }),
 });
 ```