The Gateway window
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.
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). 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).
The endpoint is disabled by default:
[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:
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
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 has the steps.
- The version is
bundle.json’sshort_version. Every build is stamped bytools/repo/admin_build_id.py: CFBundleVersion is the UTC build time (YYYYMMDD.HHMMSS), andContents/Resources/vulpine-build.jsonnames the commit. The install line readsVulpine 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.
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 <age> (<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 refusedbusy. The gateway’s validator refuses a projection whoseopenis above four.dispatchis the class of the openpi_herdr_dispatchcall that holds the session’s dispatch slot. It ismutatingwhen a prepare, pipeline, plain advance, close or another mutating call is open (the next mutating call is refusedbusy), elsewaitwhen only report waits are open, elseread. It is absent when no dispatch call is open. The line reads “dispatch: mutating”.dispatch_busycounts dispatch-conflict refusals: a second mutating call, or a second open call on one pipeline. It is counted apart from the four-run cap’sbusy_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_statusis herdr’s own word for the agent in the pane the record names, from the fleet probe:working,idle,doneorblockedwhile the pane is listed. It isgonewhen the host’s list is read and names none of the record’s panes, andunknownwhen the list is unread or older than the open stage. A record the operator closed carries none. A live pane whose agent isdoneoridlereads “agent done, not collected” in amber: the stage finished without the pipeline collecting its report.panes_closedis the record’s sweep count, shown as “panes closed N” beside the outcome.stages[]has each stage’s role and status, and itsdispute(a disputed done) ornote(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.acceptanceis the record’s acceptance contract as counts:files,commands, andmet(every stage judged against the contract endeddone_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.stalledcounts 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_reportsandprose_verdictsshow beside the outcome as “unfenced reports 2, prose verdicts 1”.fallback_kindsandreport_grace_minutesshow 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 isdoor_unreachableand 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”:
agentis the kind the stage launched with (pi,codex,claude,opencode).carrieris the path the report took:mcp(by tool),stop-hook(by a line or the fallback) orhook-spool(by a line). A pi report carries none.startis how the start was proven:proven,landed,submittedorunknown.held_byis what held the stall rule at the last advance. It is a word only; the hold’s sentence stays in the record.kind_skippedlists the kinds a start passed over, each withquotaorunavailable.fence_refusedcounts the stale-fence reports that advance set aside.report_nowis the report-now prompt’s time and whether herdr took it (never its nonce).stall_signalsays what ended a stalled stage:tokenortranscript(the pane’s own signal), ortime(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_presencerows. Rows sort by attention: awaiting input first (longest wait on top), then finished while you weren’t looking (doneand unseen), error, compacting, busy, idle.- Mark seen sends
MarkAgentPresenceSeenwith 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): enteringawaiting_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 optionalci {state, at_ms, label}. The fleet probe reads CI per herdr pane with the host’s owngh 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 anagent_cifleet 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
cionly. A row withoutcihas 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.
- Mark seen sends
- Performance → Decision shadow has ask rows on the
recentwindow (questions_n, home stage, gate reason and warm) and latency by shape (2-question against 7-question p50), from the optionalasksandby_shapefields. A warm ask is listed but never counts as asked. - Dictation reads two sources.
- The event rows from
GetEventsgive the timeline. Phasedictationgives inserts (verified or not, by app) and refusals by reason; phasedictation_cleanup_refusedgives 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 laststable_charsandlast_partial_chars, inserts by proof binding (refused ones asinsert_<reason>refusals), scratch-that, the review’s choices, and the latest 20 holds. Each hold has itspartial_charsandstream_state(open,frozen,recovered,off, thenreconciled). - The panel draws each hold’s partial length beside a stable-prefix bar. It shows counts, ids and reason words only, never the words.
- The event rows from
- Meetings runs
meetctl statuson the Admin’s own host. It looks only at~/.local/bin/meetctlor the checkout’stools/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 addslast_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] mirrornames a shadow, the decision-shadow projection carries an optionalpairblock 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-requestis_commandagreement at 0.5 and at the floors, computed astools/telemetry/shadow_pair.pycomputes 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 cratevulpine-glyphctl doctoruses). It sumsri_phys_footprintover 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, orexited. 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_reportclient control (tenths of a MiB; offered in the hello asfootprint_report). The Performance snapshot’s optionalglyph_footprintkeeps 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 asno adapterordevice lost), or a dash when the gpu look was not drawn. - Voice → Live sessions. The card reads
get_admin_live_sessionsevery 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=<id>” when more than one can be followed. The list’s rule lives incrates/admin_markers(live_sessions), sovulpine-glyphctl sessionsprints the same rows from the shell, and anobserve_ambiguousrefusal names the observable sessions.- Each row leads with the frontend’s client word from its hello (
glyph,vigil,convo-gpui,convo-freya,convo,satellite,tuiorother) and its room.convo-gpuiis the native conversation window,convo-freyaits fallback, andconvoany other conversation-window name; the tooltip says each in plain words. - An observer whose
observe_sessionasks 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_msandobserve_refusals. A client word newer than the Admin’s build reads asother.
- Each row leads with the frontend’s client word from its hello (
- Voice → Satellite fleet (ADR 0033 §6). The card reads
get_admin_satellite_fleetevery 10 s: each live room endpoint, by room. An endpoint is akind: satellitefrontend (the Voice PE puck’s bridge, a Stack-chan) or anyrole: 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’ssatellite_playbacksince 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_headrepo-policy refusal whose checkout is under the gateway’s home names it (the optionalcheckout, home-relative). The row’s button asks the typed door’s read-onlypolicy_diffverb 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_pinnedrepo-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.--writeappends the pin to the operator’s approval-policy.toml only after a confirmation (--yes, or ayat 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-doctorcarries a remote Mac’s status file into the gateway host’s state root over the route when it answers, marked"from": "<host>"(--no-shipcarries nothing). The Fleet cell then says “(away doctor on the <host>)” and the Routes line “checked on the <host>, carried here over the route”. - The headless dispatcher.
admin_core::headlessanswers 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--allownames 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_mutedis present only then. The Satellite row shows the mute and the newestsatellite_controlrow 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) andclaimed_elsewhere(a herdr report another session speaks). The optionalheldlist holds the newest 12. - Events → the voice-trace picker. Satellite (
satellite_control), Brain holds (brain_turn_held, plusbrain_turn_closedforstart_overandretry_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 (todayhomectl, which restarts on a jittered doubling backoff).upshows ready,restartingshows reconnecting with its attempt count, anddownshows degraded with “text only”, the last failure and the retry time. The contract is adapter degradation; 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_onlyandobservingfields set at the hello: “codec ui · text only”, “overlay full” or “satellite full”, and “· observing <session id>” on auirow that follows another session read-only. The wire validator requires role, kind and text_only together, text_only only on aui, and observing only on aui(1 to 64 characters). The frontend interfaces page has the observe frames. - Voice → Avatar actions card: the rig row. From
avatar_rig, the latestrig_reporta 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 declaredplay_animationnames. A word outside the closed sets is not shown. - Approvals → policy: pinned repo files. A repo file’s standing entry reads
repo file (<checkout>) · pinnedor· unpinned. A refused file says it is not pinned and thatjust approvals trust-repoprints the line to add. Once[approvals] trusted_repo_policiesis 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.brainrow:brain_retire_hook_ran(Pi exited on its own, so its shutdown hooks ran),brain_retire_killed(killed after the 2 s grace) orbrain_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 countsbrains_hook_ran,brains_killedandbrains_left. - Events: model list refusals.
brain_models_listed_refused,model_query_refusedandmodel_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_receiptframes (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, markedoperator_forwarded.
- “receipts: drawn 3 · refused 1 · last refused play_animation (no_rig)” counts the skins’ per-action
- Voice → Render panel card: the brain’s renders. A
pi_show_rendercall 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
--modelshows the loadout’spi.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) andwarmup(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_LANEis set on each Pi the gateway launches. - Brain retires and Model list refusals. The same
gateway.brainrows 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) orbrain. The validator refuses any other word. The preview door’s post nudges a declaring frontend at once, sovulpine-glyphctl rendersettles in under a second (the render contract). - 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_bytesandscale_pctonrig_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 offersrig_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; onlyeditableregistry fields, never a secret). It merges that file over the TOML at start, before the command-line flags andvalidate(). The answer isConfigAppliedwithpending_restart: true: the config is read once, so an apply shows after a gateway restart. Until then the snapshot’sdesiredreads the overlay whileeffectivekeeps 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-overlayrow names every overlaid field beside its TOML value. The Health view’sgateway.config_overlayrow (only withconfig_writeson) 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 oneconfig: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_FIELDSincrates/voice_gateway/src/admin/config_overlay.rs) takes effect there and answerspending_restart: false, so the card says Applied, next session. Every other field answerspending_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 sendsset_admin_feature_switchwith 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 asRefused: code: message. - Exactly the existing surface. A confirmed flip is one request:
SetNotifyMute { muted }, orPlanConfigMutationwith 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 withApplyConfigMutation. With[admin] config_writeson, the card says Done: Applied, needs a gateway restart; off, Planned, not applied. You can still write the TOML withtools/gateway/mini_config_patch.pyand 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 forset_admin_feature_switch, as for every write. - Left out on purpose.
admin.enabled(it would lock the Admin out), thebrain.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’sinput: requiredrule) while a question on the agent’s screen or a startup dialog holds the stage, elsetoday(the stall rule as it stands) while the agent is quiet with no report. It comes from the optionalAdminPipelineRow.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_readyreads “held by a startup dialog” on the stage line, from itsheld_bywordstartup_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
clientoutsideCLIENT_WORDSreads asother; the Live sessions tooltip says “a client the gateway has no word for”. - Presentation phase and health severity. Both enums have
unknownas 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.
AgentPresenceStateandAgentHarnesshave nounknownarm, 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 sessionsprints 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 generationprobing), 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.jsonbefore any turn: on, off, “on (Glyph default, nothing published yet)”, or “not published (a Glyph older than the switch)”. The trace row ispresence_context_attached, apart from the OCR read’sscreen_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 onadmin-relay.sockthere (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 <host>, via the Admin relay”, or, in amber, “… · the relay is down: it cannot reach the <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-installinstalls it with the Glyph relay (on by default;VULPINE_ADMIN_RELAY=offskips it), orjust setup::admin-relay-agent-installalone.just setup::admin-relay-agent-removeturns it off andjust setup::admin-relay-statusprints 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-healthbeside 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 inRELAY_DOWN_CODES), the next retry, read counts, the probe’s time, the drops, andstale_after_ms, the promised time of its next write.get_admin_gateway_sourcecarries it asrelay_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 statusprints 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.