@jr2/orchestrator 0.5.1 → 0.6.0

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

@@ -8,7 +8,7 @@ description: "Declare a Source: where a `pool()` gets its work items, one at a t
 Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
 
 ```ts
-function source<T>(spec: SourceSpec<T>): SourceSpec<T>
+function source<T, TInput = unknown>(spec: SourceSpec<T, TInput>): SourceSpec<T, TInput>
 ```
 
 Declare a Source: where a `pool()` gets its work items, one at a time. It gives back the spec
@@ -25,7 +25,7 @@ that you pass. The item type `T` types what `next` gives. `pool()` does not carr
 
 ```ts
 import { fromPromise } from "xstate";
-import { source } from "@jr2/orchestrator";
+import { source, type PoolNextInput } from "@jr2/orchestrator";
 
 type Issue = { id: string; title: string };
 
@@ -35,7 +35,7 @@ const backlog: Issue[] = [
 ];
 
 export 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;

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

@@ -51,8 +51,8 @@ cannot change `instructions` or `workspace`.
   What the Agent may do to the Workspace. Default: `"write"`.
   - `"write"`: all the Working tools (read, write, edit, bash, grep, glob).
   - `"read"`: no write or edit tool. The Agent keeps bash, so `"read"` does not stop a command
-    that writes. To keep the Agent from changing the branch, frame its Turn in the review
-    Worktree: `reviewSha` in the spec, then `cwd: context.workspace.review?.<slot>`.
+    that writes. To keep the Agent from changing the branch, frame its Turn in a detached
+    Worktree: cut it with `{ path, detach: sha }`, then give that `path` as `cwd`.
   - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
     runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it.
 

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

@@ -8,5 +8,8 @@ description: A type that the Authoring surface names.
 Type, in `@jr2/orchestrator/src/customize.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 AgentSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AgentLogic }>["src"];
+type AgentSlots<M extends AnyStateMachine> = Extract<
+  SlotsOf<M>,
+  { logic: CallbackActorLogic<AgentRunReceiveEvent, any> }
+>["src"];
 ```

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

@@ -0,0 +1,14 @@
+---
+title: AnyFramePath
+description: "A Turn's Frame: a Worktree, or `/work`, stated."
+---
+
+# `AnyFramePath`
+
+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 AnyFramePath = "/work" | `/work/${string}`;
+```
+
+A Turn's Frame: a Worktree, or `/work`, stated. `jr2Setup` narrows it to the body's slots.

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

@@ -0,0 +1,15 @@
+---
+title: AnyWorktreePath
+description: "A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the slots of the body."
+---
+
+# `AnyWorktreePath`
+
+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 AnyWorktreePath = `/work/${string}/${string}`;
+```
+
+A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the
+slots of the body.

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

@@ -0,0 +1,14 @@
+---
+title: BindActors
+description: A type that the Authoring surface names.
+---
+
+# `BindActors`
+
+Type, in `@jr2/orchestrator/src/setup.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 BindActors<A extends Record<string, UnknownActorLogic>, TInput, TContext> = {
+  [K in keyof A]: BindLogic<A[K], RepoSlotsOf<TInput, TContext>>;
+};
+```

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

@@ -14,9 +14,9 @@ type Binding = {
 };
 ```
 
-The repository of a Repo Slot: `{ url, ref }`. `url` is the Repo's git url. `ref` is the branch
-or commit that the branch Worktree starts from; absent, the Repo's default branch. Where only a
-url is needed, a string is enough.
+The repository of a Repo Slot: `{ url, ref }`. `url` is the Repo's git url. `ref` is the branch,
+the tag or the commit that the clone stays on, and that a new branch starts from; absent, the
+Repo's default branch. Where only a url is needed, a string is enough.
 
 `workspace()` and `customize()` refuse:
 - an empty `url`: ``<where>: Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot
@@ -34,8 +34,8 @@ url is needed, a string is enough.
   The Repo's git url.
 - `ref` (optional): `string`
 
-  The branch or commit that the branch Worktree starts from. Default: the Repo's default
-  branch.
+  The branch, tag or commit that the clone stays on, and that a new branch starts from. Default:
+  the Repo's default branch.
 
 **Example**
 
@@ -52,7 +52,6 @@ const body = jr2Setup().createMachine({
 
 export const machine = workspace(body, {
   repos: { app },
-  spec: () => ({ branch: "jr2/hotfix" }),
 });
 ```
 

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

@@ -8,11 +8,12 @@ description: "A command's input: one string per argv slot, and with `pin` the ap
 Type, in `@jr2/orchestrator/src/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 CommandInput<A extends readonly unknown[], P = false> = [
+type CommandInput<A extends readonly unknown[], P = false, Opt = unknown> = [
   ArgNames<A> | ([P] extends [true] ? "sha" : never),
 ] extends [never]
-  ? void
-  : { [K in ArgNames<A> | ([P] extends [true] ? "sha" : never)]: string };
+  ? (WorktreeKey<Opt> & NotWorktreeKeys) | ([Opt] extends [{ readonly env: object }] ? never : void)
+  : { [K in ArgNames<A> | ([P] extends [true] ? "sha" : never)]: string } & WorktreeKey<Opt> &
+      Omit<NotWorktreeKeys, ArgNames<A>>;
 ```
 
 A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`);

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

@@ -9,7 +9,6 @@ Type, in `@jr2/orchestrator/src/effect.ts`. The signature of an export, or a typ
 
 ```ts
 type CommandOptions = {
-  slot?: string;
   timeout?: Duration;
   tail?: number;
   env?: CommandEnv;
@@ -22,27 +21,6 @@ output it keeps, its Effect secrets, and the commit it runs against.
 
 **Fields**
 
-- `slot` (optional): `string`
-
-  The Repo Slot whose Worktree is the working directory of the command. Write it only when the
-  Workspace has more than one Repo Slot. In a Workspace with no Repo Slot, the command starts in
-  `/work`, the folder that the steps of the Workspace share.
-
-  The command starts in the root of that Worktree. To run it in a subfolder, give the path as an
-  argument, or write `["sh", "-c", "cd <dir> && <program>"]`.
-
-  When it starts, it refuses:
-  - no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
-    Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it
-    runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`. When `env` names an Effect secret,
-    the text is `command "<slot>" runs under a Workspace carrying more than one Repo Slot
-    (<slots>) — say which: { slot: "<slot>" } (ADR-0051)`.
-  - with an Effect secret in `env`, a Workspace with no Repo Slot: `command "<slot>" runs under
-    a Workspace with no Repo Slot: a command with an Effect secret runs against one commit of a
-    Repo Slot's branch, and there is none — declare a Repo Slot, or name no secret in its env, and
-    it runs in /work beside the Agent (ADR-0051)`.
-  - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
-    its Workspace does not carry (<slots>)`.
 - `timeout` (optional): [`Duration`](type-duration.md)
 
   How long the command can run: a number and a unit, such as `"90s"`, `"10m"` or `"1h"`.

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

@@ -8,7 +8,7 @@ description: "The output of a `command` Effect: what the `onDone` of its state g
 Type, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
 
 ```ts
-type CommandOutput = (ExecOutcome & { dirty?: boolean }) | Unknown;
+type CommandOutput = (ExecOutcome & { dirty?: boolean }) | Unknown | LaterOutcome;
 ```
 
 The output of a `command` Effect: what the `onDone` of its state gets as `event.output`. Every
@@ -25,6 +25,8 @@ outcome is output. A failed program is output too. Route on `outcome`:
 characters. `dirty` is `true` when a command that names an Effect secret ran against a commit,
 and the Worktree held changes that it did not see.
 
+The union is open ([`LaterOutcome`](type-lateroutcome.md)): give the rest a last arm with no guard.
+
 **Forms**: it is one of these objects.
 
 - Form 1: `outcome`, `code`, `tail`, `dirty`
@@ -48,6 +50,10 @@ and the Worktree held changes that it did not see.
 
   - `outcome`: `"unknown"`
   - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **Example**
 
@@ -56,28 +62,40 @@ import {
   command,
   type CommandOutput,
   fail,
+  isReady,
   jr2Setup,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
 type Input = Workspaced<{}, "app">;
 
+const testTree = (context: Input) => `${context.workspace.repos.app}/test` as const;
+
 const passed = (output: CommandOutput): boolean =>
   output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
-  actors: { tests: command(["npm", "test"], { timeout: "15m" }), fail: fail() },
+  actors: { cut: worktree(), tests: command(["npm", "test"], { timeout: "15m" }), fail: fail() },
 }).createMachine({
   id: "tests",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "testing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: "tests" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
     testing: {
       invoke: {
         src: "tests",
+        input: ({ context }) => ({ worktree: testTree(context) }),
         onDone: [
           { guard: ({ event }) => passed(event.output), target: "green" },
           { target: "red" },
@@ -87,13 +105,13 @@ const body = jr2Setup({
     green: { type: "final" },
     // Not a final state: a final state means `done`, and the run ends `failed` here.
     red: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
+    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: "tests" }),
 });
 ```
 

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

@@ -21,7 +21,9 @@ type Customize<M extends AnyStateMachine> = {
   image?: string;
   user?: string | UserContainer;
   resources?: Size;
-  repos?: [RepoSlotsOf<M>] extends [never] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<InputFrom<WorkspaceOf<M>>> };
+  repos?: [RepoSlotsOf<M>] extends [never]
+    ? never
+    : { [K in RepoSlotsOf<M>]?: RepoSlot<Exclude<InputFrom<WorkspaceOf<M>>, undefined>> };
 };
 ```
 
@@ -74,7 +76,7 @@ Every key is optional. Write only what you change.
   The Size, layered field by field over the Size of the `workspace()`: `{ limits: { memory } }`
   keeps the author's cpu. Only `limits.memory` and `limits.cpu`. See [`Size`](type-size.md). Only for a
   Machine that composes a `workspace()`.
-- `repos` (optional): `[ RepoSlotsOf<M> ] extends [ never ] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<InputFrom<WorkspaceOf<M>>>; }`
+- `repos` (optional): `[ RepoSlotsOf<M> ] extends [ never ] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<Exclude<InputFrom<WorkspaceOf<M>>, undefined>>; }`
 
   Bind the Repo Slots of the `workspace()`, by slot name. Each value is one of these:
 

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

@@ -18,7 +18,8 @@ type DispatchOutput =
     }
   | { outcome: "refused"; status: number; report: string[] }
   | { outcome: "unreachable"; reason: string }
-  | Unknown;
+  | Unknown
+  | LaterOutcome;
 ```
 
 The output of a `dispatch` Effect. Route on `outcome`:
@@ -34,6 +35,8 @@ The output of a `dispatch` Effect. Route on `outcome`:
 - `unreachable`: the Orchestrator of the target did not answer. No run started.
 - `unknown`: jr2 cannot tell if a run started.
 
+The union is open ([`LaterOutcome`](type-lateroutcome.md)): give the rest a last arm with no guard.
+
 **Forms**: it is one of these objects.
 
 - Form 1: `outcome`, `reason`
@@ -59,6 +62,10 @@ The output of a `dispatch` Effect. Route on `outcome`:
 
   - `outcome`: `"unreachable"`
   - `reason`: `string`
+- Form 6: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **See also**
 

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

@@ -0,0 +1,19 @@
+---
+title: DoorlessInput
+description: A type that the Authoring surface names.
+---
+
+# `DoorlessInput`
+
+Type, in `@jr2/orchestrator/src/workspace.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 DoorlessInput<TBody extends AnyStateMachine> =
+  unknown extends InputFrom<TBody>
+    ? unknown
+    : [keyof Omit<InputFrom<TBody>, "workspace">] extends [never]
+      ? unknown
+      : {} extends Omit<InputFrom<TBody>, "workspace">
+        ? Omit<InputFrom<TBody>, "workspace"> | undefined
+        : Omit<InputFrom<TBody>, "workspace">;
+```

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

@@ -1,6 +1,6 @@
 ---
 title: FileBody
-description: "`file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body."
+description: "`file(path, { segments?, contentType? })`: a Worktree file as an `http` body."
 ---
 
 # `FileBody`
@@ -11,14 +11,13 @@ Type, in `@jr2/orchestrator/src/http-effect.ts`. The signature of an export, or
 type FileBody<S extends z.ZodType | undefined = undefined> = {
   readonly file: {
     readonly path: FromInput<S, string>;
-    readonly slot?: string;
     readonly segments?: FromInput<S, readonly string[]>;
     readonly contentType?: string;
   };
 };
 ```
 
-`file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
+`file(path, { segments?, contentType? })`: a Worktree file as an `http` body.
 
 **Fields**
 
@@ -26,11 +25,8 @@ type FileBody<S extends z.ZodType | undefined = undefined> = {
 
   - `path`: `FromInput<S, string>`
 
-    The file, relative to the Repo Slot's Worktree, or to `/work` in a Workspace with no Repo
-    Slot.
-  - `slot` (optional): `string`
-
-    The Repo Slot whose Worktree holds it. Write it only when the Workspace has more than one.
+    The file, relative to the Worktree that `worktree` of the Effect's input names, or to `/work`
+    in a Workspace with no Repo Slot.
   - `segments` (optional): `FromInput<S, readonly string[]>`
 
     Path segments that jr2 adds to the end of the url, as `path` of `request` does for a json

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

@@ -0,0 +1,14 @@
+---
+title: FramePath
+description: "A Turn's Frame in a Workspace with the Repo Slots `S`."
+---
+
+# `FramePath`
+
+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 FramePath<S extends string> = WorktreePath<S> | "/work";
+```
+
+A Turn's Frame in a Workspace with the Repo Slots `S`.

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

@@ -20,10 +20,8 @@ caller sends it. jr2 writes it over any value that a caller sends.
 
 Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
 that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
-`workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`.
-
-The `spec` of a root `workspace()` also gets it, and the type of its input shows it:
-``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``.
+`workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`. For example, a cut
+can name a branch for each run: `` branch: `fix/${context.instanceId}` ``.
 
 It is not the run id. Use it, for example, to give each run a branch of its own.
 

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

@@ -79,10 +79,13 @@ An `http` Effect's definition.
   Effect secret. Do not write it beside `body`.
 - `body` (optional): `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

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

@@ -0,0 +1,20 @@
+---
+title: HttpFileInput
+description: The input of an `http` Effect with a Worktree file as its body.
+---
+
+# `HttpFileInput`
+
+Type, in `@jr2/orchestrator/src/http-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 HttpFileInput<S> = (S extends z.ZodType ? z.infer<S> : unknown) & { worktree?: AnyWorktreePath };
+```
+
+The input of an `http` Effect with a Worktree file as its body. Under a Workspace with Repo
+Slots, `worktree` names the Worktree. In a Workspace with no Repo Slot, the input has no
+`worktree`, and the path is relative to `/work`.
+
+**Fields**
+
+- `worktree` (optional): [`AnyWorktreePath`](type-anyworktreepath.md)

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

@@ -8,7 +8,7 @@ description: "The output of an `http` Effect: what the `onDone` of its state get
 Type, in `@jr2/orchestrator/src/effector-wire.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
 
 ```ts
-type HttpOutput = {
+type HttpOutput = LaterOutcome | {
   outcome: "response";
   status: number;
   headers: Record<string, string>;
@@ -37,6 +37,8 @@ outcome is output. A 4xx or 5xx status is output too. Route on `outcome`:
 - `unknown`: the call can have gone out, but no answer came, or jr2 cannot tell after a restart.
   `reason` tells why. jr2 does not send it again unless it is marked `idempotent`.
 
+The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+
 **Forms**: it is one of these objects.
 
 - Form 1: `outcome`, `status`, `headers`, `contentType`, `size`, `body`, `truncated`
@@ -52,6 +54,10 @@ outcome is output. A 4xx or 5xx status is output too. Route on `outcome`:
 
   - `outcome`: `"unknown" | "unreachable" | "refused"`
   - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **Example**
 

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

@@ -0,0 +1,21 @@
+---
+title: LaterOutcome
+description: A value of `outcome` that this kit does not give.
+---
+
+# `LaterOutcome`
+
+Type, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type LaterOutcome = { outcome: "(a later outcome)"; reason?: string };
+```
+
+A value of `outcome` that this kit does not give. It stands in the union so that no author can
+write an exhaustive check, so that a later outcome is no break: route on what you know, and give
+the rest a last arm.
+
+**Fields**
+
+- `outcome`: `"(a later outcome)"`
+- `reason` (optional): `string`

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

@@ -0,0 +1,77 @@
+---
+title: NameStart
+description: "What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path."
+---
+
+# `NameStart`
+
+Type, in `@jr2/orchestrator/src/worktree.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 NameStart =
+  | "a"
+  | "b"
+  | "c"
+  | "d"
+  | "e"
+  | "f"
+  | "g"
+  | "h"
+  | "i"
+  | "j"
+  | "k"
+  | "l"
+  | "m"
+  | "n"
+  | "o"
+  | "p"
+  | "q"
+  | "r"
+  | "s"
+  | "t"
+  | "u"
+  | "v"
+  | "w"
+  | "x"
+  | "y"
+  | "z"
+  | "A"
+  | "B"
+  | "C"
+  | "D"
+  | "E"
+  | "F"
+  | "G"
+  | "H"
+  | "I"
+  | "J"
+  | "K"
+  | "L"
+  | "M"
+  | "N"
+  | "O"
+  | "P"
+  | "Q"
+  | "R"
+  | "S"
+  | "T"
+  | "U"
+  | "V"
+  | "W"
+  | "X"
+  | "Y"
+  | "Z"
+  | "0"
+  | "1"
+  | "2"
+  | "3"
+  | "4"
+  | "5"
+  | "6"
+  | "7"
+  | "8"
+  | "9"
+  | "_";
+```
+
+What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path.

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

@@ -11,12 +11,11 @@ Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a
 type NoSlotWorkspaceOptions<TSchema extends z.ZodObject> = Omit<SandboxOptions<never>, "repos"> & {
   repos?: never;
   input: TSchema;
-  spec?: (args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput }) => NoSlotSpec;
 };
 ```
 
 The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
-`repos` is left out, and `spec` is optional.
+`repos` is left out.
 
 **Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), except `repos`, and these:
 
@@ -26,7 +25,3 @@ The options of a `workspace()` with no Repo Slot that declares the input that st
 - `input`: `TSchema`
 
   The input that starts a run, as a `z.object`, as in [`WorkspaceOptions`](type-workspaceoptions.md).
-- `spec` (optional): `(args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput; }) => NoSlotSpec`
-
-  A function from the run input to the Workspace's [`NoSlotSpec`](type-noslotspec.md): only `workGroup`.
-  Default: no `workGroup`.

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

@@ -0,0 +1,12 @@
+---
+title: NotWorktreeKeys
+description: A type that the Authoring surface names.
+---
+
+# `NotWorktreeKeys`
+
+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 NotWorktreeKeys = { cwd?: never; path?: never; branch?: never };
+```

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

@@ -8,10 +8,15 @@ description: "The input of a `command(open)`: a string for each `arg()` of the a
 Type, in `@jr2/orchestrator/src/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 OpenCommandInput<P = false> = Readonly<Record<string, string>> &
-  ([P] extends [true] ? { sha: string } : unknown);
+type OpenCommandInput<P = false, Opt = unknown> = Readonly<Record<string, string>> &
+  ([P] extends [true] ? { sha: string } : unknown) &
+  WorktreeKey<Opt>;
 ```
 
 The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds,
 and with `pin`, the commit (`{ sha }`). The compiler cannot check the names. When the input has
 no string for an `arg()`, the Effect fails when it starts.
+
+**Fields**
+
+- `worktree` (optional): [`AnyWorktreePath`](type-anyworktreepath.md)

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

@@ -8,10 +8,9 @@ description: "The options of a `workspace()` with no Repo Slot and no `input`: i
 Type, in `@jr2/orchestrator/src/workspace.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 PermissiveNoSlotWorkspaceOptions<TInput = unknown> = Omit<SandboxOptions<never>, "repos"> & {
+type PermissiveNoSlotWorkspaceOptions = Omit<SandboxOptions<never>, "repos"> & {
   repos?: never;
   input?: never;
-  spec?: (args: { input: TInput }) => NoSlotSpec;
 };
 ```
 
@@ -25,7 +24,3 @@ The options of a `workspace()` with no Repo Slot and no `input`: it starts with
 - `input` (optional): `never`
 
   Not present: a `workspace()` without `input` starts with any input.
-- `spec` (optional): `(args: { input: TInput; }) => NoSlotSpec`
-
-  A function from the input to the Workspace's [`NoSlotSpec`](type-noslotspec.md): only `workGroup`. Default:
-  no `workGroup`.