@jr2/orchestrator 0.4.1 → 0.5.1

package/docs/reference/decisions/0036-a-turn-compacts-its-own-context-mid-flight.md

@@ -0,0 +1,138 @@
+# A turn compacts its own context mid-flight
+
+The retired flue runtime compacted a conversation automatically; the
+[ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md) rewrite dropped it without recording the
+loss. `packages/orchestrator/src/config.ts` kept declaring `contextWindow` for a reader that no longer existed. This ADR
+is the unrecorded regression, decided.
+
+The failure is live, not projected. Run `588b0f5e` (`task-with-review`, a real bug hunt on a 131k window) investigated
+for 161 tool calls at ~800 tokens each, filled the window, and ended mid-sentence with no menu pick. The no-signal
+nudges then continued the SAME conversation with zero headroom: nudge 1 produced 0 tokens, nudge 2 produced one token,
+the budget went dry, and the run took the terminal `agent.fault` to a humanReview park. Once a context is full every
+conversation-continuing recovery is structurally futile — [ADR-0016](0016-agent-turn-mechanics-are-internal.md)'s nudge
+ladder cannot work there. The endpoint clamped its output rather than erroring, so the observable shape is a truncated
+`stopReason`, not a 400.
+
+**The window filled MID-turn**, and that decides the seat. jr2's shape is one long agentic turn per Submission
+([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)), so context grows in the middle of a
+Turn, not between Turns. pi-agent-core 1.x has no Compaction and keeps no conversation on disk, so jr2 owns both: the
+engine part ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md), `engine/pi/transcript.jsonl`) and the cut
+over it. pi's loop gives the seat: its `prepareRequest` hook runs before each provider request, and the context it
+returns is the context of that request and of the rest of the run.
+
+**Compaction** enters the vocabulary as the cut itself, not the act of summarizing: what the model still sees, replaced
+by a summary plus a retained tail.
+
+## Decision
+
+- **The seat is the engine's request hook, and the write goes to the engine part.** The hook is `beforeRequest` at the
+  engine seam (ADR-0027), which the pi adapter runs from pi's `prepareRequest`. It fires before every provider request,
+  the first one included, with the run's own abort signal. The engine part is complete at that moment: the Harness
+  appends each message the loop completes before the loop goes on, and pi has appended the pending messages (the prompt,
+  a steered message) before it calls the hook. The hook estimates the context tokens of the engine part against the
+  model's `contextWindow`; over the threshold it prepares the cut, asks for the summary, appends the compaction entry to
+  the engine part, and returns the rebuilt context, so the request that noticed is already compacted. Firing on a turn's
+  first request is what rescues the nudge ladder: a nudge is a fresh admission on the same conversation (`actor.ts`), so
+  it compacts before it asks. `settleAbandonedMessage` runs in the seam's `convertToLlm` hook, over each array that is
+  sent — including a rebuilt one, since the engine part stores an aborted assistant message verbatim.
+- **The algorithm is jr2's, ported from pi-agent-core 0.82.1.** Where the cut goes, which messages the summary covers,
+  the split turn, the file lists, and every text the summarizer reads (its system prompt, the summary and update
+  prompts, the serialized conversation) are pi 0.82.1's, byte for byte; replay fixtures from pi 0.82.1's own code pin
+  them. The engine part marks where each Submission starts, and the cut reads that mark as pi 0.82.1 read the tool-set
+  entry it wrote at the same place: a cut at a Submission's prompt is a split turn, whose prefix is the Submission
+  before it.
+- **The thresholds are jr2-owned, derived, and have no author surface.** `reserve = max(16384, model.maxTokens)`, with
+  flue's small-window floor (`reserve × 2 ≥ contextWindow → max(1024, contextWindow / 3)`); `keepRecentTokens` 20000.
+  The derivation is deliberate: the threshold is checked BEFORE a request that may emit up to `maxTokens`, so a reserve
+  smaller than one full response does not reserve anything. pi's flat 16384 and flue's `min(20000, maxTokens)` — which
+  shrinks the reserve as the model gains room — are both wrong for the live rig's 32768. The values and the algorithm
+  are jr2's, in `compaction.ts` beside the derivation that reads them; pi has none — so a pin bump cannot move when
+  compaction fires, and the shipped arithmetic is what the unit tier proves; `TurnDeps` carries test seams only, exactly
+  like `stepBudget`. A model with no declared `contextWindow` resolves to 0 and **compaction is off** — said out loud
+  here, because silently inert is how the original regression hid.
+- **`contextWindow` is not a compaction knob.** It sits beside `maxTokens` in the provider spec as a fact about an
+  endpoint jr2 cannot enumerate. Compaction reads it. It stops being inert without becoming an author surface, and no
+  new config field appears.
+- **The summarizer is the Turn's own model and the Turn's own thinking level.** The model because a Dial says how hard
+  to run this Turn ([ADR-0018](0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)) and mechanism
+  inherits; a separate compaction model would need its own provider entry, its own boot validation, and its own
+  unresolvable-model failure at the moment context is already full. The thinking level because overriding it would be
+  half of that same argument, and no evidence says otherwise yet. **The summarizer carries the run's abort signal** —
+  the hook's own — so a sweep does not wait on a summary jr2 no longer wants
+  ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)'s promotion ordering). **jr2's summary call
+  states its retry budget (2) and calls pi-ai's `retryAssistantCall` itself**: the Turn's own stream `maxRetries` never
+  reaches this call. A compaction that fails after those retries settles the Submission `failed` as an ADR-0016
+  **infra** fault — no new fault class: a legible compaction failure beats walking into an overflow that surfaces as
+  truncation. The failure words stay pi 0.82.1's (`Summarization failed: …`), and jr2 owns them now.
+- **The retained tail is NOT stored on the compaction entry** — the index of its first kept entry (`firstKept`) alone;
+  that is the engine part's format. An entry that carried its tail would stop the branch walk AT that entry, so the next
+  cut could not find its first kept entry on the walk and would neither summarize nor retain the previous cut's tail: up
+  to `keepRecentTokens` of the MOST RECENT work, deleted at every cut past the first. With `firstKept` alone the walk
+  stops there, the rebuilt context is `[summary, ...tail, ...after]`, and the next cut can reach the tail and summarize
+  it. jr2's mid-turn regime cuts repeatedly on one conversation, so this matters at every cut past the first.
+- **Visible in the pod log, invisible on the wire.** The printer gets one line
+  ([ADR-0023](0023-the-harness-prints-the-conversation.md)) — a reader of 161 tool calls needs the point where the agent
+  stopped being able to see the first 120, or an agent that forgets what it read at step 20 reads as a defect. Nothing
+  else: no `StreamEvent` type (the durable stream's one consumer is `wait`, and a compaction settles nothing), no
+  history entry, nothing on the ADR-0014 open band. The asymmetry is the point — mechanics narrate, they do not surface.
+  jr2's history is unaffected by construction: it records what was said, while compaction changes only what the model
+  sees, and the engine part's compaction entry is the durable record of the cut.
+- **ADR-0035's runaway counters do not reset on compaction, and the compaction call is not a step.** The watch counts
+  tool calls per Submission; compaction is a fact about tokens. A turn that compacts and continues is still spending its
+  one step budget.
+- **A tripped watch ends the run at the step boundary (the seam's `endsRun`, which the pi adapter runs from pi's
+  `finishTurn`), so no request follows and no cut is taken.** A cut there would run a full summarization on a full
+  window for a request that is never sent: real tokens, an unbounded wait against the very liveness ADR-0035 exists to
+  guarantee, and a `[compacted]` line that makes a killed turn read as a healthy one. The hook also asks for no summary
+  when the run's signal has aborted or the watch has tripped.
+- **The claims are proven in the ADR-0027 conformance suite**, where a scripted provider fabricates usage to cross the
+  threshold without burning a real window; it runs in the default `pnpm -r test` gate.
+
+## Considered options
+
+- **Threshold at turn boundaries plus overflow-retry only** (flue's exact split: `checkCompaction` after each completed
+  assistant message, and one compact-and-retry when a turn actually overflows). Rejected: it would not have saved run
+  `588b0f5e`, whose window filled at step ~161 of a single turn. It rescues the nudges after the failure, not the
+  failure.
+- **A pure transform in the request hook, never touching the engine part.** Rejected: no compaction record for the
+  printer or the engine part, and the summary would have to be cached jr2-side anyway to avoid an LLM call per request —
+  which is the compaction entry reimplemented worse.
+- **Wait for pi to own Compaction.** Rejected on ADR-0027's grounds: pi 0.82 had the arithmetic and called it from no
+  loop, pi 1.0 removed it from pi-agent-core, and the pin is exact.
+- **A compaction Dial, or a definition override** (flue accepted `reserveTokens`/`keepRecentTokens`/`model` per agent).
+  Rejected: compaction is neither identity nor how-hard-to-run, so it is not a Dial (ADR-0018), and ADR-0016 puts
+  budgets in jr2's hands. Greenfield: no workflow has needed one.
+- **A headroom check before each no-signal nudge** (fault fast when the window is full). Rejected: it needs a new wire
+  field carrying token counts to a consumer that would use it for one branch, to guard a state compaction now prevents.
+  The nudge's own first request compacts.
+
+## Consequences
+
+- `contextWindow` in the instance spec becomes live for the first time since ADR-0027.
+- **ADR-0035's step budget of 256 is now the only bound on a productive turn.** Its justification weakened: it was set
+  above an honest 161-step bug hunt that exhausted its context, and context exhaustion was the real ceiling. The number
+  does not move here — there is no data from the far side of compaction — but the next reader raising it should know the
+  backing changed.
+- Compaction can make an agent re-read what it already read. That is duplicated work, not a runaway: K counts
+  CONSECUTIVE identical calls, and a re-read after a summary is one call, not four. The two guards do not fight; a
+  compacted turn is just less efficient than its transcript suggests.
+- Inheriting the Turn's thinking level carries a known risk, recorded rather than designed against: the Harness budgets
+  the summary at `min(0.8 × reserve, model.maxTokens)` (no `maxTokens` cap when the model states none) and the model
+  spends reasoning tokens from that same budget, so a high-effort turn on a small `maxTokens` can truncate its own
+  summary. The trigger is named; if it is observed, the fix is a stated divergence, not a knob.
+- ADR-0016's no-signal ladder assumed a turn that ends with room left. That was silently false at a full window and is
+  now true by construction — so a nudge ladder observed dying with a full context again is evidence compaction failed,
+  not evidence the ladder needs a gate.
+- The degenerate edges resolve the same way: a tool result larger than the reserve leaves nothing worth cutting, and a
+  `continue: true` invocation can arrive on a conversation already at the ceiling. Both compact, and if the context is
+  still over, the turn fails as infra.
+- A cut does not lower the reading that triggered it: the estimate reads the last valid assistant usage, and a cut
+  RETAINS recent assistant messages, so the number survives the cut. When the request after a cut ends `error` or
+  `aborted` it contributes no usage of its own and the next request would cut again on a context nothing has grown — a
+  second summary over work the first already covered. A cut therefore requires assistant usage recorded AFTER the newest
+  compaction entry.
+- **The pi surface is the `prepareRequest` hook, behind the engine seam (`pi-engine.ts`), and pi-ai's message types.**
+  The hook's rule that its context "replaces the runtime values for this and later requests" is documented in pi's
+  types, not promised as a caller contract. The algorithm, the context rule and the branch walk are jr2's code, so a pin
+  bump cannot move them. The conformance suite is still the canary (ADR-0027): it asserts the mid-turn cut and the
+  SECOND cut's retention, not just the threshold arithmetic.

package/docs/reference/decisions/0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md

@@ -0,0 +1,196 @@
+# A Sandbox Image is built or brought; jr2 injects the Harness at pod time
+
+Working tools execute in the Harness container
+([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md),
+[ADR-0028](0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)), so the tools an Agent can reach
+are whatever that image carries — a toolchain is the one part of a Sandbox a user genuinely owns. Users own toolchains
+in two shapes: a Dockerfile the instance iterates on locally, and an image already baked, versioned, and hosted on their
+own registry. jr2's runtime must live in the same filesystem either way, and the constraint that decides the mechanism
+is ownership: the user's image must stay the user's — zero jr2 layers, zero rebuild, zero opinions about its `USER`,
+`HOME`, or entrypoint. Any build-time modification makes "bring your own image" impossible (jr2 becomes the owner of
+every build) and promotes incidental image properties into contract items.
+
+## Decision
+
+- **Two origins, one meaning.** A built Sandbox Image is a docker context the Machine names —
+  `workspace(body, { image: import.meta.resolve("./image") })`, a `file:` URL to the folder, which a package ships
+  beside its Machine and `jr2 up` finds by walking the registered Machines
+  ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md); the first cut discovered
+  `images/<name>/Dockerfile` by dirname, a second named it from config). The build context is **that directory**, so the
+  content hash covers exactly what the build can see and a workflow edit invalidates no image; there is no cross-image
+  `FROM`. `jr2 up` builds it, content-tags it, and delivers it
+  ([ADR-0038](0038-jr2-up-builds-every-image-it-deploys.md)). **Or a registry ref**: a `workspace()`'s `image` may name
+  an image jr2 never builds — baked and hosted by the user, pulled by the cluster, its tag discipline its owner's. The
+  two are distinguishable by shape (a `file:` scheme is a context; anything else is a ref). Resolution is: the wrapper's
+  `image` → the Instance's `images/default` → stock `jr2-harness:<kitversion>`. The middle step is a **path convention,
+  not discovery**: `jr2 init` scaffolds `images/default/Dockerfile`, `jr2 up` builds that one folder when it exists, and
+  a `workspace()` that names nothing gets it — so a local Machine never has to spell
+  `import.meta.resolve("../images/default")`. A `file:` URL that names no folder fails at `jr2 up`; a ref is the
+  cluster's to pull.
+- **The Harness arrives by volume, never by build.** Every Sandbox is composed with an `/opt/jr2` volume that is an
+  **`image` volume of the kit's harness image** (`subPath: opt/jr2`, read-only in every container that mounts it), and
+  the primary container's **command** is overridden to start the Harness. The kubelet mounts the image's own layers, so
+  nothing is copied: a pod start costs what a warm image costs, whatever else starts on the node, and every Sandbox on a
+  node reads one set of runtime pages. The ref, pull policy, and pull secrets are the harness image's as the cluster
+  already pulls it — the volume adds nothing to deliver. The image the pod runs is the user's, byte-for-byte: no
+  appended layers, no rewritten Dockerfile, no jr2 knowledge inside it. Its own `USER` and `HOME` are respected — the
+  human who execs in lands in the environment the image's author built, dotfiles included; its `ENTRYPOINT`/`CMD` simply
+  do not run, because a container has one command and the Harness must own it (its death must be the container's death —
+  the Ready probe and restart semantics are the operator's contract at `:8080`). A **built** image that declares no user
+  runs as uid 1000 with `HOME=/home/jr2` on an emptyDir as the fallback — jr2 learns "declares none" for free at build
+  time (`docker inspect`) and records it beside the ref. A **brought** ref is never inspected — that is the point of
+  refs — so the fallback cannot apply: a ref must declare a numeric non-root `USER` itself, and one that would run as
+  root fails at provision with an error that names that line (never as the kubelet's silent
+  `CreateContainerConfigError`). A process the image _wants_ running is not lost — it has its own seat, the User
+  Container ([ADR-0005](0005-sandbox-pod-composition.md)).
+- **PATH is appended at the process level, never prepended.** The Harness exports `PATH="${PATH}:/opt/jr2/bin"` for
+  itself, and Working tools spawn without an env override (`execFile(file, args, { cwd, signal })`), so children inherit
+  it: the image's `node`, `rg`, and toolchain win where present and jr2's are the fallback; prepending would silently
+  shadow a pinned toolchain inside the user's own image. The same process-level discipline carries `umask 002`: the
+  Harness sets it at startup so even what it writes _outside_ a repo tree stays group-writable for the pod's work group.
+  Inside the repo trees the umask stops mattering — the attach stamps a default ACL on each repo root and POSIX ignores
+  the umask where one exists ([ADR-0005](0005-sandbox-pod-composition.md)); this is the defence-in-depth layer, inert
+  when no other uid ever writes.
+- **git's system level is jr2's default identity, at the lowest rung.** An image with no git identity made the Agent's
+  first `git commit` fail ("Author identity unknown"), and a model then spent its Turn on `git config`; real Haiku 5.5
+  runs lost trials to it. The image is the author's, and the author may set git config at any level, so jr2's identity
+  must never override one. The runtime volume carries `/opt/jr2/etc/gitconfig`: `[user] name = jr2 Agent`,
+  `email = agent@jr2.invalid`, then `[include] path = /etc/gitconfig`. At startup the Harness sets `GIT_CONFIG_SYSTEM`
+  to it, at the process level like PATH, so every git the Harness container runs reads it — the Agent's `bash`, a
+  `command` Effect there, and the attach (which commits nothing, so the identity is unused). The include reads the
+  image's own system file after jr2's lines, so the image's values win key by key, and every higher level wins anyway:
+  global (`~/.gitconfig`, XDG), repo-local, `-c`, and `GIT_AUTHOR_*`/`GIT_COMMITTER_*`. The Harness sets nothing when:
+  - the image sets `GIT_CONFIG_SYSTEM` or `GIT_CONFIG_NOSYSTEM` (any value): it made its own choice about git's system
+    level, and a file jr2 put in front of the image's would replace a value the image set. Including the image's file in
+    place of `/etc/gitconfig` was rejected: the file is static on a read-only volume, and to name the image's file it
+    must be written at boot into a writable directory the image owns;
+  - the image's git reads another system file than `/etc/gitconfig`, or the Harness cannot tell which. A git built with
+    another prefix (a source build in `/usr/local`, Homebrew, conda) reads `<prefix>/etc/gitconfig`, which jr2's file
+    does not include, so its `safe.directory`, credential helper and identity would be lost. git 2.42 and later name the
+    file (`git var GIT_CONFIG_SYSTEM`); for an older git the Harness reads `git --exec-path`, and only
+    `/usr/lib/git-core` or `/usr/libexec/git-core` (prefix `/usr`, which reads `/etc/gitconfig`) passes. No git on PATH
+    gets nothing too. Such an image gets no default identity: that is the limit, and it sets its own;
+  - the file is not on the volume: git reads a missing system file as empty, and the image's `/etc/gitconfig` would be
+    lost.
+
+  Five limits are known and accepted. A git older than 2.32 does not read `GIT_CONFIG_SYSTEM`: it is safe (it reads
+  `/etc/gitconfig` as before) and gets no default identity. "The image's values win" holds for the config git uses (a
+  commit, `git config --get`), not for a `--system` read: `git config --system` does not follow the include, so
+  `--system --get user.name` answers `jr2 Agent` where the image's `/etc/gitconfig` names another, and `--system --list`
+  omits the image's values. An image that sets `user.useConfigOnly = true` and no identity no longer stops a commit,
+  because jr2's file supplies one; such an image sets `GIT_CONFIG_SYSTEM=/etc/gitconfig` itself, and jr2 then adds
+  nothing. With the variable set, `git config --system <key> <value>` writes jr2's file on the read-only volume and
+  fails (exit 4); without it, an Agent that runs as root wrote `/etc/gitconfig`. A `--global` or repo-local write works
+  as before. A human's `kubectl exec` shell does not get the variable, as it does not get the PATH append. jr2's other
+  git is out of scope: the sync runs under `GIT_CONFIG_NOSYSTEM` (ADR-0067); the Sandbox Effector is another container
+  with its own committer rules (ADR-0068), and a credentialed `command` Effect runs there with `PATH`, `HOME` and
+  `TMPDIR` alone, so it gets no default identity.
+
+- **The contract is the floor, and the preflight proves it.** What is inherent to "jr2's runtime in your filesystem" and
+  nothing more: a **glibc** base no older than the one jr2's node was built against (musl is out entirely), **`git`** on
+  the system PATH (relocating git means `/usr/lib/git-core`, templates, `git-remote-https` → curl + openssl + CA store —
+  a rabbit hole, and the agent wants the git you chose), a writable `HOME` for the image's user (the attach script
+  writes `$HOME/.gitconfig`, and any real toolchain needs `~/.npm`, `~/.cargo`, `~/.cache`), and `/opt/jr2`, `/work`,
+  `:8080` unclaimed. jr2 vendors the rest: **ripgrep** as its official static-musl binary and node's
+  `libstdc++.so.6`/`libgcc_s.so.1` into `/opt/jr2/lib`. The probe is one command —
+  `git config --global safe.directory "*" && /opt/jr2/bin/node -e "" && rg --version` — and it runs **only where the
+  seat is known: as an init step in the user's own image**, `/opt/jr2` mounted, before the Harness starts. It cannot run
+  at converge: the floor is a Harness-seat obligation, a built context may equally be destined for the User Container
+  seat — which owes no floor at all (ADR-0005) — and which seat a directory serves is workflow-internal and statically
+  unrecoverable (ADR-0031, the same line that puts unknown names at provision). So a broken toolchain image surfaces at
+  its first provision, in the `preflight` init container's log, with an error that names the fix (because "node did not
+  execute" is not actionable) — never as a mid-turn tool failure, and never as a converge refusal for a contract the
+  image was not under.
+- **`workspace()` names the image as a STATIC OPTION, never in the per-run spec** — what the Sandbox is _made of_ is the
+  wrapper's business in the same way its worktrees are, but it is a fact about the MACHINE, not about a run: `jr2 up`
+  finds it by walking the registered Machines ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)),
+  and a spec is a function of run input that no walk can evaluate. The User Container rides the same rule and the same
+  resolution as one more option beside `image` (`user?: string`, [ADR-0005](0005-sandbox-pod-composition.md)). Neither
+  is ever persisted: the option rides the Machine (a parts map keyed on `machine.config`, as the vocabulary is) and the
+  provisioning state re-reads it at invoke time, so a restore provisions what the Machine carries now — and a resolved
+  content-addressed tag, which would outlive the image it names, never leaves the port's side of the seam at all.
+- **A Menu-only Agent never gets a Sandbox Image.** `workspace: "none"` withholds the entire Working toolset (ADR-0028),
+  so there is no tooling to carry; the Instance Harness (ADR-0031) runs the stock image permanently. The feature has
+  exactly one seat, and it is the Workspace.
+
+## Considered options
+
+- **A build-time wrap** — jr2 builds a kit-owned stage `FROM` the user's image (`COPY /opt/jr2`, `USER 1000`,
+  `HOME=/home/jr2`, `CMD` = the Harness). Rejected on four counts. It makes jr2 the owner of every Sandbox Image build,
+  so an image baked and hosted by the user cannot exist — the registry-ref origin is unimplementable. It promotes
+  non-inherent properties into contract (`USER 1000` forced, `HOME=/home/jr2` forced, "your image must not set
+  `ENTRYPOINT`") where the inherent floor is only glibc + git + a writable home. It couples every Sandbox Image tag to
+  the resolved harness ref (the wrap is `COPY --from=<harness>`), so a kit source edit re-tags, rebuilds, and
+  re-delivers every user image on the cluster. And it needs an intermediate tag between the user's build and the wrap
+  build — a mutable shared name that serializes concurrent converges of one checkout, a problem space that exists only
+  because the wrap does.
+- **The user layers on jr2** (`FROM jr2-harness:<kitversion>`). Simplest, and the contracts come inherited. Rejected: it
+  pins every instance to jr2's debian/node base forever — you could never start from `golang:1.23` or a company base
+  image, which is the entire feature.
+- **jr2 installs the missing floor packages into the image.** Rejected: package-manager sniffing
+  (`apt`/`apk`/`dnf`/`zypper`/`pacman`) is a fragile shell ladder, distroless and scratch have no shell at all, the
+  `apk` branch is pointless because musl breaks node regardless, and reaching the network to mutate someone's image
+  behind their back fails in exactly the proxied enterprise environments where it is least debuggable. Vendoring covers
+  the same ground without any of it.
+- **A published `jr2-base:<kitversion>` for the scaffold to start from.** Rejected: a fourth image on the release train
+  that re-couples the user's Dockerfile to a jr2 tag. It would also absorb a future contract change silently, when a
+  contract change should be loud in every instance.
+- **Cross-container tool execution** — the Harness in its own kit-owned container, Working tools exec'd into a sibling
+  running the user's image, making that image truly zero-contract. Rejected: it requires a cross-container execution
+  transport jr2 does not have, bought only to delete a floor (glibc + git) that most real images already clear by
+  accident.
+- **Keeping the image's own `CMD` as the container's main process** (the Harness as a second process, or supervised by
+  the user's entrypoint). Rejected: the container's lifecycle must be the Harness's — a pod whose main process is the
+  user's entrypoint keeps "Running" through a Harness death, which makes the operator's Ready probe and restart
+  semantics lies. Unattended services belong in the User Container (ADR-0005), whose command jr2 deliberately does not
+  own.
+- **An init container copies the runtime into an emptyDir** (`init-copy`, the first mechanism). Rejected on measurement
+  (2026-09-27, home-lab Sandbox node, 4 cores): the copy is 272 MB in 18k files per pod, so its cost grows with how many
+  pods start on the node together — 3s for one pod, a 37s median for 20 at once and 46s for 40, where the `image` volume
+  took a 3.0s median for the same 20. It also charged 272 MB of ephemeral storage to every pod and gave every pod its
+  own copy of the node binary's pages. The copy existed because image volumes were not yet on by default.
+- **The copy as a fallback below the floor**, chosen by server version at provision. Rejected: two pod shapes and two
+  mechanisms to test in every tier, kept alive for clusters no Instance runs on.
+- **A runtime-only Kit image** (`FROM scratch`, `/opt/jr2` alone) as the volume's source. Rejected: it pulls 272 MB
+  instead of the harness image's 625 MB on a cold node, but adds a third Kit image to build, push, mirror, and sweep
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md) cut the kit to two). The unused 353 MB
+  costs one pull per node per kit version, and pre-pull removes it from the start path.
+- **The Agent definition or an `agentRun` dial names the image.** Rejected on both doctrine and physics: available
+  tooling is what an Agent may _do_ (ADR-0028 territory, identity — only `model` and `thinkingLevel` are dials,
+  ADR-0018), and a Turn cannot change the image of a pod that already exists. A definition-level _assertion_ ("this
+  Agent requires image X, fail at admission if its Workspace provisioned another") stays available later.
+
+## Consequences
+
+- **The runtime's version rides the volume, not the image.** A kit edit moves the harness image's own tag and re-images
+  _future_ pods without touching any Sandbox Image tag — the only way a registry-ref image could ever follow a kit
+  update. Live Sandboxes keep the runtime they started with, the same create-if-absent stance ADR-0038 takes for images.
+- **A registry ref sits outside the build-and-label world**: never built, never labeled, never swept
+  ([ADR-0039](0039-image-garbage-collects-by-reachability.md) — what jr2 did not stamp, jr2 does not touch). Its pull is
+  the cluster's own; a mutable ref is its owner's stale-image risk, named here, not solved.
+- **Concurrent converges of one checkout share no mutable image name** — a Sandbox Image build is one `docker build`
+  straight to its content tag, with no intermediate tag at all. The `@kind` tier's `--parallel` rides on this
+  ([ADR-0010](0010-bdd-acceptance-tests.md)).
+- **A human exec-ing the Harness container inherits the agent's model credentials.** The person exec-ing is the instance
+  owner, so this is an accepted trade — and the User Container (ADR-0005) or `kubectl debug` with a plain image is the
+  creds-free shell in the same pod when it matters.
+- **A glibc floor.** Bases older than the one jr2's node was built against fail the preflight, and alpine/musl is out
+  entirely. Named in the error — at converge for a built image, at provision for a ref — not discovered in a pod log.
+- **The stock Harness image is also the injection source**: the `image` volume mounts its `/opt/jr2`, and it carries the
+  vendoring step (static ripgrep per `TARGETARCH`, the two relocated C++ runtime libraries). It also carries the static
+  Effector binary at `/opt/jr2/bin/effector`, built from the top-level `effector/` Go module: a container becomes an
+  Effector by running it as its command, in whatever image it runs
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). Static, so it owes no glibc floor.
+- **A Kubernetes floor: 1.35**, where image volumes are on by default (GA in 1.36). `jr2 up` reads the server version
+  and refuses below it, naming the version found and the floor
+  ([ADR-0046](0046-a-converge-failure-carries-its-diagnosis.md)). The container runtime must support image volumes too
+  (containerd ≥ 2.1, CRI-O ≥ 1.31); jr2 cannot see the runtime cheaply, so an older one fails at the first provision, in
+  the pod's own events.
+- **The mode is what every uid gets.** An image volume keeps the layers as built — owned by root, modes as the build
+  left them — and the Sandbox Image may run any uid. The harness image's `/opt/jr2` must therefore be readable by every
+  uid, and executable where the build made it so; a build-time check holds it there, and what the build copies from a
+  checkout (whose modes are the host's umask) is copied `a+rX`. (The copy restated this with a `chmod`.)
+- **`images/` is instance-local by design.** A built Sandbox Image travels as a folder to copy; a shared one travels as
+  a registry ref — which is now a first-class origin, so sharing needs no further mechanism.
+- **GLOSSARY.md**: **Sandbox Image** covers both origins and carries no part of jr2; **User Container** is defined by
+  ADR-0005.

package/docs/reference/decisions/0038-jr2-up-builds-every-image-it-deploys.md

@@ -0,0 +1,170 @@
+# `jr2 up` builds every image it deploys, except a pinned one
+
+[ADR-0019](0019-one-converging-command-against-the-current-context.md) promised one converging command, but `jr2 up`
+builds exactly one image — the instance's. The Harness and operator images come from `just` recipes at **mutable tags**
+(`jr2-harness:local`), pointed at by `images` overrides in `jr2.config.ts`. Nothing can detect that a mutable tag moved,
+so editing `packages/harness/src` and running `jr2 up` reports convergence onto pods running last week's code — the
+failure the Instance's own artifact already fixed for itself by hashing the materialized bundle rather than the source
+folder (then its image; now its Assembly,
+[ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)).
+[ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md) would add a second class of
+build-it-yourself-first image on top of that.
+
+## Decision
+
+- **Every image `jr2 up` deploys, `jr2 up` builds — when its source is visible.** The CLI detects a kit checkout by
+  resolving from its own module URL and requiring _both_ `deploy/harness/Dockerfile` and `packages/harness/package.json`
+  naming `@jr2/harness`. In a checkout it builds the Harness and operator images; installed from npm those paths do not
+  resolve, so a real instance takes the published-`<kitversion>` path and never needs docker for kit images. **The
+  checkout is the signal** — no flag, no config key, no env. A CLI loaded from under `node_modules` is never a checkout,
+  even when a checkout contains it: an instance inside the repository that installs `@jr2/*` from npm takes its pinned
+  version's published images, never a build of HEAD beside an Orchestrator at the pin. The `just` recipes survive as
+  shortcuts for building one image without a converge, never as prerequisites. A registry-ref Sandbox Image (ADR-0037)
+  is the one deployed image whose source is nobody's here: never built, labeled, or delivered by jr2 — the cluster pulls
+  it, and its tag discipline is its owner's.
+- **A Pinned image is deployed and never built.** The Custodian runs upstream Envoy
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): jr2 writes its configuration and
+  none of its code, so there is no source to build from and a jr2-built Envoy would be a fork to maintain. The kit names
+  it by tag AND digest (`CUSTODIAN_IMAGE` in `@jr2/orchestrator`), so a kit version deploys exactly one set of bytes in
+  both worlds — checkout and installed alike — and `imagePullPolicy: IfNotPresent` is correct for the same reason a
+  content-addressed tag is. `jr2 up` resolves its ref into the image map (the `custodian` key) — re-homed onto
+  `kitRegistry` when one is set ([ADR-0044](0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md)) — and
+  delivers nothing: a node pulls it. It is not a Kit image (GLOSSARY.md: "Pinned image"), and moving the pin is a kit
+  change.
+- **Every tag is a content address.** Orchestrator, Sandbox, Harness, operator — each addressed by its own inputs and
+  its platform set, the platform as a visible tag suffix
+  ([ADR-0045](0045-the-platform-joins-the-image-address-and-the-cluster-chooses-it.md)). Three things follow:
+  `imagePullPolicy: IfNotPresent` becomes _correct_ rather than lucky (a unique tag per content means "present" implies
+  "current"), which is what makes kind and a real cluster behave identically instead of needing `Never` on one and
+  `Always` on the other; a kit source edit moves its own image's tag with no bookkeeping; and skipping is exact.
+- **Over-hash deliberately.** A kit image is hashed over its whole source directory, tests included, not over the exact
+  file list its Dockerfile copies. Deriving the list by hand means a new `COPY` silently desynchronizes it, which is the
+  invisible-stale-image bug being deleted; a needless rebuild in kit dev costs cached-layer seconds. **A Sandbox Image's
+  hash covers its build-context directory alone** — the Harness rides the pod's `/opt/jr2` volume (ADR-0037), so a kit
+  edit moves the harness image's own tag and touches no Sandbox Image tag. That hash is also the map KEY the deployed
+  Orchestrator looks the ref up by, which is what lets a Machine name its context by `file:` URL and be understood on
+  both sides without a path table ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)).
+- **A staged tree records nothing about where or when it was staged.** The Assembly's hash addresses the staged tree
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)), so anything in that tree
+  that names its own scratch directory — or the minute it was written — makes one hash name many Assemblies, and
+  "present implies current" stops being true for the one artifact every Instance publishes. `pnpm deploy` writes both:
+  each `.bin` shim bakes the staging path into `NODE_PATH`, and `node_modules/.modules.yaml` is nothing but a record of
+  where and when. So the tree is **sealed** before it is hashed — the `.bin` shims are deleted, since the Orchestrator
+  runs no bin from an Assembly and a path that names the Assembly's own directory cannot be rewritten to one that
+  contains its own hash; `.modules.yaml` is deleted with them. (**Amended by
+  [ADR-0043](0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md)**: the bundle is `pnpm deploy`'s
+  only for a workspace-member instance; a standalone one is a staged copy plus a frozen lockfile install, whose shims
+  name no absolute path — but whose pnpm branch leaves a second where-and-when record,
+  `node_modules/.pnpm-workspace-state.json`, deleted with `.modules.yaml`.) A non-UTF-8 file holding the path is a loud
+  failure, never a blind rewrite. **Nothing is excluded from the hash any more.** The old exclude set named exactly the
+  files that varied, so the tag stood still while the bytes moved and the mechanism that should have exposed the drift
+  was the one hiding it; with an empty set the failure inverts — a bundle that ever varies again re-tags on every
+  converge, in the open, where a rebuild-and-reload every single time is impossible to miss.
+- **One transport branch for all of them**, the one the Sandbox Images use: `registry` configured → push; kind context →
+  `kind load`; neither → fail loudly naming `registry`. `jr2 up` records the converged name→ref map as an annotation on
+  the Orchestrator Deployment and diffs it, so a steady-state converge spends a directory walk and no docker at all.
+  **Amended by [ADR-0041](0041-a-build-the-host-already-holds-is-not-spent-again.md)**: when the record is silent (a
+  fresh namespace), the host daemon's own labeled listing answers the _build_ question — the seal below is what made
+  "present implies current" true enough to ask it — while the record keeps answering the delivery one.
+- **The resolved name→ref map reaches the Orchestrator as a ConfigMap, read per provision — never as Deployment env.**
+  Env is a pod-template change, so every Dockerfile edit would roll the Orchestrator and put every live run through
+  snapshot restore ([ADR-0007](0007-durable-machine-state.md)) for a change that affects only _future_ Sandboxes. The
+  map is data consulted when creating a pod, not configuration defining the process. The cost is a stale-read window of
+  one kubelet propagation after `jr2 up`, and that two workspaces provisioned seconds apart can straddle a change —
+  which was already true across a roll.
+- **The `images` config block is deleted outright — no key, no env escape hatch.** Its per-image entries were kit-dev
+  overrides that auto-build now covers; the User Container's image is a static `workspace()` option the Machine carries,
+  not config (ADR-0005, [ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)), so no `user` entry
+  belongs here either. Nobody should be able to run a patched Harness against a real cluster: that is ADR-0027's "no
+  eject hatch" enforced rather than merely stated.
+- **`jr2 up` reports live workspaces on an older image; it never re-images one.** Provision is create-if-absent, so a
+  running Sandbox keeps the image its CR was created with — the only safe behavior, since replacing the pod takes the
+  worktrees and unpushed commits with it, which is precisely the Continuity break
+  [ADR-0021](0021-workspace-continuity-is-a-lease-that-answers-back.md) exists to report. So the converge lists them
+  (`kubectl get sandboxes`, no new state) and stops: _"2 running workspaces keep `…:9c1e02`; new workspaces use
+  `:4a77b1`; delete these runs to re-image."_
+- **`jr2 down` prunes this instance's images from kind nodes by default** — **superseded by
+  [ADR-0039](0039-image-garbage-collects-by-reachability.md)**, which replaces name-scoped, down-only pruning with a
+  label-scoped reachability sweep at both `up` and `down`, host daemon included. Kept as written for the record: scoped
+  to EXACT repo names: `jr2-instance-<name>:*` plus, per discovered `images/<x>/`, `jr2-sandbox-<name>-<x>:*` and its
+  `-base` intermediate (matched after stripping containerd's `docker.io/library/` namespace, which `kind load`
+  normalizes local tags into — and nothing else, so a registry-pushed tag keeps its host and stays unmatched). Exact
+  names, never one open-ended `jr2-sandbox-<name>-` prefix, which also matches instance `<name>-extra`'s images on a
+  shared node. Removal is planned **per image id**: `crictl rmi` cannot untag — it resolves any tag to the id and takes
+  the whole image, every tag with it — so an id is removed only when every tag on it is this instance's, and an id
+  sharing tags with anyone else (two instances whose image inputs are byte-identical produce one id) is kept whole and
+  reported. Content addressing means ten Dockerfile iterations leave ten full images in the node's containerd, invisible
+  to `kubectl` and on the developer's own disk. **Kit images are never pruned** — they are shared by every instance on
+  the cluster — and neither are registry-pushed tags. The accepted remainder: deleting an `images/<x>/` folder orphans
+  that image's already-loaded tags (nothing derives their names any more); they go with the cluster, or by hand.
+- **No `workspace()`, no Sandbox Image builds.** A registered Machine that composes a Sandbox is the data-plane switch,
+  read off the walk (ADR-0051): a workspace-less instance has no Sandboxes, so it must not pay a docker build for a
+  scaffolded `images/default/` it can never use.
+
+## Considered options
+
+- **An env escape hatch for kit image refs** (`JR2_HARNESS_IMAGE`, …), kept for the `@kind` tier, which pins
+  `jr2-harness-dev:local`. Rejected once the stub was read properly: `deploy/harness-dev/` is a whole alternate Harness
+  — the stub plus a hand-rolled MCP client — written when "flue's real Harness image is not part of this repo," which
+  ADR-0027 made false. The substitution belongs at the **provider**, not the image: `harness.provider` already accepts
+  any OpenAI-compatible `baseUrl`, so pointing `@kind` at a scripted model endpoint runs the **stock** Harness and
+  removes the last consumer of image substitution.
+- **The ref map as Deployment env** (symmetric with the harness config the Harness containers read from theirs).
+  Attractive because a run's Sandbox image becomes a deterministic function of the Orchestrator generation instead of a
+  read-at-a-moment. Rejected on the roll: bouncing every run in flight because someone added a CLI to a Dockerfile is
+  the wrong trade.
+- **A `--reimage` flag** that deletes and re-provisions live Sandboxes. Rejected: it destroys unpushed work, and the run
+  already has a designed path for losing its Sandbox (`workspace.lost`, ADR-0021) that the workflow's policy drives —
+  not the CLI.
+- **Hashing only the files each Dockerfile copies**, or hashing the whole kit tree via git. The first desynchronizes
+  silently; the second rebuilds every image on any edit anywhere. Per-image directory hashing sits between them and errs
+  toward rebuilding.
+- **pnpm's hoisted node linker** (`deploy --node-linker=hoisted`), which emits no absolute path at all and so needs no
+  seal. Verified to work and to leave the artifact all but identical (60 MB vs 62 MB, 3998 vs 4029 files). Rejected at
+  first on exposure, not on merit: `pnpm deploy` calls itself experimental and jr2 already pinned `--legacy`, so a third
+  deviation that changes the `node_modules` layout bought nothing the seal did not. Adopted with
+  [ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md): the Assembly must be flat
+  so the Kit closure strips as top-level entries and no pnpm store name reaches the archive, so both bundle paths
+  install hoisted now. The seal keeps its deletions; it rewrites nothing.
+- **A `.dockerignore` derived from the exclude set.** Rejected: it deletes the shims, and pnpm's shims `exec` through a
+  relative `$basedir` — they WORK in the container. An Instance whose dependency ships a CLI would lose it. The four
+  varying files are content the image should keep, holding a path that is simply wrong.
+- **Freezing the staging path** (a stable scratch dir instead of `mkdtemp`). Rejected twice over: it freezes the wrong
+  path rather than fixing it, and it makes the bundle a function of `TMPDIR` and the instance's location — the same
+  inputs would yield different bytes in CI than on a laptop, which is the property this decision exists to establish. It
+  also collides when one Instance folder is converged concurrently.
+- **`pnpm deploy` inside the Dockerfile**, so the bundle is materialized at `/instance` and no host path can leak.
+  Rejected for now: it needs the whole monorepo plus the pnpm store in the build context (or network during the build
+  for an installed Instance), and it moves the hash off the materialized bundle — the ground ADR-0019 chose
+  deliberately, because hashing guessed inputs instead is how `jr2 up` came to skip builds it needed.
+- **Opt-in `--prune-images`.** Rejected: `down` is already the destructive, always-confirms command, and abandoned
+  images are discovered at 100% disk rather than at the moment one would think to pass a flag.
+
+## Consequences
+
+- **The `@kind` tier is rewritten, not renamed.** `deploy/harness-dev/` dies; the scripted persona's behavior moves from
+  MCP client calls to OpenAI-format `tool_calls` on a fake provider (in-cluster, or host-side with a LAN `baseUrl` — the
+  config already notes a LAN address works on kind). The tier gains real-Harness coverage and becomes a **second pi
+  canary** beside the conformance suite (ADR-0027), so a pi bump can now break it too.
+- `stub-harness.ts` keeps its job — the socket-free tier reaches it by explicit `endpoint` (ADR-0031). Only the
+  containerized stub is retired.
+- **`jr2 up` in a kit checkout now needs docker for kit images**, including a Go build for the operator. Hash-skip means
+  that is a first-converge cost, not a per-converge one.
+- **An air-gapped or mirror-only cluster still cannot pull published kit images.** The answer is a registry _prefix_ for
+  kit refs, not per-image overrides — a different mechanism, deliberately deferred while nothing is published.
+  (**Resolved by [ADR-0044](0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md)**: the prefix is
+  `kitRegistry`, re-homing refs from the canonical `ghcr.io/snapwich` home, fed by a deliberate instance-less mirror.)
+- **The seal deletes garbage at its source.** Before it, every converge produced a new artifact under an unchanged
+  address, so each one orphaned a whole Orchestrator image of the Instance — 465 MB on the `@kind` instance — which
+  ADR-0039's sweep then collected. That was garbage produced by the builder on every run, not by iteration, and the
+  collector was doing work that should never have existed. The same rule now keeps a no-op converge from publishing an
+  Assembly: an unchanged tree has an unchanged hash, and the Orchestrator already holds it.
+- **`jr2 up` leans on `pnpm deploy`, which pnpm still labels experimental**, at `--legacy` and hoisted. The seal does
+  not deepen that exposure, but the assumption that staging is otherwise deterministic is now held by a test that stages
+  one Instance into two directories and compares hashes, rather than by trust. A pnpm upgrade that bakes a path
+  somewhere new fails that test instead of silently shipping two images under one tag. (**Amended by
+  [ADR-0043](0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md)**: only a workspace-member
+  instance leans on it. A standalone instance invokes whichever package manager wrote its lockfile, and `pnpm deploy` is
+  never reached.)
+- **`just` recipes stop being load-bearing**, and the `images:` line in `features/kind-instance/jr2.config.ts` is
+  deleted with the block.