@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/reference/authoring-surface/type-permissiveworkspaceoptions.md

@@ -10,23 +10,18 @@ Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a
 ```ts
 type PermissiveWorkspaceOptions<TSlots extends string, TInput = unknown> = SandboxOptions<TSlots, TInput> & {
   input?: never;
-  spec: (args: { input: TInput }) => WorkspaceSpec;
 };
 ```
 
-The options of a `workspace()` with no `input`: it starts with any input. The `input` of `spec`
-is then `unknown`, and `spec` must check it before it reads a field.
+The options of a `workspace()` with no `input`: it starts with any input. The `input` of a
+per-run Repo Slot is then `unknown`, and the mapper must check it before it reads a field.
 
-Use it for a Workspace that a Pool or another Machine starts. Give the parameter of `spec` a
-type to say what that input is: `spec: ({ input }: { input: Item }) => …`. That also types the
-input of the Workspace. For a Workspace that a caller starts, declare `input`.
+Use it for a Workspace that a Pool or another Machine starts. The body's `input` type says what
+that input is, and that also types the input of the Workspace. For a Workspace that a caller
+starts, declare `input`.
 
 **Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), and these:
 
 - `input` (optional): `never`
 
   Not present: a `workspace()` without `input` starts with any input.
-- `spec`: `(args: { input: TInput; }) => WorkspaceSpec`
-
-  A function from the input to the Workspace's [`WorkspaceSpec`](type-workspacespec.md). Its `input` is
-  `unknown` unless you give the parameter a type: `spec: ({ input }: { input: Item }) => …`.

package/docs/reference/authoring-surface/type-poolnextinput.md

@@ -0,0 +1,22 @@
+---
+title: PoolNextInput
+description: "The input of a Source's `next`: the ids of the items that workers have now, the ids of the items that settled, and the Pool's input."
+---
+
+# `PoolNextInput`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+type PoolNextInput<TInput = unknown> = { active: string[]; settled: string[]; input: TInput };
+```
+
+The input of a Source's `next`: the ids of the items that workers have now, the ids of the items
+that settled, and the Pool's input. So a Source over a list that a Machine holds needs no state
+of its own.
+
+**Fields**
+
+- `active`: `string[]`
+- `settled`: `string[]`
+- `input`: `TInput`

package/docs/reference/authoring-surface/type-poolspec.md

@@ -11,7 +11,7 @@ Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type
 type PoolSpec<T, TInput = unknown> = {
   id?: string;
   input?: z.ZodObject;
-  source: SourceSpec<T>;
+  source: SourceSpec<T, TInput> | SourceSpec<T>;
   itemId: (item: T) => string;
   cap?: number | ((args: { input: TInput }) => number);
   itemInput?: (item: T, args: { input: TInput }) => unknown;
@@ -33,7 +33,7 @@ each worker gets.
   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/type-pushinput.md

@@ -1,6 +1,6 @@
 ---
 title: PushInput
-description: "The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`."
+description: "The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and `{ message }` with `squash`."
 ---
 
 # `PushInput`
@@ -8,8 +8,27 @@ description: "The input of a `push` Effect: `{ sha }` with `pin`, and `{ message
 Type, in `@jr2/orchestrator/src/sandbox-effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
 
 ```ts
-type PushInput<O extends PushOptions> = (O["pin"] extends true ? { sha: string } : unknown) &
+type PushInput<O extends PushOptions> = {
+  worktree: O extends { slot: infer S extends string } ? `/work/${S}/${string}` : AnyWorktreePath;
+  branch?: never;
+  to?: never;
+  cwd?: never;
+  path?: never;
+} & (O["pin"] extends true ? { sha: string } : unknown) &
   (O["squash"] extends true ? { message: string } : unknown);
 ```
 
-The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`.
+The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and
+`{ message }` with `squash`. It names no branch: jr2 reads it from the cut's record, so no word of
+a Chart reaches a remote branch. The other keys are refused by name, because each is a key of a
+cut or a Turn, and a mapper's excess key is no compile error otherwise.
+
+**Fields**
+
+- `worktree`: ``O extends { slot: infer S extends string; } ? `/work/${S}/${string}` : AnyWorktreePath``
+
+  The Worktree to push: `event.output.path` of its cut, of the push's Repo Slot.
+- `branch` (optional): `never`
+- `to` (optional): `never`
+- `cwd` (optional): `never`
+- `path` (optional): `never`

package/docs/reference/authoring-surface/type-pushoutput.md

@@ -10,7 +10,8 @@ Type, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is an export of `@jr2/orc
 ```ts
 type PushOutput =
   | Exclude<PushWireOutput, { outcome: "pushed" }>
-  | (Omit<Extract<PushWireOutput, { outcome: "pushed" }>, "bundle"> & { sync: SyncState; syncReason?: string });
+  | (Omit<Extract<PushWireOutput, { outcome: "pushed" }>, "bundle"> & { sync: SyncState; syncReason?: string })
+  | LaterOutcome;
 ```
 
 The output of a `push` Effect: what the `onDone` of its state gets as `event.output`. Every
@@ -40,6 +41,8 @@ Beside `pushed`, `sync` tells what jr2 did to the Agent's branch after the push:
 
 With `busy` or `not-synced`, `syncReason` tells why, and jr2 tries again before the next push.
 
+The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+
 **Forms**: it is one of these objects.
 
 - Form 1: `outcome`, `stage`, `reason`, `detail`
@@ -70,13 +73,28 @@ With `busy` or `not-synced`, `syncReason` tells why, and jr2 tries again before
   - `squashed` (optional): `"signed" | "unsigned"`
   - `sync`: [`SyncState`](type-syncstate.md)
   - `syncReason` (optional): `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **Example**
 
 ```ts
-import { fail, jr2Setup, push, type PushOutput, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  type PushOutput,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+type Input = Workspaced<{ branch: string; sha: string }, "app">;
 
-type Input = Workspaced<{ sha: string }, "app">;
+const releaseTree = (context: Input) => `${context.workspace.repos.app}/release` as const;
 
 // A push that did not happen (`rejected` or `diverged`) is a different problem from one jr2
 // cannot see (`unknown`).
@@ -85,17 +103,24 @@ const notPushed = (output: PushOutput): boolean =>
 
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
-  actors: { publish: push({ pin: true }), fail: fail() },
+  actors: { cut: worktree({ expect: "existing" }), publish: push({ pin: true }), fail: fail() },
 }).createMachine({
   id: "release",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "publishing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: releaseTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "publishing" }, { target: "notCut" }],
+      },
+    },
     publishing: {
       invoke: {
         src: "publish",
-        input: ({ context }) => ({ sha: context.sha }),
+        input: ({ context }) => ({ worktree: releaseTree(context), sha: context.sha }),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "pushed", target: "published" },
           { guard: ({ event }) => notPushed(event.output), target: "notPushed" },
@@ -107,13 +132,13 @@ const body = jr2Setup({
     // Not final states: each one fails the run, with its own reason.
     notPushed: { invoke: { src: "fail", input: { reason: "the remote refused the push" } } },
     unknown: { invoke: { src: "fail", input: { reason: "jr2 cannot tell if the push happened" } } },
+    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: "release" }),
 });
 ```
 

package/docs/reference/authoring-surface/type-reposlot.md

@@ -24,10 +24,11 @@ The value of one Repo Slot in `workspace({ repos })`. One of:
 - a function of the run input, `({ input }) => url` or a [`Binding`](type-binding.md): each run chooses. The
   url must match an entry of `git.credentials` in `jr2.config.ts`, or the run cannot use it.
 
-The key of the slot is a directory name under `/work`. It starts with a letter, and
-`workspace()` and `customize()` refuse a key that does not: ``<where>: Repo Slot key "<key>" is
-not a directory name — a slot becomes `/work/<slot>` and its order matters, so it starts with a
-letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).`` They refuse a value of another
+The key of the slot is a directory name under `/work`. It starts with a letter, so never with
+`.`: `/work/.jr2/` is reserved for jr2. `workspace()` and `customize()` refuse a key that does
+not: ``<where>: Repo Slot key "<key>" 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).`` They refuse a value of another
 shape: ``<where>: Repo Slot "<slot>" is <what> — a slot is `open`, a url, `{ url, ref? }`, or a
 mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
 
@@ -58,7 +59,6 @@ export const deploy = workspace(body, {
     docs: "https://github.com/you/docs.git",
     config: open,
   },
-  spec: ({ input }) => ({ branch: `deploy/${input.service}` }),
 });
 ```
 

package/docs/reference/authoring-surface/type-sandboxoptions.md

@@ -10,6 +10,7 @@ Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a
 ```ts
 type SandboxOptions<TSlots extends string, TInput = unknown> = {
   image?: string;
+  workGroup?: number;
   user?: string | UserContainer;
   resources?: Size;
   repos: Record<TSlots, RepoSlot<TInput>> | typeof open;
@@ -30,6 +31,9 @@ clones. They are the same for each run.
   (`import.meta.resolve("./image")`), which `jr2 up` builds, or a registry ref. Its floor is
   glibc and git; jr2 adds its own runtime at `/opt/jr2`. Default: the Instance's
   `images/default`, then jr2's Harness image.
+- `workGroup` (optional): `number`
+
+  The group id that owns the files in `/work`. Default: 2000. A non-negative integer.
 - `user` (optional): `string | UserContainer`
 
   The User Container: a third container in the Sandbox, for a service that must run beside the
@@ -52,8 +56,8 @@ clones. They are the same for each run.
   choice. The name is the key of `workspace.repos` in the body and the directory under `/work`.
   At least one slot. Leave `repos` out for a Workspace with no Repo Slot (see
   [`NoSlotWorkspaceOptions`](type-noslotworkspaceoptions.md)). Each value is one of:
-  - a url, or `{ url, ref }`, where `ref` is the branch or commit that the Worktree starts from
-    (default: the Repo's default branch);
+  - a url, or `{ url, ref }`, where `ref` is the branch, the tag or the commit that the clone
+    stays on, and that a new branch starts from (default: the Repo's default branch);
   - `open`, for the Instance that registers the Machine to bind with `customize()`;
   - a function of the run input, `({ input }) => url` or `{ url, ref }`, when each run chooses.
 
@@ -63,8 +67,11 @@ clones. They are the same for each run.
 
   The Held secrets that this Sandbox can use: names from the `secrets` list in `jr2.config.ts`.
   The Sandbox's Custodian holds each value and puts it into requests to the hosts of that Held
-  secret. The Agent sees only a Stand-in. You need not list the model key of an Agent that runs
-  here: its provider claims it. Each name once.
+  secret. Listing a name also gives its Stand-in to the Agent's programs — each `bash` call, test,
+  build and `command` — in their env under that name, so code in `/work` can spend it ([ADR-0076](../decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
+  You need not list the model key of an Agent that runs here: its provider claims it, and the
+  Harness gives it to the model calls alone. List the model key only when code in `/work` must
+  call the model itself: such a call is outside the Turn's usage record. Each name once.
 - `effector` (optional): `object`
 
   The image of the Sandbox Effector. This container runs three kinds of Effect for this

package/docs/reference/authoring-surface/type-slothandles.md

@@ -9,9 +9,7 @@ Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a
 
 ```ts
 type SlotHandles<TSlots extends string> = {
-  repos: Record<TSlots, string>;
-  branch: string;
-  review?: Partial<Record<TSlots, string>>;
+  repos: { [K in TSlots]: `/work/${K}` };
 };
 ```
 
@@ -19,14 +17,8 @@ The handles of a Workspace that declares Repo Slots. @internal
 
 **Fields**
 
-- `repos`: `Record<TSlots, string>`
+- `repos`: ``{ [K in TSlots]: `/work/${K}`; }``
 
-  The absolute path of each Repo Slot's Worktree, `/work/<slot>/<branch>`, in the order that
-  `repos` declares the slots. Give one to an Agent's Turn as its `cwd`.
-- `branch`: `string`
-
-  The branch that the Workspace works on: the `branch` of the spec.
-- `review` (optional): `Partial<Record<TSlots, string>>`
-
-  The path of each Repo Slot's review Worktree. Present only when the spec has `reviewSha`.
-  Give one to a reviewer's Turn as its `cwd`.
+  The folder of each Repo Slot, `/work/<slot>`, in the order that `repos` declares the slots.
+  `${handle}/default` is the clone, on the Binding's base. Any other Worktree is one the Machine
+  cut with `worktree()`.

package/docs/reference/authoring-surface/type-sourcespec.md

@@ -8,12 +8,12 @@ description: "Where a Pool gets its work items: the Source."
 Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
 
 ```ts
-type SourceSpec<T> = {
+type SourceSpec<T, TInput = unknown> = {
   next:
-    | PromiseActorLogic<SourceNextResult<T>, { active: string[] }>
-    | PromiseActorLogic<{ item: T | null; open: number }, { active: string[] }>
-    | PromiseActorLogic<T | null, { active: string[] }>
-    | PromiseActorLogic<null, { active: string[] }>;
+    | PromiseActorLogic<SourceNextResult<T>, PoolNextInput<TInput>>
+    | PromiseActorLogic<{ item: T | null; open: number }, PoolNextInput<TInput>>
+    | PromiseActorLogic<T | null, PoolNextInput<TInput>>
+    | PromiseActorLogic<null, PoolNextInput<TInput>>;
   wake?: EventDef;
   pollEvery?: number;
 };
@@ -23,13 +23,13 @@ Where a Pool gets its work items: the Source. Make one with [`source`](source.md
 
 **Fields**
 
-- `next`: `PromiseActorLogic<SourceNextResult<T>, { active: string[]; }> | PromiseActorLogic<{ item: T | null; open: number; }, { active: string[]; }> | PromiseActorLogic<T | null, { active: string[]; }> | PromiseActorLogic<null, { active: string[]; }>`
+- `next`: `PromiseActorLogic<SourceNextResult<T>, PoolNextInput<TInput>> | PromiseActorLogic<{ item: T | null; open: number; }, PoolNextInput<TInput>> | PromiseActorLogic<T | null, PoolNextInput<TInput>> | PromiseActorLogic<null, PoolNextInput<TInput>>`
 
   Claim the next ready item. Write it as an xstate promise actor,
-  `fromPromise(async ({ input }) => …)`. Its input is `{ active }`: the ids of the items that
-  workers have now, which it must not give again. It must also not give again an item that a
-  worker finished. It resolves to a [`SourceNextResult`](type-sourcenextresult.md). The Pool calls it when the run
-  starts, after each claim, and when a worker settles. While workers run and no item is ready, it
+  `fromPromise(async ({ input }) => …)`. Its input is [`PoolNextInput`](type-poolnextinput.md): `active`, the ids of
+  the items that workers have now, `settled`, the ids of the items that finished or failed, and
+  `input`, the Pool's input. It must not give again an item in `active` or `settled`. It resolves
+  to a [`SourceNextResult`](type-sourcenextresult.md). The Pool calls it when the run starts, after each claim, and when a worker settles. While workers run and no item is ready, it
   also calls it on `wake` and every `pollEvery`.
 - `wake` (optional): [`EventDef`](type-eventdef.md)
 

package/docs/reference/authoring-surface/type-workspaced.md

@@ -1,6 +1,6 @@
 ---
 title: Workspaced
-description: "The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`)."
+description: "The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, the folder of each Repo Slot)."
 ---
 
 # `Workspaced`
@@ -14,7 +14,7 @@ type Workspaced<TInput, TSlots extends string> = WithoutEmptyIndex<TInput> & {
 ```
 
 The input of a `workspace()` body: the run input, plus `workspace`, the handles that the
-Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`). Use it as the type of
+Workspace adds (`workspace.repos`, the folder of each Repo Slot). Use it as the type of
 the body's input.
 
 The first argument is the run input: the `input` schema of the `workspace()`. The second is the
@@ -36,16 +36,29 @@ Its fields are the fields of the run input, and `workspace`. The run input can h
 
 ```ts
 import { z } from "zod";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  agent,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 const done = defineEvent({
   name: "done",
   description: "Call this when REVIEW.md is written.",
   input: z.object({}),
 });
-const runInput = z.object({ branch: z.string(), sha: z.string() });
+const runInput = z.object({ sha: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// A handle is the slot's folder: `/work/app`. A helper returns `as const`, so that the compiler
+// sees the slot.
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: BodyInput },
   events: [done],
@@ -55,25 +68,34 @@ const body = jr2Setup({
       instructions: "You review one commit and write REVIEW.md.",
       workspace: "read",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "review",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "reviewing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
     reviewing: {
       invoke: {
         src: "reviewer",
         input: ({ context }) => ({
-          prompt: `Review commit ${context.sha} on ${context.workspace.branch}.`,
-          cwd: context.workspace.review?.app ?? context.workspace.repos.app,
+          prompt: `Review commit ${context.sha}.`,
+          cwd: reviewTree(context),
         }),
       },
       on: { done: "finished" },
     },
     finished: { 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" } } },
   },
@@ -82,7 +104,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch, reviewSha: input.sha }),
 });
 ```
 

package/docs/reference/authoring-surface/type-workspacehandles.md

@@ -1,6 +1,6 @@
 ---
 title: WorkspaceHandles
-description: "What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the branch."
+description: "What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot."
 ---
 
 # `WorkspaceHandles`
@@ -13,11 +13,10 @@ type WorkspaceHandles<TSlots extends string> = [TSlots] extends [never]
   : SlotHandles<TSlots>;
 ```
 
-What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the
-branch. A path is correct in each Instance that registers the Machine.
+What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot. A path
+is correct in each Instance that registers the Machine.
 
 `TSlots` is the names of the Repo Slots that the body reads. `workspace()` refuses a body that
 names a slot that the Workspace does not have. Write `string` for a body that names no slot and
-reads the Worktrees in the order of `repos`, as under `repos: open`. Write `never` for a
-Workspace with no Repo Slot: its handles are `{ repos: {} }`, with no branch, and its Agents work
-in `/work`.
+reads the folders in the order of `repos`, as under `repos: open`. Write `never` for a
+Workspace with no Repo Slot: its handles are `{ repos: {} }`, and its Agents work in `/work`.

package/docs/reference/authoring-surface/type-workspaceoptions.md

@@ -13,7 +13,6 @@ type WorkspaceOptions<TSchema extends z.ZodObject, TSlots extends string> = Sand
   z.infer<TSchema>
 > & {
   input: TSchema;
-  spec: (args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput }) => WorkspaceSpec;
 };
 ```
 
@@ -24,16 +23,5 @@ The options of a `workspace()` that declares the input that starts a run.
 - `input`: `TSchema`
 
   The input that starts a run, as a `z.object`. jr2 checks each start against it. It also types
-  the `input` of `spec` and of a per-run Repo Slot, and the body must accept it plus the
+  the `input` of a per-run Repo Slot, and the body must accept it plus the
   `workspace` handles. Write it here, not on the body.
-- `spec`: `(args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput; }) => WorkspaceSpec`
-
-  A function from the run input to the Workspace's [`WorkspaceSpec`](type-workspacespec.md): the `branch` it works
-  on, and optionally `reviewSha` and `workGroup`. jr2 calls it when the run enters the
-  Workspace.
-
-  The input of `spec` also holds `instanceId`, the seed Instance ID of the run (see
-  [`HostInjectedInput`](type-hostinjectedinput.md)). Use it to give each run a branch of its own:
-  ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``. Only a root `workspace()` gets
-  it from jr2. A `workspace()` that a different Machine invokes gets only the input that its
-  parent gives it, so that parent must give `instanceId` when `spec` reads it.

package/docs/reference/authoring-surface/type-worktreefound.md

@@ -0,0 +1,16 @@
+---
+title: WorktreeFound
+description: "What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work; `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no upstream; `commit`, a detached cut."
+---
+
+# `WorktreeFound`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeFound = "held" | "local" | "remote" | "none" | "commit" | (string & {});
+```
+
+What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work;
+`local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no
+upstream; `commit`, a detached cut. Open: a later value does not break an author's code.

package/docs/reference/authoring-surface/type-worktreeinput.md

@@ -0,0 +1,56 @@
+---
+title: WorktreeInput
+description: "The input of a `worktree()`: a branch Worktree, or a detached one."
+---
+
+# `WorktreeInput`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeInput =
+  | {
+      path: AnyWorktreePath;
+      branch: string;
+      from?: string;
+      detach?: never;
+      expect?: never;
+    }
+  | {
+      path: AnyWorktreePath;
+      detach: string;
+      branch?: never;
+      from?: never;
+      expect?: never;
+    };
+```
+
+The input of a `worktree()`: a branch Worktree, or a detached one.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `path`, `branch`, `from`, `detach`, `expect`
+
+  - `path`: [`AnyWorktreePath`](type-anyworktreepath.md)
+
+    The root of the Worktree: `${context.workspace.repos.app}/<name>`, a constant word.
+  - `branch`: `string`
+
+    The branch. It resolves as a local branch, then `origin/<branch>` (tracked), then a new
+    branch.
+  - `from` (optional): `string`
+
+    Where a new branch starts. Default: the Binding's base. On a branch that exists, it must
+    be that branch's tip, or the cut is `refused`.
+  - `detach` (optional): `never`
+  - `expect` (optional): `never`
+- Form 2: `path`, `detach`, `branch`, `from`, `expect`
+
+  - `path`: [`AnyWorktreePath`](type-anyworktreepath.md)
+  - `detach`: `string`
+
+    The commit to check out, with no branch. The Worktree is forced to it and cleaned on each
+    cut. Ignored files stay, so that a reviewer can run the tests.
+  - `branch` (optional): `never`
+  - `from` (optional): `never`
+  - `expect` (optional): `never`

package/docs/reference/authoring-surface/type-worktreekey.md

@@ -0,0 +1,14 @@
+---
+title: WorktreeKey
+description: A type that the Authoring surface names.
+---
+
+# `WorktreeKey`
+
+Type, in `@jr2/orchestrator/src/effect.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type WorktreeKey<Opt> = [Opt] extends [{ readonly env: object }]
+  ? { worktree: AnyWorktreePath }
+  : { worktree?: AnyWorktreePath };
+```

package/docs/reference/authoring-surface/type-worktreeoptions.md

@@ -0,0 +1,29 @@
+---
+title: WorktreeOptions
+description: The options of `worktree()`.
+---
+
+# `WorktreeOptions`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeOptions = {
+  expect?: "new" | "existing";
+  timeout?: Duration;
+};
+```
+
+The options of `worktree()`.
+
+**Fields**
+
+- `expect` (optional): `"new" | "existing"`
+
+  `"new"`: refuse a branch that exists, local or on the remote. For a name that a planner or a
+  door chose for new work: a collision is a refusal, not someone else's branch. `"existing"`:
+  refuse a branch that does not exist, and make nothing. For a run that must continue a branch.
+  A Chart cannot change it, and a cut lent to a Chart must state it.
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long the fetch and the cut can take. Default `"10m"`.

package/docs/reference/authoring-surface/type-worktreeoutput.md

@@ -0,0 +1,45 @@
+---
+title: WorktreeOutput
+description: The output of a `worktree()`.
+---
+
+# `WorktreeOutput`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeOutput<S extends string = string> = WorktreeReady<S> | WorktreeRefused | Unknown | LaterOutcome;
+```
+
+The output of a `worktree()`. `unknown`: its state exited while it ran, or the cut did not end.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 2: `outcome`, `slot`, `path`, `branch`, `head`, `found`, `stale`
+
+  - `outcome`: `"ready"`
+  - `slot`: `S`
+  - `path`: `WorktreePath<S>`
+  - `branch`: `string | null`
+
+    The branch of the cut, from git and the cut's record, never from the folder or HEAD. `null`
+    when the Worktree is detached.
+  - `head`: `string`
+
+    The tip of `branch` (of the commit, when detached). Never HEAD.
+  - `found`: [`WorktreeFound`](type-worktreefound.md)
+  - `stale` (optional): `string`
+
+    [ADR-0053](../decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md)'s words when the remote did not answer. The cut used what the clone holds.
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`