@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/guides/set-an-agents-access-and-dials.md

@@ -0,0 +1,420 @@
+---
+title: "Set an Agent's access and Dials"
+description: Choose what an Agent can do to the Workspace, and set the Dials and continue of one Turn.
+---
+
+# Set an Agent's access and Dials
+
+Set what an [Agent](../reference/glossary.md#agent) can do to the [Workspace](../reference/glossary.md#workspace), and
+set the [Dials](../reference/glossary.md#dials) and `continue` of one [Turn](../reference/glossary.md#turn).
+
+The definition of the Agent sets its access, in the `workspace` field of
+[`agent()`](../reference/authoring-surface/agent.md). The state that invokes the Agent sets the Dials and `continue`, in
+the `input` of the invoke. In this [Workflow](../reference/glossary.md#workflow), a reviewer reads one commit and asks
+for changes. A coder makes the changes on the branch. Then a Menu-only checker decides if the changes are complete. Save
+the file as `workflows/review.ts` in your [Instance](../reference/glossary.md#instance):
+
+**Anthropic**
+
+```ts
+import { z } from "zod";
+import { assign } from "xstate";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
+
+const approve = defineEvent({
+  name: "approve",
+  description: "Call this when the change is complete and correct.",
+  input: z.object({}),
+});
+const requestChanges = defineEvent({
+  name: "request_changes",
+  description: "Call this when the change is not complete or not correct. Say what to change.",
+  input: z.object({ notes: z.string() }),
+});
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when you committed the changes. Say what you changed.",
+  input: z.object({ summary: z.string() }),
+});
+
+// The run input: the branch, the commit to review, and an optional model for the coder's Turns.
+const runInput = z.object({ branch: z.string(), sha: z.string(), model: z.string().optional() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+type Context = BodyInput & { notes: string; summary: string };
+
+// Two Worktrees of one clone: the coder's branch, and the commit that the reviewer reads.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/work` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: Context },
+  events: [approve, requestChanges, finished],
+  actors: {
+    // "read": no write tool and no edit tool. It keeps bash.
+    reviewer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You review one commit. You do not change files.",
+      workspace: "read",
+    }),
+    // No `workspace` field: "write", all the Working tools.
+    coder: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You change code as the review asks, and you commit each change.",
+    }),
+    // "none": a Menu-only Agent. It has no Working tools, and it runs on the Instance Harness.
+    checker: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You read review notes and the summary of a change, and you decide if the change is complete.",
+      workspace: "none",
+      thinkingLevel: "low",
+    }),
+    cut: worktree(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "review",
+  context: ({ input }) => ({ ...input, notes: "", summary: "" }),
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "detaching" }, { target: "notCut" }],
+      },
+    },
+    // The second cut has no branch: the Worktree holds the commit, detached.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({
+          prompt: `Review commit ${context.sha}.`,
+          // The review Worktree holds the commit, detached from the branch.
+          cwd: reviewTree(context),
+          // A Dial: this Turn thinks harder than the default of the model.
+          thinkingLevel: "high",
+        }),
+      },
+      on: {
+        approve: "done",
+        request_changes: { target: "fixing", actions: assign({ notes: ({ event }) => event.notes }) },
+      },
+    },
+    fixing: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({
+          prompt: `Change the code on the branch as the review asks:\n\n${context.notes}`,
+          cwd: coderTree(context),
+          // Each Turn of the coder continues the same conversation.
+          continue: true,
+          // A Dial: the model of this Turn, from the run input. Absent, the model of the definition.
+          model: context.model,
+        }),
+      },
+      on: { finished: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
+    },
+    checking: {
+      invoke: {
+        src: "checker",
+        input: ({ context }) => ({
+          prompt: `The review asked for this:\n\n${context.notes}\n\nThe coder did this:\n\n${context.summary}`,
+        }),
+      },
+      on: {
+        approve: "done",
+        request_changes: { target: "fixing", actions: assign({ notes: ({ event }) => event.notes }) },
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/<you>/app.git" },
+});
+```
+
+**Local**
+
+```ts
+import { z } from "zod";
+import { assign } from "xstate";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
+
+const approve = defineEvent({
+  name: "approve",
+  description: "Call this when the change is complete and correct.",
+  input: z.object({}),
+});
+const requestChanges = defineEvent({
+  name: "request_changes",
+  description: "Call this when the change is not complete or not correct. Say what to change.",
+  input: z.object({ notes: z.string() }),
+});
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when you committed the changes. Say what you changed.",
+  input: z.object({ summary: z.string() }),
+});
+
+// The run input: the branch, the commit to review, and an optional model for the coder's Turns.
+const runInput = z.object({ branch: z.string(), sha: z.string(), model: z.string().optional() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+type Context = BodyInput & { notes: string; summary: string };
+
+// Two Worktrees of one clone: the coder's branch, and the commit that the reviewer reads.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/work` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: Context },
+  events: [approve, requestChanges, finished],
+  actors: {
+    // "read": no write tool and no edit tool. It keeps bash.
+    reviewer: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You review one commit. You do not change files.",
+      workspace: "read",
+    }),
+    // No `workspace` field: "write", all the Working tools.
+    coder: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You change code as the review asks, and you commit each change.",
+    }),
+    // "none": a Menu-only Agent. It has no Working tools, and it runs on the Instance Harness.
+    checker: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You read review notes and the summary of a change, and you decide if the change is complete.",
+      workspace: "none",
+      thinkingLevel: "low",
+    }),
+    cut: worktree(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "review",
+  context: ({ input }) => ({ ...input, notes: "", summary: "" }),
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "detaching" }, { target: "notCut" }],
+      },
+    },
+    // The second cut has no branch: the Worktree holds the commit, detached.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({
+          prompt: `Review commit ${context.sha}.`,
+          // The review Worktree holds the commit, detached from the branch.
+          cwd: reviewTree(context),
+          // A Dial: this Turn thinks harder than the default of the model.
+          thinkingLevel: "high",
+        }),
+      },
+      on: {
+        approve: "done",
+        request_changes: { target: "fixing", actions: assign({ notes: ({ event }) => event.notes }) },
+      },
+    },
+    fixing: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({
+          prompt: `Change the code on the branch as the review asks:\n\n${context.notes}`,
+          cwd: coderTree(context),
+          // Each Turn of the coder continues the same conversation.
+          continue: true,
+          // A Dial: the model of this Turn, from the run input. Absent, the model of the definition.
+          model: context.model,
+        }),
+      },
+      on: { finished: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
+    },
+    checking: {
+      invoke: {
+        src: "checker",
+        input: ({ context }) => ({
+          prompt: `The review asked for this:\n\n${context.notes}\n\nThe coder did this:\n\n${context.summary}`,
+        }),
+      },
+      on: {
+        approve: "done",
+        request_changes: { target: "fixing", actions: assign({ notes: ({ event }) => event.notes }) },
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/<you>/app.git" },
+});
+```
+
+Write your GitHub user name in place of `<you>`. Each Agent uses the model of the tab.
+
+## Set the access
+
+The `workspace` field selects the [Working tools](../reference/glossary.md#working-tools) of the Agent. It also selects
+where its Turns run. The default is `"write"`.
+
+| `workspace`         | The Working tools                            | Where the Turn runs                                                                |
+| ------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `"write"` (default) | read, write, edit, bash, grep and glob       | The [Sandbox](../reference/glossary.md#sandbox) of the Workspace                   |
+| `"read"`            | read, bash, grep and glob: no write, no edit | The Sandbox of the Workspace                                                       |
+| `"none"`            | none                                         | The [Instance Harness](../reference/glossary.md#instance-harness), with no Sandbox |
+
+An Agent with `"write"` or `"read"` works in a Sandbox. Thus invoke it in the body of a
+[`workspace()`](../reference/authoring-surface/workspace.md). An Agent with `"none"` is a Menu-only Agent. It reads its
+prompt and picks from its [Menu](../reference/glossary.md#menu). You can invoke it in the body of a `workspace()`, as
+the example does, or in a [Machine](../reference/glossary.md#machine) with no Workspace.
+
+A `"read"` Agent keeps bash, so a command can still change a file or the branch. To keep a reviewer away from the
+branch, give its Turn a detached [Worktree](../reference/glossary.md#worktree):
+
+1. Cut the Worktree with [`worktree()`](../reference/authoring-surface/worktree.md), with `{ path, detach }`.
+2. In the Turn, set `cwd` to that path.
+
+The Worktree holds the commit, with no branch. In the example, the path is `/work/app/review`, and the commit comes from
+the run input. [Cut a Worktree](cut-a-worktree.md) tells more.
+
+The access is a part of the identity of the Agent. Only the definition sets it. A Turn cannot change it.
+
+## Set the Dials of a Turn
+
+The Dials are `model` and `thinkingLevel`. Write them in the `input` of the invoke, beside the
+[Frame](../reference/glossary.md#frame) (`prompt` and `cwd`). A Dial changes only that Turn. When the Turn sets no Dial,
+it uses the value of the definition.
+
+- `thinkingLevel` is one of `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` and `"xhigh"`. In the example, the
+  definition of `checker` sets `"low"`, and the `reviewing` state sets `"high"` for the reviewer's Turn. A definition
+  with no `thinkingLevel` uses `"off"`. A model can lack a level. Then the [Harness](../reference/glossary.md#harness)
+  runs the Turn at a different level, and the printed conversation names it in a `[thinking level]` line. See
+  [Watch a run](watch-a-run.md).
+- `model` is `<provider>/<model id>`, as in the definition. In the example, the `fixing` state gives the coder the
+  `model` of the run input. When the run input has no `model`, the value is `undefined`, and the Turn uses the model of
+  the definition.
+
+Run [`jr2 up`](../reference/cli.md#up) to converge the new Workflow:
+
+```sh
+jr2 up
+```
+
+The `effects:` lines show the cut. The `seats:` lines show the picks of the three Agents.
+
+To give a model to the coder's Turns, add `model` to the run input:
+
+```sh
+jr2 run review --input '{"branch":"<branch>","sha":"<commit>","model":"<provider>/<model id>"}' --detach
+```
+
+```text
+→ context kind-jr2 / namespace my-instance
+{"runId":"48401e39-f8b2-4246-a24e-6ee2665ee892"}
+```
+
+The first line gives your kubectl context and the namespace of the Instance. `runId` is the id of the new run. Your run
+id is different.
+
+Write a new branch name for the coder in place of `<branch>`. The branch starts from the default branch of the
+[Repo](../reference/glossary.md#repo). Thus write the full id of a commit on the default branch in place of `<commit>`,
+such as its tip. [Start a run](start-a-run.md) tells how to follow the run.
+
+[`jr2 up`](../reference/cli.md#up) reads the models of the definitions. It cannot read a model that a Turn sets as a
+Dial. Thus:
+
+- The Harness checks a Dial model only when it admits the Turn. A model that it cannot find gives
+  [`agent.fault`](../reference/mechanism-events.md#agent-fault).
+- `jr2 up` gives each pod the model key of the providers that the definitions of its Agents name. For an Agent in a
+  Sandbox, use a Dial model of a provider that a definition in that Sandbox names. For a Menu-only Agent, use a provider
+  that a Menu-only definition of the Instance names.
+
+## Continue a conversation
+
+Without `continue`, each Turn starts a new conversation. With `continue: true`, the Turn continues the conversation of
+this Agent in this Machine instance. In the example, the first `fixing` Turn starts the coder's conversation. When the
+checker picks `request_changes`, the run goes back to `fixing`, and the coder continues with what it did before.
+
+Set `continue: true` on each Turn that must join the conversation. A Turn without it starts a new conversation and does
+not join.
+
+After `agent.fault` on a Turn with `continue: true`, the next Turn with `continue: true` starts a new conversation. A
+Harness restart that cut only the Turn is the exception: the conversation stays. Thus write a prompt that gives the full
+task, also on a Turn that continues. In the example, each `fixing` prompt gives the notes of the review.
+
+## Rules
+
+- jr2 refuses a Turn whose `input` has a key that a Turn does not have, such as `instructions` or `workspace`. Only the
+  definition sets those two. `<keys>` is each key that is not correct, in backticks, with a comma between them:
+  ``agent "<slot>": the Turn's input carries <keys>, which a Turn has no use for — its input is its Frame (`prompt`, `cwd`), its Dials (`model`, `thinkingLevel`), and `continue` (ADR-0057)``
+- Under a Workspace with [Repo Slots](../reference/glossary.md#repo-slot), jr2 refuses a Turn of an Agent with Working
+  tools that sets no `cwd`:
+  ``turn <id>: agent "<slot>" works under a Workspace with Repo Slots (<slots>) and its Turn framed no `cwd`: say where it works, a Worktree, or `cwd: "/work"` above them (ADR-0057)``
+- `workspace()` refuses a body with an invoke that does not say where it works, when it can read the input:
+  ``workspace(): state "<state>": "<slot>" names no `<key>`, and a Workspace with Repo Slots says where each Turn and Effect works: a Worktree, or `cwd: "/work"` for a Turn (ADR-0057)``
+- The Harness refuses a `cwd` that is not an absolute path. The run gets `agent.fault`, with this reason:
+  ``harness admission failed (400): agent "<slot>": the Turn's Frame carries a `cwd` that is not an absolute path — the Frame says WHERE this Turn works (ADR-0057), and a Turn rooted anywhere else would work in the wrong directory silently``
+- The Harness refuses a model that is not in its catalog and not a model of the custom provider. The run gets
+  `agent.fault`, with this reason:
+  `harness admission failed (400): agent "<slot>": model "<provider>/<model id>" resolves to nothing — not in pi's catalog, and no custom provider "<provider>" is configured (ADR-0018)`
+- The Harness refuses a model that is not in the form `<provider>/<modelId>`. The run gets `agent.fault`, with this
+  reason:
+  `harness admission failed (400): agent "<slot>": model "<model>" is not a <provider>/<modelId> specifier (ADR-0018)`
+- jr2 refuses a Turn of a `"write"` or `"read"` Agent outside a `workspace()`:
+  ``turn <id>: agent "<slot>" has workspace: "<access>" — invoke it inside a workspace() (ambient resolution), or pass an explicit `endpoint` (workspace-less stub path)``
+- `model` is required in each definition. A Machine from a package can leave it [Open](../reference/glossary.md#open).
+  `jr2 up` refuses an Open model that nobody bound:
+  `refusing: workflow "<workflow>" leaves Agent "<slot>" open — bind it where the Machine is registered: export const machine = customize(<import>, { agents: { <slot>: { model: "<provider>/<model>" } } })  (ADR-0054)`
+- When a Turn starts with an Open model, jr2 refuses it:
+  ``agent "<slot>" has an Open model — nobody bound it; bind it where the Machine is registered (`customize(<machine>, { agents: { <slot>: { model: "<provider>/<model>" } } })`), because a packaged Machine cannot pick a model on your behalf (ADR-0054)``
+
+## Read next
+
+- [Agents and Turns](../concepts/agents-and-turns.md): the definition, the Frame, the Dials and `continue`.
+- [Workspaces](../concepts/workspaces.md): the Worktrees.
+- [Cut a Worktree](cut-a-worktree.md): a detached Worktree for a reviewer.
+- [The Menu](../concepts/the-menu.md): the picks of an Agent.
+- [Bind a shipped Machine's Open parts](bind-open-parts.md): bind an Open model.
+- Reference: [`agent`](../reference/authoring-surface/agent.md),
+  [`AgentDefinition`](../reference/authoring-surface/type-agentdefinition.md),
+  [`ThinkingLevel`](../reference/authoring-surface/type-thinkinglevel.md),
+  [`WorkspaceAccess`](../reference/authoring-surface/type-workspaceaccess.md) and
+  [`agent.fault`](../reference/mechanism-events.md#agent-fault).
+- [ADR-0028](../reference/decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md): what an
+  Agent can do to the Workspace is a part of its definition.
+- [ADR-0057](../reference/decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md): a Turn is its
+  Frame, its Dials, and `continue`.
+- [ADR-0018](../reference/decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md): an Agent is a
+  definition.

package/docs/guides/size-a-workspace.md

@@ -0,0 +1,217 @@
+---
+title: Size a Workspace
+description: Give a Workspace the memory and cpu that its Sandbox needs, and see how jr2 divides them in the pod.
+---
+
+# Size a Workspace
+
+Give a [Workspace](../reference/glossary.md#workspace) the memory and cpu that its
+[Sandbox](../reference/glossary.md#sandbox) needs.
+
+The [Size](../reference/glossary.md#size) is the most memory and cpu that the whole Sandbox can use. jr2 reserves all of
+it on a node, so the Sandbox always has it. Write it in the `resources` option of `workspace()`. In this example, the
+[Workflow](../reference/glossary.md#workflow) `workflows/e2e.ts` runs Playwright with 4 GiB of memory and 2 cpus:
+
+```ts
+import { z } from "zod";
+import { command, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
+
+const runInput = z.object({ branch: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+// The Worktree that the tests run in.
+const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: {
+    cut: worktree(),
+    // JR2_CPUS holds the cpu limit of the container. Playwright does not read that limit.
+    e2e: command(["sh", "-c", "npx playwright test --workers=$JR2_CPUS"], { timeout: "30m" }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "e2e",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
+    testing: {
+      invoke: {
+        src: "e2e",
+        input: ({ context }) => ({ worktree: testTree(context) }),
+        onDone: [
+          {
+            guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
+            target: "passed",
+          },
+          { target: "failed" },
+        ],
+      },
+    },
+    passed: { type: "final" },
+    // Not final states: each one fails the run, and the run ends `failed`.
+    failed: { invoke: { src: "fail", input: { reason: "the Playwright tests did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  // The Size of the whole Sandbox: 4 GiB of memory and 2 cpus. jr2 reserves all of it on a node.
+  resources: { limits: { memory: "4Gi", cpu: "2" } },
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+The [Sandbox Image](../reference/glossary.md#sandbox-image) must have Playwright and its browsers.
+[Add tools to the Sandbox](add-tools-to-the-sandbox.md) tells how.
+
+## Choose the numbers
+
+A Size is `{ limits: { memory, cpu } }`, and nothing else. Each value is a Kubernetes quantity: `"4Gi"` or `"512Mi"` for
+memory, `"2"` or `"1500m"` for cpu.
+
+The kit default is memory `2Gi` and cpu `1`. It is enough for `tsc` and vitest, for `cargo build`, and for Playwright
+with 2 workers. State a larger Size for Playwright with more workers, or for a large monorepo.
+
+A larger Size is not free. The Sandbox holds all of its Size while the run waits, also at a
+[Gate](../reference/glossary.md#gate). When no node has room for the Size, the Workspace waits in the
+[Placing](../reference/glossary.md#placing) state, with no time limit. [Workspaces](../concepts/workspaces.md#placing)
+tells how to see the wait.
+
+`jr2 up` warns when no node can hold a Size now. It does not stop, because the nodes can change. For example, a kind
+node with 16 cpus cannot hold a Size of memory `64Gi` and cpu `32`:
+
+```text
+…
+sandbox nodes: jr2-control-plane
+warning: no Sandbox node right now has the allocatable for a Size of memory 64Gi, cpu 32 (workflow "e2e") — its Sandbox stays Pending until one does
+…
+```
+
+## Where the Size comes from
+
+The Size is a fact of the [Machine](../reference/glossary.md#machine). A run cannot change it. jr2 uses the first of
+these that states a Size:
+
+1. [`customize(machine, { resources })`](../reference/authoring-surface/customize.md), in the
+   [Instance](../reference/glossary.md#instance) that registers the Machine.
+2. `resources` on the `workspace()`.
+3. [`sandbox.resources`](../reference/config.md#sandbox-resources) in `jr2.config.ts`, such as
+   `sandbox: { resources: { limits: { memory: "3Gi" } } }`.
+4. The kit default.
+
+These rules apply to the order:
+
+- `customize()` writes over the Size of the `workspace()` one field at a time. Thus
+  `customize(machine, { resources: { limits: { memory: "6Gi" } } })` keeps the cpu of the Machine.
+- `sandbox.resources` applies only to a Workspace that states no Size. It never changes a Size that a Machine states.
+- A field that the chosen Size does not state comes from the kit default. For example, under
+  `resources: { limits: { memory: "4Gi" } }`, the cpu is `1`, also when `sandbox.resources` states a cpu.
+
+Use `customize()` to change the Size of a Machine from a package, such as `task` from
+[`@jr2/machines`](../reference/machines.md). See [Bind a shipped Machine's Open parts](bind-open-parts.md).
+
+## How jr2 divides the Size in the pod
+
+The pod has the Size as one limit. Inside the pod, jr2 divides it among the containers:
+
+| Container                                                         | Its part                                                                                                         |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| The [Custodian](../reference/glossary.md#custodian)               | A fixed part: memory `64Mi`, cpu `50m`.                                                                          |
+| The [User Container](../reference/glossary.md#user-container)     | The part that `user.resources` gives. With no part, it shares the rest.                                          |
+| The [Sandbox Effector](../reference/glossary.md#sandbox-effector) | No part of its own. It shares the rest.                                                                          |
+| The `harness` container                                           | The rest, as its own limit. The [Agent](../reference/glossary.md#agent)'s processes and the `command`s run here. |
+
+`jr2 up` refuses a Size that leaves the `harness` container less than `256Mi` of memory, or no cpu.
+
+To give the User Container a part, write `user` as an object:
+`user: { image: import.meta.resolve("./shell"), resources: { limits: { memory: "256Mi", cpu: "250m" } } }`. The part
+comes out of the part of the `harness` container. It is not added to the Size.
+
+The Size holds only memory and cpu. jr2 also sets these, and you cannot change them:
+
+- `/dev/shm` in the `harness` container is 25% of the container's memory, and not less than `64Mi`. It counts in that
+  memory. To get more, state a larger Size.
+- `/work` has a disk request of `10Gi`, with no limit. The disk is not part of the Size.
+
+## Use the cpus
+
+jr2 enforces the cpu limit. Many tools read the limit, such as Node's `availableParallelism()`, Go, cargo and the JVM.
+For tools that do not read it, these environment variables in the `harness` container hold its cpu limit, rounded up to
+a whole number: `JR2_CPUS`, `OMP_NUM_THREADS`, `PYTHON_CPU_COUNT` and `GOMAXPROCS`.
+
+Node's `os.cpus()` gives the cpus of the node, not the limit. Playwright uses it to choose its number of workers. Thus
+the example gives `--workers=$JR2_CPUS`. A `command` sees these variables.
+
+## When the memory is not enough
+
+The [Harness](../reference/glossary.md#harness) watches the memory of its container. Near the limit, it stops all of the
+Agent's processes. Then the Agent's `bash` call returns this text, and the Agent can try again with less:
+
+```text
+killed: memory limit (peak <peak> of <limit>); use fewer workers or a larger Size
+```
+
+The Harness also watches when no `bash` call runs. A process that a Turn left running, such as a dev server, can pass
+the limit while the workflow waits at a [Gate](../reference/glossary.md#gate). Then no `bash` call returns the text. jr2
+tells the next Agent that works in the Workspace: the next Turn, or an open Turn that jr2 asks again.
+
+The Harness can miss a fast increase. Then the kernel stops the whole container, and the
+[Turn](../reference/glossary.md#turn) faults. The reason starts with `memory limit`:
+
+```text
+memory limit (OOMKilled, limit <memory>): the Workspace's processes passed the Harness container's memory limit and the kernel killed the container, the conversation with it. Use fewer workers, or give the Workspace a larger Size (ADR-0060, ADR-0061).
+```
+
+Each conversation that was in the Workspace at the kill gets a notice of it one time, and so does the next Turn of the
+Agent whose Turn the kill cut. When you see either text again and again, state a larger Size.
+
+## Rules
+
+- `workspace()`, `customize()` and the config refuse a key other than `limits`, where you write it. `<where>` is
+  `workspace(): resources`, `customize(): resources`, `<file> at sandbox.resources`, `workspace() user.resources` or
+  `customize() user.resources`:
+  `<where>.requests is not accepted — jr2 reserves the whole Size, so every request equals its limit — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template size (ADR-0060)`
+  and
+  `<where>.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template size (ADR-0060)`.
+- They refuse a key in `limits` other than `memory` and `cpu`:
+  `<where>.limits.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template size (ADR-0060)`.
+- They refuse a value that is not a quantity more than zero:
+  `<where>.limits.memory: <value> is not a positive quantity (e.g. "2Gi", "512Mi")` and
+  `<where>.limits.cpu: <value> is not a positive quantity (e.g. "2", "1500m")`.
+- They refuse a Size, or a `limits`, that is not an object:
+  `<where>: expected an object (got <value>) — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template size (ADR-0060)`
+  and the same text for `<where>.limits`.
+- `customize()` refuses `resources` for a Machine that has no `workspace()`:
+  ``customize(): `resources` say what a SANDBOX is made of, how big it is and which Repos it attaches, and machine "<id>" composes none — only a workspace() wrapper carries those seats, that Size and those slots (ADR-0049, ADR-0037, ADR-0051, ADR-0060).``
+- `jr2 up` refuses a Size that leaves the `harness` container less than `256Mi` of memory. The text names each number
+  and where it came from. The part `− the User Container's <memory> (its user.resources.limits.memory)` is there only
+  when `user.resources` gives a memory:
+  `refusing: workflow "<workflow>": the Size leaves the Harness container <memory> memory, below its 256Mi floor: memory <size> (<source>) − the Custodian's 64Mi − the User Container's <memory> (its user.resources.limits.memory) — raise the Size's limits.memory, or shrink the User Container's split (ADR-0060)`.
+  The text can also name the Machine that states the Size, and it can end with the `customize()` line that changes the
+  Size. For cpu, the text holds `the Size leaves the Harness container no cpu:`.
+- `jr2 up` refuses a cluster that drops pod-level resources:
+  `refusing: <context> (Kubernetes <version>) drops pod-level resources — the PodLevelResources feature gate is off, and a Workspace's Size cannot hold (ADR-0060). Enable the gate on the API server and kubelets. The namespace was created; nothing else was applied.`
+
+## Read next
+
+- [Workspaces](../concepts/workspaces.md#size): the Size, and Placing.
+- [Add tools to the Sandbox](add-tools-to-the-sandbox.md): the User Container.
+- Reference: [`Size`](../reference/authoring-surface/type-size.md),
+  [`UserContainer`](../reference/authoring-surface/type-usercontainer.md),
+  [`sandbox.resources`](../reference/config.md#sandbox-resources), [`jr2 up`](../reference/cli.md#up)
+- [ADR-0060](../reference/decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md): a Workspace states
+  its Size, and jr2 reserves all of it.
+- [ADR-0061](../reference/decisions/0061-a-memory-kill-ends-the-agents-processes-not-the-harness.md): a memory kill ends
+  the Agent's processes, not the Harness.
+- [ADR-0064](../reference/decisions/0064-a-workspace-waits-for-capacity.md): a Workspace waits for capacity.