@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/reference/decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md

@@ -0,0 +1,79 @@
+# jr2 requires Landlock on every Sandbox node
+
+Two boundaries of jr2 are Landlock domains. [ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
+confines the child of a credentialed `command` in the Effector, so that the Agent's code cannot read the Effector's key
+or a secret that the command does not name.
+[ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md) confines each process that the
+Harness starts in `/work`, so that no Workspace code can read the control credential and act as an Agent. On a node with
+no Landlock, neither boundary exists. A path that runs there with less confinement is a second jr2, with a weaker
+boundary, to support and to test.
+
+## Decision
+
+- **Landlock is a requirement of jr2 on every Sandbox node.** It holds where Workspace code runs, which is also where
+  the check reaches. No component has an unconfined branch, anywhere.
+- **The Repo cache agent detects it, on each Sandbox node.** The cache agent's DaemonSet has one pod on each Sandbox
+  node, by the same `nodeSelector` and `tolerations` as the Sandboxes
+  ([ADR-0052](0052-a-sandbox-lands-where-an-ordinary-pod-lands-and-the-cache-follows-it.md)). The agent probes Landlock
+  on its node. On a node without it, the agent is NotReady, and its status gives the reason.
+- **`jr2 up` refuses to converge while a Sandbox node lacks Landlock.** It reads the DaemonSet's pods (one list call),
+  and it names each Sandbox node whose cache agent reports no Landlock
+  ([ADR-0019](0019-one-converging-command-against-the-current-context.md)). The admin keeps a bad node out of the set
+  with `sandbox.nodeSelector` or a taint, as ADR-0052 says. There is still no jr2 node label.
+- **The refusal is an ordinary converge failure** (ADR-0019). It comes within the cache agent's rollout wait, which
+  `jr2 up` already makes. It names each Sandbox node without Landlock, the probe's reason, and the fix: keep the node
+  out with `sandbox.nodeSelector` or a taint (ADR-0052), or enable Landlock in its kernel. A run of `jr2 up` after the
+  fix converges.
+- **Each confining component probes at its start, and refuses to serve without it.** These are the Harness of a Sandbox
+  and the Sandbox Effector. The probe is `landlock_create_ruleset` with `LANDLOCK_CREATE_RULESET_VERSION`. This is the
+  backstop for a node that joins after the converge.
+- **No component keeps a path for a node that cannot confine a child.** ADR-0068's Effector refuses to start on such a
+  node, whatever its Workspace holds.
+- **The minimum ABI is 3.** Under ABI 1, a confined process can never move or link a file into another folder, whatever
+  the rules allow, and package managers, git and `mv` do that. ABI 2 adds the `REFER` right, so the domain can do it
+  (ADR-0076). Under ABI 2, Landlock does not handle `truncate(2)`, so a confined process can truncate a file that the
+  rules let it do nothing else to: a conversation under `/run/jr2`, which the Harness rebuilds an Agent's record from.
+  ABI 3 adds the `TRUNCATE` right, and the confiner always handles it. The confiner uses the scopes of abstract Unix
+  sockets and of signals (ABI 6) when the kernel offers them. Each probe refuses a kernel below ABI 3, with the ABI that
+  it found.
+- **The components that probe.** The cache agent probes as the detector, though it confines nothing. The Harness of a
+  Sandbox and the Sandbox Effector probe because they confine. The Instance Harness and the Instance Effector confine
+  nothing: a Menu-only Agent has no Working tools ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)),
+  and the Instance Effector runs no `command`. They do not probe.
+
+## Considered options
+
+- **A minimum of ABI 1.** Rejected: under it no confined process can move a file into another folder, which stops normal
+  work.
+- **A minimum of ABI 2.** Rejected: under it the domain can truncate a file under `/run/jr2`. One Agent's code can then
+  erase or roll back another Agent's conversation, and below ABI 6 it can end the Harness so that the Harness rebuilds
+  from the cut file. It admits Linux 5.19 to 6.1 (Debian 12's stock kernel among them), for a boundary with a hole.
+- **Refuse only a Sandbox with more than one Agent on a node without Landlock.** Rejected: it keeps a less secure
+  branch, which jr2 must then support and test.
+- **Run unconfined, with a warning.** Rejected: Workspace code can then read the control credential, and a warning does
+  not stop it.
+- **A check pod on each node at each `jr2 up`.** Rejected: it starts one pod for each node on every converge, and it
+  misses a node that joins later.
+- **One check pod, with the start-up probe as the backstop.** Rejected: a bad node shows only when a run lands there and
+  fails.
+- **jr2 labels the nodes that have Landlock, and a Sandbox requires the label.** Rejected: it reverses ADR-0052, and it
+  needs a cluster-wide permission to patch Nodes.
+
+## Consequences
+
+- **The kernels that this excludes.** Landlock ABI 3 is in Linux 6.2 and later. A node with an older kernel cannot run
+  jr2: for example RHEL 8 (4.18), Debian 11 (5.10), Debian 12 on its stock kernel (6.1), Ubuntu 20.04 and 22.04 on their
+  first kernels (5.4, 5.15), and Amazon Linux 2 (4.14 or 5.10). A distribution kernel can carry a backport: the probe,
+  not the version, decides. A newer kernel must also enable Landlock: its list of security modules (`CONFIG_LSM`, or the
+  `lsm=` boot parameter) must name `landlock`. On a node, `/sys/kernel/security/lsm` lists the modules that run.
+  Measured from a hardened pod with no capabilities: kind on WSL2 (6.6) offers ABI 3; the home cluster's arm64 nodes
+  (6.8), ABI 4; spark (6.11, arm64), ABI 5.
+- **kind on a host inherits the host's kernel.** A kind node is a container, so the kernel of the host decides. On macOS
+  or Windows, Docker runs the nodes in a virtual machine, and the kernel of that machine decides.
+- **A mixed cluster.** `jr2 up` names each Sandbox node without Landlock and refuses until the admin keeps it out of the
+  set. A node that joins after the converge shows as a NotReady cache agent. A Sandbox placed on it fails at its start,
+  because its Harness refuses to serve.
+- **The check runs when a Machine uses a Sandbox.** `jr2 up` converges the cache agent then
+  ([ADR-0051](0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)). With no Sandbox, no node needs
+  Landlock, and there is nothing to check.
+- **The docs list the requirement** where they list what jr2 needs from a cluster and from a host.

package/docs/reference/decisions.md

@@ -81,3 +81,6 @@ Each architecture decision record (ADR) says what jr2 decided, why, and what it
 | 0072 | [The docs ship inside the Kit, and an Instance's `AGENTS.md` indexes them](decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md) |
 | 0073 | [A Machine fails a run with `fail()`, and an uncaught Failure ends it `failed`](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md) |
 | 0074 | [An unrouted mechanism event is refused at load and faults the run](decisions/0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md) |
+| 0075 | [A Machine cuts a Worktree, and the Workspace only clones](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md) |
+| 0076 | [An Agent's control credential lives only where no Workspace code runs](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md) |
+| 0077 | [jr2 requires Landlock on every Sandbox node](decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md) |

package/docs/reference/glossary.md

@@ -213,7 +213,16 @@ _Avoid_: humanGate (humans are one caller among many), approval (one possible ev
 **Sender**:
 The party that delivered an event: an Agent or a Gate. Only the Orchestrator writes the Sender, on each event that a
 party delivers, and the Machine's own events have none.
-_Avoid_: origin, caller (the human or system behind a Gate)
+_Avoid_: origin, Caller (the holder of the credential behind a Gate's answer)
+
+<a id="caller"></a>
+
+**Caller**:
+The holder of a credential that acts on an Instance from outside its Machines, such as a person, a CI job or a bridge
+to a chat service: it starts a run, answers a Gate or cancels a run. A Caller can act **on behalf of** another party,
+but that is the Caller's claim, which jr2 does not check.
+_Avoid_: principal (it brings policies and roles that an Instance does not have), user (a CI job is a Caller), actor
+(xstate's word), Sender (a party inside the run)
 
 <a id="emit"></a>
 
@@ -414,7 +423,8 @@ re-prompt of an open Turn)
 
 **Working tools**:
 The file and shell tools that the Harness runs in its own container: what an Agent may do, as its Menu is what it may
-say. The Agent's access to the Workspace decides which of them it gets, and a Menu-only Agent gets none.
+say. Every program that they run, and their file I/O, is confined, so it cannot reach what the Harness itself holds. The Agent's access to
+the Workspace decides which of them it gets, and a Menu-only Agent gets none.
 _Avoid_: tools (unqualified), sandbox tools
 
 ### Sandboxes, Harnesses and secrets
@@ -463,17 +473,37 @@ firewall
 
 **Held secret**:
 A credential that the Harness uses through its pod's Custodian but never holds: a model API key above all, and the
-Sandbox token. The Harness holds only its Stand-in, so the Agent cannot take the secret out of the pod, but it can spend
-it through the Custodian while the pod lives.
+Sandbox tokens. The Harness holds only its Stand-in, so no Agent can take the secret out of the pod. Workspace code can
+spend it through the Custodian, while the pod lives, only when its Workspace grants that secret.
 _Avoid_: masked secret, injected secret, proxied key, secret (unqualified)
 
 <a id="stand-in"></a>
 
 **Stand-in**:
-The public value that the Harness holds in place of a Held secret. It means something only to the Custodian, and only
-toward a host that the secret is bound to; sent anywhere else, it arrives as it left.
+The value that the Harness holds in place of a Held secret. It means something only to the Custodian, and only toward a
+host or a route that the secret is bound to; sent anywhere else, it arrives as it left. It is secret, and only the
+Harness itself holds it: Workspace code gets a Stand-in only for a secret that its Workspace grants, and never the one
+for the control token. The one public Stand-in is the fetch token's, which can only ask for a fetch.
 _Avoid_: placeholder (an Open part's word), dummy key, fake key, token, mask
 
+<a id="sandbox-token"></a>
+
+**Sandbox token**:
+A credential that jr2 makes for one Sandbox, which its Custodian alone holds. There are two. The **control token** lets
+the Harness read each Agent's Menu and deliver its picks, for the Agent that the Harness names. The **fetch token** lets
+a process in the pod ask for a fetch of a Repo that the Sandbox holds. Each one is good only for its own work and in its
+own Sandbox, and neither one reaches a Gate.
+_Avoid_: pod token, agent token, slot token, Instance token (the Caller's credential)
+
+<a id="workspace-code"></a>
+
+**Workspace code**:
+Each process in a Sandbox whose program or input comes from the Workspace's shared files: what an Agent's Working tools
+run, tests and builds, git and what a repository's own config makes it run, and a command that a Machine runs there. Any
+Agent can run what another Agent wrote, so jr2 trusts none of it, and no credential that acts for an Agent is where
+Workspace code runs.
+_Avoid_: agent code (any Agent can run another's), user code, untrusted code (unqualified), tool process
+
 <a id="check-pod"></a>
 
 **Check pod**:
@@ -629,20 +659,29 @@ _Avoid_: role, alias, repo name, workdir, primary repo
 <a id="binding"></a>
 
 **Binding**:
-What a Repo Slot resolves to: a Repo's url and an optional base from which the Worktree is cut. With no base, the
-Worktree is cut from the Repo's own default branch.
+What a Repo Slot resolves to: a Repo's url and an optional base. The Sandbox's own clone stays on that base, and a new
+branch starts from it. With no base, both use the Repo's own default branch.
 _Avoid_: config, catalog entry
 
 <a id="project-layout"></a>
 
 **Project layout**:
 The convention for the checkouts in a Sandbox: under each Repo Slot, the Sandbox's own clone of the Repo, with the
-Worktrees beside it. The node's cache of the Repo is not part of the layout.
+Worktrees beside it. An Agent reads the clone and works in a Worktree. The node's cache of the Repo is not part of the
+layout.
 _Avoid_: directory structure, repo tree
 
 <a id="worktree"></a>
 
 **Worktree**:
-A git worktree of a Repo Slot for the one branch that its Workspace works on, beside the Sandbox's own clone. Its work
-is sequential commits on that branch, not separate worktrees; the Machine, not jr2, chooses the branch and its scope.
-_Avoid_: per-task worktree, task branch
+A git worktree of a Repo Slot, in a folder that a Machine names, beside the Sandbox's own clone. It holds one branch, or
+one commit with no branch. The Machine, not jr2, chooses how many Worktrees it cuts, their branches, and which Agents
+work in them.
+_Avoid_: checkout, task branch
+
+<a id="cut"></a>
+
+**Cut**:
+An Effect's act that makes a Worktree, or reads the one that a cut already made at that path. A cut that cannot happen
+changes nothing.
+_Avoid_: attach (the Workspace's step, which only clones), provision

package/docs/reference/http-api.md

@@ -178,8 +178,8 @@ Any token jr2 minted: the Instance token, or a Sandbox token. A Sandbox token re
 
 ### `GET /agents/:instanceId/surface`
 
-- Summary: An Agent's Menu and this Turn's Allowed picks. A Sandbox token reads only its own Sandbox's.
-- Response: [`AgentSurfaceView`](#type-agentsurfaceview)
+- Summary: An Agent's Menu, this Turn's Allowed picks and the conversation's pending notices. A control token reads only its own pod's, for the slot it states.
+- Response: [`AgentSurfaceView`](#type-agentsurfaceview) & { notices: Array<{ id, notice }> }
 - Stream: no
 - Decisions: [ADR-0013](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md), [ADR-0029](decisions/0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)
 
@@ -202,11 +202,21 @@ Any token jr2 minted: the Instance token, or a Sandbox token. A Sandbox token re
 - Stream: no
 - Decisions: [ADR-0013](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md), [ADR-0024](decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)
 
+<a id="post-agents-instanceid-notices"></a>
+
+### `POST /agents/:instanceId/notices`
+
+- Summary: Acknowledge the notices a step boundary appended to the Turn: they are heard in its conversation.
+- Body: { heard: string[] }
+- Response: { heard: number }
+- Stream: no
+- Decisions: [ADR-0062](decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md), [ADR-0076](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)
+
 <a id="post-sandboxes-name-fetch"></a>
 
 ### `POST /sandboxes/:name/fetch`
 
-- Summary: Ask the node cache to fetch one Repo that this Sandbox mounts. A Sandbox token asks only for its own.
+- Summary: Ask the node cache to fetch one Repo that this Sandbox mounts. A fetch token asks only for its own.
 - Body: { identity }
 - Response: [`FetchAnswer`](#type-fetchanswer): { fetched } | { stale, asOf }
 - Stream: no
@@ -498,6 +508,7 @@ type RunStatus = RunRecord & {
   chartHashes?: string[];
   output?: unknown;
   dispatched?: Dispatched[];
+  worktrees?: RunWorktree[];
 };
 ```
 
@@ -554,6 +565,12 @@ A run's current observable state. `fault` carries the error message when status
   The runs this run's `dispatch` Effects started, oldest first ([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)): the chain's other
   direction, read off the caller's own ledger rows. A foreign dispatch's run is a run of the
   Orchestrator its target names. Absent when it started none.
+- `worktrees` (optional): `RunWorktree[]`
+
+  The Worktrees this run's cuts made, oldest first ([ADR-0075](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), read off its ledger's settled
+  `ready` rows, so an Agent's `git switch` does not change them. A re-cut of one path and branch
+  is one entry. Behind the token, like `context`: a branch name is the workflow's data. Absent
+  when the run cut none.
 
 <a id="type-repostatus"></a>
 
@@ -632,6 +649,7 @@ type AgentSurfaceView = {
   instanceId: string;
   runId: string;
   sandbox?: string;
+  slot?: string;
   menu: SurfaceEvent[];
   allowed: string[];
 };
@@ -655,6 +673,10 @@ sandbox), and serving it lets a caller fail loudly on a surface that is not its
 - `instanceId`: `string`
 - `runId`: `string`
 - `sandbox` (optional): `string`
+- `slot` (optional): `string`
+
+  The slot this surface belongs to ([ADR-0076](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)): its Agent's actor path and agent name — the slot
+  the Harness must state to speak here. Absent on a registration no pod hosts.
 - `menu`: `SurfaceEvent[]`
 - `allowed`: `string[]`
 
@@ -951,6 +973,23 @@ ledger row was written.
 - `run`: `string`
 - `at`: `string`
 
+<a id="type-runworktree"></a>
+
+### `RunWorktree`
+
+```ts
+type RunWorktree = { slot: string; path: string; branch: string | null };
+```
+
+One Worktree a `worktree()` Effect of this run cut ([ADR-0075](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)): its Repo Slot, its path, and the
+branch of the cut. `branch` is `null` for a detached Worktree.
+
+**Fields**
+
+- `slot`: `string`
+- `path`: `string`
+- `branch`: `string | null`
+
 <a id="type-reponodestate"></a>
 
 ### `RepoNodeState`
@@ -1229,7 +1268,7 @@ How the party that sends an event gets its answer.
 
 ```ts
 type EffectDoc =
-  | { kind: "command"; argv: string[]; timeoutMs: number; slot?: string; secrets?: string[]; pin?: true }
+  | { kind: "command"; argv: string[]; timeoutMs: number; secrets?: string[]; pin?: true }
   | {
       kind: "http";
       method: string;
@@ -1244,16 +1283,15 @@ type EffectDoc =
 ```
 
 An Effect slot's parts, as the doc carries them ([ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)): a command's argv (an argv slot reads
-`<name>`), its timeout, and the Repo Slot whose Worktree is its cwd, when it names one.
+`<name>`) and its timeout. Its input names its Worktree, so the doc does not ([ADR-0075](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)).
 
 **Forms**: it is one of these objects.
 
-- Form 1: `kind`, `argv`, `timeoutMs`, `slot`, `secrets`, `pin`
+- Form 1: `kind`, `argv`, `timeoutMs`, `secrets`, `pin`
 
   - `kind`: `"command"`
   - `argv`: `string[]`
   - `timeoutMs`: `number`
-  - `slot` (optional): `string`
   - `secrets` (optional): `string[]`
   - `pin` (optional): `true`
 - Form 2: `kind`, `method`, `target`, `secrets`, `timeoutMs`, `idempotent`, `file`

package/docs/reference/machines.md

@@ -119,7 +119,6 @@ import { body, type TaskInput } from "@jr2/machines";
 
 const fixed = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: ({ input }: { input: TaskInput }) => ({ branch: input.branch ?? "jr2/fix" }),
 });
 
 export const machine = customize(fixed, {

package/docs/why.md

@@ -115,8 +115,8 @@ It talks to the model, and it runs the tools of the Agent. The Agent can run eac
 Agent that needs only its Menu has no Sandbox. Its Turns run on the
 [Instance Harness](reference/glossary.md#instance-harness).
 
-The Harness container holds no credential, so a command that an Agent runs cannot read one. jr2 keeps each credential in
-one of the two containers beside it:
+The Harness runs each command of an Agent confined with Landlock, so the command cannot read a credential, and it cannot
+send a pick for a different Agent. jr2 keeps each credential in one of the two containers beside the Harness:
 
 - The [Custodian](reference/glossary.md#custodian) holds each [Held secret](reference/glossary.md#held-secret): a key
   that the Agents can use, but cannot read. The Harness holds only a [Stand-in](reference/glossary.md#stand-in) for it.
@@ -192,8 +192,9 @@ These steps follow one run of the example Machine in the diagram. You write a Ma
 1. **You start a run.** You run `jr2 run feature`, with the ticket as the input of the run. The Machine starts in its
    first state, `code`.
 2. **The coder works in a Sandbox.** The state `code` is in a Workspace, so jr2 makes a Sandbox for it. The Sandbox
-   holds a [Worktree](reference/glossary.md#worktree) of your Repo, on the branch of the run. The coder edits the files,
-   runs the tests and commits. Then it picks `finish`, and the Machine moves to `review`.
+   holds a clone of your Repo, and the Machine cuts a [Worktree](reference/glossary.md#worktree) on the branch of the
+   run. The coder edits the files, runs the tests and commits. Then it picks `finish`, and the Machine moves to
+   `review`.
 3. **The reviewer gets a Turn.** The state `review` gives the reviewer a prompt and its Menu: `approved` and `changes`.
    The reviewer reads the change in the same Sandbox.
 4. **The reviewer picks.** If it picks `approved`, the Machine moves to `approval`. If it picks `changes`, the Machine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "The jr2 Orchestrator: xstate runtime, HTTP API and Console, and the kit pieces a Workflow imports.",
   "license": "MIT",
   "private": false,
@@ -42,11 +42,11 @@
     "ts-blank-space": "^0.9.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/agent-protocol": "0.5.1"
+    "@jr2/agent-protocol": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.5.1"
+    "@jr2/harness": "0.6.0"
   },
   "files": [
     "bin",