@jr2/orchestrator 0.5.1 → 0.6.0

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`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```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`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```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: 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."
+---
+
+# `WorktreeRefused`
+
+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 WorktreeRefused = { outcome: "refused"; reason: string };
+```
+
+No Worktree, and nothing changed: 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`

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

@@ -1,6 +1,6 @@
 ---
 title: workspace
-description: "Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one branch."
+description: "Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot."
 ---
 
 # `workspace`
@@ -20,30 +20,33 @@ function workspace<
 ): WorkspaceMachine<WithoutEmptyIndex<z.infer<TSchema>>, OutputFrom<TBody>, TBody, TSlots>
 ```
 
-Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one
-branch. The result is a Machine. Register it as a Workflow, or invoke it from another Machine as
+Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot. The result is
+a Machine. Register it as a Workflow, or invoke it from another Machine as
 an actor slot.
 
 When a run enters it, the Workspace makes the Sandbox and waits for room on a node, with no
-deadline. It clones each Repo Slot and makes its Worktree on the `branch` that `spec` gives. Then
-it runs the body with the run input plus `workspace`, the handles (see [`Workspaced`](type-workspaced.md)). The
-Agents with Working tools and the `command` Effects in the body run in that Sandbox. An Agent
+deadline. It clones each Repo Slot to `/work/<slot>/default`, on the Binding's base, and makes no
+Worktree: the body cuts each Worktree that it needs with `worktree()`. A slot that is only read
+needs no cut. No work happens in `default/`. Then it runs the body with the run input plus
+`workspace`, the handles (see [`Workspaced`](type-workspaced.md)). The Agents with Working tools and the `command` Effects in the body run in that Sandbox. An Agent
 with `workspace: "none"` runs on the Instance Harness. When the body reaches a final state, the
-Workspace deletes the Sandbox, and its output is the body's output. Push the branch before
+Workspace deletes the Sandbox, and its output is the body's output. Push each branch before
 then: jr2 deletes the Sandbox's commits with it.
 
+The author chooses how many Agents work in a Workspace. Agents in one Worktree share git, as
+people in one checkout do. Each coder that needs its own branch gets its own Worktree of the one
+clone.
+
 Leave out `repos` for a Workspace with no Repo Slot: its Agents and `command` Effects share
-`/work`, as the steps of one job share a folder, and `spec` is optional and gives only
-`workGroup`. The body's input is then `Workspaced<RunInput, never>`. An `http` Effect sends a
-file of `/work` with `file(path)`. A `push`, and a `command` with an Effect secret in its `env`,
-need a Repo Slot, so jr2 refuses them there. jr2 deletes `/work` with the Sandbox: send what
+`/work`, as the steps of one job share a folder. The body's input is then `Workspaced<RunInput, never>`. An `http` Effect sends a
+file of `/work` with `file(path)`. A `worktree()`, a `push`, and a `command` with an Effect secret in its
+`env`, need a Repo Slot, so jr2 refuses them there. jr2 deletes `/work` with the Sandbox: send what
 must stay before the body ends.
 
 Give each run a different branch, so that two runs do not push to one branch. Make it from a
 field of the run input, or from `instanceId` when the run input has no field that is different
-for each run: ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``. The input of
-`spec` holds `instanceId` with no cast, also for the door `z.object({})`. Only a root
-`workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets
+for each run: ``branch: `fix/${context.instanceId}` `` in the input of the cut. Add
+`HostInjectedInput` to the body's input type to read it. Only a root `workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets
 it only when its parent gives it.
 
 The Sandbox is Lost when its pod is evicted or its node goes. Then the body gets the event
@@ -67,7 +70,7 @@ It refuses, when you call it:
 - a body with its own `input`: ``workspace(): the body "<id>" declares its own run input, which
   nothing will ever serve or enforce — the wrapper feeds the body the run input PLUS the injected
   `workspace` handles, so the body's schema is not the door. Move it to the wrapper:
-  workspace(body, { input, spec }) (ADR-0033).``
+  workspace(body, { input }) (ADR-0033).``
 - an empty `image`: ``workspace(): `image` must be a non-empty string (got <value>) — either a
   `file:` URL to a docker context this module ships (`import.meta.resolve("./image")`) or a
   registry ref (ADR-0037).``
@@ -77,9 +80,7 @@ It refuses, when you call it:
   `repos: { app: "https://…" }` — or `open` whole, for a map the consumer names; leave it out
   for a Workspace with no Repo Slot (ADR-0051).``
 - a bad Repo Slot name or value (see [`RepoSlot`](type-reposlot.md))
-- a `spec` that is not a function, or no `spec` on a Workspace with Repo Slots: ``workspace():
-  `spec` must be a function from the run input to the spec — spec: ({ input }) => ({ branch }) —
-  and only a Workspace with no Repo Slot may leave it out (ADR-0051).``
+- a `workGroup` that is not a gid: ``workspace(): `workGroup` must be a gid (got <value>)``
 - a bad `secrets` list: ``workspace(): `secrets` must be a list of distinct names from
   jr2.config.ts's `secrets` list (got <value>) — secrets: ["JIRA_TOKEN"] (ADR-0059).``
 - a bad `effector`: ``workspace(): `effector` is { image } — a `file:` URL to a docker context
@@ -95,19 +96,16 @@ It refuses, when you call it:
   (ADR-0060)``, or the same text for `resources.limits.<key>`. The other texts are in
   [`Size`](type-size.md).
 
-And when a run enters it, a spec without a `branch` (or with `branch: "default"`), or with a bad
-`reviewSha` or `workGroup`: ``workspace spec invalid: <fields> — the spec derives from run input;
-does `jr2 run --input` carry every field this workflow's workspace() mapping reads?``. With no
-Repo Slot, a spec with a `branch` or a `reviewSha`: ``workspace spec invalid: <field> (the
-Workspace has no Repo Slot, so it has no branch and no review Worktree; its spec gives only
-workGroup) …``
+And when a run enters it, a per-run Repo Slot's mapper that gives no `url`, or a bad `ref`:
+``workspace invalid: repos.<slot> mapper returned <fields> — the mapper derives from run
+input; does `jr2 run --input` carry every field this workflow's workspace() slot reads?``
 
 **Parameters**
 
 - `body`: The Machine to run in the Sandbox. Its input is `Workspaced<RunInput, Slots>`.
 - `options` ([`WorkspaceOptions`](type-workspaceoptions.md) | [`NoSlotWorkspaceOptions`](type-noslotworkspaceoptions.md)): What the Sandbox is made of (`image`, `user`, `resources`, `effector`), the
-  Repo Slots it clones (`repos`), the Held secrets it can use (`secrets`), the run input
-  (`input`), and the function from the run input to the branch (`spec`).
+  Repo Slots it clones (`repos`), the Held secrets it can use (`secrets`), the pod's `fsGroup`
+  (`workGroup`), and the run input (`input`).
 
 **Returns**: A Machine whose input is the run input and whose output is the body's output.
 
@@ -118,8 +116,10 @@ import { z } from "zod";
 import {
   command,
   fail,
+  isReady,
   jr2Setup,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -127,23 +127,36 @@ import {
 const runInput = z.object({ ticket: z.string(), repo: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app" | "docs">;
 
+// The Worktree of this run. An Agent or a command that only reads `docs` uses `/work/docs/default`.
+const buildTree = (context: BodyInput) => `${context.workspace.repos.app}/build` as const;
+
 const passed = (output: CommandOutput): boolean =>
   output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
-  types: {} as { input: BodyInput },
+  types: {} as { input: BodyInput; context: BodyInput },
   actors: {
-    build: command(["npm", "run", "build"], { slot: "app" }),
+    cut: worktree(),
+    build: command(["npm", "run", "build"]),
     fail: fail(),
   },
 }).createMachine({
   id: "build",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "building",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: buildTree(context), branch: `fix/${context.ticket}` }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+      },
+    },
     building: {
       invoke: {
         src: "build",
+        input: ({ context }) => ({ worktree: buildTree(context) }),
         onDone: [
           { guard: ({ event }) => passed(event.output), target: "built" },
           { target: "broken" },
@@ -152,6 +165,7 @@ const body = jr2Setup({
     },
     built: { type: "final" },
     broken: { invoke: { src: "fail", input: { reason: "npm run build did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
@@ -164,7 +178,6 @@ export const machine = workspace(body, {
     app: ({ input }) => input.repo,
     docs: { url: "https://github.com/you/docs.git", ref: "main" },
   },
-  spec: ({ input }) => ({ branch: `fix/${input.ticket}` }),
 });
 ```
 
@@ -175,9 +188,12 @@ import { z } from "zod";
 import {
   command,
   fail,
+  isReady,
   jr2Setup,
   workspace,
+  worktree,
   type CommandOutput,
+  type HostInjectedInput,
   type Workspaced,
 } from "@jr2/orchestrator";
 
@@ -187,18 +203,30 @@ const passed = (output: CommandOutput): boolean =>
 // The run input has no field that is different for each run, so the branch comes from
 // `instanceId`.
 const runInput = z.object({});
+type BodyInput = Workspaced<z.infer<typeof runInput> & HostInjectedInput, "app">;
+
+const nightlyTree = (context: BodyInput) => `${context.workspace.repos.app}/nightly` as const;
 
 const body = jr2Setup({
-  types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
-  actors: { test: command(["npm", "test"], { slot: "app" }), fail: fail() },
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: { cut: worktree(), test: command(["npm", "test"]), fail: fail() },
 }).createMachine({
   id: "nightly",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "testing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: nightlyTree(context), branch: `nightly/${context.instanceId}` }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
     testing: {
       invoke: {
         src: "test",
+        input: ({ context }) => ({ worktree: nightlyTree(context) }),
         onDone: [
           { guard: ({ event }) => passed(event.output), target: "tested" },
           { target: "red" },
@@ -207,6 +235,7 @@ const body = jr2Setup({
     },
     tested: { type: "final" },
     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" } } },
   },
 });
@@ -215,7 +244,6 @@ export const machine = workspace(body, {
   input: runInput,
   image: "docker.io/library/node:24",
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: `fix/${input.instanceId}` }),
 });
 ```
 
@@ -234,10 +262,10 @@ export const machine = workspace(body, {
 function workspace<
   TBody extends AnyStateMachine,
   TSlots extends string = never,
-  TInput = unknown,
+  TInput = DoorlessInput<TBody>,
 >(
   body: TBody & BodyAcceptsSlots<TBody, TSlots>,
-  options: PermissiveWorkspaceOptions<TSlots, TInput> | PermissiveNoSlotWorkspaceOptions<TInput>,
+  options: PermissiveWorkspaceOptions<TSlots, Exclude<TInput, undefined>> | PermissiveNoSlotWorkspaceOptions,
 ): WorkspaceMachine<TInput, OutputFrom<TBody>, TBody, TSlots>
 ```
 
@@ -249,7 +277,7 @@ what it refuses.
 
 - `body`: The Machine to run in the Sandbox. Its input is the input of the Workspace plus
   `workspace`, the handles.
-- `options` ([`PermissiveWorkspaceOptions`](type-permissiveworkspaceoptions.md) | [`PermissiveNoSlotWorkspaceOptions`](type-permissivenoslotworkspaceoptions.md)): The options of the Sandbox, and `spec`. There is no `input`.
+- `options` ([`PermissiveWorkspaceOptions`](type-permissiveworkspaceoptions.md) | [`PermissiveNoSlotWorkspaceOptions`](type-permissivenoslotworkspaceoptions.md)): The options of the Sandbox. There is no `input`.
 
 **Returns**: A Machine whose input is the run input and whose output is the body's output.
 

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

@@ -0,0 +1,71 @@
+---
+title: worktree
+description: "Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there."
+---
+
+# `worktree`
+
+Function, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function worktree(options: WorktreeOptions = {}): EffectLogic<WorktreeInput, WorktreeOutput>
+```
+
+Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there. Put it
+in `actors`, and invoke it from a `workspace()` body.
+
+With `{ path, branch, from? }`, the branch resolves in this order, after a fetch: a local branch;
+`origin/<branch>`, tracked; a new branch from `from` or the Binding's base, with no upstream. With
+`{ path, detach }`, the Worktree is forced to that commit and cleaned, each time. `path` is exactly
+`/work/<slot>/<name>`. Each outcome is output: `ready`, `refused`, `unknown`.
+
+`expect` says if the branch can exist: `worktree({ expect: "new" })` refuses a branch that exists,
+and `worktree({ expect: "existing" })` refuses a branch that does not exist. A run cannot change it.
+
+A cut needs a Repo Slot. Under a Workspace with no Repo Slot, `jr2 up` refuses it, and the invoke
+fails with `worktree "<slot>" runs under a Workspace with no Repo Slot: a cut makes a Worktree of a
+Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`.
+
+**Parameters**
+
+- `options` ([`WorktreeOptions`](type-worktreeoptions.md)): Optional. `expect`, and `timeout`, how long the fetch and the cut can take.
+  Default: `"10m"`.
+
+**Returns**: The actor logic of the Effect's slot. Its output is a [`WorktreeOutput`](type-worktreeoutput.md).
+
+**Example**
+
+```ts
+import { fail, isReady, jr2Setup, worktree, type Workspaced } from "@jr2/orchestrator";
+
+type BodyInput = Workspaced<{ branch: string }, "app">;
+const tree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
+export const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: { cut: worktree({ expect: "new" }), fail: fail() },
+}).createMachine({
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".notCut" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: tree(context), branch: context.branch }),
+        // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "done" }, { target: "notCut" }],
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+  },
+});
+```
+
+**See also**
+
+- [Cut a Worktree](../../guides/cut-a-worktree.md)
+- [Workspaces](../../concepts/workspaces.md)
+- [Effects](../../concepts/effects.md)
+- [ADR-0075: A Machine cuts a Worktree, and the Workspace only clones](../decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)

package/docs/reference/authoring-surface.md

@@ -35,8 +35,8 @@ An Agent slot and the definition it carries ([ADR-0028](decisions/0028-what-an-a
 
 A Sandbox and the Repo Slots it binds ([ADR-0012](decisions/0012-workspace-wrapper-machine.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)).
 
-- [`workspace`](authoring-surface/workspace.md) (function): Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one branch.
-- [`Workspaced`](authoring-surface/type-workspaced.md) (type): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`).
+- [`workspace`](authoring-surface/workspace.md) (function): Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot.
+- [`Workspaced`](authoring-surface/type-workspaced.md) (type): 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).
 - [`Binding`](authoring-surface/type-binding.md) (type): The repository of a Repo Slot: `{ url, ref }`.
 - [`RepoSlot`](authoring-surface/type-reposlot.md) (type): The value of one Repo Slot in `workspace({ repos })`.
 
@@ -46,6 +46,7 @@ Work a Machine does outside itself, as an actor slot ([ADR-0067](decisions/0067-
 
 - [`arg`](authoring-surface/arg.md) (constant): Mark one argv entry of a `command` that the input of the Effect fills.
 - [`CommandOutput`](authoring-surface/type-commandoutput.md) (type): The output of a `command` Effect: what the `onDone` of its state gets as `event.output`.
+- [`LaterOutcome`](authoring-surface/type-lateroutcome.md) (type): A value of `outcome` that this kit does not give.
 - [`command`](authoring-surface/command.md) (function): Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
 - [`basic`](authoring-surface/basic.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`.
 - [`bearer`](authoring-surface/bearer.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret.
@@ -54,8 +55,22 @@ Work a Machine does outside itself, as an actor slot ([ADR-0067](decisions/0067-
 - [`secret`](authoring-surface/secret.md) (function): Name an Effect secret: `secret("jira")`.
 - [`text`](authoring-surface/text.md) (function): Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret("x")}` ``.
 - [`HttpOutput`](authoring-surface/type-httpoutput.md) (type): The output of an `http` Effect: what the `onDone` of its state gets as `event.output`.
-- [`push`](authoring-surface/push.md) (function): Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
+- [`push`](authoring-surface/push.md) (function): Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot.
 - [`PushOutput`](authoring-surface/type-pushoutput.md) (type): The output of a `push` Effect: what the `onDone` of its state gets as `event.output`.
+- [`branchName`](authoring-surface/branchname.md) (constant): A kit schema for a pick param that names a branch.
+- [`isReady`](authoring-surface/isready.md) (constant): Is it `ready`?
+- [`readyOf`](authoring-surface/readyof.md) (function): The `ready` output of an `onDone` arm that `isReady` guards.
+- [`worktree`](authoring-surface/worktree.md) (function): Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there.
+- [`AnyFramePath`](authoring-surface/type-anyframepath.md) (type): A Turn's Frame: a Worktree, or `/work`, stated.
+- [`AnyWorktreePath`](authoring-surface/type-anyworktreepath.md) (type): A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the slots of the body.
+- [`FramePath`](authoring-surface/type-framepath.md) (type): A Turn's Frame in a Workspace with the Repo Slots `S`.
+- [`WorktreeFound`](authoring-surface/type-worktreefound.md) (type): 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.
+- [`WorktreeInput`](authoring-surface/type-worktreeinput.md) (type): The input of a `worktree()`: a branch Worktree, or a detached one.
+- [`WorktreeOptions`](authoring-surface/type-worktreeoptions.md) (type): The options of `worktree()`.
+- [`WorktreeOutput`](authoring-surface/type-worktreeoutput.md) (type): The output of a `worktree()`.
+- [`WorktreePath`](authoring-surface/type-worktreepath.md) (type): A Worktree of the Repo Slots `S`.
+- [`WorktreeReady`](authoring-surface/type-worktreeready.md) (type)
+- [`WorktreeRefused`](authoring-surface/type-worktreerefused.md) (type): No Worktree, and nothing changed: 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.
 - [`dispatch`](authoring-surface/dispatch.md) (function): Make a `dispatch` Effect: it starts a run of a Workflow.
 - [`DispatchOutput`](authoring-surface/type-dispatchoutput.md) (type): The output of a `dispatch` Effect.
 - [`answer`](authoring-surface/answer.md) (function): Set what the Agent reads when jr2 answers its pick.
@@ -74,6 +89,7 @@ A part left Open, a Machine's parts retuned, a Pool over a Source ([ADR-0017](de
 - [`UserContainer`](authoring-surface/type-usercontainer.md) (type): The User Container in its object form: its image, and its part of the Workspace's Size.
 - [`pool`](authoring-surface/pool.md) (function): Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once.
 - [`source`](authoring-surface/source.md) (function): Declare a Source: where a `pool()` gets its work items, one at a time.
+- [`PoolNextInput`](authoring-surface/type-poolnextinput.md) (type): 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.
 
 ## Charts
 
@@ -109,7 +125,7 @@ The signature of an export, or a type here, names each of these types. They are
 - [`WithoutEmptyIndex`](authoring-surface/type-withoutemptyindex.md): The fields of the run input `T`.
 - [`PermissiveWorkspaceOptions`](authoring-surface/type-permissiveworkspaceoptions.md): The options of a `workspace()` with no `input`: it starts with any input.
 - [`PermissiveNoSlotWorkspaceOptions`](authoring-surface/type-permissivenoslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
-- [`WorkspaceHandles`](authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the branch.
+- [`WorkspaceHandles`](authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot.
 - [`ExecOutcome`](authoring-surface/type-execoutcome.md): How an exec ended.
 - [`Unknown`](authoring-surface/type-unknown.md): The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
 - [`Arg`](authoring-surface/type-arg.md): One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it.
@@ -119,11 +135,14 @@ The signature of an export, or a type here, names each of these types. They are
 - [`Secret`](authoring-surface/type-secret.md): What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`.
 - [`Text`](authoring-surface/type-text.md): What the `text` template gives: a string of literal text and Effect secrets, in order.
 - [`FromInput`](authoring-surface/type-frominput.md): A value of a file body's part: as written, or from the Effect's input.
-- [`FileBody`](authoring-surface/type-filebody.md): `file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
+- [`FileBody`](authoring-surface/type-filebody.md): `file(path, { segments?, contentType? })`: a Worktree file as an `http` body.
 - [`HttpDefinition`](authoring-surface/type-httpdefinition.md): An `http` Effect's definition.
+- [`HttpFileInput`](authoring-surface/type-httpfileinput.md): The input of an `http` Effect with a Worktree file as its body.
 - [`OpenSecret`](authoring-surface/type-opensecret.md): `secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and leaves for its composer to name (ADR-0054).
 - [`PushOptions`](authoring-surface/type-pushoptions.md): The options of `push()`.
-- [`PushInput`](authoring-surface/type-pushinput.md): The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`.
+- [`PushInput`](authoring-surface/type-pushinput.md): The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and `{ message }` with `squash`.
+- [`Duration`](authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
+- [`NameStart`](authoring-surface/type-namestart.md): What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path.
 - [`DispatchDefinition`](authoring-surface/type-dispatchdefinition.md): The definition of a `dispatch` Effect (ADR-0071).
 - [`DispatchInput`](authoring-surface/type-dispatchinput.md): A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
 - [`DispatchOpenParts`](authoring-surface/type-dispatchopenparts.md): The Open part a dispatch definition states: its target, when it is `open`.
@@ -138,10 +157,7 @@ The signature of an export, or a type here, names each of these types. They are
 - [`Sender`](authoring-surface/type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
 - [`FailureInput`](authoring-surface/type-failureinput.md): What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader.
 - [`SandboxOptions`](authoring-surface/type-sandboxoptions.md): The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
-- [`WorkspaceSpec`](authoring-surface/type-workspacespec.md): What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields.
-- [`NoSlotSpec`](authoring-surface/type-noslotspec.md): What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`.
 - [`SlotHandles`](authoring-surface/type-slothandles.md): The handles of a Workspace that declares Repo Slots.
-- [`Duration`](authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
 - [`CommandEnv`](authoring-surface/type-commandenv.md): The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a file that holds it.
 - [`TextPart`](authoring-surface/type-textpart.md): One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret.
 - [`HttpMethod`](authoring-surface/type-httpmethod.md): The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.
@@ -165,18 +181,20 @@ The signature of an export, or a type here, names each of these types. They are
 - [`ToProvidedActor`](authoring-surface/type-toprovidedactor.md)
 - [`MergedActors`](authoring-surface/type-mergedactors.md)
 - [`ToParameterizedObject`](authoring-surface/type-toparameterizedobject.md)
+- [`BindActors`](authoring-surface/type-bindactors.md)
 - [`SentByGuards`](authoring-surface/type-sentbyguards.md)
 - [`AgentLogic`](authoring-surface/type-agentlogic.md)
 - [`BodyAcceptsDoor`](authoring-surface/type-bodyacceptsdoor.md)
 - [`WorkspaceMachine`](authoring-surface/type-workspacemachine.md)
+- [`DoorlessInput`](authoring-surface/type-doorlessinput.md)
 - [`BodyAcceptsSlots`](authoring-surface/type-bodyacceptsslots.md)
 - [`EffectLogic`](authoring-surface/type-effectlogic.md)
 - [`OpenOf`](authoring-surface/type-openof.md)
 - [`EnvOpenParts`](authoring-surface/type-envopenparts.md)
 - [`OpenEffect`](authoring-surface/type-openeffect.md)
 - [`MarkedIf`](authoring-surface/type-markedif.md)
-- [`HttpInput`](authoring-surface/type-httpinput.md)
 - [`HttpOpenParts`](authoring-surface/type-httpopenparts.md)
+- [`HttpInput`](authoring-surface/type-httpinput.md)
 - [`PushWireOutput`](authoring-surface/type-pushwireoutput.md)
 - [`SyncState`](authoring-surface/type-syncstate.md)
 - [`AnswerAction`](authoring-surface/type-answeraction.md)
@@ -192,6 +210,8 @@ The signature of an export, or a type here, names each of these types. They are
 - [`PoolMachine`](authoring-surface/type-poolmachine.md)
 - [`EventFrom`](authoring-surface/type-eventfrom.md)
 - [`ArgNames`](authoring-surface/type-argnames.md)
+- [`WorktreeKey`](authoring-surface/type-worktreekey.md)
+- [`NotWorktreeKeys`](authoring-surface/type-notworktreekeys.md)
 - [`OpenSecretMark`](authoring-surface/type-opensecretmark.md)
 
 These names come from a dependency: from `zod`, `z.ZodObject`, `z.infer`, `z.ZodType`; from `xstate`, `MachineContext`, `UnknownActorLogic`, `ParameterizedObject`, `NonReducibleUnknown`, `EventObject`, `MetaObject`, `ActionFunction`, `GuardPredicate`, `DelayConfig`, `SetupReturn`, `AnyStateMachine`, `OutputFrom`, `ProvidedActor`, `AnyActorRef`, `InputFrom`, `PromiseActorLogic`.

package/docs/reference/cli.md

@@ -196,7 +196,7 @@ jr2 kit push <registry>
 
 Mirror the published kit images into a registry.
 
-The v0.5.1 kit images (harness, operator, orchestrator) from their canonical home, and the Custodian's pinned Envoy from its own, for a cluster whose `kitRegistry` names the registry.
+The v0.6.0 kit images (harness, operator, orchestrator) from their canonical home, and the Custodian's pinned Envoy from its own, for a cluster whose `kitRegistry` names the registry.
 
 **Arguments**
 

package/docs/reference/config.md

@@ -76,8 +76,9 @@ config loads: `<file> at secrets[<i>]<path>: <problem>`, followed by the shape o
 - Type: `string`
 - Required: yes
 
-As a Held secret, the name of the env var that the Harness container sees, which holds the
-Stand-in. As an Effect secret, the name that `secret("<name>")` names, and the name of the
+As a Held secret, the name of its Stand-in: the file the Harness reads it from, the env var
+that the engine reads a model key from, and the env var of the Agent's programs when the
+`workspace()` lists it under `secrets`. As an Effect secret, the name that `secret("<name>")` names, and the name of the
 Effector's file. For a Held secret, it must match `[A-Z_][A-Z0-9_]*`:
 `secrets[<i>].name "<name>" is not an env var name ([A-Z_][A-Z0-9_]*)`. It must not start with
 `JR2_` and must not be a proxy or trust variable of the kit:
@@ -377,7 +378,7 @@ checks from inside the cluster that the endpoint answers.
 
 The API key, when the endpoint needs one. Read it from `process.env`. It is a Held secret,
 `JR2_PROVIDER_API_KEY`: `jr2 up` gives the value to the Custodian only, bound to the host of
-`baseUrl`, and the Harness container holds only its Stand-in. Thus `baseUrl` must be
+`baseUrl`, and the Harness process holds only its secret Stand-in. Thus `baseUrl` must be
 `https://` when you set it:
 `harness.provider.apiKey is set, and harness.provider.baseUrl is not https://`.
 
@@ -467,6 +468,11 @@ deployments, so read it from `process.env` (`.env`).
 
 Env vars for the Harness container. The Agent can read every one of them, so do not put a
 credential here. A known model key is refused here. Put it in the top-level `secrets` list.
+The Harness process gets each one, except a name that loads code from a path, such as
+`NODE_OPTIONS` or `LD_PRELOAD`, and `HOME`, which is its own; the Agent's programs get each
+one. A name that starts with `JR2_` is jr2's own, and is refused. A credential file that the
+Harness process reads, such as `AWS_CONFIG_FILE`, is refused in a folder that the Agent's code
+writes (`/work`, `/tmp`, `/home/jr2`), and gives a warning anywhere else.
 See `HarnessEnvVar`.
 
 <a id="harness-env-name"></a>
@@ -508,7 +514,10 @@ pod as it is. A reference to a Secret of the kit is refused:
 - Required: no
 
 Secrets and ConfigMaps that you manage, whose keys all become env vars of the Harness
-container. See `HarnessEnvFromSource`.
+process and of the Agent's programs, as `env` does. In the container's spec each key has the
+prefix `JR2_ENVFROM_`, so that the Harness can tell jr2's names from the image's; the Harness
+removes it. A key that starts with `JR2_` is refused: `jr2 up` refuses it, and the Harness does
+not start with one. See `HarnessEnvFromSource`.
 
 <a id="harness-envfrom-prefix"></a>
 

package/docs/reference/decisions/0001-operator-owned-generic-sandbox.md

@@ -34,7 +34,7 @@ Sandbox will run must be in the spec at spin-up.
 
 One Harness **image** serves many **Agents** — the Harness resolves model, instructions, and its Menu at runtime without
 a rebuild, reading the definition each admission carries (ADR-0018, ADR-0049) and reading the Menu through the Custodian
-per turn (ADR-0013). So the Orchestrator injects a fixed Harness image plus **config** (env + the prepared worktree),
+per turn (ADR-0013). So the Orchestrator injects a fixed Harness image plus **config** (env + the prepared clones),
 never a per-Agent image build. The HTTP prompt body itself carries only `{message, images}`, so anything persona-shaping
 is set at provision time, not per request.
 
@@ -91,14 +91,15 @@ one keeps the name and the endpoint and costs no node anything. Deferred until a
 These are accepted gaps in the current operator, recorded so they aren't silently forgotten. Each is a deliberate
 deferral.
 
-- **Egress is not restricted.** The pod is hardened at the host boundary — `automountServiceAccountToken: false`,
-  pod/container `securityContext` (`runAsNonRoot`, `allowPrivilegeEscalation: false`, drop `ALL`, seccomp
-  `RuntimeDefault`) — and its _ingress_ is the Orchestrator's alone: `jr2 up` converges a NetworkPolicy that admits no
-  other pod to a Sandbox ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)), which kind's `kindnet`
-  enforces. Nothing yet restricts _egress_: an untrusted Agent can still reach the cluster's API server IP (it holds no
-  credential there) and the internet. A default-deny egress policy with an allowlist is the next layer, and ADR-0058
-  records it open. The ADR-0013 boundary does not depend on either: only the token bounds what a pod may _do_;
-  NetworkPolicy bounds where it may _talk_.
+- **Egress is open.** The pod is hardened at the host boundary — `automountServiceAccountToken: false`, pod/container
+  `securityContext` (`runAsNonRoot`, `allowPrivilegeEscalation: false`, drop `ALL`, seccomp `RuntimeDefault`) — and its
+  _ingress_ is the Orchestrator's alone: `jr2 up` converges a NetworkPolicy that admits no other pod to a Sandbox
+  ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)), which kind's `kindnet` enforces. _Egress_ is open
+  except for the cloud metadata addresses, which no Harness pod reaches
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)): an untrusted Agent can
+  still reach the cluster's API server IP (it holds no credential there) and the internet. A default-deny egress policy
+  with an allowlist is the next layer, and ADR-0058 records it open. The ADR-0013 boundary does not depend on either:
+  only the token bounds what a pod may _do_; NetworkPolicy bounds where it may _talk_.
 - **Sidecars are plain containers, not native sidecars.** They are scheduled as ordinary `containers`, not Kubernetes
   ≥1.29 native sidecars (`initContainers` with `restartPolicy: Always`). There is no start-ordering or
   termination-ordering guarantee between the Harness and its sidecars — the Harness may begin serving before the