Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

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 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=<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 <host>)” and the Routes line “checked on the <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; 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 <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).
  • 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 <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-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.

Was this page helpful?