# 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.
