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