@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md

@@ -0,0 +1,101 @@
+# The Console unlocks with a Caller's credential, and shows what its scopes allow
+
+[ADR-0014](0014-observation-is-open-run-state-is-not.md) built the HTTP surface on one premise: the visualizer page is a
+browser, and a browser holds no token — so it got a projection instead of a credential, and "give the page a token" was
+explicitly rejected. That page is now the **Console**: it starts runs, answers Gates and cancels runs, which are writes
+on the guarded surface. This ADR records how a browser earns those writes without moving the open band. The person
+presents a credential; the page never ships with one.
+
+## Decision
+
+- **The person presents a Caller's credential; the page never ships with one.** The Console's nav carries a password
+  field, and a login button for each JWT issuer that the Instance declares with `login: true`
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Empty, the page is
+  precisely ADR-0014's observer: open structure and observation, no control rendered. With a credential, the page sends
+  `Authorization: Bearer` on the guarded surface. The credential is any Caller's: the Instance token, a named Caller
+  token, or a JWT. The login gets a JWT from the issuer with OIDC (the authorization code flow with PKCE, as a public
+  client), and the page then uses it as it uses a typed token. The page as _served_ stays open and inert; ADR-0014's
+  rejection stands, because what it rejected was baking the credential into the page.
+- **The login's facts come from an open route, and its client id is the issuer's `audience`.** Before a login, the page
+  reads `GET /console/config`: `{ login: [{ issuer, clientId }] }`, from the issuers of the current Assembly that have
+  `login: true`. The route is in the open band (ADR-0014), because the page reads it before it holds a credential, and
+  both values are public: a public client has no secret, and the issuer's URL is in every JWT that it signs. The client
+  id is the issuer entry's `audience`, because the JWT that the login gives names its client as its audience, and that
+  is what the JWT authenticator checks. A login is opt-in for each issuer, because an issuer for machines (a CI
+  provider's tokens) has no login page. The page reads the issuer's discovery document, asks for `openid`, `profile`,
+  `email` and `groups` where the issuer lists each, and sends the ID token as the bearer: an access token's audience and
+  form differ between providers. The return address is always the Console's root (`/`), so the client registers one
+  redirect URI; the page then puts the address back to where the login began. The verifier, the state and that address
+  wait in `sessionStorage` until the return, and a return whose state does not match is refused. PKCE needs
+  `crypto.subtle`, so a login needs the Console on https or on localhost, and the issuer must let the Console's origin
+  call its discovery document and its token endpoint (CORS).
+- **The page shows only what the Caller's scopes allow.** On entry the page asks `GET /whoami` for the Caller record:
+  its name, the name that jr2 shows, and its scopes for each Workflow. It renders a control only where a scope opens its
+  route: the start form with `start` for that Workflow, Gate cards with `answer`, cancel with `cancel`, a run's full
+  state with `read`, and the Steering box with `steer`. The page re-fetches a run on a frame only for a Caller with
+  `answer` or `read` on its Workflow. The nav shows who the page acts as: the name that jr2 shows, else `<via>/<name>`,
+  with the scopes in its title, and a sign-out button in place of the field. The server still checks each request
+  (ADR-0014); the page hides a control so that a person does not meet a 403, not as a guard.
+- **The credential lives in `sessionStorage`** — survives a reload, dies with the tab, never a cookie (no ambient
+  credential, no CSRF surface). A typed token and a login's JWT live there alike. A later 401 (an expired JWT, a rotated
+  token) drops the UI back to observer mode rather than failing per widget.
+- **Gate discovery is a frame-triggered guarded read, not an open-band extension.** A Gate exists exactly while its
+  invoking state is entered ([ADR-0011](0011-workflow-defined-events.md)), and every entry/exit lands a status frame on
+  the open workflow feed (ADR-0022) — so a Console whose Caller has `answer` reads `GET /gates` on entry and again on
+  each frame, and folds the Gates into its store. `GET /gates` lists only the Gates that the Caller may answer, across
+  every Workflow (ADR-0078), so the Gate cards are the person's inbox and never show a Gate the person cannot answer.
+  Synchronized, no polling loop, and the observation projection is untouched. A delivery's success is likewise confirmed
+  by the next frame emptying the card, never by local bookkeeping.
+- **The rail lists ended runs too.** It lists the live runs and, under them, the ended runs of the selected Workflow
+  from `GET /runs?status=ended&workflow=<name>` (ADR-0009), each with its status, and a `drifted` run with its reason
+  (ADR-0030). An ended run opens as a live one does: its graph, its last status and its conversations, for as long as
+  jr2 keeps the run (ADR-0065). A run on an older Assembly carries the mark "older Assembly · <hash>" and is drawn on
+  its own Machine, live or ended: an ended run's row names the Machine it ran on
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). A `drifted` run has no
+  Machine to draw, so it shows its drift reason in place of the graph. The Console shows each outstanding pick as
+  "outstanding since".
+- **A conversation opens in a bottom drawer.** A full-width drawer across the bottom of the page shows the run's
+  conversations ([ADR-0023](0023-the-harness-prints-the-conversation.md)). A person can change its height, and the page
+  keeps the height for that viewer. Closed, it is a bar of tabs, one for each Agent slot, with a dot on a slot whose
+  Turn is live. Open, it shows the selected slot's conversation and follows a live Turn, with the Steering box beside it
+  for a Caller with `steer`. It reads the conversation routes, so it needs `read`. The right drawer keeps Attention and
+  Activity.
+- **Page addresses content-negotiate; JSON is the default dialect.** `/` and `/workflows/:name` serve the Console shell
+  to `Accept: text/html` and JSON to everything else — so the workflow-detail resource keeps its natural address (the
+  run-input schema's home, [ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)) and no future page has to
+  squat on a mangled sibling path. Nothing existing moves: EventSource asks `text/event-stream`, and the Harness's Menu
+  and the CLI never ask for HTML. `/viz/*` is deleted (greenfield, no redirects); assets move to `/assets/*`, which also
+  retires the "a workflow named `assets` is shadowed" hazard.
+
+## Considered options
+
+- **`jr2 ui` — the CLI opens the browser through an authenticated local proxy.** A convenience layer worth building _on
+  top of_ the token field later, not a substitute: it has no answer for the deployed jr2 Application behind an ingress,
+  where the browser talks to the Service directly and the CLI is not in the path.
+- **The Instance token alone.** Rejected (ADR-0078): a person who must answer Gates and holds no cluster RBAC would then
+  hold every act on every run. A scoped Caller's credential is what that person holds.
+- **The conversation in the right drawer.** Rejected: a conversation needs the page's width, and the right drawer keeps
+  Attention and Activity.
+- **Announce gates on the open observation feed** (even just `{runId, gate}`). Rejected: it widens the projection for a
+  convenience the credential already solves, and the open band has an unresolved exposure question as it stands (spawn
+  ids — the ADR-0014 open call). The projection stays the one place the line is drawn.
+- **A `/ui` path prefix, or moving the API under `/api`.** Rejected for negotiation: the first is ceremony on the
+  address a human types, the second churns the Harness's Menu, the Custodian's route allowlist, the CLI, and the
+  ADR-0009/0013 route tables for cosmetics.
+
+## Consequences
+
+- **No new band.** The server-side diff of the Console itself is: negotiate two addresses, serve the shell, retire
+  `/viz/*`, and serve `GET /console/config` in the open band. The scopes, `GET /whoami` and the login's issuers are
+  ADR-0078's.
+- **Possession follows the credential.** The Instance token stays one `kubectl get secret` away for whoever holds
+  cluster RBAC; a named token is what its holder was given; a login is what the identity provider's groups grant.
+- **The XSS caveat is the real one and is bounded by what the page is:** a credential in `sessionStorage` is readable by
+  scripts on the page, so the Console must keep serving only its own assets — no CDN, no third-party script, exactly the
+  constraint the viz page already lives under.
+- **GLOSSARY.md**: **Console** is a glossary term (visualizer, dashboard, UI, viz on its Avoid list).
+- **The Console's UX gets a browser tier** — `@console`-tagged Cucumber scenarios holding a Playwright page, in
+  `@jr2/e2e`, excluded from the default profile ([ADR-0010](0010-bdd-acceptance-tests.md) as amended). What the page
+  _believes_ stays unit-tested in `console-store.test.ts`, and the login's pure half in `console-login.test.ts`; the
+  browser tier asserts what a user does and sees, and the login against Dex in a container (ADR-0078). The login
+  scenario is also tagged `@dex`, because it needs docker, which the rest of the tier does not.

package/docs/reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md

@@ -3,7 +3,7 @@
 `POST /workflows/:name/runs` takes a JSON body and hands it to the machine as xstate `input` — unvalidated, and
 undescribed: the module contract is `export const machine` alone (ADR-0011/0015), so nothing at runtime says what a run
 of a given workflow should be started _with_. The Console's start form
-([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)) forced the question, but the gap predates it —
+([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)) forced the question, but the gap predates it —
 `jr2 run` has the same blindness, and a typo'd input surfaces as a confusing mid-run failure instead of a refusal at the
 door. Meanwhile every event a machine _accepts_ already carries a zod schema, attached to the machine itself
 ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)'s vocabulary-on-the-machine). The input that starts a
@@ -93,8 +93,9 @@ machine is the one piece of its vocabulary that pattern missed.
 - **The door takes an idempotency key, out of band.** A start may carry one in a header, never in the body (a body field
   would be one every door had to reserve); a repeat with the same key answers with the run the first one made. A
   `dispatch` Effect sends its ledger row's id ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), so a
-  start whose answer was lost is sent once where it may have arrived (ADR-0067) and makes one run. `jr2 run` and the
-  Console send none.
+  start whose answer was lost is sent once where it may have arrived (ADR-0067) and makes one run. With a second header,
+  a start is a key-only ask: the door answers the run under the key, or that no run has it, and starts nothing.
+  `jr2 run` and the Console send none.
 
 ## Considered options
 

package/docs/reference/decisions/0034-the-console-renders-with-preact-and-the-server-erases-the-types.md

@@ -1,11 +1,11 @@
 # The Console renders with Preact, and the server erases the types
 
-The Console ([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)) outgrew its framework-free form: `main.js`
-reached ~1,500 lines, much of it hand-rolled DOM reconciliation (`memo()`, `paint()`, manual list diffing) — work a view
-library exists to own. Three standing constraints shaped the replacement: the repo is zero-build (Node 24 strips types;
-nothing compiles), the Console serves only its own assets (ADR-0032), and `@jr2/orchestrator` is a library that serves
-its files from disk wherever the process starts. A fourth arrived with this decision: Console source is TypeScript like
-everything else.
+The Console ([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)) outgrew its framework-free form:
+`main.js` reached ~1,500 lines, much of it hand-rolled DOM reconciliation (`memo()`, `paint()`, manual list diffing) —
+work a view library exists to own. Three standing constraints shaped the replacement: the repo is zero-build (Node 24
+strips types; nothing compiles), the Console serves only its own assets (ADR-0032), and `@jr2/orchestrator` is a library
+that serves its files from disk wherever the process starts. A fourth arrived with this decision: Console source is
+TypeScript like everything else.
 
 ## Decision
 

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

@@ -81,10 +81,11 @@ every build) and promotes incidental image properties into contract items.
   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.
+  as before. A raw `kubectl exec` shell does not get the variable, as it does not get the PATH append;
+  `jr2 workspace shell` starts through the spawner, as an Agent's `bash` does (ADR-0009). 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

package/docs/reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md

@@ -47,27 +47,27 @@ because they are one problem: **what a Machine depends on that is not inside it.
   ADR-0011 adopted for Vocabulary.
 - **Customization is `customize(machine, parts)`**, a plain function in the family of `workspace()` and `pool()`,
   returning a plain `StateMachine`. `parts` has the declaration's own shape, recursively partial:
-  `{ agents?: { <slot>?: Partial<AgentDefinition> }, effects?: { <slot>?: { url } | { argv } | { secret } }, image?, user?, repos?: { <slot>?: Binding }, actors?: { <child>?: parts } }`
+  `{ agents?: { <slot>?: Partial<AgentDefinition> }, effects?: { <slot>?: { url } | { argv } | { secret } | { server } | { tool } }, image?, user?, repos?: { <slot>?: Binding }, actors?: { <child>?: parts } }`
   — the two image seats together, since ADR-0005 gives the User Container the same static option, and the Repo Slots
   beside them, since ADR-0051 makes a Repo a `workspace()` slot a composer binds. `effects` binds an Effect's Open url,
-  argv or secret name, once — an Effect with an Open secret and an Open url or argv takes one object with both keys,
-  `{ url, secret }` or `{ argv, secret }`
-  ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)): the slot's logic is built
-  again with the bound part and substituted as an Agent override is. Internally an Agent override is xstate's
-  `machine.provide({ actors: { researcher: agent(merged) } })`, with the override layered over the stock definition; a
-  child override is the same call one level down, recursing — each level is exactly the one-level reach ADR-0015 found
-  `provide` has, held by the composer who owns the child object, never host-side injection. jr2's wrappers are
-  transparent: `customize(research, { agents })` reaches the body through the `body` slot (and `pool()`'s `worker`, at
-  any depth), so a consumer never writes `body`. The images and the Repo bindings are the parts `provide` cannot carry
-  (xstate copies only implementations, and every part is keyed on the config it passes through by reference), so those
-  fields clone the wrapper's config and rebuild it with the same implementations, re-attaching what the original
-  carried. A bound argv's load warnings are such a part too: `customize()` rebuilds the Machine the author wrote the
-  same way, with the vocabulary, the seats and the door it carried and the warnings the walk gives for the bound argv,
-  so no attachment is keyed on anything but the config. Only DECLARED parts can be retuned, and the compiler is what
-  says so: the slots are read off xstate's own `TActor` parameter, so an Agent, a Repo Slot, or a child the Machine does
-  not carry is a type error (ADR-0050), and the runtime refuses the same call naming the Machine's own slots. Rejected:
-  a `.with()` method on the machine — it needs a jr2-owned machine type over xstate's, which ADR-0015 avoided, and it
-  vanishes after any `.provide()`; a callable-machine hybrid — verified to work, reads as a trick.
+  argv, MCP server and tool, or secret name, once — an Effect with an Open secret and an Open url or argv takes one
+  object with both keys, `{ url, secret }` or `{ argv, secret }`, and an `mcp` Effect with an Open server and tool takes
+  `{ server, tool }` ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)): the
+  slot's logic is built again with the bound part and substituted as an Agent override is. Internally an Agent override
+  is xstate's `machine.provide({ actors: { researcher: agent(merged) } })`, with the override layered over the stock
+  definition; a child override is the same call one level down, recursing — each level is exactly the one-level reach
+  ADR-0015 found `provide` has, held by the composer who owns the child object, never host-side injection. jr2's
+  wrappers are transparent: `customize(research, { agents })` reaches the body through the `body` slot (and `pool()`'s
+  `worker`, at any depth), so a consumer never writes `body`. The images and the Repo bindings are the parts `provide`
+  cannot carry (xstate copies only implementations, and every part is keyed on the config it passes through by
+  reference), so those fields clone the wrapper's config and rebuild it with the same implementations, re-attaching what
+  the original carried. A bound argv's load warnings are such a part too: `customize()` rebuilds the Machine the author
+  wrote the same way, with the vocabulary, the seats and the door it carried and the warnings the walk gives for the
+  bound argv, so no attachment is keyed on anything but the config. Only DECLARED parts can be retuned, and the compiler
+  is what says so: the slots are read off xstate's own `TActor` parameter, so an Agent, a Repo Slot, or a child the
+  Machine does not carry is a type error (ADR-0050), and the runtime refuses the same call naming the Machine's own
+  slots. Rejected: a `.with()` method on the machine — it needs a jr2-owned machine type over xstate's, which ADR-0015
+  avoided, and it vanishes after any `.provide()`; a callable-machine hybrid — verified to work, reads as a trick.
 - **A package exports a Machine, nothing beside it.** The door (ADR-0033), the vocabulary, the Agents, and the image all
   ride the exported object. The three uses:
 

package/docs/reference/decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md

@@ -17,7 +17,12 @@ a definition lives, and the gate that enforces it.
   an Effect names it with `secret("name")`, and the Instance declares it in the top-level `secrets` list
   ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). The name is a string, not a type: the
   walk after the typecheck refuses an Effect that names a secret the list does not hold, before anything is built.
-  `jr2.config.ts` holds reach and credentials (`harness`, `secrets`, `git.credentials`, `registry`).
+  `jr2.config.ts` holds reach and credentials (`harness`, `secrets`, `git.credentials`, `registry`, and the Callers'
+  `callers`, `hooks` and `cors`,
+  [ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). A Machine names no Hook: a
+  Gate's or a Source's handlers are keyed by the Hook's kind ([ADR-0011](0011-workflow-defined-events.md)), and only a
+  Hook's address names it. A Hook kind is code that the config and the Workflows import by name, so it is neither
+  declared nor discovered: it comes in by `import`, as a nested Machine does, and `jr2 up` bundles it into the Assembly.
 - **The slot key types a Repo.** A `workspace()` declares its Repos as slots —
   `repos: { target: open, docs: { url, ref } }` — and the keys are a phantom on the wrapper type, read through
   `pool()`'s `worker` and `workspace()`'s `body` as the image is (ADR-0049). A

package/docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md

@@ -31,48 +31,63 @@ the one part ADR-0049/0051 left a package unable to leave unsaid: **the model.**
   who never reads the file spends money on a model they did not choose, silently, which is the failure class `jr2 up`
   exists to make loud. Rejected: a Machine factory `task({ model })` — ADR-0049 settled that a package exports a Machine
   and retunes with `customize`, and a factory reopens that.
-- **Open widens to an Effect's url, argv and secret, bound once.** A package cannot know the host its `http` Effect
-  calls, the program its `command` runs
+- **Open widens to an Effect's url, argv, MCP server and tool, and secret, bound once.** A package cannot know the host
+  its `http` Effect calls, the program its `command` runs, the MCP server and tool its `mcp` Effect calls
   ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)), or the secret its
   composer spends, so it may leave each Open: `http({ method, url: open, auth, input, request })`,
-  `http({ method: "PUT", url: open, body: file(path) })`, `command(open, { env, pin })`, and `secret(open)` in place of
-  a secret's name. The url, the argv and the secret's name are the Open parts of an Effect that exist; everything else
-  the definition says is the package's as written — the method, the headers, the auth and the secrets they name, the
-  input, `request`, the env, `pin` — and is checked when the Machine is built. `secret(open)` is taken by `bearer`,
-  `basic` (the user or the password), a header's value, and a command's env, as its value or its `.path`; in a url it is
-  refused when the Machine is built ("leave the whole url Open"), since a url that carries a secret is left Open whole
-  (below). An Effect takes one Open secret: a second `secret(open)` in one definition is refused when the Machine is
-  built ("an Effect takes one Open secret"); the one `secret(open)` may stand in several places, a value and its
-  `.path`. An Effect that names an Open secret is placed as one that names a secret is — a credentialed command in the
-  Sandbox Effector, an `http` where its body places it — before the name is known. The composer binds the parts with
-  `customize(machine, { effects: { <slot>: { url } } })`, `{ argv }` or `{ secret }`, and an Effect with an Open url or
-  argv beside an Open secret takes one object with both keys (`{ url, secret }`, `{ argv, secret }`): a url is a string
-  or a `text` with a secret in its path, an argv is the usual list, and a secret is a name that obeys `secret()`'s own
-  rule — it is the secret's file in the Effector's mount (ADR-0068). The type of `effects` is the intersection of the
-  Open parts' bindings, so a binding that leaves one of them unbound is a compile error, as an unbound url is; at run
-  time, a binding that leaves one unbound gives an Effect still Open in it, which a later `customize()` may bind. Each
-  is bound ONCE, to a value: never a mapper over the door, so a host is fixed in the definition or bound before any run,
-  and no run chooses one, nor a secret. Binding builds the Effect again with its constructor, with the bound name in
-  every place `secret(open)` stood, so a bound part meets every rule the constructor checks — a literal host, no secret
-  in a query, a non-empty argv, a secret's name — and the bound Effect is the one the same definition written with that
-  name gives; `jr2 up` reads it as written: the placement, the secrets it names, and the Effector's fence
-  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)) are the bound ones, and the bound secret
-  is placed only in that Effect's Effector, as a named secret is. Only an Open part is offered: a part the author fixed
-  is no key of `effects` and is refused at the call, and a part bound once is fixed from then on, so a second composer
-  cannot move it. `effects` reaches through `workspace()`'s body, `pool()`'s worker and a composed Machine's `actors`,
-  as `agents` does, typed off the slot's logic. An Open argv's slots are the composer's, so the load walk counts every
-  pick param as read by it when the Machine is built, and `customize()` runs the walk's pick-param check again once the
-  argv is bound — a param the bound argv does not read is refused there, and a warning it gives for the bound argv is
-  the bound Machine's, as it is the same Machine's written with that argv: the bound Machine gets a config of its own,
-  which carries those warnings ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)), so a copy
-  `provide()` makes of it — a run's — keeps them, and the Open Machine keeps its own. The compiler's check does not
-  reach a bound argv: an Open argv's input is one string per key, so nothing at build or at `customize()` checks that
-  the invoke supplies each slot the bound argv names, and a slot it does not supply faults when the Effect starts — its
-  state's `onError`, with nothing run. The `jr2 up` walk reports an Open Effect beside Open Repo Slots and Agents and
-  refuses the converge naming the `effects` line — `{ effects: { <slot>: { secret: "<name>" } } }` for an Open secret,
-  one object with both keys for an Effect with two Open parts; the Effect refuses to run while Open, as the second fence
-  — its state's `onError`, with nothing sent and no ledger row. The Open part is the whole url, the whole argv, or the
-  secret's name.
+  `http({ method: "PUT", url: open, body: file(path) })`, `command(open, { env, pin })`,
+  `mcp.call(open, open, { input })`, and `secret(open)` in place of a secret's name. The url, the argv, an `mcp`
+  Effect's server and tool, and the secret's name are the Open parts of an Effect that exist; everything else the
+  definition says is the package's as written — the method, the headers, the auth and the secrets they name, the input,
+  `request`, the env, `pin` — and is checked when the Machine is built. `secret(open)` is taken by `bearer`, `basic`
+  (the user or the password), a header's value, and a command's env, as its value or its `.path`; in a url it is refused
+  when the Machine is built ("leave the whole url Open"), since a url that carries a secret is left Open whole (below).
+  An Effect takes one Open secret: a second `secret(open)` in one definition is refused when the Machine is built ("an
+  Effect takes one Open secret"); the one `secret(open)` may stand in several places, a value and its `.path`. An Effect
+  that names an Open secret is placed as one that names a secret is — a credentialed command in the Sandbox Effector, an
+  `http` where its body places it — before the name is known. The composer binds the parts with
+  `customize(machine, { effects: { <slot>: { url } } })`, `{ argv }`, `{ secret }`, `{ server }` or `{ tool }`, and an
+  Effect with two Open parts takes one object with both keys (`{ url, secret }`, `{ argv, secret }`,
+  `{ server, tool }`): a url is a string or a `text` with a secret in its path, an argv is the usual list, and a secret
+  is a name that obeys `secret()`'s own rule — it is the secret's file in the Effector's mount (ADR-0068) — and a server
+  is a name of the `mcp` block of `jr2.config.ts`, whose secret is the server's own, so an `mcp` Effect takes no
+  `secret(open)`
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). The
+  type of `effects` is the intersection of the Open parts' bindings, so a binding that leaves one of them unbound is a
+  compile error, as an unbound url is; at run time, a binding that leaves one unbound gives an Effect still Open in it,
+  which a later `customize()` may bind. Each is bound ONCE, to a value: never a mapper over the door, so a host is fixed
+  in the definition or bound before any run, and no run chooses one, nor a secret. Binding builds the Effect again with
+  its constructor, with the bound name in every place `secret(open)` stood, so a bound part meets every rule the
+  constructor checks — a literal host, no secret in a query, a non-empty argv, a secret's name — and the bound Effect is
+  the one the same definition written with that name gives; `jr2 up` reads it as written: the placement, the secrets it
+  names, and the Effector's fence ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)) are the
+  bound ones, and the bound secret is placed only in that Effect's Effector, as a named secret is. Only an Open part is
+  offered: a part the author fixed is no key of `effects` and is refused at the call, and a part bound once is fixed
+  from then on, so a second composer cannot move it. `effects` reaches through `workspace()`'s body, `pool()`'s worker
+  and a composed Machine's `actors`, as `agents` does, typed off the slot's logic. An Open argv's slots are the
+  composer's, so the load walk counts every pick param as read by it when the Machine is built, and `customize()` runs
+  the walk's pick-param check again once the argv is bound — a param the bound argv does not read is refused there, and
+  a warning it gives for the bound argv is the bound Machine's, as it is the same Machine's written with that argv: the
+  bound Machine gets a config of its own, which carries those warnings
+  ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)), so a copy `provide()` makes of it — a run's
+  — keeps them, and the Open Machine keeps its own. The compiler's check does not reach a bound argv: an Open argv's
+  input is one string per key, so nothing at build or at `customize()` checks that the invoke supplies each slot the
+  bound argv names, and a slot it does not supply faults when the Effect starts — its state's `onError`, with nothing
+  run. The `jr2 up` walk reports an Open Effect beside Open Repo Slots and Agents and refuses the converge naming the
+  `effects` line — `{ effects: { <slot>: { secret: "<name>" } } }` for an Open secret, one object with both keys for an
+  Effect with two Open parts, `{ effects: { <slot>: { server: "<name>" } } }`, `{ tool: "<tool>" }` or both for an `mcp`
+  Effect, with only its Open keys; the Effect refuses to run while Open, as the second fence — its state's `onError`,
+  with nothing sent and no ledger row. The Open part is the whole url, the whole argv, an MCP server's name or a tool's
+  name, or the secret's name.
+- **Open widens to a hooked Gate's look, which only warns.** A package writes the Hook handlers of its Gate slots for
+  each forge that it supports, because a forge's payload is public, so a handler is never Open. It imports the Hook kind
+  of each forge that it hears, for the payload types, and it has `@jr2/orchestrator`, which holds the kinds, as a peer
+  dependency ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Which Hooks of
+  those kinds exist is the Instance's config. A look needs a url and a token, so a package leaves `look: open`, and the
+  composer binds it once, to a look or `"none"`, with `customize(machine, { gates: { <slot>: { look } } })`, which can
+  also add, replace or remove a handler by kind and event key ([ADR-0011](0011-workflow-defined-events.md)). An Open
+  look that nobody binds is the one Open part that `jr2 up` does not refuse: it warns, as it warns about a hooked Gate
+  with no look, because the Gate still works when a person answers it with `jr2 send`.
 - **The per-run Dial is the escape hatch, not the default.** A shipped Machine's door may carry `model` and
   `thinkingLevel` (ADR-0018's two Dials) and fold them into each invoke's input; the bound definition is what `jr2 up`
   preflights, the door value overrides it for one run's Turns. Nothing in jr2 changes for this — it is the Machine's own

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

@@ -16,10 +16,10 @@ version, images, gate, trigger.
   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.
+  had to be. `publishConfig.access: public` stays on every public package, 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
@@ -50,11 +50,11 @@ version, images, gate, trigger.
   ([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.
+  tag produces one staged tarball per public package 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
@@ -94,14 +94,15 @@ version, images, gate, trigger.
   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.
+  publisher on each public package and revoke the token. Each new public package needs the same step once: publish its
+  first version by hand before the first tag that holds it, or that tag's `npm stage publish` of it fails. 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`,
+- The public 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/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md

@@ -52,6 +52,13 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
   - **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.
+  - **Each segment of the actor path is encoded, then the segments are joined with `.`.** An actor id can be any text
+    (an item id is the source's), and with plain `.` joints the paths `a.b`, `c` and `a`, `b.c` were one conversation. A
+    letter, a digit, `-` and `_` stay as they are; each other character becomes `~` and two upper-case hex digits for
+    each of its UTF-8 bytes (`F.12` is `F~2E12`). So a segment has no `.` and no `/`, the iid's two joints, and nothing
+    that a URL path or a header must escape. The root Machine's path is `root`. Two segments are escaped although each
+    of their characters may stay: `root` is `~72oot`, and the empty id is `~`. So no other path is `root` or empty, and
+    two paths never have one spelling.
   - **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

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

@@ -42,7 +42,7 @@ and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harne
   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
+  which is what [ADR-0032](0032-the-console-unlocks-with-a-callers-credential.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.
@@ -52,9 +52,11 @@ and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harne
   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.
+- **Starting a run needs a Caller with `start`.** `POST /workflows/:name/runs` moves from `authenticated` to the guarded
+  band, where a Caller's `start` scope opens it
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). A Sandbox token is no
+  Caller: its scope is its own agent surface. The Custodian's route allowlist does not forward this route, but that is
+  not a control.
 
 ## Considered options
 
@@ -84,10 +86,14 @@ and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harne
   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 Console, `jr2 workspace forward` and `jr2 workspace shell --user` into the User Container
+  ([ADR-0005](0005-sandbox-pod-composition.md), [ADR-0009](0009-cli-and-instance-interface.md)) keep working: they reach
+  the pod by port-forward and exec through the kube API, and no Service routes to the User Container. 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.
+  CLI reads the Instance token: over the kube API, with RBAC as the gate. A human reads a conversation from the
+  Orchestrator's record with `jr2 logs`, behind `read` ([ADR-0023](0023-the-harness-prints-the-conversation.md)), and
+  needs no bearer of a Harness.
 - **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.