@jr2/orchestrator 0.5.1 → 0.7.0

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`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```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-lends.md

@@ -12,6 +12,7 @@ type Lends = {
   agents?: string[];
   effects?: string[];
   machines?: string[];
+  gates?: string[];
   guards?: string[];
   actions?: string[];
   delays?: string[];
@@ -21,7 +22,9 @@ type Lends = {
 ```
 
 The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`,
-`actions` and `delays`. `gate: true` lends the Gate, so that a Chart can wait for an answer from
+`actions` and `delays`. `gates` lends Gate slots (`gate({ … })`) that hear a Hook, by slot name:
+the door refuses a Chart that invokes one whose `delivers` names an event that is not in the
+Chart's `events`. `gate: true` lends the Gate, so that a Chart can wait for an answer from
 outside the run. `fail: true` lends the Part that fails the run, so that a Chart can end its run
 as a Failure ([ADR-0073](../decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)): the Machine decides which ends a Chart can choose. A Chart can use no
 other part.
@@ -31,6 +34,7 @@ other part.
 - `agents` (optional): `string[]`
 - `effects` (optional): `string[]`
 - `machines` (optional): `string[]`
+- `gates` (optional): `string[]`
 - `guards` (optional): `string[]`
 - `actions` (optional): `string[]`
 - `delays` (optional): `string[]`

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

@@ -0,0 +1,14 @@
+---
+title: LookOutput
+description: A type that the Authoring surface names.
+---
+
+# `LookOutput`
+
+Type, in `@jr2/orchestrator/src/gate.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 LookOutput<R> = R extends { getInitialSnapshot: (...a: never[]) => { output?: infer O } }
+  ? Exclude<O, undefined>
+  : unknown;
+```

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

@@ -0,0 +1,78 @@
+---
+title: McpCallOutput
+description: "The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`."
+---
+
+# `McpCallOutput`
+
+Type, in `@jr2/orchestrator/src/effector-wire.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 McpCallOutput =
+  | { outcome: "returned"; isError: boolean; text: string; structured?: unknown; truncated?: boolean }
+  | McpNotReturned;
+```
+
+The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`. Every
+outcome is output. Route on `outcome`:
+
+- `returned`: the server answered the call. `isError` is the tool's own `isError`: the tool ran
+  and says that it failed. `text` joins the text of the result's content; a part that is not text
+  is one line that names its type. `structured` is the result's `structuredContent`, when it has
+  one. `text` and `structured` each have the byte bound of the Effect's `maxBody`: past it, jr2
+  cuts `text`, drops `structured`, and sets `truncated`.
+- `refused`: the request did not run. The server answered an HTTP 3xx or 4xx status (a 401 or a
+  403 included) at any step, the handshake too; it refused the handshake; or it answered the
+  request with the JSON-RPC error `-32700`, `-32600`, `-32601` or `-32602`: a request that it
+  could not read, an unknown method, an unknown tool, or bad arguments; or it answered a read with
+  `-32002`: the resource does not exist. It is also the Effector's
+  own refusal, with nothing sent: the server or its secret is not in its `effector.json`.
+- `unreachable`: nothing of the request was sent: the name did not resolve, or the connection,
+  TLS or the handshake failed otherwise (a 5xx, the timeout, an answer that is not MCP's, a
+  revision of MCP that jr2 does not speak).
+- `input-required`: the server asked for input, which jr2 does not give. After the error
+  `-32042`, the tool did not run. After an `elicitation/create` request, which comes while the
+  tool runs, the tool may have begun. jr2 does not send the request again: a Machine that
+  invokes the Effect again after a Gate can run a part of the tool two times.
+- `unknown`: the request was sent and no answer came (the timeout, a reset, a stream that ended
+  first), or the server answered with a 5xx or another JSON-RPC error. The tool may have acted.
+  jr2 does not send it again unless it is marked `idempotent`.
+
+jr2 replaces each value of an Effect secret that the Effector holds with `[secret:<name>]`, in
+every string of the output. 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`, `isError`, `text`, `structured`, `truncated`
+
+  - `outcome`: `"returned"`
+  - `isError`: `boolean`
+  - `text`: `string`
+  - `structured` (optional): `unknown`
+  - `truncated` (optional): `boolean`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"unreachable"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"input-required"`
+  - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 6: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [ADR-0079: An Agent holds MCP tools, a Machine calls them as an Effect, and the Machine is the approval](../decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)

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

@@ -0,0 +1,42 @@
+---
+title: McpNotReturned
+description: The outcomes that an `mcp` Effect gives besides `returned`.
+---
+
+# `McpNotReturned`
+
+Type, in `@jr2/orchestrator/src/effector-wire.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 McpNotReturned =
+  | { outcome: "refused"; reason: string }
+  | { outcome: "unreachable"; reason: string }
+  | { outcome: "input-required"; reason: string }
+  | { outcome: "unknown"; reason: string }
+  | LaterOutcome;
+```
+
+The outcomes that an `mcp` Effect gives besides `returned`. Each one has a `reason` in words.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"unreachable"`
+  - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"input-required"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`

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

@@ -0,0 +1,47 @@
+---
+title: McpOptions
+description: The options of an `mcp` Effect.
+---
+
+# `McpOptions`
+
+Type, in `@jr2/orchestrator/src/mcp-effect.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 McpOptions<S extends z.ZodObject | undefined = undefined> = {
+  input?: S;
+  timeout?: Duration;
+  maxBody?: number;
+  idempotent?: boolean;
+};
+```
+
+The options of an `mcp` Effect.
+
+**Fields**
+
+- `input` (optional): `S`
+
+  The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+  gives it. For `mcp.call` the parsed input is the tool's arguments; for `mcp.prompt`, the
+  prompt's arguments, each a string. 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): `mcp
+  "<slot>": its input does not match the definition's input schema — <path>: <message>`. With no
+  schema, the input of the `invoke` is the arguments as it is, and `{}` when it has none.
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default:
+  the server's `timeout` in `jr2.config.ts` (60 seconds when it sets none). With no answer in
+  that time, the output is `unknown`. It refuses a value that is not a positive duration: `mcp:
+  timeout "<timeout>" is not a positive duration (like "30s", "2m")`.
+- `maxBody` (optional): `number`
+
+  The largest number of bytes of `text`, and of `structured` as JSON, that the output keeps.
+  Default 65536. Past it, jr2 cuts `text`, drops `structured`, and sets `truncated`. It refuses
+  a value that is not a positive whole number: `mcp({ maxBody }): a positive number of bytes`.
+- `idempotent` (optional): `boolean`
+
+  `true` when it is safe to send the request two times: the tool only reads, or it has its own
+  idempotency key. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the
+  request went out. Then it sends an idempotent one again, and gives any other the output
+  `unknown`. jr2 does not read the tool's `idempotentHint`.

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

@@ -0,0 +1,50 @@
+---
+title: McpOutput
+description: "The output of any `mcp` Effect: a call's, a read's or a prompt's."
+---
+
+# `McpOutput`
+
+Type, in `@jr2/orchestrator/src/effector-wire.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 McpOutput = McpCallOutput | McpReadOutput;
+```
+
+The output of any `mcp` Effect: a call's, a read's or a prompt's.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `isError`, `text`, `structured`, `truncated`
+
+  - `outcome`: `"returned"`
+  - `isError`: `boolean`
+  - `text`: `string`
+  - `structured` (optional): `unknown`
+  - `truncated` (optional): `boolean`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"unreachable"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"input-required"`
+  - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 6: `outcome`, `text`, `structured`, `truncated`
+
+  - `outcome`: `"returned"`
+  - `text`: `string`
+  - `structured` (optional): `unknown`
+  - `truncated` (optional): `boolean`
+- Form 7: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`

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

@@ -0,0 +1,53 @@
+---
+title: McpReadOutput
+description: The output of an `mcp.read` or an `mcp.prompt` Effect.
+---
+
+# `McpReadOutput`
+
+Type, in `@jr2/orchestrator/src/effector-wire.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 McpReadOutput =
+  | { outcome: "returned"; text: string; structured?: unknown; truncated?: boolean }
+  | McpNotReturned;
+```
+
+The output of an `mcp.read` or an `mcp.prompt` Effect. Its outcomes are those of
+[`McpCallOutput`](type-mcpcalloutput.md), with no `isError`. For a read, `text` joins the text of the resource's
+contents, and `structured` is the `contents` list: a blob is given only as its `mimeType` and its
+size. For a prompt, `text` joins the text of the prompt's messages, and `structured` is the
+`messages` list. Past the bound, `structured` is dropped and `truncated` is set.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"unreachable"`
+  - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"input-required"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 5: `outcome`, `text`, `structured`, `truncated`
+
+  - `outcome`: `"returned"`
+  - `text`: `string`
+  - `structured` (optional): `unknown`
+  - `truncated` (optional): `boolean`
+- Form 6: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**See also**
+
+- [Effects](../../concepts/effects.md)

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

@@ -0,0 +1,50 @@
+---
+title: McpRemoteServer
+description: A remote MCP server, which the Harness reaches over Streamable HTTP.
+---
+
+# `McpRemoteServer`
+
+Type, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, in the [Config](group-config.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type McpRemoteServer = {
+  url: string;
+  secret?: string;
+  timeout?: `${number}s` | `${number}m` | `${number}h`;
+};
+```
+
+A remote MCP server, which the Harness reaches over Streamable HTTP. An Agent that names it in its
+`mcp` list gets the tools that its `tools` allowlist names.
+
+A server with a `secret` needs an `https://` url, because the Custodian puts the value on TLS
+only: `mcp.<name>.url must be an https:// URL`. A server with no secret can use `http://`. The
+Harness sends `Authorization: Bearer <Stand-in>`, and the Custodian of each pod whose Agents name
+the server puts the value in its place. A `secret` that the `secrets` list does not hold is
+refused when the config loads: `<file> at mcp.<name>.secret: "<NAME>" is not an entry of secrets`.
+Past `timeout`, the Harness cancels the call, and the model reads jr2's text.
+
+**Fields**
+
+- `url`: `string`
+
+  Its Streamable HTTP endpoint: `https://` when it has a `secret`.
+- `secret` (optional): `string`
+
+  A name of the `secrets` list: its bearer token. With no `hosts`, that entry is bound to the
+  url's host, in `authorization`. Default: none.
+- `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+  How long one call can run, such as `"90s"`. Default `"60s"`.
+
+**Example**
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  secrets: [{ name: "SLACK_ACME_TOKEN", value: process.env.SLACK_ACME_TOKEN }],
+  mcp: { "slack-acme": { url: "https://mcp.slack.example/mcp", secret: "SLACK_ACME_TOKEN" } },
+});
+```

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

@@ -0,0 +1,41 @@
+---
+title: McpServer
+description: "One MCP server of the Instance: a `McpRemoteServer` (`url`) or a `McpStdioServer` (`command`)."
+---
+
+# `McpServer`
+
+Type, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, in the [Config](group-config.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type McpServer = McpRemoteServer | McpStdioServer;
+```
+
+One MCP server of the Instance: a [`McpRemoteServer`](type-mcpremoteserver.md) (`url`) or a [`McpStdioServer`](type-mcpstdioserver.md)
+(`command`).
+
+**Forms**: it is one of these objects.
+
+- Form 1: `url`, `secret`, `timeout`
+
+  - `url`: `string`
+
+    Its Streamable HTTP endpoint: `https://` when it has a `secret`.
+  - `secret` (optional): `string`
+
+    A name of the `secrets` list: its bearer token. With no `hosts`, that entry is bound to the
+    url's host, in `authorization`. Default: none.
+  - `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+    How long one call can run, such as `"90s"`. Default `"60s"`.
+- Form 2: `command`, `args`, `timeout`
+
+  - `command`: `string`
+
+    A program of the Sandbox Image.
+  - `args` (optional): `readonly string[]`
+
+    Its arguments.
+  - `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+    How long one call can run, such as `"90s"`. Default `"60s"`.

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

@@ -0,0 +1,42 @@
+---
+title: McpStdioServer
+description: "A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent conversation, through jr2's spawner, inside the Agent's confinement."
+---
+
+# `McpStdioServer`
+
+Type, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, in the [Config](group-config.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type McpStdioServer = {
+  command: string;
+  args?: readonly string[];
+  timeout?: `${number}s` | `${number}m` | `${number}h`;
+};
+```
+
+A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent
+conversation, through jr2's spawner, inside the Agent's confinement. It is Workspace code: its env
+holds only the Stand-ins that the `workspace()` grants, so it has no `secret` of its own. A
+`"none"` Agent cannot name one, because its Turns run on the Instance Harness, where no Workspace
+code runs.
+
+**Fields**
+
+- `command`: `string`
+
+  A program of the Sandbox Image.
+- `args` (optional): `readonly string[]`
+
+  Its arguments.
+- `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+  How long one call can run, such as `"90s"`. Default `"60s"`.
+
+**Example**
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({ mcp: { notes: { command: "notes-mcp", args: ["--root", "/work"] } } });
+```

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

@@ -1,6 +1,6 @@
 ---
 title: NamedSecret
-description: "A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present."
+description: A secret bound to a name, never `secret(open)`.
 ---
 
 # `NamedSecret`
@@ -11,9 +11,9 @@ Type, in `@jr2/orchestrator/src/http-effect.ts`. The signature of an export, or
 type NamedSecret = Secret & { readonly [K in keyof OpenSecretMark]?: never };
 ```
 
-A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a
-secret — a dispatch's target ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)) — the secret is bound with it, to a name, so the mark
-`secret(open)` carries may not be present. One type for the definition and the binding.
+A secret bound to a name, never `secret(open)`. Where a definition's Open part is a whole that
+holds a secret — a dispatch's target ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)) — the secret is bound with it, to a name, so the
+mark `secret(open)` carries may not be present. One type for the definition and the binding.
 
 **Fields**
 

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-openbodydeclaration.md

@@ -5,7 +5,7 @@ description: "What an Open body declares: the parts that it lends a Chart, what
 
 # `OpenBodyDeclaration`
 
-Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type OpenBodyDeclaration = {

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

@@ -5,7 +5,7 @@ description: The output of an Open body.
 
 # `OpenBodyOutput`
 
-Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type OpenBodyOutput =

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`.