@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/agents-block.md

@@ -1,5 +1,5 @@
-jr2 is newer than your training data. Before you write a Machine or change jr2.config.ts, read the bundled docs in node_modules/@jr2/orchestrator/docs/. They are the docs of this Instance's Kit version, 0.5.1. Start with guides/write-a-workflow.md and with reference/authoring-surface.md, the contents page of the Authoring surface. Read one page with each call of your file tool, because a file tool cuts off a long output. Before you give a change to the user, run `npx --no jr2 check` in the Instance folder. It does the typecheck and the load of each Workflow that `jr2 up` does first, with no cluster, and it gives the same refusals.
+jr2 is newer than your training data. Before you write a Machine or change jr2.config.ts, read the bundled docs in node_modules/@jr2/orchestrator/docs/. They are the docs of this Instance's Kit version, 0.6.0. Start with guides/write-a-workflow.md and with reference/authoring-surface.md, the contents page of the Authoring surface. Read one page with each call of your file tool, because a file tool cuts off a long output. Before you give a change to the user, run `npx --no jr2 check` in the Instance folder. It does the typecheck and the load of each Workflow that `jr2 up` does first, with no cluster, and it gives the same refusals.
 
 A final state means that the work succeeded: the run ends `done`. When the work did not succeed, invoke `fail()` from a state (reference/authoring-surface/fail.md), and the run ends `failed`. Do not throw to fail: a throw is a defect, and the run ends `error`.
 
-[jr2 docs index]|root: ./node_modules/@jr2/orchestrator/docs|reference:{authoring-surface.md,machines.md,config.md,cli.md,http-api.md,mechanism-events.md,glossary.md,decisions.md}|reference/authoring-surface:{one file per export and type; reference/authoring-surface.md lists them}|guides:{iterate-on-a-machine-on-kind.md,write-a-workflow.md,bind-open-parts.md,set-an-agents-access-and-dials.md,run-a-command-or-call-a-url.md,push-and-sign-a-branch.md,start-a-run-from-a-run.md,add-tools-to-the-sandbox.md,size-a-workspace.md,run-one-worker-per-item.md,publish-a-machine-as-an-npm-package.md,let-an-agent-write-a-chart.md,run-a-chart-by-name.md,start-a-run.md,answer-a-gate.md,watch-a-run.md,look-inside-a-sandbox.md,cancel-a-run.md,open-the-console.md,use-a-local-model.md,use-a-hosted-provider.md,give-the-cluster-git-credentials.md,move-from-kind-to-a-shared-cluster.md,mirror-the-kit-images.md,upgrade-the-kit-version.md,clean-up.md,fix-a-failed-converge.md}|concepts:{machines-and-workflows.md,agents-and-turns.md,the-menu.md,gates.md,effects.md,workspaces.md,composition.md,charts.md,pools-and-sources.md,architecture.md,secrets-and-trust.md,converge.md,durable-runs.md}|.:{index.md,why.md}|get-started:{install.md,create-an-instance.md,connect-a-model.md,a-model-decides.md,an-agent-in-a-sandbox.md,have-your-assistant-write-a-machine.md}|reference/decisions:{one file per ADR; reference/decisions.md lists them}
+[jr2 docs index]|root: ./node_modules/@jr2/orchestrator/docs|reference:{authoring-surface.md,machines.md,config.md,cli.md,http-api.md,mechanism-events.md,glossary.md,decisions.md}|reference/authoring-surface:{one file per export and type; reference/authoring-surface.md lists them}|guides:{iterate-on-a-machine-on-kind.md,write-a-workflow.md,bind-open-parts.md,set-an-agents-access-and-dials.md,cut-a-worktree.md,run-a-command-or-call-a-url.md,push-and-sign-a-branch.md,start-a-run-from-a-run.md,add-tools-to-the-sandbox.md,size-a-workspace.md,run-one-worker-per-item.md,publish-a-machine-as-an-npm-package.md,let-an-agent-write-a-chart.md,run-a-chart-by-name.md,start-a-run.md,answer-a-gate.md,watch-a-run.md,look-inside-a-sandbox.md,cancel-a-run.md,open-the-console.md,use-a-local-model.md,use-a-hosted-provider.md,give-the-cluster-git-credentials.md,move-from-kind-to-a-shared-cluster.md,mirror-the-kit-images.md,upgrade-the-kit-version.md,clean-up.md,fix-a-failed-converge.md}|concepts:{machines-and-workflows.md,agents-and-turns.md,the-menu.md,gates.md,effects.md,workspaces.md,composition.md,charts.md,pools-and-sources.md,architecture.md,secrets-and-trust.md,converge.md,durable-runs.md}|.:{index.md,why.md}|get-started:{install.md,create-an-instance.md,connect-a-model.md,a-model-decides.md,an-agent-in-a-sandbox.md,have-your-assistant-write-a-machine.md}|reference/decisions:{one file per ADR; reference/decisions.md lists them}

package/docs/concepts/agents-and-turns.md

@@ -49,8 +49,10 @@ for one Turn, because then the name of the Agent would not tell what it is.
 ## The Working tools
 
 The [Working tools](../reference/glossary.md#working-tools) are the file and shell tools of an Agent: read, write, edit,
-bash, grep and glob. The [Harness](../reference/glossary.md#harness) runs them in its own container. The `workspace`
-field selects them:
+bash, grep and glob. The [Harness](../reference/glossary.md#harness) runs them in its own container. Each program that
+they start, and the file I/O of read, write and edit, runs confined with Landlock. It can do all that the user of the
+container can do, but it cannot read what the Harness holds. [Secrets and trust](secrets-and-trust.md) tells why. The
+`workspace` field selects the Working tools:
 
 - `"write"` gives all the Working tools.
 - `"read"` gives no write tool and no edit tool. The Agent keeps bash, so a command can still write a file. A review
@@ -69,9 +71,10 @@ The field also tells where the Turn runs. An Agent with `"write"` or `"read"` wo
 The `input` of the invoke is the Turn. It has five keys, and no other:
 
 - **The [Frame](../reference/glossary.md#frame): `prompt` and `cwd`.** The prompt tells what this Turn is about. `cwd`
-  is the directory where the Working tools work. A definition cannot hold a `cwd`, because the Worktree of a run exists
-  only when the run starts. Under a Workspace with one [Repo Slot](../reference/glossary.md#repo-slot), the default
-  `cwd` is the Worktree of that slot.
+  is the directory where the Working tools work. A definition cannot hold a `cwd`, because a Worktree exists only after
+  a run cuts it. Under a Workspace with [Repo Slots](../reference/glossary.md#repo-slot), a Turn of an Agent with
+  Working tools states its `cwd`. A Turn that wants `/work` states it too. There is no default, because a search in
+  `/work` hits `default/`, and a relative write lands outside each Worktree.
 - **The [Dials](../reference/glossary.md#dials): `model` and `thinkingLevel`.** They tell how hard the Agent works on
   this Turn, and they replace the values of the definition for this Turn only. The Agent stays the same Agent.
 - **`continue`.** It tells if the Turn continues the conversation of the Agent. See
@@ -90,7 +93,7 @@ changes, the coder continues its conversation and thinks harder on that Turn:
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const finish = defineEvent({
   name: "finish",
@@ -112,6 +115,9 @@ const runInput = z.object({ branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { summary: string; notes: string };
 
+// The Worktree of each Turn of the coder.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [finish, approve, requestChanges],
@@ -128,21 +134,30 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "fix",
   context: ({ input }) => ({ ...input, summary: "", notes: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
         // The Frame (prompt and cwd) and continue. This Turn starts the coder's conversation.
         input: ({ context }) => ({
           prompt: "Make `node --test` pass, then commit.",
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
         }),
       },
@@ -161,7 +176,7 @@ const body = jr2Setup({
         // The same conversation as in coding, with a Dial: the coder thinks harder on this Turn.
         input: ({ context }) => ({
           prompt: `The fix is not complete: ${context.notes}\nFix it, then commit.`,
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
           thinkingLevel: "high",
         }),
@@ -169,6 +184,7 @@ const body = jr2Setup({
       on: { finish: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
     },
     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" } } },
   },
@@ -177,7 +193,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -186,7 +201,7 @@ export const machine = workspace(body, {
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const finish = defineEvent({
   name: "finish",
@@ -208,6 +223,9 @@ const runInput = z.object({ branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { summary: string; notes: string };
 
+// The Worktree of each Turn of the coder.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [finish, approve, requestChanges],
@@ -224,21 +242,30 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "fix",
   context: ({ input }) => ({ ...input, summary: "", notes: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
         // The Frame (prompt and cwd) and continue. This Turn starts the coder's conversation.
         input: ({ context }) => ({
           prompt: "Make `node --test` pass, then commit.",
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
         }),
       },
@@ -257,7 +284,7 @@ const body = jr2Setup({
         // The same conversation as in coding, with a Dial: the coder thinks harder on this Turn.
         input: ({ context }) => ({
           prompt: `The fix is not complete: ${context.notes}\nFix it, then commit.`,
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
           thinkingLevel: "high",
         }),
@@ -265,6 +292,7 @@ const body = jr2Setup({
       on: { finish: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
     },
     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" } } },
   },
@@ -273,7 +301,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -355,9 +382,18 @@ itself. It tells nothing about the task: the prompt tells the task. It has two p
   carries a [Chart](../reference/glossary.md#chart), the Turn part also tells how a Chart runs (see
   [Charts](charts.md)).
 
-A notice tells the next Turn what happened before it. For example: the conversation is new and the earlier context is
-gone, or the processes of the Sandbox stopped at its memory limit. jr2 gives each notice one time, to the next Turn that
-it is for.
+A notice tells a Turn what happened before it. For example: the conversation is new and the earlier context is gone, or
+the processes of the Sandbox stopped at its memory limit. A notice about a conversation goes to the next Turn of that
+conversation. A notice about the Workspace goes to each conversation that was in the Workspace when the processes
+stopped:
+
+- A Turn that is open hears it before its next model request.
+- A continued conversation hears it at its next Turn.
+- The next Turn of the Agent whose Turn the stop cut hears it, also when that Turn is fresh.
+
+A conversation hears each notice one time. A conversation whose own bash call already told it about the stop does not
+hear the notice. A conversation that starts after the stop does not hear it, except the next Turn of the Agent whose
+Turn the stop cut.
 
 You cannot turn the Briefing off. It contains only facts that make the Agent work better. An `instructions` that tells
 the same fact again does no harm.
@@ -409,8 +445,8 @@ the model in `models`. A model with no context window gets no Compaction.
   different key.
 - A Turn cannot set `instructions` or `workspace`.
 - `cwd` is an absolute path. The Harness refuses a Turn with a relative `cwd`.
-- Under a Workspace with more than one Repo Slot, each Turn of an Agent with Working tools sets `cwd`. jr2 refuses the
-  Turn without it.
+- Under a Workspace with Repo Slots, each Turn of an Agent with Working tools sets `cwd`. jr2 refuses the Turn without
+  it.
 - An Agent with `"write"` or `"read"` runs in the body of a `workspace()`. jr2 refuses its Turn outside one.
 - `jr2 up` sees only the models of the definitions. It cannot see a model that a Turn sets as a Dial. The Harness
   refuses a model that it cannot find when the Turn starts.

package/docs/concepts/architecture.md

@@ -19,8 +19,8 @@ runs and what it does.
 ## Why the parts are separate
 
 An Agent that works on a Repo runs code. Its [Working tools](../reference/glossary.md#working-tools) give it a shell.
-With the shell, it can read each file and each variable in its container. It can also connect to each address that its
-pod can reach. Thus jr2 puts each thing that the Agent must not touch in a different place:
+With the shell, it can run each program of its image on the files in `/work`. It can also connect to each address that
+its pod can reach. Thus jr2 puts each thing that the Agent must not touch in a different place:
 
 - The control of a run is in the Orchestrator. An Agent cannot change its own Machine. It can only pick from its
   [Menu](../reference/glossary.md#menu), and the Orchestrator decides what each pick does.
@@ -28,6 +28,8 @@ pod can reach. Thus jr2 puts each thing that the Agent must not touch in a diffe
   processes. Agents in two Workspaces share no files and no ports. [Workspaces](workspaces.md) tells more.
 - The credentials are in containers in which the Agent executes nothing: the Custodian, the Effector and the Repo cache.
   [Secrets and trust](secrets-and-trust.md) tells how.
+- The Harness holds one secret value, with which it sends the picks. Each program that it starts runs confined with
+  Landlock, so the code of an Agent cannot read that value.
 
 ## What runs where
 
@@ -66,7 +68,7 @@ The [Instance Harness](../reference/glossary.md#instance-harness), the
 sections below tell when.
 
 A Sandbox pod can also have a [User Container](../reference/glossary.md#user-container), when its `workspace()` names
-one. It runs its own image, and it mounts the [Worktree](../reference/glossary.md#worktree) read-write.
+one. It runs its own image, and it mounts `/work`, with each [Worktree](../reference/glossary.md#worktree), read-write.
 [Workspaces](workspaces.md) tells more.
 
 ## On your computer
@@ -115,14 +117,15 @@ To isolate two sets of Workflows, use two Instances. Each Instance has its own n
 
 The Harness is jr2's own server for the Turns of Agents. It speaks to the model provider. It gives the model the Agent's
 Menu and its Working tools. It executes each Working tool that the model calls, and sends each pick through the
-Custodian. It holds no Agents of its own. Each Turn brings the Agent's definition with it.
-[Agents and Turns](agents-and-turns.md) tells what happens in a Turn.
+Custodian. Each program that a Working tool starts runs confined with Landlock. The Harness holds no Agents of its own.
+Each Turn brings the Agent's definition with it. [Agents and Turns](agents-and-turns.md) tells what happens in a Turn.
 
 The Harness has two placements:
 
 - **In each Sandbox.** The Harness is the primary container of the Sandbox pod, named `harness`. It runs in the
   [Sandbox Image](../reference/glossary.md#sandbox-image), and jr2 mounts the Harness into the pod at `/opt/jr2`. Thus
-  the Working tools of the Agent reach the tools of that image. An Agent that works on a Repo has its Turns here.
+  the Working tools of the Agent reach the tools of that image. Each Agent that works on a Repo has its Turns here: one
+  Harness serves all the Agents of the Sandbox.
 - **As the Instance Harness.** The Instance Harness is one StatefulSet for each Instance, `jr2-instance-harness`. Each
   Turn of a Menu-only Agent (`workspace: "none"`) runs here. Its pod has a Harness and a Custodian, and no Worktree. It
   keeps each conversation on its volume while a run can continue it. `jr2 up` converges it when a Machine of the
@@ -130,16 +133,20 @@ The Harness has two placements:
 
 A Harness answers only the Orchestrator. The Orchestrator sends a bearer token on each call, and the Harness accepts no
 call without it, except its health check. `jr2 up` also converges NetworkPolicies that let only the Orchestrator's pods
-connect to a Harness pod.
+connect to a Harness pod, and that stop each Harness pod at the cloud metadata addresses
+([Secrets and trust](secrets-and-trust.md#what-a-held-secret-does-not-stop)).
 
 ## The Custodian
 
 Each Harness pod has a Custodian: each Sandbox, and the Instance Harness. The Custodian is a container beside the
 Harness. The Agent executes no code in it. It does two things:
 
-- It carries four kinds of call from the pod to the Orchestrator: the Menu reads, the picks, the polls for the answer to
-  a pick, and the fetch asks. It sends each one with the pod's Sandbox token. These four routes are all that it
-  forwards. It refuses all other routes.
+- It carries five kinds of call from the pod to the Orchestrator: the Menu reads, the picks, the polls for the answer to
+  a pick, the reports that a step boundary gave its notices to the model, and the fetch asks. It sends the first four
+  with the control token of the Sandbox, and the fetch asks with its fetch token. These five routes are all that it
+  forwards. It refuses all other routes. The Harness sends the first four on a Unix socket in `/run/jr2`. A confined
+  program cannot make a socket there, and the Custodian refuses a request on it that does not have the control Stand-in.
+  The fetch asks go to port `8081` on loopback.
 - It holds the [Held secrets](../reference/glossary.md#held-secret) of its pod, such as a model API key. It puts the
   value into the requests that go to the hosts of each Held secret.
 
@@ -154,15 +161,16 @@ names a target. Thus a credential that an Effect uses stays out of the Harness c
 program, and it runs in a container in which the Agent executes nothing. [Effects](effects.md) tells which Effect runs
 where. It has two placements:
 
-- **The Sandbox Effector** is a container in a Sandbox pod, named `effector`. It mounts the Worktree read-only. It runs
-  a `push`, an `http` Effect whose body is a Worktree file, and a `command` that names an Effect secret. Its image is
-  the Sandbox Image, unless the `workspace()` names a different image.
+- **The Sandbox Effector** is a container in a Sandbox pod, named `effector`. It mounts `/work` read-only. It runs a
+  `push`, an `http` Effect whose body is a Worktree file, and a `command` that names an Effect secret. Its image is the
+  Sandbox Image, unless the `workspace()` names a different image.
 - **The Instance Effector** is one pod for each Instance, `jr2-instance-effector`. It runs each `http` Effect that reads
   no Worktree file, and each `dispatch` that starts a run on a different Orchestrator. It holds the Instance token of
   that Orchestrator as an Effect secret. It runs in the `jr2-harness` Kit image.
 
 Each placement exists only when a Machine of the Instance puts an Effect there. A `command` that names no Effect secret
-does not use an Effector. It runs in the Harness container of its Sandbox, with the same tools and access as the Agent.
+does not use an Effector. It runs in the Harness container of its Sandbox, with the same tools and access as the Agent,
+and confined in the same way.
 
 The Orchestrator signs each request that it sends to an Effector, and the Effector signs each answer. The Orchestrator
 only asks, and the Effector holds the credentials.
@@ -188,7 +196,8 @@ the Orchestrator stopped for longer than the Lease allows. [Workspaces](workspac
 
 The Repo cache keeps one bare clone of each Repo on each node that needs it. It is a DaemonSet, `jr2-repo-cache`, in the
 namespace of the Instance. It has one pod on each [Sandbox node](../reference/glossary.md#sandbox-node). `jr2 up`
-converges it when a Machine of the Instance uses a Sandbox.
+converges it when a Machine of the Instance uses a Sandbox. Each pod also checks that the kernel of its node has
+Landlock. On a node without Landlock, the pod is not ready, and `jr2 up` names that node and refuses to converge.
 
 The operator mounts the cache of each Repo into a Sandbox, read-only, at `/repos`. The clone in the Sandbox gets its
 objects from that cache. A `git fetch origin` in the Sandbox asks the Repo cache for a fetch. Then the Repo cache
@@ -204,6 +213,8 @@ credential to fetch.
 - A Harness accepts a call only from the Orchestrator, with the bearer of its own pod. Only its health check needs no
   bearer.
 - The Agent executes code only in the Harness container. It executes nothing in the Custodian or in the Effector.
+- In the Harness container, each program that the Harness starts runs confined. It cannot read what the Harness holds.
+- Each Sandbox node needs Landlock in its kernel. `jr2 up` refuses to converge while a Sandbox node has none.
 - The Orchestrator watches the Sandbox resources and never reads a pod. The operator puts the facts of the pod on the
   status of the Sandbox resource.
 - A Sandbox has one pod for its life. A lost pod is never made again.
@@ -226,5 +237,7 @@ credential to fetch.
   [ADR-0053](../reference/decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md),
   [ADR-0058](../reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md),
   [ADR-0059](../reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md),
-  [ADR-0063](../reference/decisions/0063-the-orchestrator-watches-the-cluster.md) and
-  [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
+  [ADR-0063](../reference/decisions/0063-the-orchestrator-watches-the-cluster.md),
+  [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md),
+  [ADR-0076](../reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md) and
+  [ADR-0077](../reference/decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md)

package/docs/concepts/charts.md

@@ -39,8 +39,10 @@ it bad text.
   and the size of the Chart in bytes.
 
 A Chart gets nothing else. A lent Effect keeps its url, its argv and its secrets, so a Chart fills only its input. A
-Chart has no url, no secret, no image and no Repo of its own. The Open body also decides where each Turn of the Chart
-runs: in the Sandbox of its `workspace()`, or on the [Instance Harness](../reference/glossary.md#instance-harness).
+lent [`worktree()`](../reference/authoring-surface/worktree.md) must state `expect`, because a Chart cannot state it. A
+Chart reads the cut with the kit guard `jr2.ready`, then gives the same literal path as `cwd` and `worktree`. A Chart
+has no url, no secret, no image and no Repo of its own. The Open body also decides where each Turn of the Chart runs: in
+the Sandbox of its `workspace()`, or on the [Instance Harness](../reference/glossary.md#instance-harness).
 
 ## What a Chart holds
 
@@ -48,7 +50,8 @@ A Chart is [xstate](https://xstate.js.org)'s own JSON config, with these limits:
 
 - States, transitions, `after` delays, and nested and parallel states. A Chart has 200 states at most, 8 levels deep.
 - Each `invoke.src` is a lent slot key or an Agent of the Chart. Each guard, action and delay is a lent name. Each Chart
-  also has the guard `jr2.failure`, which is true on an `onError` when the error is a Failure.
+  also has the guard `jr2.failure`, which is true on an `onError` when the error is a Failure, and the guard
+  `jr2.ready`, which is true on an `onDone` when the cut is `ready`.
 - A state that invokes an Agent can route [`agent.fault`](../reference/mechanism-events.md#agent-fault) in its `on`, but
   it does not have to. When no transition of the Chart takes `agent.fault`, the Open body sends it, unchanged, to the
   Chart wrapper. The wrapper's own `agent.fault` route takes it, as for an Agent of the wrapper, so one route on the

package/docs/concepts/converge.md

@@ -83,6 +83,9 @@ the cluster, see [Architecture](architecture.md).
 12. It applies the operator. For a Repo with an ssh url, it asks where the deploy key comes from.
 13. It applies the Secrets and the Orchestrator, and waits for the rollout. When the Machines need them, it also waits
     for the Repo cache, the Instance Harness and the [Instance Effector](../reference/glossary.md#instance-effector).
+    The Repo cache agent on each Sandbox node checks that the kernel of its node has Landlock, which jr2 needs. While a
+    Sandbox node has no Landlock, the converge fails. The error names each such node, the reason, and the fix: keep the
+    node out with `sandbox.nodeSelector` or a taint, or enable Landlock in its kernel. Then run `jr2 up` again.
 14. It publishes the Assembly to the Orchestrator. When the Orchestrator already has this Assembly, it publishes
     nothing.
 15. It removes the images that nothing uses now.