@jr2/orchestrator 0.4.1 → 0.5.1

package/docs/reference/decisions/0006-agent-control-surface.md

@@ -0,0 +1,47 @@
+# The agent picks from a Machine-defined, schema-backed menu; it does not drive the workflow
+
+The control plane is Menu tool calls (ADR-0002), but **which** events an Agent may emit is scoped to the current Machine
+state and defined by the Machine, not an open set the Agent invents. The menu derives from the invoking state's
+transitions (ADR-0015 — the consumer authors no tool lists), is read by the Harness through the pod's Custodian
+(ADR-0013), and the Agent **chooses one** (controlled agency); the Machine owns the transition table. The Agent never
+steers the workflow — it answers within a frame the Machine set — and because its only control-plane peer is the
+Custodian (which holds a credential it cannot read), that frame is _enforced_, not advertised. Menus only change at turn
+boundaries, and the Harness re-reads the Menu per Submission (ADR-0013/0027), so no `list_changed` push channel is
+needed.
+
+There is no jr2-blessed event vocabulary: every menu entry is a workflow-defined event (ADR-0011).
+
+## Encode flat
+
+A named event schema must compile to a flat tagged object (an `enum` discriminator + each option's params as optionals
+
+- a validation `check`), **never a top-level `oneOf`/`anyOf`**. Measured (PoC #5b): a strict variant (→ `oneOf`/`const`
+  tool schema) is unsatisfiable for Qwen3-Coder — it serializes the tool args as a JSON string and validation fails on
+  every retry. A flat object is satisfied first try. A conditional contract ("`notes` required iff `request_changes`")
+  is enforced by jr2 after the pick, not by the tool schema.
+
+## A pick declares its input, never its answer
+
+A def states what the Agent supplies (`input`) and nothing about what comes back. Every pick is `ack`: delivered and
+answered on the same call. A pick that moves the workflow to work inside the Agent's state is answered when that work is
+done (ADR-0024), and the answer is the Machine's: the last reply since the pick, or what its `answer` action sets
+(ADR-0067). So a def has no `output` schema and no `deferred` semantics; `defineEvent` refuses both. `poll` stays
+reserved (ADR-0013).
+
+## One path: every conversation lives on the agent wire
+
+The wire has exactly one conversation surface (ADR-0027): `POST /agents/:name/:id`, resumable by `(name, iid) + offset`.
+There is no separate "workflow run" surface, and nothing on the wire forces a structured result out of a turn — the menu
+is the only structured channel. Consequences:
+
+- **All continuing, multi-turn work lives on the agent path**, driven by `agentRun` (ADR-0016).
+- **A turn that settles without a valid pick is re-prompted by jr2** — the budgeted no-signal nudge _inside_ `agentRun`
+  (ADR-0016). The workflow sees one terminal `agent.fault` on exhaustion.
+- **Self-contained, single-shot decisions** (an LLM-judge / classifier / "given this diff + this rubric, return a
+  verdict") are one-turn conversations whose menu is the verdict — the same path, not a second mechanism.
+
+## Residual
+
+Unsolicited mid-turn steering remains the hard case (ADR-0002): the menu only opens when the Agent reaches a checkpoint
+or a turn boundary. Evidence for the findings above: `poc/actor/POC-5B-FINDINGS.md`, `poc/actor/POC-5C-FINDINGS.md`
+(`poc/` is gitignored; conclusions live here).

package/docs/reference/decisions/0007-durable-machine-state.md

@@ -0,0 +1,109 @@
+# Durable Machine state: serializable context, live things constructed from input
+
+The Orchestrator is a forever-running daemon that must survive a `kill -9` and resume in-flight work, so every Machine
+has to be reconstructable from a persisted xstate snapshot. That forces one invariant across everything that runs in a
+Machine:
+
+> Machine context and actor input hold **plain serializable data only** — ids, counters, status, data-shaped handles
+> (e.g. a Sandbox's `endpoint` string). Live infrastructure — HTTP servers, clients, live actor references — is
+> **constructed per-invocation from serializable input** (ADR-0011's static-import doctrine) and never persisted.
+> Parent↔child coordination uses `sendParent` events plus serializable ids, never a held child-actor reference.
+
+PoC #7 discovered this the hard way (a live `http.Server` in context crashed `JSON.stringify`); PoC #8 was designed to
+it from the start (the top Machine keeps only counts + ids, children report completion UP via
+`sendParent('FEATURE_DONE')`). They are the same invariant — #8's discipline is precisely what makes #7's
+snapshot/restore possible.
+
+The store's own durability — what a persist survives, and how long a finished run's row lives — is
+[ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md).
+
+Durable **agent handles** do not ride Machine context at all: the host persists an `iid → admission` ledger beside the
+snapshot in the same save (ADR-0016). Iids are globally unique, so restore needs no context-tree walking to find them.
+An admission names the Turn ID of the Turn that ledgered it, because the continued Turns of one conversation share an
+iid. A restore re-attaches only that Turn (ADR-0016).
+
+**Effects** keep a **ledger** beside the snapshot in the same save (ADR-0067): one row per Effect, by its id. An
+`intent` row is written before the call — saved at the write, so the snapshot that holds the Effect and the row land
+together, before the request leaves; a `settled` row is written with the output, saved at the write before the
+transition the output drives and again in the save that carries that transition; an `aborted` row when the Effect's
+state exited while it ran, kept in memory and saved by the save that carries that exit (a cancel's final save included),
+never by a save inside the transition. A restore reads the row and never guesses: settled → the output is delivered (the
+transition's save was lost); intent → per kind: a command that names no secret re-attaches to its exec by id, or settles
+`unknown` when the Harness no longer knows it; an http call (a Worktree file body included) asks every replica of its
+Effector for its id and follows the one that holds it, and when none does it is sent again only when the author marked
+it `idempotent`, else it settles `unknown`; a push and a credentialed command ask their Sandbox Effector for their id,
+and when it no longer holds them are sent again with only the commit the intent row pinned — never the Agent's tip now —
+or settle `unknown` when no commit was pinned; no row → nothing was sent, so it starts. jr2 runs an Effect it started a
+second time only where its author marked it `idempotent`, or where its run is a function of a pinned commit (a push, a
+credentialed command); a command that names no secret never. A row replaces the one before it and is never dropped: a
+restored child that is done or stopped never starts, so no restore reads a finished Effect's row, and the settled and
+aborted rows keep the Effect's id, kind and outcome for the run's life: the record of what the run's Effects did. A
+settled row's output TAIL is dropped once the save that carries its transition is on disk — that save's snapshot no
+longer holds the Effect running, so no restore reads it, and the full stream is on the run's feed. A push row keeps its
+Repo Slot, its published commit, its source, its `squashed` and its sync's answer whole: every later push of its
+Workspace and Repo Slot sends them as one of its pairs, and the newest push's sync, when it did not finish, runs again
+(ADR-0067); git's words are its tail, and so is its bundle, except on the newest push of its Repo Slot while that push's
+sync is `busy` or `not-synced`: that row keeps the bundle, which the sync that runs again moves the branch from. Only
+the newest push's sync runs again, so once a newer push of the slot published, the older row's bundle goes at the next
+save — at most one bundle per Repo Slot. The ledger grows by one short row per Effect a run starts, never by its tails,
+and lives as long as the run's row (ADR-0065). An outstanding pick's hold is saved in the same blob and keeps its
+`chain` whole until the pick is answered (ADR-0067); that is the only place an Effect's tails accumulate.
+
+**Pending timers** do not ride the snapshot either. The host persists a **timer table** beside it in the same save: one
+row per pending `after`, named delay, delayed `raise` or delayed `sendTo` in the run's tree, with its absolute deadline.
+The author writes plain xstate `after`; there is no kit timer actor, and `after` is refused nowhere.
+
+## Mechanism (the non-obvious parts)
+
+- **Re-attach is driven by the child's persisted input, not the parent `invoke`.** On restore, xstate v5 re-spawns an
+  invoked actor from its **persisted input** — it does **not** re-evaluate the parent's `invoke: { input: … }`. So the
+  re-attach lever is rewriting the child's persisted input on hydrate (drop `prompt`, mark it attaching) so the run
+  resumes its stream instead of re-POSTing. Keep the parent-side input expression as defence-in-depth, but know it is
+  not what fires on restore.
+- **A timer is re-armed by the host, because xstate 5 drops it.** xstate 5 keeps a delayed event on the actor SYSTEM's
+  scheduler, not in the snapshot, and a restore runs no entry action again, so a pending `after` never fires after a
+  restore (Pool's `pollEvery` included, ADR-0017). At each save the host reads the scheduler's table and writes each
+  timer as `{ source, target, id, event, delay, deadline }`, actors named by their child-id path below the root. The
+  deadline is a time on the host's wall clock (`RunHostOptions.now`, `Date.now` by default; tests pass one that does not
+  step). On restore the order is: `start()`, then re-arm each row with `deadline − now` clamped to `[0, delay]`, in
+  deadline order. Re-armed before `start()`, a timer is armed twice, because the system's own `start()` schedules its
+  table. The id is xstate's own, so a state's exit after the re-arm cancels a re-armed timer. `start()` drains the
+  mailbox, so a child that sends on start can exit a state before any row is re-armed; the host records each cancel
+  during `start()` and does not re-arm a row it names. A child stopped during `start()` is stopped with xstate's
+  `cancelAll`, which sees an empty table, and its parent state entered again puts a new child at the same path; so the
+  host resolves each row's actors before `start()` and re-arms a row only on the same actors after it. So a timer fires
+  once, after the time that remained; at once if its deadline passed while the Orchestrator was down, and timers that
+  are all overdue fire in the order they fell due; never if an exit cancelled it, before the save, during `start()` or
+  after the re-arm; and never later than its own delay when the wall clock went backwards. A wall clock that jumped
+  forwards fires it early: only the wall clock survives a process. "Once" is with respect to the saved state: a timer
+  that fired after the last save fires again on restore, as any event after the last save replays. A delayed send to an
+  actor outside the run's tree is not recorded; jr2 has no such idiom.
+- **The re-arm reads an xstate internal** (`system.getSnapshot()._scheduledEvents`, `system.scheduler.schedule`, and
+  `system.scheduler.cancel`, wrapped for the length of `start()`; `packages/orchestrator/src/timers.ts`). The same two
+  scheduler functions are also wrapped for the life of the run's system, to tell a timer that fires from an event an
+  actor sends at once: both reach the inspection stream alike, and the scheduler forgets a timer as it fires it. An
+  outstanding pick's stopped answer needs that difference (ADR-0024). Raw-xstate tests that show xstate itself dropping
+  the timer are the canary for an xstate bump. xstate 6 persists timers in the snapshot and re-arms them with the same
+  deadline and clamp; on xstate 6 the timer table is deleted.
+- **Reconcile against the live world before re-attaching.** Restore is not blind resume: a present Sandbox CR →
+  re-attach; an absent one → the defined failure path (`workspace.lost` into the body — ADR-0012), never a silent
+  re-provision.
+- **Reconcile against the MACHINE too** (added 2026-08-02,
+  [ADR-0030](0030-a-snapshot-names-the-machine-it-was-written-under.md)). "Reconstructable from a persisted snapshot"
+  was only ever true of the Machine that WROTE it, and a run resolves its workflow by filename while the state volume
+  outlives the image — so a run parked across a deploy meets whatever was baked in next. The snapshot now carries a
+  digest of its Machine's shape, and a mismatch is refused rather than interpreted. This is not belt-and-braces: xstate
+  accepts a `value` naming a state the chart no longer has and starts with `value: undefined`, so nothing downstream
+  would have caught it.
+
+## Consequences
+
+- Actors may not stash live connections in context for convenience; anything live is rebuilt per-invocation from
+  serializable input (the Harness client from an `endpoint`, the kube client from ambient config) — which is also why a
+  mock↔real swap happens at the wire (ADR-0011's stub Harness), never inside actor code.
+- An Effect has no at-most-once sliver: its intent row is on disk before the call leaves, so a restart either finds no
+  row (nothing was sent) or finds the intent and settles `unknown` when it cannot re-attach — or, for an http call the
+  author marked `idempotent` that no replica holds, sends it again under the same id.
+- The known durability edge stands for Agents: a crash between "run admitted" and "admission persisted" degrades to an
+  at-most-once re-POST (a live-run probe replays from `-1`; a genuinely-absent run re-POSTs), and an in-flight POST at
+  the instant of the kill is the irreducible at-most-once sliver.

package/docs/reference/decisions/0008-orchestrator-as-deployed-app.md

@@ -0,0 +1,60 @@
+# jr2 is a library + CLI; an Orchestrator instance hosts many workflows
+
+jr2 ships as a **library** (engine + agent-protocol) and a **CLI** (`jr2`). You don't build a workflow into its own
+image. Instead you `jr2 init` an **Orchestrator instance** — a small, user-owned _code_ project (a folder) that imports
+the kit, configures it, and holds one or more **workflows** (Machines authored via `jr2Setup`, ADR-0015). One instance
+hosts **many** workflows; the CLI publishes that instance's workflow modules to a running Orchestrator as its Assembly
+([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). The instance folder is the
+**jr2 Application** — the GitOps unit; the same folder/manifests run on kind locally and on a real cluster.
+
+Machine definitions are **code, not declarative config.** We rejected expressing machines as YAML/CRD config: a useful
+agentic Machine is mostly logic (guards, prompt-building, `assign`s), and a declarative form becomes a DSL-over-xstate
+that loses type-safety and still cannot express branching. The instance is a code project (it imports `@jr2/*`), so
+"code, not config" survives — machine definitions simply live in the user's instance folder rather than baked into the
+kit. The rule has one deliberate complement: a human writes code, and what a RUN supplies is data — a Chart bound into a
+Machine's Open body ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)) carries no logic of its own.
+
+## The Orchestrator instance
+
+An instance is a **stateful, single-writer daemon**: it holds the live in-memory xstate actors, so it runs `replicas: 1`
+and persists its snapshots to sqlite on its volume (ADR-0009, ADR-0065). `replicas: 1` means single _writer_ (no
+split-brain on the snapshot) — **not** one workflow per process. One instance registers N workflows and **hosts many
+runs** of any of them. Work arrives two ways that both reduce to injecting events into an actor: a **Source** (pull,
+ADR-0017) and the **HTTP API** (push) — so push/pull coexist with no special machinery. Isolation or independent scaling
+is achieved by running **another instance**, not by replicating one run; the default is one instance, many workflows.
+
+## The Harness stays on the Agent side
+
+The Agent/Sandbox Harness is jr2's own server, `@jr2/harness` (ADR-0002/0018/0027) — and the Orchestrator is **not** a
+harness: its state is an xstate snapshot, not an agent session, and its loop is a deterministic state machine, not an
+LLM-in-harness. The two share ergonomics, not implementation: the instance folder convention (`jr2.config.ts` + the
+discovered `workflows/` dir — the Agents ride the Machines it holds, ADR-0049), the `jr2` CLI as the primary interface,
+and an HTTP API shaped as "durable run addressed by id" (`POST` to start/feed, `GET /…/:id` for status, SSE for events)
+— so both sides of the system speak one protocol without sharing a runtime.
+
+## The Orchestrator pod
+
+It is sized and prioritised like the other control pods (ADR-0060: requests 500m and 1Gi, memory limit 1Gi, CPU
+unlimited, the `jr2-control` PriorityClass), keeps its store on its own volume (ADR-0065), and carries two probes on
+`/healthz`. Readiness (2s period, 15 failures) takes a stalled process out of its Service after 30s and does nothing
+else: a `replicas: 1` writer that is restarted is an outage plus a restore, so a GC pause or a busy node must never
+trigger one. Liveness (10s period, 30 failures) restarts a process that has answered nothing for five minutes: a process
+silent that long is not stalled but dead, and without it the pod would sit NotReady until a human deleted it, while a
+process that exits is restarted by the container's restart policy regardless.
+
+## Consequences
+
+- The deployable unit is the Orchestrator **Kit image** plus the instance's **Assembly**, which `jr2 up` publishes to
+  the running Orchestrator ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md);
+  a CI-only `jr2 build` is planned), run as one `replicas: 1` `Deployment` + `Service`. The two-repo pattern (instance
+  code → Assembly; manifests → GitOps) is expected, and the instance folder carries both.
+- Concrete workflows do **not** live in the jr2 source repo — only the kit, the Machines it ships (`@jr2/machines`,
+  ADR-0054), and the `templates/default` model instance do. A user's workflows live in their `jr2 init` instance folder.
+- jr2 ships and deploys only its **`Sandbox` operator** (its own CRD), deployed once per cluster. The snapshot store is
+  sqlite on the Instance's own volume (ADR-0065); the model backend is a **dependency you provide** — jr2 points at it
+  (model env), it does not own or operate it. Instances are deployed per user/project.
+- Users interact through the **`jr2` CLI** far more than raw HTTP; the HTTP API is the machine-to-machine surface (push
+  work, human-in-the-loop, status) the CLI itself sits on top of.
+- Code is never loaded dynamically: only `jr2 up` publishes an Assembly, typechecked on the host first
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). A run may bind a
+  Machine's Open body with a Chart, which is data ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)).

package/docs/reference/decisions/0009-cli-and-instance-interface.md

@@ -0,0 +1,275 @@
+# The `jr2` CLI and instance interface
+
+ADR-0008 fixed that jr2 is a library + CLI and that an Orchestrator instance is a user-owned folder hosting many
+workflows. This ADR fixes the **instance folder convention**, the **orchestrator HTTP API**, and the **`jr2` CLI** — one
+set of conventions both sides of the system speak. Operational mechanics (how `jr2 up` converges a cluster, addressing,
+secrets) live in ADR-0019.
+
+## Instance folder convention (filename discovery)
+
+```
+my-orchestrator/
+  jr2.config.ts     # instance config: reach and credentials — harness, git.credentials, registry; nothing a Machine names (ADR-0050)
+  workflows/       # filename-discovered: workflows/review.ts (contract: export const machine) → "review"
+  images/default/  # the fallback docker context a `workspace()` with no `image` uses (ADR-0037); a path convention, not discovery
+  manifests/       # user-supplied objects applied by `jr2 up` (e.g. SealedSecrets); optional
+  .env             # local secrets + deployment-varying env; uncommitted
+  .jr2/             # scratch; nothing durable lives on the host (state is in-cluster, ADR-0019)
+```
+
+`workflows/<name>.ts` registers a workflow named `<name>` via `export const machine` — the one-export module contract
+(ADR-0015; vocabulary rides the machine object, so there is no manifest export). Workflows are the one discovered kind
+because nothing in code names one: `jr2 run` and the API do. Agents, images, and Repos are named from Machines, so they
+ride the Machine — Agent slots, `workspace()` options, Repo Slots (ADR-0049, ADR-0051) — and nothing in config names
+them (ADR-0050).
+
+**The instance repo is a deployment assembly, not a sharing unit** (ADR-0019): reusable workflows/agents are published
+as npm packages and re-exported here; `jr2.config.ts` holds only what is specific to this deployment's reach,
+credentials, and cluster — committed, because the instance repo is the GitOps unit (ADR-0008), with deployment-varying
+values resolved from env.
+
+## Minimum config, and the Repo cache
+
+`jr2.config.ts` favors convention over configuration — an Instance whose Machines compose Sandboxes can be as small as:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  name: "my-orchestrator",
+  git: { credentials: [{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }] }, // narrow before untrusted runs
+});
+```
+
+- **`name` is the instance's identity**; its namespace defaults to it (`-n` overrides — ADR-0019).
+- **There is no `repos` list.** A Repo is a slot on a `workspace()`, bound by url (ADR-0051); `jr2.config.ts` holds what
+  reaches one — `git.credentials`, the prefix-matched list that is also the fence a per-run slot's url must pass. The
+  scaffold writes one wildcard entry, commented, for the user to narrow (ADR-0051). The operator keeps a bare cache per
+  node from the `Repo` resources the Orchestrator creates off its Machines (ADR-0004); Sandboxes clone `--shared`
+  against it. There is no host-side directory — a Repo pods should see must be fetchable from the cluster.
+- **A registered Machine that composes a Sandbox is the data-plane switch** (ADR-0051), read off `jr2 up`'s walk: with
+  one, the instance gets the kubectl Sandbox backend; without one, the instance is workspace-less. There is **no
+  `images` config block**: `jr2 up` builds every image it deploys and resolves each to a content-addressed tag
+  ([ADR-0038](0038-jr2-up-builds-every-image-it-deploys.md)). Image composition is per Workspace, not per instance — a
+  `workspace()` names its Sandbox Image statically (a `file:` docker context the Machine ships or a registry ref,
+  [ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md),
+  [ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)) and opts into a User Container the same way
+  ([ADR-0005](0005-sandbox-pod-composition.md)); `images/default` is the one path convention `jr2 up` still checks.
+  Every Harness pod gets a Custodian — an Agent without one cannot act (ADR-0013, ADR-0059) — and that is not
+  configurable. Agent-runtime concerns live in `harness` (ADR-0018).
+- **`harness` is the agent-runtime section** (ADR-0018): custom provider (`api`, `baseUrl`), the gateways pi's catalog
+  providers call (`catalog`) and any other env — never which model to use; each definition names its own (ADR-0018).
+- **`secrets` is the Instance's one list of secrets**
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)): the credentials the Agents use — an
+  Anthropic key, read from `process.env`/`.env`, held by the Custodian and never by the Harness (ADR-0059) — and the
+  ones an Effect names, which only its Effector holds. Where each goes is read, never declared.
+- **`registry`** (deployment-varying, resolve from env): absent → images are `kind load`-ed; present → pushed
+  (ADR-0019). **`kitRegistry`** (also env) re-homes the published Kit image refs for self-hosted, air-gapped, or
+  mirror-only clusters ([ADR-0044](0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md)).
+- **The snapshot store is sqlite** on a PVC in the instance's namespace (zero setup); no other store is owed
+  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md)) — the single-table, single-writer snapshot fits
+  sqlite, and `replicas: 1` keeps it single-writer.
+- Git credentials for private repos: an HTTPS token from `.env`, or a `jr2-git-ssh` Secret holding the key `jr2 up`
+  asked the user to choose — a generated in-cluster deploy keypair (the recommended default), a local key, or one pasted
+  on stdin (ADR-0019, [ADR-0047](0047-the-git-ssh-key-source-is-the-users-choice.md)). Kube target: the current
+  `kubectl` context (`--context` to override).
+
+## Machines ship as npm; instances compose or customize
+
+The kit publishes to npm under `@jr2/*`; stock Agent definitions ship in **`@jr2/agents`** (coder, reviewer, …), and a
+package may ship whole Machines with their Agents and image inside (ADR-0049). Because a definition is plain data
+(ADR-0018), composition needs no API: a Machine carries `agent(coder)`, a workflows file exports a packaged Machine
+as-is or through `customize(machine, { agents: { coder: { model: "…" } } })`. Adding tools/skills waits on the
+definition contract growing that seat (ADR-0018).
+
+## Orchestrator HTTP API (hono, run-addressed-by-id)
+
+Push + control + observe only — the **pull** path needs no HTTP (the Orchestrator's Source pulls, ADR-0017). Auth bands
+per ADR-0014: structure + observation open; the Agent surface takes the Sandbox token; run state, control, and gates
+take the Instance token.
+
+```
+GET  /workflows                        # list registered workflows                       [open]
+GET  /workflows/:name/machine  /viz/*  # machine structure + visualizer                  [open]
+GET  /workflows/:name/runs[, /:runId/events]  # observation projection (ADR-0014)        [open]
+GET  /workflows/:name/events           # SSE: the whole workflow, level-triggered (ADR-0022) [open]
+POST /workflows/:name/runs             # start a run (push work); body = input → { runId } [instance]
+GET  /runs   GET /runs/:runId          # live list; durable run status (read-through)    [instance]
+GET  /runs/resolve?prefix=<p>          # run ids sharing a prefix, live + settled        [instance]
+GET  /runs/:runId/events               # SSE: status replay + live deltas                [instance]
+POST /runs/:runId/events               # run-level infra interrupt: CANCEL               [instance]
+POST /runs/:runId/gates/:gate/events   # deliver a workflow event to an open gate        [instance]
+GET  /repos                            # per-Repo node-cache sync state (ADR-0048)        [instance]
+GET  /agents/:iid/surface   POST /agents/:iid/events   # the Menu, via the Custodian    [sandbox]
+POST /sandboxes/:name/fetch                            # the ask (ADR-0053)             [sandbox]
+GET  /healthz   GET /readyz
+```
+
+`GET /repos` is [ADR-0048](0048-the-orchestrator-boots-without-its-repos.md)'s observability half: a failed clone
+degrades the Repo, not the boot, so each `Repo` resource's status (per node: synced, or git's own error) is a thing to
+ask the instance for, read off the resources (ADR-0051). `jr2 status` with **no** run id renders it — the place
+ADR-0047's "register the key, the cache agent retries" points at. Instance band, not open: a row names a Repo and
+carries git's error text, exactly the class of author/deployment detail the open projections strip (ADR-0014).
+
+Gates are the human/webhook/CI seam (ADR-0011): a gated state registers `{ gate, accepts, meta }`; `GET /runs/:runId`
+lists the open gates (with schemas + `meta`), and the gate POST validates the body against the named event schema and
+delivers it into that state. Per-gate addressing exists because concurrent children park concurrently — a run-level
+events POST is ambiguous. `CANCEL` is the one reserved run-level event; everything else is workflow vocabulary. It
+**ends** the run — its Agents' turns end with it and it does not restore
+([ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)).
+
+## The `jr2` CLI
+
+```
+# lifecycle (instance)
+jr2 init [dir] [--name <n>]        # scaffold the minimum runnable instance
+jr2 check                          # the typecheck and the Machine walk of `up`, with no cluster (ADR-0050)
+jr2 up [--yes] [--force] [--skip-provider-preflight]
+                                   # converge the current context to this instance (ADR-0019)
+jr2 down [--all] [--yes]           # remove the instance from the cluster (--all: operator too)
+jr2 gc [--dry-run]                 # sweep unreachable labeled images — the same sweep up/down run (ADR-0039)
+
+# kit (instance-less)
+jr2 kit push <registry>            # mirror the published Kit images into a self-hosted registry (ADR-0044)
+
+# what runs where
+jr2 version [--local] [--json]     # this jr2, the global that handed off, the Instance's Kit, and what the cluster runs
+
+# runs / workflows (wrap the HTTP API)
+jr2 run <workflow> [--input <json>] [--detach]
+jr2 runs   jr2 status [runId|abbrev]   jr2 logs <runId|abbrev> [-f]   # bare `status` = the instance's repos (ADR-0048)
+jr2 send <runId|abbrev> --event CANCEL
+jr2 send <runId|abbrev> --gate <gate> --event <name> [--input <json>]
+
+# workspaces (kubectl-style, over the operator's Sandbox CRs) — decided, not yet in the binary
+jr2 ls                             # list workspaces + run + status + endpoint
+jr2 ssh <workspace>                # exec into the Sandbox's harness container (ADR-0037)
+jr2 logs <workspace>   jr2 rm <workspace>
+```
+
+`jr2 ssh` is `kubectl exec -c harness` into the Sandbox Image
+([ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md)) — the inspect seat: the agent's own
+tools, worktrees, and filesystem. The optional User Container ([ADR-0005](0005-sandbox-pod-composition.md)) is reached
+by its own front door (its sshd, or `kubectl exec -c user`), not by this verb — its point is sessions and services the
+agent's container must not host.
+
+The CLI is the everyday surface; HTTP is the machine-to-machine one. The workspace verbs make the orchestrator feel like
+`kubectl` for agents: the run↔workspace link rides on the CR's labels (`jr2.dev/run`, `jr2.dev/workflow`), so `jr2 ls`
+can group without the orchestrator being reachable. CLI and hono app sit on one shared API client.
+
+A planned `jr2 build` (build + push + render manifests, no apply — the pure-GitOps CI verb) is deferred; `jr2 up` in CI
+covers the interim (ADR-0019).
+
+## Settled CLI behavior (v1)
+
+**Instance addressing.** The CLI finds its instance by walking up from cwd to the directory containing `jr2.config.ts` —
+the root marker. The _deployment_ is addressed by the current kube context + the instance's namespace: run-verbs
+port-forward the Orchestrator Service for the duration of the command and read the Instance token from its in-cluster
+Secret (kube RBAC is the gate). `--url` / `JR2_URL` (+ token env) overrides both — the ingress-exposed/remote-caller
+case — and skips the folder walk entirely. Every run-verb prints the context it targets on stderr, so ambient-context
+drift is visible (ADR-0019).
+
+**The command table.** Each verb is an entry in `packages/cli/src/command-table.ts`: its arguments, its flags, the env
+vars it reads, what it prints, and its ADRs, as data. The verb's `parseArgs` options come from its entry, and so does
+the help, so a flag cannot be accepted and not documented, or documented and not read. `jr2 --help` prints the whole
+table. `jr2 <verb> --help` or `-h` prints that verb's entry, runs nothing, and exits 0. A usage error prints the verb's
+usage line. The CLI Reference of the docs is generated from the same table
+([ADR-0072](0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md)).
+
+**Two output classes (amended 2026-09-20).** The stream rule below — JSON result on stdout, activity on stderr — was
+written for `jr2 run`, whose reason is the pipe: `jr2 run … | jq` must yield the result alone. It generalises to every
+**result verb** — `run`, `runs`, `status <runId>`, `logs`, `kit push` — because their result is small and the stderr
+lines beside it are advisory. It does not generalise to a **report verb** — `version`, and `status` with no run id —
+whose output is a diagnosis a human reads whole: dual-printing there shows a JSON blob and a partial table, and the
+readable form exists nowhere. So a report verb prints its human table on **stdout**, and `--json` swaps the table for
+the one object. No `isatty` sniffing: output that changes with how it is invoked is a debugging trap of its own. `init`,
+`check`, `up`, `down`, `gc` and `send` are neither class — activity only, no result.
+
+**`jr2 version` (amended 2026-09-20).** The report you paste into a bug: what is _here_ and what is _deployed_, side by
+side, so the gap between the halves is the answer ("you edited the pin and never ran `jr2 up`"). The local half: `cli`
+(the copy that runs — version + real path, so the path says global or Instance), `global` (the copy that handed off,
+ADR-0056), `kit` (the `@jr2/orchestrator` the Instance resolves + the ADR-0056 check result, and
+`package.json pins X, reinstall` when the manifest disagrees with what is installed), `instance` (name, root, and mode:
+kit checkout or installed from which registry — the reader needs the mode to know whether deployed Kit tags are versions
+or content hashes), `node`. The deployed half, best-effort: `orchestrator` (what the pod answers on `/healthz` —
+version + hash, flagging a Deployment label that disagrees as an incomplete rollout), `operator` (its version label —
+never downgraded, so no skew verdict on it), `harness`/`custodian` and any Sandbox Image refs from the `jr2-images`
+ConfigMap pods actually read, and one `skew` verdict comparing the two kit numbers: `same`/`behind`/`ahead`/`unknown`,
+with the `jr2 up` consequence spelled out and, in checkout mode, a reminder that `same` is weak and the hash is the
+address. Nothing is computed that `jr2 up` computes: no bundle staging, no local hash. It is the one Instance verb that
+reads the Instance without asserting it — a Kit mismatch is a line, never the ADR-0056 refusal, because this is the verb
+you reach for when that refusal fires. It hands off like every verb. The shared addressing flags (`--url`, `-n`,
+`--context`) as every run verb; `--url` leaves only the orchestrator line; `--local` skips the cluster. Exit 0 whatever
+it finds: a report. No registry lookup: "out of date" here means behind the Instance, and `npm view` answers the other
+question.
+
+**`jr2 check`.** It runs the Instance check of `jr2 up` and nothing more. First it runs the Instance's own
+`tsc --noEmit`. Then it loads each registered Workflow and walks its Machine. The load and the walk find the refusals
+that the compiler cannot make: a refusal of `createMachine`, `defineEvent` or `workspace()` when a module loads, an Open
+part, a Chart file, a dispatch, an Effect secret, a Size. It reads no kube context. It touches no cluster, docker or
+registry, and it writes no file. When it refuses, it exits 1 with the `refusing:` or `error:` line of `jr2 up`. It is
+one function with `jr2 up` (`checkInstance`), not a copy, so the two cannot disagree.
+
+It is for an Assistant that may not run `jr2 up`. `npm run typecheck` loads no module. And `node` cannot import a
+workflow module of an installed Instance. The kit's `.ts` sources are under `node_modules`, and Node does not strip
+types there. The `jr2` binary strips them. The scaffold names `jr2 check` as its `check` script. The AGENTS.md block
+names it as the step before the Assistant gives a change to the user (ADR-0072).
+
+It does not stage the Assembly. Staging installs the production dependencies from the lockfile, and its refusals are
+about that install. It also does not write the AGENTS.md block. An Assistant or CI must be able to run a check with no
+diff as a result.
+
+**`jr2 run` — blocking, attach-by-default.** Start the run, stream activity to **stderr**, print the terminal
+`RunStatus` as JSON to **stdout**, exit — so `jr2 run … | jq` yields just the result. It **attaches to the running
+orchestrator**, not a temporary per-invocation runtime — a jr2 run is durable and may park on a Gate indefinitely,
+outliving the CLI call. `--detach` starts the run, prints its `runId`, returns.
+
+**Attach / detach / re-attach.** A run lives server-side, so attaching = opening `GET /runs/:runId/events` and detaching
+= closing it (Ctrl-C); neither affects the run. `jr2 logs <runId> -f` re-attaches to any running run. On attach, the SSE
+**replays the run's current status immediately** (so a parked run shows where it is) before streaming live deltas; it
+carries `status` events (auto, per transition) and `emit` events (the workflow author's `emit({…})`).
+
+**Terminal runs stay readable.** The final snapshot persists to the store before the run drops from the live registry,
+so `status` / `GET /runs/:runId` **read through to the store** — a completed run reports its terminal status/context
+instead of `404`. (`GET /runs` stays live-only; history via `?all` is deferred.)
+
+**Run ids abbreviate to a unique prefix.** A run id is a bare uuid, so every id-taking verb takes a git-style short
+form: `jr2 status 1a2b3c4d`. **Prefix only** — not fuzzy, not suffix — which keeps it an indexed range scan and keeps
+the mental model borrowed intact. Four characters is the floor, and that floor is about **noise, not safety**: a short
+prefix never resolves to the wrong run, it resolves to a list. Safety comes from ambiguity being an error — matching
+more than one id prints the candidates and fails (exit 1), never guesses. A malformed or too-short argument is a usage
+failure (exit 2); a full id short-circuits resolution entirely, so scripted pipelines issue unchanged traffic.
+
+**The CLI resolves; the addressed routes stay full-id.** Abbreviation is a human affordance and lives on the human
+surface — `GET /runs/resolve` answers prefix→ids, and the CLI then addresses the run by its full id. `/runs/:runId` and
+both event POSTs never accept a prefix, because **a prefix is not an identity**: one that resolves today goes ambiguous
+tomorrow when an unrelated run starts, and `jr2 send <prefix> --event CANCEL` is a write. Resolving as a separate
+read-only step is what guarantees no write is ever prefix-sensitive. (It also gives a bad id a real error: `host.stop()`
+returns silently for an unknown run, so an unresolved CANCEL used to report success.)
+
+The candidate set is the ids that **exist**, not the ones that read: `lost` runs are included, because dropping them
+would let a prefix they share with a live run resolve silently to the live one. The set unions the live registry with
+the store — neither alone is complete, since `persist()` is microtask-scheduled (a just-started run is live before it is
+stored) and a settled run is stored but not live. Note the deliberate tension with `GET /runs`'s deferred `?all`: this
+route does reveal that settled run **ids** exist to an Instance-token holder. It answers ids only — no status, no
+context, no gates — to keep that widening as small as the feature allows, and it is Instance-only rather than open,
+since prefix probing on an open route would be a run-id enumeration oracle.
+
+**`jr2 init` (v1).** Scaffolds the minimum runnable instance: `jr2.config.ts` (root marker), `package.json` (deps on
+`@jr2/*` + xstate), one starter `workflows/<name>.ts`, `images/default/Dockerfile` (the Sandbox Image every Workspace
+falls back to, ADR-0037), `.gitignore` (`.jr2/`, `.env`, `node_modules/`), and `AGENTS.md` with a `CLAUDE.md` that
+imports it (the index of the Kit's bundled docs for an Assistant, ADR-0072). `[dir]` positional (default cwd); `--name`
+for the package name (default: the folder's name). It skips each file that exists, and says so; for an `AGENTS.md` with
+no markers, or a `CLAUDE.md` that does not import `AGENTS.md`, it also says what to add. `manifests/` and `.env` are
+added by their later slices. No auto-install — it prints the next step, naming no package manager, since the instance's
+lockfile is what picks one ([ADR-0043](0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md)).
+
+## Consequences
+
+- The instance-facing packages (`@jr2/cli`, `@jr2/orchestrator`, `@jr2/agent-protocol`) publish to npm; `@jr2/harness`
+  ships inside a Kit image, never via npm
+  ([ADR-0043](0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md)). The CLI ships as the `jr2`
+  bin (`npx jr2`).
+- Workspaces are a first-class CLI resource backed by the operator's `Sandbox` CRs, label-linked to their runs.
+- Code is never loaded from a third party at run time (ADR-0008, ADR-0069): discovery is over the instance's own
+  Assembly, which only `jr2 up` publishes. A run may bind a Machine's Open body with a Chart, which is data (ADR-0070).