---
title: "The Gateway window"
description: "Fox9 Admin (shown as Vulpine Admin), the native local operator surface of ADR 0016: the gateway owns its projections and mutation admission, the app reads them over the owner-only Unix socket, the install recipe, and each panel (health, events, presentation, agents, dictation, meetings, plus the shadow pair, satellite, held announcements and adapter rows) with its current mutation boundary."
type: "living"
source: "docs/admin.md"
verified: "2026-11-07"
group: "Frontends"
---

> **Living doc**, checked against the code 2026-11-07

The Gateway window is the operator's local control surface, the window of Vulpine Gateway.app. The code and the
glossary call this surface the Admin. It is not a Frontend Skin. It does not own voice capture, playback, Brain turns,
provider credentials, arbitrary files or processes, or production activation. The Voice Gateway owns the Admin
projections and admits every mutation. The app sends generated `AdminRequest` messages over the Gateway's owner-only
Unix socket and never writes configuration itself.

The app is the GPUI app in `apps/admin-shadow` ([Vulpine Gateway.app](/docs/frontends/gateway-app)). It calls
`crates/admin_core` in process. Its sidebar has eight groups: Overview; Live (Voice, Performance, Events, Decision with
the Label queue); Gateway (Controls, Health, Setup, Configuration with Connectivity, Models, Transports, Sessions and
Audio); Extend (Hardpoints, Packs with the Catalog, Tools); Fleet & reach (Fleet, Reach, Agents, Approvals, Pipelines
with Dispatch, Brain); House (Home, Room speakers, Meetings, Dictation, Glyph); Records (Speech text, Reads, Operator
affect); and Looks (`GROUPS` in `apps/admin-shadow/src/sections.rs`). The page names below are the sidebar's.


## Authority and transport

The Voice Gateway owns the Rust-authored Admin projection. `crates/admin_core` (UI-free) sends the generated
`AdminRequest::GetSnapshot` over the owner-only Unix socket and returns the generated `AdminSnapshot`. Every other
panel reads its own `AdminRequest::Get*` the same way. The Gateway screens every answer before it leaves the socket.


`PlanConfigMutation` only plans. It checks `expected_revision` against the snapshot's `revision` and answers with an
`AdminMutationPlan` (base and target revision, apply mode). `ApplyConfigMutation` (owner-local, ADR 0065) applies a
plan to the gateway's Admin config overlay when `[admin] config_writes = true`. Otherwise it is refused
`config_writes_off` (see [Current mutation boundary](#current-mutation-boundary)).

The endpoint is disabled by default:

```toml
[admin]
enabled = true
socket_name = "admin.sock"
```

`socket_name` is a bounded portable basename. The Gateway resolves it beneath the canonical state directory and
rejects arbitrary paths and unsafe ancestors. Before you enable Admin, provision the `0700` Admin directory, the
`.fox9-admin-owner` file and the `.fox9-admin-endpoint` marker (the effective basename plus a newline), both mode
exactly `0600`, as below. Startup fails closed when any of them is missing or invalid. The Gateway never creates or
repairs these paths; it creates only the owner-only socket. Gateway startup and the Admin both validate the basename
through `AdminConfig::socket_path`. The UI never receives a filesystem path.

The default directory is `$HOME/.local/state/vulpine/admin` on macOS and Linux (`crates/admin_markers/src/roots.rs`;
an install that has only the old `foxline` state root still resolves there for one release). Provision the default
endpoint exactly once before enabling Admin:

```sh
admin_dir="$HOME/.local/state/vulpine/admin"
install -d -m 0700 "$admin_dir"
umask 077
printf 'fox9-admin-socket-v1\n' >"$admin_dir/.fox9-admin-owner"
printf 'admin.sock\n' >"$admin_dir/.fox9-admin-endpoint"
chmod 0600 "$admin_dir/.fox9-admin-owner" "$admin_dir/.fox9-admin-endpoint"
```

## Development

```bash
cargo test -p admin_core
python3 tools/apps/check_gpui_apps.py --apps admin-shadow --steps check,clippy,test
just apps::admin-shadow-parity --check
```

The app has a status item in the menu bar with **Open** and **Quit**. Closing the main window hides it. Snapshot
refresh is read-only and bounded by the Gateway Admin client deadline. A disconnected Admin keeps the last confirmed
snapshot, marks it disconnected and shows the endpoint error. It never invents replacement state.


### Install

`just apps::admin-install [host]` builds, signs and installs the app on the gateway host, keeping the old bundle as
`Vulpine Gateway.app.previous` (the rollback); [Vulpine Gateway.app](/docs/frontends/gateway-app) has the steps.

- The version is `bundle.json`'s `short_version`. Every build is stamped by `tools/repo/admin_build_id.py`:
  CFBundleVersion is the UTC build time (`YYYYMMDD.HHMMSS`), and `Contents/Resources/vulpine-build.json` names the
  commit. The install line reads `Vulpine Gateway <version> build <id>`.
- The install never launches the app. A running copy keeps the old bytes until you quit it. Open the new one from
  Finder the first time (AMFI).
- The Admin draws its own Pop out window, so the bundle carries no pop-out binaries. There is no Sparkle and no
  notarization.
- The newer gateway fields below are optional and serde-default. An older app still reads a newer gateway, and an
  older gateway shows those cells empty.


## Health and topology

`get_admin_health` is available only through the owner-local Admin socket. Every component row is bound to one
observation generation. It carries requirement, state, severity, freshness, probe, desired/effective/live identity,
degraded capability, reconnect evidence, queue capacity and drops, terminal reason, and a bounded repair action. Edges
name both admitted components, the transport kind, the state and the same generation.

The Gateway probes itself, the Admin Unix socket and its in-process subsystems (retrieval, operator and host memory,
the Swift bridge, mic control, providers). Each bound session's Brain, speech workers and Frontend Skin project from
what that session's pipeline observed. A component it has not observed renders as `unknown` with no live identity. The
Admin may show `stale` from the observation and expiry times, but it cannot promote unknown or stale evidence to
healthy.

## Events and errors

The Gateway owns an immutable, owner-local event projection capped at 80 records. Events carry component,
continuity/operation correlation, generation, phase, severity, recoverability, terminal outcome, sanitized message,
repair action, observation time and persistence. Within the newest 256 event IDs, a duplicate identical ID is
idempotent and a conflicting ID is rejected. Consequential failed or terminal events must be persistent; they are kept
ahead of ordinary observations. A full timeline first drops a non-persistent row from a component that holds half of
it or more, else the oldest non-persistent row.

The timeline can pause, clear, include or exclude, and group its rows without clearing Gateway evidence. Exports are
redacted again, drop non-persistent rows first, and never exceed 64 KiB. The Gateway never admits raw audio,
transcripts, prompts, results, credentials, URL query or fragment, private paths, headers or HTML.

## Presentation and Persona

The presentation projection keeps these apart: Agent, Persona, Voice Profile ID/label/source, voice lock, Visual
Theme, speech owner, semantic phase, input/output activity, Avatar Actions, reduced motion, listener state, and
persistent errors. Absent runtime evidence serializes as `unknown` or `null`. The Admin never derives voice identity
from a theme, provider, token, process or animation.

Visual Theme and reduced motion are Shell-owned settings. Applies require the confirmed revision, accept a closed theme
set, persist through an owner-only atomic file replacement, and return authoritative readback. They never change Brain
Agent, Persona, Voice Profile, speech ownership or production activation. The recursive admission and export invariant
is in [`admin-event-string-safety.md`](/docs/frontends/admin-event-string-safety).


Each session card may add lines from optional fields of the session row. A gateway that does not send a field shows no
line.

- `stt_fault {since_ms, reason, on_fault}` reads "speech recognition down since &lt;age> (&lt;reason>, text only)". The age
  uses the Admin's own clock, so it ticks while the snapshot is unchanged. The panel header counts the sessions in
  fault.
- `door_runs {open, busy_refused}` reads "door runs: N open", adding "busy refused: M" when M is above zero. These are
  the session's open Tool door runs (receipt calls and read-verb fetches, at most four) and the runs it refused
  `busy`. The gateway's validator refuses a projection whose `open` is above four.
- `dispatch` is the class of the open `pi_herdr_dispatch` call that holds the session's dispatch slot. It is
  `mutating` when a prepare, pipeline, plain advance, close or another mutating call is open (the next mutating call
  is refused `busy`), else `wait` when only report waits are open, else `read`. It is absent when no dispatch call is
  open. The line reads "dispatch: mutating".
- `dispatch_busy` counts dispatch-conflict refusals: a second mutating call, or a second open call on one pipeline.
  It is counted apart from the four-run cap's `busy_refused`. The line reads "dispatch busy: K".

The validator takes only the three closed `dispatch` words, and only while a run is open. The `tool_door_invoked`
trace row carries the same `dispatch` word for every `pi_herdr_dispatch` call.

## Dispatch and Pipelines

**Dispatch** lists the agents' task reports. Its header adds a door line read from the session rows' `door_runs`: the
strongest class open across the sessions ("door: a mutating call holds the dispatch slot (the next one is busy)",
"report waits open (the slot is free)", "a read open") and the summed `dispatch_busy`. It reads "door: no dispatch call
open" when sessions carry door rows and none holds the slot. The line is absent when no session has a door row.

**Pipelines** shows one row per herdr pipeline record that the gateway read on its own host (`GetPipelines`). A row has
the name, repo, host, stage, status, outcome and close, and the agent column. `liveness` is running, reported, stale or
unknown. Optional fields at the end of `AdminPipelineRow`:

- `agent_status` is herdr's own word for the agent in the pane the record names, from the fleet probe: `working`,
  `idle`, `done` or `blocked` while the pane is listed. It is `gone` when the host's list is read and names none of the
  record's panes, and `unknown` when the list is unread or older than the open stage. A record the operator closed
  carries none. A live pane whose agent is `done` or `idle` reads "agent done, not collected" in amber: the stage
  finished without the pipeline collecting its report.
- `panes_closed` is the record's sweep count, shown as "panes closed N" beside the outcome.
- `stages[]` has each stage's role and status, and its `dispute` (a disputed done) or `note` (an unverified done, or a
  review with no verdict). Each text is one line of at most 120 characters. A word the Admin's prose rule refuses (a
  home path, a URL, a secret's shape) is `[redacted]`. The section lists them under the row as "stage 1 build:
  disputed — …". The mission, the task and the summary never leave the gateway.
- `acceptance` is the record's acceptance contract as counts: `files`, `commands`, and `met` (every stage judged
  against the contract ended `done_verified`). The stage cell reads "acceptance 2 files, 1 check: met", or "open" while
  the pipeline runs and "not met" once it settled. The paths and the commands never leave the gateway.
- `stalled` counts the stages the stall rule ended (the agent done or gone with no report). The row reads "stalled"
  beside the outcome, the header reads "N stalled", and a "stalled only" toggle filters the rows.
- `unfenced_reports` and `prose_verdicts` show beside the outcome as "unfenced reports 2, prose verdicts 1".
  `fallback_kinds` and `report_grace_minutes` show as "fallback pi; report grace 10 min".

A settled row the operator has not closed carries a close-me hint: the agent word, then
`pi_herdr_dispatch close {name: "<name>", outcome, reason}`. The hint is amber when the pane is still listed.

Each row has two actions, sent through the typed tool door. The Admin's `pipeline_door_action` passes one `InvokeTool`
for `pi_herdr_dispatch` to the Glyph on the Admin's own host, the same door `vulpine-glyphctl tool` uses. The gateway
admits it through the bound loadout's `allowed_pi`, then the extension's guard. The Admin socket stays read-only for
pipelines.

- **Advance** shows on an open row. It sends `advance {name}` with no wait, so a button press never holds the
  session's dispatch slot for a report wait.
- **Close…** shows until the row is closed. It opens a form with the outcome (abandoned or done) and a one-line
  reason of at most 200 characters, then sends `close {name, outcome, reason}`. The tool refuses it while the stage's
  agent is still live, and the row says so.
- The tool's `say` (spoken-safe, never a path) shows under the row, or the refusal in amber. With no Glyph on the host
  the refusal is `door_unreachable` and nothing is sent. The section reads the pipelines again after each action.

The headless door is the same door with no frontend, on its own owner-only socket: `tools/gateway/doorctl.py` on the
gateway's host, or `just voice::door` from another Mac. Its pipelines show here like any other. Its approvals are rows
in the Approvals panel; an always_confirm card stays pending until the operator answers it in a bound desktop app.
Its runs are not in the sessions' "door runs" line. Each headless call runs through the gateway's Pi (its own mutation socket,
token and `door-` call id). Every home act through it is denied.

The brain records closed words on each stage, as optional fields at the end of `AdminPipelineStage`. A word outside
its set drops the field, never the record. The section lists them as one line per stage, for example "stage 2 review:
codex, reported by tool (mcp), start landed, held by subagents":

- `agent` is the kind the stage launched with (`pi`, `codex`, `claude`, `opencode`).
- `carrier` is the path the report took: `mcp` (by tool), `stop-hook` (by a line or the fallback) or `hook-spool` (by
  a line). A pi report carries none.
- `start` is how the start was proven: `proven`, `landed`, `submitted` or `unknown`.
- `held_by` is what held the stall rule at the last advance. It is a word only; the hold's sentence stays in the
  record.
- `kind_skipped` lists the kinds a start passed over, each with `quota` or `unavailable`. `fence_refused` counts the
  stale-fence reports that advance set aside.
- `report_now` is the report-now prompt's time and whether herdr took it (never its nonce).
- `stall_signal` says what ended a stalled stage: `token` or `transcript` (the pane's own signal), or `time` (the
  stall rule's minutes). The stage's note line ends with "(ended by its transcript)". A stalled stage with no note gets
  its own line.

**Fleet.** A host route whose doctor found nothing answering carries `refused: true` on `AdminHostRoute`. The Fleet
row then reads "nothing answers, refuses (run just hosts away-doctor)".

**Approvals.** `repo_policy_refused` lists each checkout whose own `.vulpine/policy.toml` a dispatch read and refused at
its last read, with a closed reason word: `differs_from_head`, `not_committed`, `not_top_of_repository`,
`link_or_folder`, `too_large`, `unreadable` or `invalid`. The policy section shows "repo policy refused: my-repo —
working copy differs from HEAD" in amber. The path and the file's text stay in the gateway log.

## Agents, dictation and meetings

- **Agents** reads the fleet projection's `agent_presence` rows. Rows sort by attention: awaiting input first (longest
  wait on top), then finished while you weren't looking (`done` and unseen), error, compacting, busy, idle.
  - **Mark seen** sends `MarkAgentPresenceSeen` with one id; **Mark all seen** sends an empty list. The watermark moves
    on that request (`seen_reason: operator`) and when a probe finds the agent's herdr pane focused
    (`seen_reason: focus`). The answer is the fleet after the mark.
  - Each row may carry `attention_events` (newest first, at most eight): entering `awaiting_input`, and the CI state of
    the agent's branch (`ci_failed`, `ci_passed`, `ci_running`, `ci_pending`, `ci_cancelled`) when the fleet row has an
    optional `ci {state, at_ms, label}`. The fleet probe reads CI per herdr pane with the host's own `gh run list`: one
    call per branch, cached 60 s in `~/.local/state/foxline/fleet-ci.json`, none without a gh login. A finishing event
    after the watermark makes the row unseen. Each new CI state is also an `agent_ci` fleet change.
  - When any agent reports CI the panel gains a CI column: one chip per agent with its state, the workflow label and
    its age, read from the row's own `ci` only. A row without `ci` has an empty cell. A gateway that reports no CI shows
    no column.
  - The brain reads the same book through `pi_fleet_status`: awaiting / busy / done-unseen per harness and the rows
    most-urgent first, with no ids or panes.
- **Performance → Decision shadow** has ask rows on the `recent` window (`questions_n`, home stage, gate reason and
  warm) and latency by shape (2-question against 7-question p50), from the optional `asks` and `by_shape` fields. A
  warm ask is listed but never counts as asked.
- **Dictation** reads two sources.
  - The event rows from `GetEvents` give the timeline. Phase `dictation` gives inserts (verified or not, by app) and
    refusals by reason; phase `dictation_cleanup_refused` gives cleanup refusals. The event list holds at most 80
    records, so those counts cover the retained rows only.
  - The gateway's dictation window (`AdminEventSnapshot.dictation`, optional) covers everything since the gateway
    started: holds by mode, partials sent with the last `stable_chars` and `last_partial_chars`, inserts by proof
    binding (refused ones as `insert_<reason>` refusals), scratch-that, the review's choices, and the latest 20 holds.
    Each hold has its `partial_chars` and `stream_state` (`open`, `frozen`, `recovered`, `off`, then `reconciled`).
  - The panel draws each hold's partial length beside a stable-prefix bar. It shows counts, ids and reason words only,
    never the words.
- **Meetings** runs `meetctl status` on the Admin's own host. It looks only at `~/.local/bin/meetctl` or the checkout's
  `tools/meet/meetctl`, gives the command 3 seconds, and never shows the session directory. It shows the call,
  platform, legs, windows per leg and whether notice was given. Without the binary the card reads "no adapter". From
  the gateway it adds `last_minutes {call_id, decisions_n, open_questions_n, doubts_n, at_ms}` on the events window,
  absent until minutes are drafted: the counts, the age and the call id shortened, with the full id on hover. Without
  it the card reads "no minutes yet".

## Batch VIII to XI additions (v519 and later)

- **Performance → Shadow pair.** When `[decision_shadow] mirror` names a shadow, the decision-shadow projection carries
  an optional `pair` block over the last 200 asks that planned a mirror. Per entry: decided, p50, failed, skipped,
  breaker-open and the precision-0.90 floor, plus the same-request `is_command` agreement at 0.5 and at the floors,
  computed as `tools/telemetry/shadow_pair.py` computes it. Counts only. Without a mirror the card says so.
- **Performance → Glyph footprint.** A once-a-minute read of the Glyph on the Admin's own host, through
  `crates/host_footprint` (the crate `vulpine-glyphctl doctor` uses). It sums `ri_phys_footprint` over the Glyph's
  resource coalition: the app, its helpers and WebKit's helpers, OS services left out. The row shows main against
  WebKit MB, the helpers, the total and the lifetime max, with the read's age. No Glyph shows "not running on this
  host". A failed read shows its reason: `shared_coalition` (the Glyph and the Admin were started from one terminal),
  `no_coalition`, or `exited`. A Glyph on another host shows through its own report (below).
- **Performance → Glyph footprint, reported.** A Glyph sends its own footprint to the gateway once a minute as the
  `footprint_report` client control (tenths of a MiB; offered in the hello as `footprint_report`). The Performance
  snapshot's optional `glyph_footprint` keeps the latest. The card reads "Glyph as it reported itself to the gateway
  (session …, N processes): read on its own host 3 min ago" with the same five cells, so the Gateway window on the
  gateway host sees a desktop app on another Mac. Nothing shows until a Glyph reports. A sixth cell, **WebGPU**, says whether the Glyph's gpu orb
  draws its WGSL pass: `runs`, `canvas fallback (<reason>)` (closed reasons such as `no adapter` or `device lost`), or
  a dash when the gpu look was not drawn.
- **Voice → Live sessions.** The card reads `get_admin_live_sessions` every 10 s while the page is open: each live session's id with its
  role, kind, text only, what it observes and its phase, the observable ones first. It adds "N sessions can be
  observed: pick one with --observe=&lt;id>" when more than one can be followed. The list's rule lives in
  `crates/admin_markers` (`live_sessions`), so `vulpine-glyphctl sessions` prints the same rows from the shell, and an
  `observe_ambiguous` refusal names the observable sessions.
  - Each row leads with the frontend's client word from its hello (`glyph`, `vigil`, `convo-gpui`, `convo-freya`,
    `convo`, `satellite`, `tui` or `other`) and its room. `convo-gpui` is the native conversation window,
    `convo-freya` its fallback, and `convo` any other conversation-window name; the tooltip says each in plain words.
  - An observer whose `observe_session` asks were refused reads amber with the count and the last code ("55 observe
    refusals, last observe_ambiguous").
  - The fields are the presentation row's `client`, `room`, `started_at_ms` and `observe_refusals`. A client word
    newer than the Admin's build reads as `other`.
- **Voice → Satellite fleet** (ADR 0033 §6). The card reads `get_admin_satellite_fleet` every 10 s: each live room
  endpoint, by room. An endpoint is a `kind: satellite` frontend (the Voice PE puck's bridge, a Stack-chan) or any
  `role: speaker`. A row reads "satellite in living-room — full, speaking", with its playback link under it: "3
  playbacks acked, last 2.2 s audible · 1 drop resumed, 4 chunks replayed · 1 resume refused, last ring_expired"
  (amber once a resume was refused). The counts are the row's `satellite_playback` since the bind. An endpoint that
  acked and resumed nothing reads "no playback acked or resumed yet".
- **Approvals → "show the diff from HEAD".** A `differs_from_head` repo-policy refusal whose checkout is under the
  gateway's home names it (the optional `checkout`, home-relative). The row's button asks the typed door's read-only
  `policy_diff` verb through this host's Glyph and shows the diff as plain text under it ("the working copy differs
  from HEAD:", or "matches HEAD now").
- **Approvals → "pin this".** A `not_pinned` repo-policy refusal (the operator's sha256 opt-in is on and the committed
  file's digest is not pinned) names its checkout the same way. The row shows the hint "pin this: ~/work/my-repo — just
  approvals trust-repo ~/work/my-repo --write (on the gateway's host)", with no diff button. For a checkout outside
  the gateway's home, the hint names the folder word. The digest stays in the gateway log. `--write` appends the pin to
  the operator's approval-policy.toml only after a confirmation (`--yes`, or a `y` at a terminal), and backs the file
  up first.
- **Pipelines header → fallbacks**: "fallbacks N: unfenced reports A (removed 2026-10-28), prose verdicts B (removed
  2026-11-10)", summed over the listed rows (amber when above zero). A stage with more than one kind adds "start order
  codex → claude". The closed words (carriers, start proofs, hold words, stall signals, skip reasons, the removal
  dates) are one table, `benchmarks/fixtures/pipeline-closed-words.v1.json`, that the brain, the gateway and the Admin
  all read.
- **Fleet → a carried away-doctor row.** `just hosts away-doctor` carries a remote Mac's status file into the gateway
  host's state root over the route when it answers, marked `"from": "<host>"` (`--no-ship` carries nothing). The Fleet
  cell then says "(away doctor on the &lt;host>)" and the Routes line "checked on the &lt;host>, carried here over the route".
- **The headless dispatcher.** `admin_core::headless` answers the same commands by name without a window
  (`cargo run -p admin_core --example admin-headless`). It binds loopback by default. Off loopback it needs a token
  file, and a writing command runs only when `--allow` names it.
- **Home → presence strip and Satellite row.** A **mic muted** badge shows while the session's mic is muted (the puck's
  switch or a long press); the presence projection's optional `mic_muted` is present only then. The Satellite row
  shows the mute and the newest `satellite_control` row from the event ring (kind, mapping, the mute after it, a
  dial's room volume) with its age.
- **Home → Recent announcements** lists held lines beside dispatched ones, newest first: `wake_in_progress` (held
  while the wake is armed) and `claimed_elsewhere` (a herdr report another session speaks). The optional `held` list
  holds the newest 12.
- **Events → the voice-trace picker.** Satellite (`satellite_control`), Brain holds (`brain_turn_held`, plus
  `brain_turn_closed` for `start_over` and `retry_hold_expired`), Announcements held, and Ask-back budget, which also
  counts the spoken-no reset (`ask_back_reset`). High-rate kinds coalesce.
- **Health → `adapter.<name>` Connector rows.** One row per supervised adapter (today `homectl`, which restarts on a
  jittered doubling backoff). `up` shows ready, `restarting` shows reconnecting with its attempt count, and `down`
  shows degraded with "text only", the last failure and the retry time. The contract is
  [adapter degradation](/docs/contracts/adapter-degradation.v1); the knob is `[adapters.supervision]` (on by default).

## Session binding, the rig row, and brain retires


- **Voice → session row: what bound.** From the optional `role`, `kind`, `text_only` and `observing` fields
  set at the hello: "codec ui · text only", "overlay full" or "satellite full", and "· observing &lt;session id>" on a
  `ui` row that follows another session read-only. The wire validator requires role, kind and text_only together,
  text_only only on a `ui`, and observing only on a `ui` (1 to 64 characters). The
  frontend interfaces page has the observe frames.
- **Voice → Avatar actions card: the rig row.** From `avatar_rig`, the latest `rig_report` a frontend sent since its
  hello: "rig: vulpi v4 · clip · thinking · snapshots decoded in 569 ms", "… · still (reduced motion)", "… · img (the
  browser plays the clip)" or "rig: portrait", under the declared `play_animation` names. A word outside the closed
  sets is not shown.
- **Approvals → policy: pinned repo files.** A repo file's standing entry reads `repo file (<checkout>) · pinned` or
  `· unpinned`. A refused file says it is not pinned and that `just approvals trust-repo` prints the line to add. Once
  `[approvals] trusted_repo_policies` is set, repo policy files are honored only at a pinned sha256, and the reload
  event says so. Without it, the HEAD rule alone applies.
- **Events: brain retires.** Every Pi retirement is a `gateway.brain` row: `brain_retire_hook_ran` (Pi exited
  on its own, so its shutdown hooks ran), `brain_retire_killed` (killed after the 2 s grace) or `brain_exited` (gone
  before the retire). Each has a HOOK RAN, KILLED or EXITED badge, the timing, the exit and the stderr byte count. The
  last 64 KiB of Pi's stderr stays in the gateway log and the trace. The "Brain retires" voice trace counts the
  three. On SIGTERM the gateway retires every pooled Pi within 3 s after the 15 s session drain, and the "voice gateway
  stopped" log line counts `brains_hook_ran`, `brains_killed` and `brains_left`.
- **Events: model list refusals.** `brain_models_listed_refused`, `model_query_refused` and
  `model_switch_dropped` (a switch held behind the opening model query, dropped by a start over or a failover rebind)
  count under the "Model list refusals" voice trace.

## Avatar receipts, the motion plan, and satellite faces


- **Voice → Avatar actions card: receipts and the motion plan.**
  - "receipts: drawn 3 · refused 1 · last refused play_animation (no_rig)" counts the skins' per-action
    `avatar_receipt` frames (amber on a refusal).
  - "plan: low_margin 0.21 · fell back · play_animation 4s ago" is the decision model's last motion-plan verdict.
  - Above it, from the row's `motion_plan_state`: "motion plan: on", "motion plan: off (the Glyph's "Fox follows
    replies" switch)", or "motion plan: off ([decision_shadow] motion_plan = false on the gateway)".
  - The rig line can read "img under the pass (frames decoding)".
  - An operator action sent with `vulpine-glyphctl avatar --session <id>` routes on the target session's own row, so
    its routed or refused line shows there, marked `operator_forwarded`.
- **Voice → Render panel card: the brain's renders.** A `pi_show_render` call goes through the session's render
  router, so the card's sent, dropped and receipt counts move with the brain's renders.
- **Voice → the satellite row's face.** A satellite whose link declares a face reads "satellite full" and lists
  "set_expression: neutral, angry, sad, happy, sleepy, doubtful, cold, hot" from the vocabulary field.

## The Brain section (batch XLIII, 2026-10-15)

The Brain section shows the brain lifecycle. It reads `get_admin_brain` while the section is open: admin_core projects
the events snapshot, whose optional `brain` block is the gateway's roster since it started. An older gateway shows the
grouped rows alone and says so.

- **Pooled pis.** One row per pooled Pi, the most recently started first (at most 32): the continuity id, the model it
  was launched with, "up 12m" while it runs or "stopped", its starts since the gateway started, and its last close
  report ("hook ran in 120 ms, code 0, 40 B of stderr in the gateway log, 2m ago"). A Pi launched with no `--model`
  shows the loadout's `pi.model`; "loadout default" means the loadout names none. The stderr tail never crosses the
  socket.
- **While working.** Per pooled Pi: "busy: fleet digest, 1m" while one of its turns is inside a tool (the tool's chip
  words and how long it has run), else "idle". Then the operator's lines that reached a turn while its tool ran, since
  the gateway started: "while busy: 3 heard, 2 queued (2 acknowledged), 1 status, 0 stopped". Queued lines went to the
  running turn with a spoken acknowledgement. Status means "how's it going" was answered from the progress ledger.
  Stopped means a stop cut the work. A Pi whose turns never opened a tool reads "no tool yet". The row holds counts
  and the tool's words only, never what was said (`AdminBrainPi.during_work`).
- **Lanes, counted apart.** Launches and close outcomes per lane: `pooled`, `background` (the background-work
  attempts), `tidy` (the dictation review's one-shot Pi) and `warmup` (fire and forget, no close report). The header
  reads "2 of 3 pooled pis running; 4 pooled launches, 5 other-lane launches counted apart". The gateway log's "brain
  retired" line names the lane too. `VULPINE_BRAIN_LANE` is set on each Pi the gateway launches.
- **Brain retires** and **Model list refusals.** The same `gateway.brain` rows the Events voice traces count, newest
  first, 20 of each, with the HOOK RAN, KILLED or EXITED badge.

## The render card's producer and the rig's memory


- **Voice → Render panel card: the last producer.** The card's last line names who drew: "last: sent bar.v1 by the
  brain tool 4s ago", from the optional `AdminRenderRouting.last_producer`, read off the render id: `preview` (the
  door), `gateway_events` (the events bar), `tool` (pi_show_render) or `brain`. The validator refuses any other word.
  The preview door's post nudges a declaring frontend at once, so `vulpine-glyphctl render` settles in under a second
  ([the render contract](/docs/contracts/answer-card.v1)).
- **Voice → Avatar actions card: the rig's decoded memory and a face.** The rig line adds "· 4.9 MB held at 25%" from
  the optional `held_bytes` and `scale_pct` on `rig_report` (bounded to 4 GiB and 1 to 100; an out-of-range report is
  dropped). A face rig reads "rig: stackchan-demo · face · sleepy drawn as sad · text" (`AvatarRigKind::Face`, sent
  only to a gateway that offers `rig_face`).
- **Voice → the satellite row's hands.** A face satellite's avatar card lists "play_animation: clap, thinking,
  rock-paper-scissors" after its emotions, from the vocabulary field. The mood a face follows is not on the card.

## Operator affect: the friction count and reading the records

The operator-affect panel gains one friction row while `[operator_affect] friction_records` is on (with `opt_in` and
`live`; ADR 0044). The row reads "Friction records: N today, M in 7 days (last …); top cues …". It carries counts, a
clock and cue names from the closed list. It never shows a record, a sentence or a path.

The records are the one place text exists by design. Each record holds the operator's words for the window's turns and
the reply as handed to the voice after the diagnosis guard. They stay on the gateway host. The files are
`friction-<YYYYMMDD>.jsonl` (UTC days, mode 0600) in the directory of `receipt_path`. The retention purge removes them
after `retention_days`. Read them on the gateway host, for example
`jq -c '{w: .window, cues: .affect.cues, tools: .tools, refusals: .refusals}' friction-<day>.jsonl` from that
directory. Each line has these fields: `schema` (`fox9.friction/v1`), `session_id`, `gateway_build`, `loadout`,
`window` (first and last turn id, start and end Unix ms), `turns[]` (`turn_id`, `text`, `verb`, `tier`,
`reply_text_spoken`, `interrupted`, `typed`), `tools[]` (`name`, `ok`, `error_code`), `refusals[]` (`event`,
`reason`), `affect` (`score`, `cues[]`, `prosody` z-scores or null) and `hint_sent` (null until the style hint lands).
The session trace's `operator_friction` row (`cues, score, turns, tools_failed, refusals, written`) marks each window
without any text.


## Current mutation boundary


No Admin code writes TOML or calls a generic shell or filesystem API. Config is written from two places: the Setup
page's **Feature switches** card (below) and the Controls page's config and loadout cards
(`apps/admin-shadow/src/panels/controls.rs`, its plans from `crates/admin_core`). After a confirmation each sends
`PlanConfigMutation` for an editable field, then `ApplyConfigMutation` with that plan (ADR 0065).

- **With `[admin] config_writes = true`**, the gateway writes the field to `<state>/admin-config-overlay.json` (0600 in
  a 0700 folder; only `editable` registry fields, never a secret). It merges that file over the TOML at start, before
  the command-line flags and `validate()`. The answer is `ConfigApplied` with `pending_restart: true`: the config is
  read once, so an apply shows after a gateway restart. Until then the snapshot's `desired` reads the overlay while
  `effective` keeps the running value.
- **Off (the default)**, the apply is refused `config_writes_off`, the overlay is ignored and kept, and the card says
  **Planned, not applied**.
- **Seeing it.** The doctor's `config:admin-overlay` row names every overlaid field beside its TOML value. The Health
  view's `gateway.config_overlay` row (only with `config_writes` on) lists each field as applied, pending a gateway
  restart (a Warning until then) or dropped, and says when the file cannot be read.
- **Undo.** Flip the switch back, or move the overlay out of the state folder (or set `config_writes = false`) and
  restart.
- **A roll keeps the overlay and shows it.** When an overlay file exists, the roll's post-check prints the rolled
  binary's `doctor --row config:admin-overlay`. A doctor that is older, slow (20 s) or missing gives one
  `config:admin-overlay: ...` line and never fails the roll.
- **Fields that apply at the next voice session.** The gateway binds each new session with a live config handle. An
  apply whose every field is one a session reads at bind (`retrieval.enabled`, `retrieval.top_k`,
  `retrieval.max_context_bytes`, `invocation.lexicon_enabled`, `invocation.armed_commit_floor_db`, `hardpoints.stt`,
  `hardpoints.tts`, `hardpoints.tts_voice`; `NEXT_SESSION_FIELDS` in
  `crates/voice_gateway/src/admin/config_overlay.rs`) takes effect there
  and answers `pending_restart: false`, so the card says **Applied, next session**. Every other field answers
  `pending_restart: true`.

## Feature switches

The Setup section draws a **Feature switches** card under the census. Its rows are admin_core's allow-list
(`FEATURE_SWITCHES` in `crates/admin_core/src/feature_switches.rs`). Each takes its value from the snapshot's
effective config or the Health row `gateway.notify` (`get_admin_feature_switches`):

| Switch | Goes to | Takes effect |
| --- | --- | --- |
| `notify.mute` | `SetNotifyMute` (the live mute) | at once |
| `presence.enabled`, `brain.prewarm`, `brain.cache_warming`, `debug_traces` | `PlanConfigMutation` | after a gateway restart |
| `retrieval.enabled`, `invocation.lexicon_enabled` | `PlanConfigMutation` | at the next voice session |

- **Asked first.** Turn on… / Turn off… opens a CONFIRM THIS WRITE card naming the change (`Presence
  (presence.enabled): off -> on`), where the write goes and when it takes effect ("needs a restart" when it does).
  Only its Confirm sends `set_admin_feature_switch` with the card's words (`turn presence.enabled on`). Before any
  socket is touched, admin_core refuses a write without them (`confirmation_required`), a switch not on the list
  (`not_allow_listed`) and anything shaped like a credential (`secret_not_writable`). A refusal, admin_core's or the
  gateway's, shows as `Refused: code: message`.
- **Exactly the existing surface.** A confirmed flip is one request: `SetNotifyMute { muted }`, or
  `PlanConfigMutation` with the snapshot's revision and the one boolean change, checked against the gateway's field
  registry (`crates/voice_gateway/src/admin/fields.rs`) and then applied with `ApplyConfigMutation`. With `[admin]
  config_writes` on, the card says **Done: Applied, needs a gateway restart**; off, **Planned, not applied**. You can
  still write the TOML with `tools/gateway/mini_config_patch.py` and restart. The Admin runs no script.
- **Off by default.** The card is read-only (every flip button disabled, and the summary says so) unless the Admin
  runs with `VULPINE_ADMIN_SWITCH_WRITES=on`. For the app from Finder: `launchctl setenv VULPINE_ADMIN_SWITCH_WRITES
  on`, then reopen it. Unset it to turn writes off. A headless shell on a network bind needs loopback or its allow
  list for `set_admin_feature_switch`, as for every write.
- **Left out on purpose.** `admin.enabled` (it would lock the Admin out), the `brain.no_*` launch flags, and the
  invocation and barge tuning. Secrets are never listed, shown or written.

## The pipelines' shadow verdict and startup-dialog hold

- **Pipelines: the shadow verdict.** The row's name cell adds "shadow: today" (muted) or "shadow: needs you" (amber),
  and nothing when the row carries none. It is the current stage's stage-verdict
  action in shadow mode. The brain records `needs_you` (the stage-verdict pack's `input: required` rule) while a
  question on the agent's screen or a startup dialog holds the stage, else `today` (the stall rule as it stands) while
  the agent is quiet with no report. It comes from the optional `AdminPipelineRow.verdict_shadow`. Nothing routes on
  it; it is there to compare with what the stall rule did. A stalled stage keeps the shadow it had.
- **Pipelines: the startup-dialog hold.** A start that herdr answered `agent_not_ready` reads "held by a
  startup dialog" on the stage line, from its `held_by` word `startup_dialog`.

## Panels the tools fill

The weather and the fleet put a card of their own on a screen that draws one, through the same render router as
`pi_show_render`. The Voice page's Render panel card counts them like any render: sent or dropped, the panel's
receipts, `last_kind` `card.v1`, and the producer word `tool` ("by the brain tool"). The session's declared kinds on
that card include `card.v1` once Vigil binds; the card's block kinds never appear there. A tool's panel that the
gateway refuses is an event-timeline row (`gateway.render`, `render_refused`).

## The event timeline's pop-out

The Admin draws the event timeline's Pop out window itself; the bundle carries no pop-out binary. The timeline draws
the newest 80 rows of the filtered set. The severity filter is one segmented strip: **All**, **Info and up**,
**Warnings and up** and **Errors** (`LEVELS` in `apps/admin-shadow/src/panels/errors.rs`); an unknown severity reads
as a warning. The pop-out window keeps its own filters.


## An Admin older than its gateway

A word newer than the Admin's build does not break a panel. Each reader looks such a word up through one helper and
shows "not understood by this build". A value that is not a word at all (capitals, spaces, a path, over 32 bytes) is
still dropped or refused, and no raw word is shown.

- **Client words.** A presentation row's `client` outside `CLIENT_WORDS` reads as `other`; the Live sessions tooltip
  says "a client the gateway has no word for".
- **Presentation phase and health severity.** Both enums have `unknown` as their `#[serde(other)]` arm, so a read with
  a newer word still decodes. A newer phase reads as idle.
- **Agents.** A newer state sorts after idle and its State cell reads "not understood by this build". A newer harness
  counts under `other`, so the per-harness totals add up.
- **Enrollment, Room note and cards.** A newer word keeps the row and reads "not understood by this build". On a card
  it ranks above pending and below a warning.
- **Still in lockstep.** `AgentPresenceState` and `AgentHarness` have no `unknown` arm, so a newer word still fails the
  Admin's typed decode of the fleet read. The response check still refuses a newer enrollment or room-note word, a
  newer observe-refusal code, render kind or producer, and brain close outcome.



## The conversation window's health on the Live sessions row

The Glyph restarts a crashed conversation window (after 1 s, then 4 s, then it gives up) and says so on its card and in
`vulpine-glyphctl doctor`. It reports the window's health to the gateway as the `sidecar_report` client frame, behind
the hello feature of that name (the protocol). The
gateway keeps the latest on the Glyph's presentation row (`sidecar`).

- **Voice → Live sessions.** Under the Glyph's row, in amber: "conversation window restarting (1 of 2)" while the Glyph
  waits to start it again, then "(2 of 2)", "conversation window stopped" once it gave the window up, and
  "conversation window failed to start" when no window could be started. A running, cleanly exited or switched-off
  window shows nothing, and so does a state word newer than the Admin's build. `vulpine-glyphctl sessions` prints the
  same words.


## The Glyph's microphone route on the Live sessions row

The Glyph reports each change of its microphone as a generation-bound media route: the `media_route_report` client
frame, behind the hello feature of that name
(the protocol). The gateway keeps the latest per route
on the Glyph's presentation row (`media_routes`). Client Core stays the only capture owner; the Glyph only names what
its capture owner's callbacks mean.

- **Voice → Live sessions.** One line per route under the Glyph's row: "microphone active · generation 3 · chosen
  device". The states, in words: probing, permission denied, unavailable, chosen device gone, replacing, active,
  "capture died, reacquiring" (`degraded`), "stopping, not yet released" (`stopping`) and settled. Denied,
  unavailable, chosen device gone, degraded and stopping read amber; active plain; the rest muted. A route or state
  word newer than the Admin's build draws no line.
- **The generation.** Each acquisition counts one: the first start, a device change or reset (`replacing`, then the
  next generation `probing`), a reacquire after a dead capture (`degraded`, then the next). The gateway refuses a
  report whose generation is below the one it kept (`stale_generation`), so a late superseded acquisition never paints
  over its successor.
- **Privacy.** The report names the route, the generation, the state and whether the default or a chosen device was
  asked for (`default`, `chosen`). Never a device id or label.


## The brain's front app on the Live sessions row

With Operations > Session > Brain > "Share the front app with the brain" on in the Glyph, every brain turn carries the
front app on the Glyph's machine as typed facts: its bundle id, a coarse category and the idle seconds
(`screen_context_report`, the protocol). The feed is
on by default: `[screen_context] share` absent means on, and the switch turns it off. The gateway keeps the context it
last attached on the Glyph's presentation row (`screen_context`).

- **Voice → Live sessions.** One muted line under the Glyph's row: "brain saw: terminal · com.mitchellh.ghostty · idle
  4 s". No idle reads "active"; a minute or more reads in minutes; nothing frontmost reads "an unnamed app"; a
  category word newer than the Admin's build reads "other kind". No line while the switch is off or before the first
  turn.
- **Privacy.** The line and the row carry the bundle id, the category and the idle seconds. Never a window title, text
  or pixels: the frame cannot carry them (its context refuses unknown fields), and the gateway refuses a bundle id
  that is not reverse-DNS characters.
- **The Glyph section.** The **Front app to the brain** row shows the switch from `switches.json` before any turn: on,
  off, "on (Glyph default, nothing published yet)", or "not published (a Glyph older than the switch)". The trace row
  is `presence_context_attached`, apart from the OCR read's `screen_context_attached`.


## The laptop Admin reads the mini through the Admin relay (batch LX, 2026-10-24)

The Admin opens only the owner-local Admin socket. When the gateway runs on another Mac (the gateway host), a
Gateway window on the operator's own Mac reads it through `runtime/relay/admin_gateway_relay.py`, which bridges the gap without touching the Admin's checks. It runs as the launchd job
`com.voidfab.vulpine.admin-relay`, beside the Glyph relay's job.


- **What it stands up.** On the operator's Mac it owns `<state>/admin` (the 0700 directory the Admin reads) and
  listens on `admin-relay.sock` there (0600). While the gateway host's Admin socket answers a probe, it writes the
  owner and endpoint markers naming that socket. When the probe fails, or on exit, it removes the markers it wrote, so
  the Admin reads "no gateway", never a dead socket. A third marker, `.fox9-admin-relay`
  (`fox9-admin-relay-v1 <host> up|down`), names the relay. The relay leaves alone a directory whose endpoint marker it
  did not write (a gateway on this Mac) and an owner marker the operator provisioned.
- **Each connection.** The relay sends each request (at most 64 KiB) as one frame over one long-lived ssh session to
  the gateway host, in BatchMode, never a prompt. Nothing is installed on the gateway host. The bridge checks the
  gateway host's Admin directory and markers the way the Admin does before every frame. An answer is at most 256 KiB, and a whole request
  has 25 s, inside the Admin's 30 s deadline. The log holds codes, byte counts and milliseconds, never a request or a
  response byte.
- **The session.** It opens when the relay starts and carries every read and the 15 s probe. When it drops (ssh dies,
  the network goes, a probe gets no answer in 15 s), the markers come down at once, so the Admin reads "no gateway".
  The relay reconnects at once, then after 1, 2, 4 … 60 s; a hello from the bridge resets the backoff. The log counts
  sessions (`bridge up session=N`).
- **The trust boundary (ADR 0016).** Only the owner's processes on the operator's Mac reach the relay's socket, as
  with a local gateway. Every relayed request leaves as the owner (the owner's ssh key and account) and lands on the
  gateway host's owner-only socket. The gateway's mutation admission is unchanged. No TCP listener opens anywhere. The
  relay grants nothing the owner's ssh to the gateway host did not already allow.
- **The header.** One line names the gateway the Admin reads (`get_admin_gateway_source`,
  `crates/admin_core/src/gateway_source.rs`, markers only, no socket opened): "Gateway: this Mac", "Gateway: the
  &lt;host>, via the Admin relay", or, in amber, "… · the relay is down: it cannot reach the &lt;host>"
  (the relay runs, the probe fails) or "… · the relay is down: it is not running" (its launchd job is installed and the
  markers are gone). With neither: "Gateway: none on this Mac (no Admin socket, no Admin relay)".
- **Install.** `just setup::glyph-relay-agent-install` installs it with the Glyph relay (on by default;
  `VULPINE_ADMIN_RELAY=off` skips it), or `just setup::admin-relay-agent-install` alone.
  `just setup::admin-relay-agent-remove` turns it off and `just setup::admin-relay-status` prints what the directory
  says.
- **The poll through the relay.** The Admin reads a cycle every 6 s while its gateway source is the relay (up or down),
  and every 4 s from a gateway on this Mac. The gateway line's tooltip says which.
- **The relay row.** After every probe, drop and retry the relay writes `.fox9-admin-relay-health` beside its markers
  (0600, one JSON line, at most 1 KiB) and removes it on exit. It holds the bridge's state and session number, when it
  came up or went down, the last down reason as a code (`ssh_unreachable`, `probe_timeout`, `session_ended` … the
  closed set in `RELAY_DOWN_CODES`), the next retry, read counts, the probe's time, the drops, and `stale_after_ms`,
  the promised time of its next write. `get_admin_gateway_source` carries it as `relay_health`. The Health section
  draws an **Admin relay** row above the component evidence:
  - UP with the session, uptime, reads, probe and drops;
  - DOWN in amber with how long, why in words and when it tries next;
  - STALE when the promised write is late (the relay stopped without taking its markers down);
  - NOT RUNNING when its job is installed and nothing is there.

  `python3 runtime/relay/admin_gateway_relay.py status` prints the same health.
- **Camera frames.** Camera frames are files beside the gateway host's socket (`frames/`), so the relayed Admin's Home cameras
  show the frame read's refusal.

