@jr2/orchestrator 0.5.1 → 0.7.0

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

@@ -1,6 +1,6 @@
 ---
 title: SourceSpec
-description: "Where a Pool gets its work items: the Source."
+description: A pull Source.
 ---
 
 # `SourceSpec`
@@ -8,37 +8,46 @@ 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;
+  hooks?: SourceHooks<Reread, TInput>;
+  reply?: SourceReply<T>;
 };
 ```
 
-Where a Pool gets its work items: the Source. Make one with [`source`](source.md).
+A pull Source. `next` claims one item at a time. 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
-  also calls it on `wake` and every `pollEvery`.
+  `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`, on a Hook's `reread()` and every `pollEvery`.
 - `wake` (optional): [`EventDef`](type-eventdef.md)
 
   An external event, made with `defineEvent`, that tells the Pool that new work is ready, for
-  example from a webhook or `jr2 send`. While workers run and no item is ready, it makes the Pool
-  call `next` at once. The Pool serves it as a Gate named `source` for the whole run
-  (`<path>.source` when the Pool is composed in another Machine). Default: none.
+  example from `jr2 send`. While workers run and no item is ready, it makes the Pool call `next`
+  at once. The Pool serves it as a Gate named `source` for the whole run (`<path>.source` when the
+  Pool is composed in another Machine). Default: none.
 - `pollEvery` (optional): `number`
 
   While workers run and no item is ready, call `next` again after this many milliseconds. Use
   it for a Source whose items change while the run waits. Default: none, so the Pool calls
-  `next` again only when a worker settles or `wake` comes.
+  `next` again only when a worker settles, `wake` comes, or a Hook's handler gives `reread()`.
+- `hooks` (optional): `SourceHooks<Reread, TInput>`
+
+  What a Hook's delivery does: a handler for each Hook kind id and event key gives `reread()` or
+  `skip(reason)`. Default: none.
+- `reply` (optional): `SourceReply<T>`
+
+  The text that the person who acted reads, from the verdict. Default: none.

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

@@ -0,0 +1,49 @@
+---
+title: SourceVerdict
+description: "A Source's verdict on one delivery, as its `reply` reads it (ADR-0017)."
+---
+
+# `SourceVerdict`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type SourceVerdict<T> =
+  | { readonly verdict: "held"; readonly key: string; readonly item: T }
+  | { readonly verdict: "existing"; readonly key: string; readonly item: T; readonly run?: string }
+  | { readonly verdict: "hold-full"; readonly key: string; readonly item: T }
+  | { readonly verdict: "reread" }
+  | { readonly verdict: "skipped"; readonly reason: string };
+```
+
+A Source's verdict on one delivery, as its `reply` reads it ([ADR-0017](../decisions/0017-pool-over-a-source-port.md)). `held`, `existing` and
+`hold-full` come from a push Source and carry the item and its key; `existing` names the run
+that holds the key, when one holds it. `reread` comes from a Source that can read. `skipped`
+carries the reason. A Pool that is paused has no run, so no `reply` of it runs: the door writes
+that text.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `verdict`, `key`, `item`
+
+  - `verdict`: `"held"`
+  - `key`: `string`
+  - `item`: `T`
+- Form 2: `verdict`, `key`, `item`, `run`
+
+  - `verdict`: `"existing"`
+  - `key`: `string`
+  - `item`: `T`
+  - `run` (optional): `string`
+- Form 3: `verdict`, `key`, `item`
+
+  - `verdict`: `"hold-full"`
+  - `key`: `string`
+  - `item`: `T`
+- Form 4: `verdict`
+
+  - `verdict`: `"reread"`
+- Form 5: `verdict`, `reason`
+
+  - `verdict`: `"skipped"`
+  - `reason`: `string`

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

@@ -0,0 +1,12 @@
+---
+title: StandingPoolMachine
+description: A type that the Authoring surface names.
+---
+
+# `StandingPoolMachine`
+
+Type, in `@jr2/orchestrator/src/pool.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 StandingPoolMachine = StateMachine<any, any, any, any, any, any, any, any, any, {}, never, any, any, any>;
+```

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

@@ -0,0 +1,51 @@
+---
+title: StandingPoolSpec
+description: What you pass to `pool()` for a Pool of runs.
+---
+
+# `StandingPoolSpec`
+
+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 StandingPoolSpec<T, I> = {
+  id?: string;
+  standing: true;
+  source: SourceSpec<T, {}> | SourceSpec<T> | ReadSourceSpec<T, {}> | ReadSourceSpec<T> | PushSourceSpec<T>;
+  itemId: (item: T) => string;
+  cap: number;
+  itemInput?: (item: T) => I;
+  input?: never;
+  onDrained?: never;
+  failures?: never;
+};
+```
+
+What you pass to `pool()` for a Pool of runs. The worker is a `dispatch(...)` slot, and the Pool
+stands. Each item is a run of the slot's Workflow, keyed by `itemId` in that Workflow.
+
+**Fields**
+
+- `id` (optional): `string`
+
+  The Machine id: the name of the Pool in the Console. Default: `"pool"`.
+- `standing`: `true`
+
+  A Pool of runs stands: jr2 keeps one live run of its Workflow, and it never ends by itself.
+- `source`: `SourceSpec<T, {}> | SourceSpec<T> | ReadSourceSpec<T, {}> | ReadSourceSpec<T> | PushSourceSpec<T>`
+
+  Where the items come from: a pull, a read or a push Source. Make it with [`source`](source.md).
+- `itemId`: `(item: T) => string`
+
+  The id of an item, and the KEY of its run in the slot's Workflow ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)): every Pool, every
+  hand-over and every `jr2 run` that gives this key to that Workflow gets the same run while its
+  row lives — while it is live, and for `runs.retain` after it ends.
+- `cap`: `number`
+
+  The most LIVE runs at once that this Pool dispatched. You must choose it.
+- `itemInput` (optional): `(item: T) => I`
+
+  Make a run's body from its item. Default: the item itself.
+- `input` (optional): `never`
+- `onDrained` (optional): `never`
+- `failures` (optional): `never`

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

@@ -0,0 +1,20 @@
+---
+title: SteerArgs
+description: "The arguments a `steer` text or `from` function gets: the Machine's context and the event that the transition takes."
+---
+
+# `SteerArgs`
+
+Type, in `@jr2/orchestrator/src/steer.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 SteerArgs<TContext, TEvent> = { context: TContext; event: TEvent };
+```
+
+The arguments a `steer` text or `from` function gets: the Machine's context and the event that
+the transition takes.
+
+**Fields**
+
+- `context`: `TContext`
+- `event`: `TEvent`

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

@@ -5,7 +5,7 @@ description: "How hard the model thinks before it answers: `\"off\"`, `\"minimal
 
 # `ThinkingLevel`
 
-Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";

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

@@ -5,7 +5,7 @@ description: "The User Container in its object form: its image, and its part of
 
 # `UserContainer`
 
-Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type UserContainer = {

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

@@ -1,11 +1,11 @@
 ---
 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`
 
-Type, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+Type, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, in the [Workspaces and Repos](group-workspaces-and-repos.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type Workspaced<TInput, TSlots extends string> = WithoutEmptyIndex<TInput> & {
@@ -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.
+---
+
+# `WorktreeFound`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```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`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```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`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```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`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```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`

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

@@ -0,0 +1,16 @@
+---
+title: WorktreePath
+description: A Worktree of the Repo Slots `S`.
+---
+
+# `WorktreePath`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type WorktreePath<S extends string> = `/work/${S}/${NameStart}${string}`;
+```
+
+A Worktree of the Repo Slots `S`. One segment below the slot, that starts with a letter, a
+digit or `_`: `${context.workspace.repos.app}/run`. The compiler sees the start of the name; a
+`/` further on is the Effect's own refusal.

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

@@ -0,0 +1,37 @@
+---
+title: WorktreeReady
+description: Type, an export of @jr2/orchestrator.
+---
+
+# `WorktreeReady`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type WorktreeReady<S extends string = string> = {
+  outcome: "ready";
+  slot: S;
+  path: WorktreePath<S>;
+  branch: string | null;
+  head: string;
+  found: WorktreeFound;
+  stale?: string;
+};
+```
+
+**Fields**
+
+- `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.

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

@@ -0,0 +1,21 @@
+---
+title: WorktreeRefused
+description: No Worktree, and nothing changed.
+---
+
+# `WorktreeRefused`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type WorktreeRefused = { outcome: "refused"; reason: string };
+```
+
+No Worktree, and nothing changed. The cause is a bad path, a name git or the push refuses, a
+re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
+name that the remote cannot confirm.
+
+**Fields**
+
+- `outcome`: `"refused"`
+- `reason`: `string`