@jr2/orchestrator 0.4.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

@@ -0,0 +1,86 @@
+---
+title: Decisions
+description: Every architecture decision record of jr2, by number.
+---
+
+# Decisions
+
+Each architecture decision record (ADR) says what jr2 decided, why, and what it gave up. An ADR is updated in place: it states the latest decision. The pages of the docs link to the ADR behind a rule; the `ADR-NNNN` in a page is its number here.
+
+| ADR | Title |
+| --- | --- |
+| 0001 | [Sandboxes are provisioned by a Kubernetes operator via a generic CRD](decisions/0001-operator-owned-generic-sandbox.md) |
+| 0002 | [The agent actor is a duplex channel; its control plane is Menu tool calls](decisions/0002-duplex-streaming-actor.md) |
+| 0004 | [A Sandbox's workspace is a private local clone of a read-only cache, not a shared worktree](decisions/0004-worktree-provisioning-model.md) |
+| 0005 | [The Sandbox pod's containers: Harness, Custodian, an optional User Container, and an optional Sandbox Effector](decisions/0005-sandbox-pod-composition.md) |
+| 0006 | [The agent picks from a Machine-defined, schema-backed menu; it does not drive the workflow](decisions/0006-agent-control-surface.md) |
+| 0007 | [Durable Machine state: serializable context, live things constructed from input](decisions/0007-durable-machine-state.md) |
+| 0008 | [jr2 is a library + CLI; an Orchestrator instance hosts many workflows](decisions/0008-orchestrator-as-deployed-app.md) |
+| 0009 | [The `jr2` CLI and instance interface](decisions/0009-cli-and-instance-interface.md) |
+| 0010 | [BDD acceptance tests via Cucumber.js (black-box, scenario-isolated)](decisions/0010-bdd-acceptance-tests.md) |
+| 0011 | [Control events are workflow-defined and delivered by closure, not routed](decisions/0011-workflow-defined-events.md) |
+| 0012 | [`workspace()` wraps a body Machine and owns only Sandbox lifecycle](decisions/0012-workspace-wrapper-machine.md) |
+| 0013 | [The Agent reaches its Machine through a container it cannot read](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md) |
+| 0014 | [Observation is open; run state and control need the Instance token](decisions/0014-observation-is-open-run-state-is-not.md) |
+| 0015 | [Workflows are authored through `jr2Setup`; vocabulary and agent menus derive from the machine](decisions/0015-authoring-surface-absorbs-the-mechanism.md) |
+| 0016 | [Agent-turn mechanics are jr2-internal: ambient coordinates, host-side offsets, absorbed retries, fresh sessions](decisions/0016-agent-turn-mechanics-are-internal.md) |
+| 0017 | [The run loop is a jr2 `pool` over a generalized source port](decisions/0017-pool-over-a-source-port.md) |
+| 0018 | [The instance authors Agent definitions; jr2 assembles the Harness](decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md) |
+| 0019 | [The operational surface is one converging command against the current kube context](decisions/0019-one-converging-command-against-the-current-context.md) |
+| 0020 | [Private-CA trust is a named concept, not volume plumbing](decisions/0020-private-ca-trust-is-a-named-concept.md) |
+| 0021 | [Workspace continuity is watched; the lease asserts](decisions/0021-workspace-continuity-is-a-lease-that-answers-back.md) |
+| 0022 | [Observation is a level-triggered feed, and an API before it is a page](decisions/0022-observation-is-a-level-triggered-feed.md) |
+| 0023 | [The Harness prints the conversation, and the reasoning is the part that prints](decisions/0023-the-harness-prints-the-conversation.md) |
+| 0024 | [An Agent's turn ends with the state that asked for it](decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) |
+| 0025 | [CANCEL ends a run; stopping one parks it](decisions/0025-cancel-ends-a-run-stop-parks-it.md) |
+| 0026 | [A Turn that is over is never prompted, and only a Turn that is over answers 404](decisions/0026-a-turn-that-is-over-is-never-prompted.md) |
+| 0027 | [The Harness is jr2's own server: flue retires, the wire stays](decisions/0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md) |
+| 0028 | [What an Agent may do to the Workspace is part of its definition](decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md) |
+| 0029 | [A Menu is fixed for a conversation, and a Turn is told its Allowed picks](decisions/0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md) |
+| 0030 | [A snapshot names the Machine it was written under](decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md) |
+| 0031 | [Menu-only Agents run on the Instance Harness](decisions/0031-menu-only-agents-run-on-the-instance-harness.md) |
+| 0032 | [The Console unlocks with the Instance token, and the bands do not move](decisions/0032-the-console-unlocks-with-the-instance-token.md) |
+| 0033 | [A Machine declares the input that starts it](decisions/0033-a-machine-declares-the-input-that-starts-it.md) |
+| 0034 | [The Console renders with Preact, and the server erases the types](decisions/0034-the-console-renders-with-preact-and-the-server-erases-the-types.md) |
+| 0035 | [A runaway turn is ended by the Harness, rerolled once, then a fault](decisions/0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md) |
+| 0036 | [A turn compacts its own context mid-flight](decisions/0036-a-turn-compacts-its-own-context-mid-flight.md) |
+| 0037 | [A Sandbox Image is built or brought; jr2 injects the Harness at pod time](decisions/0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md) |
+| 0038 | [`jr2 up` builds every image it deploys, except a pinned one](decisions/0038-jr2-up-builds-every-image-it-deploys.md) |
+| 0039 | [Image garbage collects by reachability](decisions/0039-image-garbage-collects-by-reachability.md) |
+| 0041 | [A build the host already holds is not spent again](decisions/0041-a-build-the-host-already-holds-is-not-spent-again.md) |
+| 0042 | [Ready is not routable: the two calls a turn starts with re-ask a Service that has not answered](decisions/0042-ready-is-not-routable-an-admission-retries-its-connection.md) |
+| 0043 | [The kit is tested as installed: a local registry stands in for npm](decisions/0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md) |
+| 0044 | [Kit images live at a canonical home; a self-host mirrors it](decisions/0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md) |
+| 0045 | [The platform joins the image address, and the cluster chooses it](decisions/0045-the-platform-joins-the-image-address-and-the-cluster-chooses-it.md) |
+| 0046 | [A converge failure carries its diagnosis](decisions/0046-a-converge-failure-carries-its-diagnosis.md) |
+| 0047 | [The git ssh key source is the user's choice](decisions/0047-the-git-ssh-key-source-is-the-users-choice.md) |
+| 0048 | [The Orchestrator boots without its repos](decisions/0048-the-orchestrator-boots-without-its-repos.md) |
+| 0049 | [A Machine carries its parts and composes by invoke](decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md) |
+| 0050 | [What code names, config declares; what the CLI names, discovery finds](decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md) |
+| 0051 | [A Repo is a slot on the `workspace()` and a cache on the node](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md) |
+| 0052 | [A Sandbox lands where an ordinary pod lands, and the cache follows it](decisions/0052-a-sandbox-lands-where-an-ordinary-pod-lands-and-the-cache-follows-it.md) |
+| 0053 | [A fetch inside the pod asks the node cache, and the cache asks the remote](decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md) |
+| 0054 | [The kit ships Machines, and a shipped Machine leaves its parts Open](decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md) |
+| 0055 | [A release is a pushed tag, and the publish guard is the credential](decisions/0055-a-release-is-a-pushed-tag-and-the-publish-guard-is-the-credential.md) |
+| 0056 | [A global `jr2` hands off to the Instance's own, and an Instance has one Kit version](decisions/0056-a-global-jr2-hands-off-to-the-instances-own-and-an-instance-has-one-kit-version.md) |
+| 0057 | [A Turn is its Frame, its Dials, and whether it continues](decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md) |
+| 0058 | [A Harness answers the Orchestrator alone](decisions/0058-a-harness-answers-the-orchestrator-alone.md) |
+| 0059 | [A Harness holds stand-ins; the Custodian holds the keys](decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md) |
+| 0060 | [A Workspace states its Size, and jr2 reserves all of it](decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md) |
+| 0061 | [A memory kill ends the Agent's processes, not the Harness](decisions/0061-a-memory-kill-ends-the-agents-processes-not-the-harness.md) |
+| 0062 | [jr2 briefs the Agent on its seat, never on its task](decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md) |
+| 0063 | [The Orchestrator watches the cluster](decisions/0063-the-orchestrator-watches-the-cluster.md) |
+| 0064 | [A Workspace waits for capacity](decisions/0064-a-workspace-waits-for-capacity.md) |
+| 0065 | [A persist survives a crash, and history is a week](decisions/0065-a-persist-survives-a-crash-and-history-is-a-week.md) |
+| 0066 | [A `@model` tier runs a real model, and a change to what the model reads runs the tier](decisions/0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md) |
+| 0067 | [An Effect is an actor slot, and runs at most once unless marked idempotent](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md) |
+| 0068 | [An Effector holds an Effect's secrets and signs its wire](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md) |
+| 0069 | [The Orchestrator is a Kit image, and an Instance publishes its Assembly](decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md) |
+| 0070 | [A Machine lends its parts to a Chart](decisions/0070-a-machine-lends-its-parts-to-a-chart.md) |
+| 0071 | [A run starts a run through a `dispatch` Effect](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md) |
+| 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) |