@jr2/orchestrator 0.3.0 → 0.5.1

package/docs/reference/decisions/0055-a-release-is-a-pushed-tag-and-the-publish-guard-is-the-credential.md

@@ -0,0 +1,107 @@
+# A release is a pushed tag, and the publish guard is the credential
+
+[ADR-0043](0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md) made the accidental-publish guard
+a manifest line — `publishConfig.registry: http://localhost:4873` — and named the edit of that line the "we are ready"
+commit. Preparing the first real publish (2026-09-20) found the guard has no exit: `publishConfig` outranks `--registry`
+by design, so the edit that lets the kit reach npmjs is the same edit that breaks every reader of the guard at once —
+`packages/cli/test/publish.test.ts` asserts a localhost registry, `scripts/dist-publish.sh` refuses any other, and the
+`@dist` fixture publishes to whatever the manifest names. After the flip the local loop cannot publish at all, and
+flipping it back per release keeps the unit gate red for the length of the release. The property that made the guard
+strong is the property that makes it unreleasable. This ADR amends ADR-0043's guard and settles the rest of the release:
+version, images, gate, trigger.
+
+## Decision
+
+- **The guard is the credential, not the manifest.** `publishConfig.registry` leaves every manifest. The only holder of
+  an npmjs credential is the release job, and it holds no token: it publishes with npm trusted publishing (OIDC from
+  GitHub Actions), so nothing long-lived exists to leak. A `pnpm -r publish` on a dev box reaches npmjs and fails
+  `ENEEDAUTH`, which is the guard — an absence that cannot be edited past, where the manifest line was a presence that
+  had to be. `publishConfig.access: public` stays on all four, because a scoped package's first publish is 402 without
+  it. `scripts/dist-publish.sh` passes `--registry` again, and `publish.test.ts` inverts: it asserts that **no** public
+  manifest names a registry, so the old guard cannot be smuggled back in one package and silently pin a release to
+  localhost.
+- **Lockstep, and `main` carries the next version.** One number across `packages/*` and `templates/default`, because
+  [ADR-0019](0019-one-converging-command-against-the-current-context.md)'s one release train already reads a single
+  `KIT_VERSION`, ADR-0043's scaffold pins two packages at one exact number, and `workspace:*` packs to an exact
+  inter-dependency — independent versions would need ranges, and 0.x ranges break. `0.0.0` stops being special: it was
+  the ephemeral registry's value only because nothing was released, and a fresh verdaccio publishes any version cleanly.
+  `just release patch|minor|major` (or an explicit version) computes the number the way `npm version` does, writes it to
+  every manifest and the template, runs the unit gate (`init.test.ts` is the tripwire), commits, and tags `v<ver>`.
+  Nothing rewrites a version at publish time: a loop that edits manifests tests edited manifests (ADR-0043), and a
+  checkout `KIT_VERSION` must read the number the checkout will ship.
+- **The tag push is the release, and the train runs in order.** `release.yml` runs on `v*`. Its first job refuses if the
+  tag disagrees with any manifest, and then asks every other refusal of the publish
+  (`scripts/publish.sh --stage --check`: the tree, the ref, the strict docs build, no output block not yet run). These
+  take seconds, so a tag that cannot publish starts no tier. Then the full gate, as parallel jobs that each need that
+  first one — unit, harness conformance, the default e2e profile, the docs site build and the Custodian suite in one
+  job; `@kind` as four shards, each on a kind cluster its own runner creates (the operator's own e2e job already works
+  this way); and `@dist` on one more — so the installed path is proven on the tree that publishes, not on a maintainer's
+  box the day before. The tiers are jobs and not steps of one job because one runner ran them in series: v0.5.0's job
+  spent 37 minutes in `@kind` alone, two workers being the most a 4-vCPU runner holds, and then failed at a refusal of
+  the publish that takes a second. Only when every tier job passes does the one job that holds the rights run:
+  `scripts/kit-push.sh ghcr.io/snapwich` (multi-arch, `GITHUB_TOKEN` with `packages: write`), and **only then** npm:
+  each public package is packed with pnpm, which rewrites `workspace:*` to the exact version, and **staged** with
+  `npm stage publish`, the client that speaks trusted publishing — in pnpm's topological order, dependencies first,
+  skipping a version npm already holds live so a re-run converges. The order is the contract: a package whose images are
+  not at the home fails at pull on the user's first `jr2 up`
+  ([ADR-0044](0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md)); images with no package are inert,
+  and stay so while the packages sit staged. A second job, `pages`, follows the release job and deploys the docs site of
+  the same tree to GitHub Pages
+  ([ADR-0072](0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md)). It does not wait for the
+  npm approval, so the site can be ahead of the live packages until the maintainer approves them.
+- **The job stages; the maintainer approves.** Each trusted publisher is configured for `npm stage publish` only, so the
+  tag produces four staged tarballs and one 2FA approval per package (`npm stage approve`, dependencies first) makes
+  them live. This is the one human act a release keeps, and it is kept on purpose: the job's identity is bound to the
+  repository and the workflow file, so a stolen GitHub session or a bad edit to that file could otherwise publish under
+  the project's name; staged, it can stage and nothing more. It is not a runbook step — nothing has to be remembered in
+  order, the staged tarballs wait.
+- **Two executors of one train.** `scripts/publish.sh` is the irreversible half — images, then packages, dependencies
+  first, live versions skipped — and the job runs it with `--stage`. A maintainer runs it as `just publish` from the
+  pushed tag when a 0.x release cannot wait the job's hour: `npm publish` with a 2FA prompt per package in place of an
+  approval, and the job converges behind it. The checks are the same in both (lockstep, clean tree, HEAD is the pushed
+  tag), and so is the guard: a login alone publishes nothing under write-2FA, so a dev box holds no credential that
+  publishes by itself.
+- **`ci.yml` on push and PR is the light gate**: frozen install, typecheck, format check, `pnpm -r test`, the default
+  Cucumber profile — minutes, no docker. The heavy tiers and the Custodian suite run on the tag and by hand
+  (`just e2e-kind`, `just e2e-dist`, `just custodian-test`) when a change touches build, deploy, or dist code.
+- **`@jr2/machines` peers on `@jr2/orchestrator` exactly.** `workspace:*` stays; a Machine is written against one
+  orchestrator, and a mismatched pair fails at install with a peer error instead of at run.
+- **`engines.node: ">=24"` on every public package and the root.** Every runtime the kit runs in is Node 24 already
+  (both Kit Dockerfiles, the instance Dockerfile, the `registerHooks` bin); the root's `>=22` was the straggler.
+
+## Considered options
+
+- **Keep the localhost line; the release job rewrites it before publish.** Rejected by ADR-0043's own rule — the
+  published manifest would be one no tier tested.
+- **Point the manifests at npmjs; the dist loop rewrites them to localhost.** The same objection inverted: the tier that
+  proves the tarballs would test a manifest the release never ships.
+- **A `prepublishOnly` guard** (refuse unless localhost or `JR2_RELEASE=1`). In-tree, but it rests on pnpm exposing the
+  effective registry to lifecycle scripts, and a one-variable bypass is a guard shaped like a suggestion.
+- **CI stamps the version from the tag; `main` stays `0.0.0`.** Rejected twice: edited manifests, and a checkout's
+  `KIT_VERSION` would read `0.0.0` forever.
+- **Changesets in fixed mode.** The right tool once there are contributors and changelogs; today it is a version PR in
+  front of a five-file edit. The contract it would implement — tag equals manifests, lockstep — is the one chosen here,
+  so adopting it later changes no ADR.
+- **`workflow_dispatch` with a version input.** CI would make the bump commit, so the gate runs on a tree the maintainer
+  never saw at that version.
+- **Manual `just kit-push` before tagging.** A runbook step in front of a release (ADR-0019 calls that an interface
+  failure), and nothing checks the images exist before npm publish.
+
+## Consequences
+
+- ADR-0043's "What publishes, and the guard" is amended: the guard is credential absence; the "we are ready" commit is
+  no longer an edit, it is the first pushed tag. Its consequence "localhost `publishConfig` … is the real shipping
+  configuration" no longer holds; the rest of that list does.
+- **Bootstrap, once:** create the `jr2` org on npmjs (a scope is a user or an org), publish the first version by hand
+  with a token — npm attaches a trusted publisher only to a package that already exists — then configure the trusted
+  publisher on all four packages and revoke the token. After that no token that publishes on its own exists anywhere:
+  the job's identity stages, a maintainer's login needs its second factor. Likewise once: make the three GHCR packages
+  public after the first push, because GHCR creates them private.
+- `publish.test.ts` asserts no registry, `access: public`, and `engines`; `dist-publish.sh` drops its manifest read-back
+  and passes `--registry`; the `@dist` fixture takes its registry from `JR2_DIST_PORT`'s default rather than the
+  manifest; `kit-push.sh`'s cli-vs-orchestrator cross-check widens to every manifest; `just release` is new;
+  `.github/workflows/` gains `ci.yml` and `release.yml`.
+- A release costs a runner kind cluster and roughly ten minutes of docker. Accepted: it is the only time the installed
+  path must be proven on the exact tree that ships.
+- The four tarballs gain the npm-page fields (`description`, `repository` with `directory`, `homepage`, `bugs`,
+  `keywords`) and a README each; the root README's "only scaffolding exists" line goes.

package/docs/reference/decisions/0056-a-global-jr2-hands-off-to-the-instances-own-and-an-instance-has-one-kit-version.md

@@ -0,0 +1,62 @@
+# A global `jr2` hands off to the Instance's own, and an Instance has one Kit version
+
+[ADR-0043](0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md) made `jr2 init` pin `@jr2/cli` as
+an exact devDependency beside `@jr2/orchestrator`, and said instances upgrade "by editing two dep lines". That pin only
+means something if the Instance's copy of the CLI is the one that runs — and nothing made it so. `bin/jr2.js` ran
+itself, whatever cwd it was run from, and `KIT_VERSION` was read from the `@jr2/orchestrator` the **running CLI**
+resolved, never the one the Instance resolved. The first bump after 0.1.0 (2026-09-20) showed the hole: a global
+`jr2@0.1.1` in an Instance pinning `@jr2/orchestrator@0.1.2` and `@jr2/cli@0.1.0` converged 0.1.1 Kit images around a
+0.1.2 bundle, and nothing said a word. Published `@jr2/cli@X` depends on `@jr2/orchestrator@X` exact, so a mismatched
+pin quietly nests a **second** orchestrator under the CLI — the class-identity failure commit 2685d9b had already
+patched one symptom of. This ADR settles which binary runs, and what "the Instance's version" is.
+
+## Decision
+
+- **A global `jr2` hands off (the gulp/grunt model).** Before any verb, the binary walks up from cwd to `jr2.config.ts`
+  (ADR-0009's root marker). If that folder resolves `@jr2/cli` to a real path other than its own, it runs that package's
+  `bin.jr2` with the same arguments and stdio, and exits with its code. Nothing else — no flag parsing, no verb
+  exceptions (`--url` inside an Instance still hands off; the rule stays one sentence). _Amended 2026-09-20:_ plus one
+  env var, `JR2_HANDOFF_FROM=<version> <realpath>`, naming the copy that handed off. `jr2 version` prints it as the
+  `global` line, so "is my global out of date" is answered without leaving the Instance; nothing else reads it. It is
+  the only fact the local copy cannot learn on its own (`npm ls -g` is slow and per-manager). A global that predates the
+  variable hands off without it, and the report then shows no `global` line at all — indistinguishable from `npx jr2`,
+  and there is no third source to ask.
+- **Spawn, not import.** gulp loads the local gulp in-process because local gulp is a _library_ its CLI drives; here the
+  local is a _binary_. Spawning couples the global to one contract — the local package's `bin` field, npm's own, stable
+  across versions — and the local's preamble runs: its pinned `ts-blank-space`, its hooks, whatever a future bin adds.
+  Importing `src/cli.ts` would make the local's internal layout and `main` signature a cross-version API the global must
+  honor forever, and the global is the copy that cannot be updated once it ships. One extra Node start per invocation is
+  the price. Ctrl-C is unchanged: both share the process group.
+- **An Instance has one Kit version: the `@jr2/orchestrator` it resolves**, because that is the Kit image its
+  Orchestrator runs and the version its Assembly is written against
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). Wherever the CLI loads
+  an Instance (the root walk every Instance verb goes through; `--url` verbs skip the walk per ADR-0009, `jr2 init` has
+  no Instance yet), it resolves `@jr2/orchestrator/package.json` from the Instance root and from itself and requires the
+  two **real paths** to be equal, and that copy's version to be the CLI's own. Not equal — or absent — is a refusal that
+  names both versions and the two lines to edit, then says reinstall. Real-path identity first: same file means same
+  version by construction under npm hoisting, pnpm dedup, and checkout symlinks alike, and it is exactly the property
+  the class-identity bug needs. But one copy is not yet one version: when the Instance edits only the
+  `@jr2/orchestrator` line, the root's own pin wins over the CLI's peer, the one copy is hoisted, and the old CLI
+  resolves it at the same real path. So the CLI's own number must equal it too, which one release train makes true for a
+  correct pin ([ADR-0055](0055-a-release-is-a-pushed-tag-and-the-publish-guard-is-the-credential.md)).
+- **`@jr2/orchestrator` is a peer of `@jr2/cli`, not a dependency.** `peerDependencies: workspace:*` (pnpm rewrites it
+  exact at publish) plus the same under `devDependencies` for the checkout's own tests. A mismatched pin is then a peer
+  conflict at install. npm does not always fail it: the root's own `@jr2/orchestrator` line wins over the peer of a
+  devDependency with `npm warn ERESOLVE overriding peer dependency`, and pnpm and bun warn too, so the check above is
+  what refuses. The CLI stops carrying an orchestrator of its own, so a second copy can only come from the Instance's
+  resolution — the copy we want. The CLI stays a **devDependency** of every Instance: the bundle installs
+  `--omit=dev`/`--prod`, and the image has no use for a CLI or its erasure hook; peers of a devDependency still
+  auto-install and still `ERESOLVE`.
+- **`jr2 init` reads the CLI's own version.** A global with no Instance around it must not need its peer resolved, so
+  the scaffold's exact pin comes from `@jr2/cli`'s `package.json`. The numbers are equal by construction: one release
+  train, lockstep ([ADR-0055](0055-a-release-is-a-pushed-tag-and-the-publish-guard-is-the-credential.md)).
+
+## Consequences
+
+- ADR-0043's "edit two dep lines" is amended: an Instance is upgraded by editing two lines **to the same number**, and
+  editing one is now a refusal (or an install error), never a silent skew.
+- A global installed before this ADR does not hand off; the user updates it once. After that the global's version stops
+  mattering inside an Instance, which is the point.
+- The `@dist` tier exercises the handoff for free: its installed global drives an Instance whose own `@jr2/cli` came
+  from the same verdaccio at a different real path. The mode-line assertion it already makes now asserts the local
+  copy's line.

package/docs/reference/decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md

@@ -0,0 +1,152 @@
+# A Turn is its Frame, its Dials, and whether it continues
+
+A live `task` run (2026-09-20, `fa45e88f`, seven tool calls, eight minutes, zero bytes of the target read) exposed the
+seam: the prompt said `Work in /work/target/summarize` while every Working tool resolved relative paths at `/work`,
+because `cwd` lived on the Agent definition and a definition is written before any run — before any worktree — exists.
+The package compensated with prose, and a weak model ignored prose: it wrote `SUMMARY.md` outside the worktree, called
+`finish`, and the run parked at `review` claiming done. The audit that followed found the invoke input carrying four
+ways to name one conversation (`session: "continue"`, `scope`, `conversation`, and an undeclared `instanceId`), one of
+them (`scope`) with two unrelated author intents, none with a stated precedence, and every `@kind` fixture bypassing all
+of them. ADR-0028 already said the reviewing state hands a per-round worktree path as the reviewer's "cwd and prompt";
+ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thing had no field to land in.
+
+## Decision
+
+- **A Turn's input is its Frame, its Dials, and whether it continues — nothing else.**
+
+  ```ts
+  { prompt, cwd?, continue?, model?, thinkingLevel? }
+  ```
+
+  Identity — `instructions`, `workspace` — stays on the definition, and the definition is exactly identity plus one
+  default: `agent({ model, instructions, workspace?, thinkingLevel?, description? })`.
+
+- **The Frame is `prompt` and `cwd`: what this Turn is about and where it works.** Neither identity nor a Dial. A
+  worktree path is per run by nature — `/work/<slot>/<branch>` exists only once a run has a branch — so no definition
+  can name it, and a directory is not a property of a persona any more than a prompt is. `cwd` leaves `AgentDefinition`.
+  The Harness roots the Working tools at the Frame's `cwd`, which rides the admit body beside the prompt and the Dials.
+
+- **The Briefing is not the Frame.** jr2's Turn part
+  ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)) follows the prompt — the resolved working
+  directory, the Allowed picks and any notices — in a block of its own. The prompt stays the Machine state's words
+  alone; jr2 never writes into it.
+
+- **Under a Workspace, an absent `cwd` resolves to the only Repo Slot's Worktree, and is refused when there is more than
+  one.** With one slot there is no choice, so no convention is being smuggled in (ADR-0051: the kit gives no slot a
+  meaning). With two or more, the state must say which — `cwd: context.workspace.repos.target` — and the actor refuses
+  the Turn before admission, naming the slots and the line to add. The trap is accepted with open eyes: a composer who
+  adds a second slot on the `customize` line can make a Machine that ran yesterday refuse today, in a file the Machine's
+  author never sees. The refusal is explicit, at the first Turn, before any pod is spent; `jr2 up` cannot see it because
+  the invoke's input is a function. A `workspace: "none"` Agent has no Working tools and no `cwd` (ADR-0028); a
+  stub-Harness run with no Workspace keeps `/work`. `task` always passes its `cwd`, because "the first slot is the one
+  the coder edits" is its convention and a convention is stated, not defaulted.
+
+- **`continue: true` is the whole continuation surface.** Absent, every invocation is a fresh conversation — jr's lossy
+  handoff, ADR-0016's default, unchanged. Present, the Turn lands on **this Agent's one conversation in this Machine
+  instance**, whichever state of the Machine invokes it. The Instance ID is structural —
+  `<runId>/<machine actor path>/<agent>` — so the author writes a boolean, not a key: in a state machine the identity is
+  already on the page (the run, the Machine instance, the Agent slot), and a caller-chosen string would only restate it,
+  or contradict it. Every surveyed orchestration framework makes the caller hold a key (LangGraph `thread_id`, Temporal
+  Workflow Id, Mastra `threadId`) because nothing else can; here something else can.
+
+  - **Fan-out is safe by construction.** A Pool spawns each worker with the item id as its actor id (pool.ts), so three
+    `task` children each mint their own `…/backlog.worker.<item>/coder`. The packaged Machine never learns it is under a
+    Pool.
+  - **States of one Machine share by saying `continue`.** States differ by Menu — a coder in `implement` offers
+    `finish`, the same coder in `fix` offers `finish` and `dispute` — and the same conversation is wanted across them. A
+    state that wants a clean context leaves `continue` off. A Turn joins only a conversation that an earlier Turn
+    started with `continue: true`, so a retry loop says `continue` on each Turn, the first too: a first attempt without
+    it is not in the conversation that attempt 2 continues. Thus the docs show `continue: true` on each Turn of a retry
+    loop, and a conditional spread (`...(clean ? {} : { continue: true as const })`) only for a state that must start a
+    clean conversation on some Turns only (a state that always starts clean leaves `continue` off). A clean Turn does
+    not start the continued conversation again: the next Turn with `continue: true` joins the earlier one, so attempt 4
+    after a clean attempt 3 continues attempts 1 and 2. The alternative, a spread on `attempts > 0`, keeps attempt 1 out
+    of the conversation, so attempt 2 does not see it. The cost of `continue: true` on attempt 1 is the Runaway reroll
+    (ADR-0035): a continued Turn gets none, so a Runaway on attempt 1 sends `agent.fault` at once, and burns the
+    conversation. The docs accept this cost, so that attempt 2 sees attempt 1.
+  - **Two Agents never share a conversation.** The agent name is in the id, and it always was; a second persona under
+    one transcript would swap the system prompt mid-conversation. The memory-Agent shape ("read the coder's
+    conversation, store what matters") is served by handing the transcript as prompt _data_ to an Agent with its own
+    conversation — Letta's sleep-time agents — not by joining; how a transcript reaches a Machine as data is a follow-on
+    decision.
+  - **A faulted conversation is never continued.** No fault leaves a conversation worth continuing: a runaway either had
+    its reroll or has a poisoned context; infra and no-signal mean the Harness that held it is unreachable (ADR-0035).
+    jr2 keeps an **epoch** per continued conversation in the ledger beside the snapshot; the terminal `agent.fault`
+    bumps it, and the next `continue` on that Agent mints `<id>/<epoch>` — a virgin conversation. The author deletes
+    their generation counter. What stays with the author is re-briefing: the fault event is the signal that the next
+    prompt must carry the whole task again, and jr2 cannot write that prompt. The one fault that is not the
+    conversation's is a Harness restart that cut the Turn (`Turn lost`, or `memory limit` behind it): the rebuilt
+    Harness holds the conversation ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)), so the epoch
+    stays and the next `continue` lands on it; a rebuild that could not read it answers that Turn's `holds` check, which
+    gives a `conversation-new` notice (ADR-0062).
+  - **The reroll stays closed to continued conversations** (ADR-0035): the one recovery jr2 knows is the identical
+    prompt on a fresh conversation, and a continued Turn's prompt ("Continue.") is meaningless fresh. Fault route plus
+    re-brief is the recovery.
+  - **Two live invocations of one continued id — parallel states — are refused at the registration table**, one live
+    surface per address; a Submission that arrives behind a live one on the _Harness_ queues (ADR-0027). Sequential
+    states never race, because ADR-0024 ends the previous Turn before the next state invokes.
+
+- **`session`, `scope`, `conversation`, and `instanceId` retire.** `session: "continue"` was already this boolean under
+  a longer name — its id was the invoking Machine's actor path plus `scope` — so what retires there is the name and the
+  suffix; `conversation` was the cross-Machine pin (a name _replacing_ the path, so two Machine instances — two Pool
+  children — collided by construction, the hazard ADR-0049 recorded and could not refuse); `scope` suffixed all of them
+  and carried two intents (a subject under `continue`, a generation counter in `task`); `instanceId` bypassed minting
+  for tests. One boolean replaces all four because the id is deterministic when continued, so nothing needs a handle to
+  address it.
+
+- **The author type carries no mechanism.** `endpoint` and `sandbox` — set only by stub-tier fixtures that have no
+  `workspace()` to resolve from — move to a mechanism type the tests import. `tools`, the Menu override, retires: a
+  hand-written Menu can only agree with the invoking state's transitions or lie about them, and the lie is a pick that
+  moves nothing (ADR-0029). The one shape it hid — picks written on the CHILD STATES of the invoking state — is derived:
+  those child states are the state's modes (ADR-0015). A state that allows no picks stays legal, because a state a Gate
+  or a timer moves asks its Agent for text and nothing else. A real run never sets any of them: a Sandbox Agent resolves
+  ambiently (ADR-0016), a `workspace: "none"` Agent lands on the Instance Harness (ADR-0031).
+
+## Considered options
+
+- **Prompt-only** — tell the model that relative paths resolve at `/work` and demand absolute ones. Rejected by the
+  incident: ADR-0024 already established that the same prompt produces compliance on one run and not the next, and every
+  other Machine would repeat the sentence.
+- **`cwd` stays on the definition, overridable per Turn.** Rejected: a definition-level `cwd` can only ever say `/work`,
+  the parent of every checkout, where grep and glob hit the pristine `default/` clone beside the worktree. A default
+  that is wrong under every `workspace()` is not a default.
+- **`cwd` as a third Dial.** Rejected on the word: Dials say how hard to run. A directory says where, which is the same
+  kind of fact as the prompt — hence Frame.
+- **Default `cwd` to the first Repo Slot.** Rejected: reverses ADR-0051 ("there is no `workdir`"). The single-slot
+  default is not the same thing — with one slot there is nothing to privilege.
+- **Refuse an absent `cwd` under every Workspace.** The safer twin of the single-slot default: one line per invoke, no
+  composition trap. Not taken: the trap's failure is explicit and early, and the line is noise for the common
+  single-repo Machine.
+- **A caller-chosen conversation key (`conversation: "coder"`).** Rejected: it either restates the structure or
+  contradicts it. Path-scoping the key was proposed and made the key redundant — once the id is
+  `<run>/<machine path>/<agent>`, the author has nothing left to name.
+- **Continuation scoped to the invoking state.** Rejected: splits one conversation across the states that differ only by
+  Menu, which is the case continuation exists for.
+- **The cross-Machine pin kept as an opt-in.** Rejected: zero users since `examples/coding` went (ADR-0054), never sound
+  — the two states it joined sat on different Harnesses, and a conversation lives on one server (ADR-0031) — and an
+  unused opt-in is the fourth mechanism back under a new name. If a sound case appears it is a new decision.
+- **Continue a faulted conversation, author's choice.** Rejected: there is no case. Every fault class leaves either a
+  poisoned context or no server — except a Harness restart, which cuts the Turn and keeps the conversation (above).
+
+## Consequences
+
+- `AgentTurnInput` is `{ prompt, cwd?, continue?, model?, thinkingLevel? }`; `AgentDefinition` loses `cwd`. The Harness
+  admit body gains the Frame's `cwd`; `ResolvedDefinition.cwd` resolves from it, not the definition; the Harness stops
+  validating `description`, which the Orchestrator strips before admission (it is Console material).
+- **A Frame's `cwd` is absolute or the admission is refused**, naming the Frame. Absent is the one silent case, and it
+  says `/work` — a stated default. A relative path has no such answer: it would resolve against whatever directory the
+  Harness process sits in, which is the silent wrong directory this ADR was written for, one level further from the
+  author. The refusal is a 400 at admission, before a pod is spent.
+- `task` passes `cwd: worktreeOf(context).path` and `continue: true`, and drops `generation` (and its `scope`). It keeps
+  `turns`, reset on `agent.fault`, because re-briefing is prompt policy.
+- The ledger record for a continued conversation carries its epoch; the input mapper reads it at mint time, so the
+  minted id persists with the input and restore re-attaches the same conversation (ADR-0016's mapper rule holds — the
+  fresh suffix is still the random component).
+- The `@kind` fixtures drop `tools:` and `instanceId:`; the steps compute the continued id from the actor path, as they
+  already computed today's pin.
+- A regression scenario for the silent success: a `task` whose model uses relative paths must produce its file inside
+  the worktree, and a multi-slot Machine with no `cwd` must be refused with the slots named.
+- GLOSSARY.md: **Frame** enters; **Dials** loses `cwd`; **Instance ID** states the `continue` scope and that a faulted
+  conversation is not continued. ADR-0016 (continuation), ADR-0018 (identity line), ADR-0031 (placement scenario),
+  ADR-0035 (reroll gate wording), ADR-0049 (persona hazard), and ADR-0054 (`task`'s continuation) are edited to state
+  this truth.

package/docs/reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md

@@ -0,0 +1,106 @@
+# A Harness answers the Orchestrator alone
+
+A red-team review (2026-09-22) found that the Harness wire had no authentication. `POST /agents/:name/:id`, the stream
+and history views, and `.../abort` checked no bearer, and the server bound `0.0.0.0:8080`. Iids are derivable
+(`<runId>/<machine>/<agent>` for a continued conversation,
+[ADR-0057](0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md)), so any pod that could reach a Harness could
+admit a Turn into another conversation, read its history, or abort it. An Agent with bash in one Sandbox could do this
+to another Sandbox, or to the Instance Harness, which holds every Menu-only conversation in the Instance
+([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)). No NetworkPolicy existed to limit the reach. The
+review also found that the echo ([ADR-0023](0023-the-harness-prints-the-conversation.md)) sent the raw Instance token to
+every Sandbox Harness on each push. The env held only its digest, but the token itself passed through the process that
+the Agent executes code beside. So we authenticate the wire with a bearer that each Harness can verify and cannot mint,
+and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harness pod.
+
+## Decision
+
+- **One bearer per placement.** The Orchestrator presents
+  `harnessToken(key, placement) = HMAC(signing key, "harness:" + placement)` on every Harness wire call: admit, each
+  long-poll, abort, and echo. `placement` is the name of the pod that hosts the Turn: the Sandbox's name, or
+  `jr2-instance-harness`. This is the same name the registration records as its delivery scope
+  ([ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)), so one name scopes both
+  directions. The Custodian there may speak for the Turn's picks, and only this bearer may drive the conversation there.
+- **A key per Effector placement, derived the same way**
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)).
+  `effectorKey(key, placement) = HMAC(signing key, "effector:" + placement)` signs every request the Orchestrator sends
+  an Effector and every answer it takes back. `placement` is `instance` for the Instance Effector and the Sandbox's name
+  for a Sandbox Effector, so each Sandbox pod has its own key and a request signed for one Sandbox is refused by every
+  other; no Sandbox name is `instance`, since each one starts `ws-`. The `effector:` prefix keeps it apart from every
+  Harness bearer and Sandbox token. Unlike a Harness, an Effector holds the key itself — it must sign its answers — in a
+  Secret only its own container mounts. `jr2 up` writes the Instance Effector's (`jr2-instance-effector`) from the kept
+  signing key. The Orchestrator writes a Sandbox Effector's at provision, as it writes the Sandbox token: into
+  `<sandbox>-effector`, a Secret the Sandbox CR owns, so it goes with the pod. Either way the Orchestrator stores
+  nothing and derives the key again after a restart, and a re-provision applies the same value.
+- **The Harness holds only the digest.** Its env carries `JR2_HARNESS_TOKEN_SHA256 = sha256(bearer)`. The Agent can read
+  that env, and a digest inverts to nothing. So a Harness can verify its own bearer, and it can mint none, for itself or
+  for another pod. The HMAC key never leaves the Orchestrator's Secret.
+- **The bearer is derived, not stored.** This is the reason the Sandbox token is a signed name (`tokens.ts`). The
+  Orchestrator holds no per-pod state. A restarted Orchestrator derives the same bearer that a live Harness already
+  checks, so re-attach ([ADR-0012](0012-workspace-wrapper-machine.md)) survives with no change. The `harness:` prefix
+  separates it from the Sandbox token: no DNS-label name produces it.
+- **Every route is gated, and the gate runs first.** Admit, stream, history, abort and echo answer 401 without the
+  bearer. A 401 comes before a 404, so a refused caller does not learn which conversations exist. A refused admission
+  creates no conversation. The Harness requires `JR2_HARNESS_TOKEN_SHA256` at boot and fails loudly without it.
+- **The echo uses the same bearer.** `JR2_ECHO_TOKEN_SHA256` is removed. The Instance token no longer enters any pod,
+  which is what [ADR-0032](0032-the-console-unlocks-with-the-instance-token.md) and
+  [Secrets and trust](../../concepts/secrets-and-trust.md) say.
+- **A refused stream is a fault, not a reconnect.** The bearer is derived, so a Harness that refuses it once refuses it
+  on every retry. `wait` settles a 401 or 403 as a `SettlementFault` and does not park the Turn forever.
+- **Ingress to every Harness pod comes from the Orchestrator alone.** `jr2 up` converges two NetworkPolicies in the
+  instance namespace. `jr2-sandbox-ingress` selects every pod that has the operator's `sandbox.jr2.dev/name` label.
+  `jr2-instance-harness-ingress` selects `app: jr2-instance-harness`. Both admit ingress only from this instance's
+  Orchestrator pods (`app: jr2-orchestrator`, `jr2.dev/instance: <name>`). They are converged unconditionally, so a
+  Harness pod is never created before its policy exists. The Instance Effector gets a third of the same form,
+  `jr2-instance-effector`, applied with it in one List (ADR-0068).
+- **Starting a run needs the Instance token.** `POST /workflows/:name/runs` moves from `authenticated` to
+  `instanceOnly`. The scope of a Sandbox token is its own agent surface. The Custodian's route allowlist does not
+  forward this route, but that is not a control.
+
+## Considered options
+
+- **Ed25519, one short-lived token per admission, scoped to one iid.** This was the first proposal. Rejected. `wait`
+  reconnects indefinitely by design, and re-attach after a restart follows a ledgered admission of any age, so a short
+  expiry breaks both unless each poll gets a new token. That adds a public key in every pod and a dependency on clock
+  sync. What it buys over a per-placement bearer is scoping inside one pod. But the Agent already has code execution in
+  that pod's Harness container, so that scope protects nothing.
+- **The Instance token's digest, as the echo used.** Rejected. It is one secret for every pod, and it sends the Instance
+  token, the full-trust credential, into each Harness process.
+- **One Instance-wide Harness token.** Rejected. A digest does not let a Harness mint, but the bearer arrives in every
+  Harness process on every call. A per-placement bearer that leaks from one pod opens only that pod, which the Agent
+  there already controls.
+- **NetworkPolicy alone.** Rejected, for the reason ADR-0013 gives: a policy bounds where a pod may talk, and only a
+  token bounds what it may do. The policy cannot separate the Harness from the Custodian in one pod, and a cluster whose
+  CNI does not enforce policy gets nothing from it.
+
+## Consequences
+
+- **The stub Harness checks nothing.** It is a host-side test fixture that is reached by an explicit `endpoint`, and a
+  run on the stub path names no placement, so it sends no bearer. This is the second documented divergence from the
+  normative model ([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)). Conformance tests
+  inject the check (`checkBearer`), and `auth.test.ts` in `@jr2/harness` pins the routing of the gate.
+- **kindnet enforces NetworkPolicy.** On the kind version this repo pins, a deny-ingress policy blocks pod-to-pod
+  traffic, so the `@kind` tier proves both controls. A Sandbox's own Harness refuses an unauthenticated admission over
+  loopback, where no policy applies. A Sandbox cannot connect to the Instance Harness at all. The second test asserts a
+  transport failure, not a status, because a 401 would mean the bearer stopped it and the policy did not.
+- **Port-forward and probes are not affected.** `kubectl port-forward` enters the pod's network namespace through the
+  kubelet, and the kubelet's probes come from the node. On kind, neither is filtered by an ingress policy. So the CLI,
+  the Console, and a human's shell into the User Container ([ADR-0005](0005-sandbox-pod-composition.md)) keep working.
+  If routable access to the User Container is added later (ADR-0005 leaves it open), it must add its own ingress rule.
+- **The `@kind` history reads present the bearer.** The steps derive it from the instance Secret's signing key, as the
+  CLI reads the Instance token: over the kube API, with RBAC as the gate. A human reading a conversation does the same.
+- **Model keys are not in the Harness container.** `JR2_PROVIDER_API_KEY` and every other held secret live in the
+  Custodian, and the Harness container's env holds their Stand-ins (ADR-0059). `jr2 up` refuses a known model key in
+  `harness.env` or in an `envFrom` Secret.
+- **Open gaps, recorded here and not fixed:**
+  - **Sandbox egress.** An Agent with bash can reach the internet and send out anything it can read — which no longer
+    includes a held key: a client that goes around the Custodian carries only Stand-ins. A default-deny egress policy
+    needs an allowlist: DNS, the Orchestrator, the model provider, and whatever the work needs (package registries, for
+    example). That needs a config surface and cluster CIDRs, so it is a separate decision.
+  - **A held key can be spent.** The Agent can use a key through the Custodian while its pod lives, and a SigV4 or ADC
+    credential cannot be held at all ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)).
+  - **The Orchestrator's Secret writes are namespace-wide.** Its Role may create and patch every Secret, and may not get
+    or list one ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)): it applies its own
+    per-Sandbox Secrets and holds no git credential and no Effect secret. RBAC cannot pin `create` to a name, and
+    `resourceNames` has no prefix form. Two residuals stay, named in ADR-0068: a PATCH answers with the object, so a
+    caller that knows a Secret's name can still read it; and a Role that creates pods (through the Sandbox CR) can mount
+    a Secret into one.