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

Glossary: runtime terms

The glossary's second half, split from CONTEXT.md on 2026-10-15: the decision model, decision.v1 and its shadow, the injection guard, the two brain lanes, the approval socket and sealed grants, adapters, rooms and home verbs, the tool door, the STT fault rule, the read and turn-close terms, the routing heads, the gateway's answer windows, the first-token budget, the speech lanes, the Meet legs, satellite controls, and the doctor, runtime manifest and language rule.

Living doc, checked against the code 2026-11-14

The second half of the glossary. Read the glossary first: it holds the core language (the gateway, the brain, skins, the Client Core, the protocol, agents, personas, loadouts) and the presentation glossary.

Decision model, brain lanes and integrations (current)

Decision model: The small typed-decision model beside the turn. While the operator speaks it is asked typed questions about the first partial transcripts: is this addressed to Vulpine (is_command), is the utterance finished (complete), and which verb it means. The turn never waits for it, and it is optional: the Decision shadow that asks it is off by default. It is self-hosted on the gateway host and replaceable, since every candidate speaks decision.v1; one build runs as the runtime/systemone-ane helper on the Neural Engine. Its one routed decision today is the Decision gate, which drops a follow-up not meant for Vulpine. A verb is matched by the gateway’s own grammar at the commit, and everything else the model answers is the Decision shadow. Avoid: router model, intent classifier, Jev (the proprietary model whose contract it keeps)

decision.v1: The typed-decision wire every Decision model speaks (docs/contracts/decision.v1.md). One request carries a state and a map of typed questions (noul, choice, score). The answer gives each question a value with probabilities. The contract is the fixed point; the model behind it is replaceable. Avoid: Jev API, System One API (System One is the wire’s origin)

Decision shadow: The Voice Gateway’s [decision_shadow] lane (off by default): it asks the Decision model about the first partials of each utterance (up to partials, default 2) and traces each typed answer as a decision_shadow row with a stable verdict. Nothing reads it to decide. The decidectl cascade asks [[decision_shadow.entries]] in order under one deadline (the session’s follow-up window, or fallback_deadline_ms when it is off): by default the LoRA on kev.serve at loopback :8871, then the frozen-encoder head (tools/verbs/head_server.py) on :8872, each behind its own breaker. A mirror entry (mirror = ["ane"]) is also asked beside the cascade under its own timeout and breaker and traced as decision_shadow_mirror with the same request_id. The Admin’s Shadow pair card counts those pairs per entry (decided, p50, failed, skipped, breaker-open) with their is_command agreement at 0.5 and at each entry’s precision-0.90 floor. Avoid: tier 3 (tier 3 is the verb resolver’s Jaccard table it may replace)

Decision gate: The Decision model’s one routed decision (ADR 0062; [decision_gate], on by default). In the Follow-up window, a final whose latest front-door is_command is under the lock’s threshold is refused (follow_up_refused {reason: decision_gate}) and never reaches the Brain. The gate only drops, reading the shadow answer that landed before the final; it never adds a turn, asks or waits past commit. With the Decision shadow off (its default) no answer is in, so the gate abstains. It abstains to the ungated path when it is off or has no valid lock, when no answer was in, the breaker was open, the reply guard refused the answer or another identity served, on a question pack or key order other than the lock pins (pack_mismatch), and when the final ran more than 150 characters past the partial the answer read (stale_answer). The lock (benchmarks/verbs/decision-gate.v1.lock.json; v2 also pins the pack’s sha256 and criteria_order) holds the identity, head temperature and threshold. Three Missed labels on its drops in seven days turn the gate off. The Admin’s gateway.decision_gate row says active or abstaining and why; Recent turns shows “dropped by the decision gate”. Avoid: router (it routes nothing to a verb), wake gate (the callsign path is unchanged)

Injection guard: The Voice Gateway’s shadow rule over where a committed utterance came from, not what it says (crates/voice_gateway/src/injection_guard.rs). It marks a turn held on any of four signals: Vulpine’s own playout explains at least half its voiced energy (echo_overlap), the operator’s machine is in a call (call_active), speaker verification ran and did not match the enrolled operator (speaker_unverified; no verdict never holds), or Vulpine was audible while it was recognized (playback_live). It is traced as injection_guard per commit when [decision_shadow] injection_guard is on. Nothing is held, refused or routed on it. Avoid: prompt-injection filter (it never reads the words), echo gate (the echo gate is one live text rule; this is four source signals in shadow)

Lyric reference: The echo gate’s second reference text ([echo] lyrics, off by default; crates/voice_gateway/src/lyrics_ref.rs): the synced lyric lines the playing Spotify track sings within 8 s of its position, fetched once per track from lrclib.net. A commit that matches them by the gate’s own rule is held as song_lyrics, and every commit judged against them is traced as echo_lyrics. Avoid: lyrics filter (it holds only what the song is singing right now)

Compact lane: The on-device Brain for background attempts that need no tools and little context: Apple Foundation Models through fm-brain (or llama-brain), run via [brain] background_command. An attempt is routed here by the shape of its objective and falls back to the Remote lane. Foreground turns stay on Pi. Avoid: local brain, fast brain

Remote lane: The Pi Brain with the loadout’s model and tools, over Pi RPC. It takes every foreground turn and any background attempt the Compact lane does not. Avoid: cloud brain

Approval socket: The Voice Gateway’s owner-local Unix socket (<state>/approvals/approval.sock, authenticated by a key file) where an agent sends one typed request: exec, cp, create, update, delete, grant or batch. Pending requests are spoken as one card, and the operator’s yes or no travels back down the same connection; the socket runs nothing. A policy file, a 24-hour grant or learned trust may answer first, but create, update and delete are never pre-authorized, and delete never becomes trusted. An exec request is judged by its Approval shape. A command on the typed DANGER list (danger_p 1.0: a recursive delete, chmod or chown of home or root, mkfs, dd to a device, a force push, a fetched script piped to a shell, a shutdown or reboot) is the operator’s every time, and saying yes to it writes no grant. A CAUTION command (0.5) is only marked on the Admin row (ADR 0040). Avoid: approval API, permission server

Approval shape: What policy globs, grants and never_trusted judge an approval request by: agent:exec:<asset>:<program> for an exec request, where the program is the real one read through any wrapper or -c shell (sudo rm -rf ~ shapes as rm) and a list names every program it runs (cd+rm). Learned trust judges the shape plus the exact command (trust_key). Avoid: command pattern, argv0

Sealed grant: A 24-hour grant as the gateway stores and shows it: the Approval shape it covers and is matched on, a preview (the value’s first whitespace token, at most 24 characters, an = assignment dropped whole, … for the rest) and the SHA-256 of the full command, path or detail. Only the spoken card says the command. The grants file (fox9.approval-grants/v2), the approval socket’s status, the Admin socket and event log (for grants and for waiting and decided requests) and the learned-trust store (fox9.learned-trust/v2, keyed by the shape and the SHA-256 of <shape>|<exact command>) hold only shapes, previews and hashes. An expired grant is traced once as approval_grant_expired. Avoid: remembered command, grant label

Revoke verb: The gateway verb that takes back a standing approval by name: “forget the systemctl approval”, “revoke the grant for web 01”, “stop trusting cargo”, or “forget that approval” for the one granted or used last. The subject is matched against the closed list of live Sealed grants and learned-trust rows (the operator-public store and the session owner’s), never used as free text. One clear match removes every grant on that Approval shape (approval_grant_revoked), resets its learned trust (learned_trust_reset {by: revoke_verb}), adds a revoked row to the decided requests and says “I’ve forgotten the

Adapter: A process outside the Voice Gateway that speaks one of the two ADR 0034 contracts: verbs out (a command and one JSON receipt) or events in (JSON lines). It keeps the upstream’s names and credentials to itself and hands the Gateway Vulpine’s names. Avoid: integration, plugin (a Glyph Plugin is something else)

Room: A lowercase kebab name Vulpine owns (kitchen, living-room, office); the key for Subjects and Room targets.

Subject: A thing Vulpine can observe or act on, named by Vulpine as <room>/<thing> (kitchen/player, office/light, camera-1/car). An upstream’s own id lives only in the Adapter’s map file, never in a trace row, an Admin projection or a Brain tool result. Avoid: entity, entity id, device id

Home verb: A closed Gateway verb that changes a Subject through the home Adapter (vulpine-home act <subject> <verb>; homectl is its alias). The verb comes from a fixed table; the subject is open words resolved to a Subject, and an unresolved one is refused, never guessed. Avoid: smart-home command, HA service call

Room target: Where Vulpine makes a Room say or play something, always through one interface: the verbs-out Adapter vulpine-room (alias roomctl; rooms in ~/.config/vulpine/rooms.json), used by the Gateway’s room-speaker route and the Brain tool pi_room_speak. Avoid: speaker, output device

Fleet adapter: vulpine-fleet (alias fleetctl), the Adapter that probes the operator’s hosts over ssh (the Gateway never does) and emits one fleet_snapshot per interval: reachability, load, memory, disk, logins, Herdr agents and quota, as Vulpine-labeled facts the Gateway projects. Avoid: host monitor

Fleet CI row: The optional ci {state, at_ms, label} on a Fleet adapter agent row: the latest GitHub Actions run of the branch that agent’s checkout is on (failed, passed, running, pending or cancelled, with the workflow’s name). The probe reads it with the host’s own gh, read-only and cached 60 s; the branch, repo and run id never leave the probe. The Gateway turns each change into a ci_* attention event on the agent’s presence row, drawn in the Admin as the agent’s CI chip. Avoid: build status, CI badge

Tool door: The Gateway’s typed path that runs one Brain tool with no Brain turn, nothing spoken and no model asked (ClientControl::InvokeTool, vulpine-glyphctl tool, and verbs built on it such as vulpine-glyphctl recall and vulpine-glyphctl meet minutes). The call passes the bound loadout’s allowed_pi and the extension’s guard, runs in a short-lived run-tool.ts runner while the session keeps serving, and ends in one typed receipt (ok, or a code such as not_allowed, timeout, busy). A tool the Gateway answers itself gets a door-<uuid> call id and the session Brain’s mutation socket in the runner’s environment. The runner lives at most [brain] tool_door_timeout_secs (60 s); a call may ask for longer (vulpine-glyphctl tool --timeout <s>, the frame’s timeout_secs) up to [brain] tool_door_timeout_max_secs (300 s), and a longer ask is refused with a receipt naming the max. Avoid: tool API, direct tool call

STT fault: A session’s recognizer lost mid-session (its transport closed or failed to read, or a second ready arrived). The client gets the typed stt_error {reason, recoverable}, and [stt] on_fault decides what happens: end_session (the default) ends the session; text_only keeps it with typed turns, refuses the microphone with one spoken line and rebuilds the recognizer on a backoff until one takes a frame (stt_recovered). Avoid: STT crash, mic error (the microphone is fine; the recognizer is not)

Wire notices: The shared, skin-neutral view-model of typed wire events (packages/vulpine-voice-ui-state’s wireNotices.ts, drawn by packages/vulpine-voice-ui’s WireNotices.tsx): the STT fault banner (stt_error until stt_recovered or the recognizer’s words again), the Tool door’s refused receipt (busy, timeout, other), a read that ended on a read_fetch_* error, and a dictation insert’s refusal. Reason words, codes and ids only, never a transcript. Vigil renders it. Avoid: toasts, error banner (most notices are not errors)

Door runs: The runners a session’s Tool door has open (LiveSessionState.door_runs), each with a purpose: receipt (a tool call ending in one typed receipt) or read (the read verb’s page fetch). At most four are open per session (MAX_DOOR_RUNS); one more is refused busy and counted. A run clears when it settles or times out; a fetch also clears, and its runner is killed, when reading_control stop cancels it (reading_fetch_failed {code: cancelled}) or a newer read supersedes it (superseded). The Admin shows each session’s door_runs {open, busy_refused} as “door runs: N open”, adding “busy refused: M” when M is above zero. Every tool_door_settled and reading_fetch_* trace row carries the purpose. Avoid: door calls, door jobs, pending tools

Canceled read: A read whose page fetch ended before the page landed, because a stop (typed reading_control stop, or “stop reading” said) canceled it or a newer start_read superseded it; its runner is killed (docs/contracts/reading.v1.md). Its start_read is answered by error {code: read_fetch_cancelled | read_fetch_superseded, request_id: <that start_read's>}, and then a stop that found no read open by reading_progress {request_id: <the stop's>, active: false, state: stopped}; the spoken stop says “Stopped.” The Client Core passes the error’s code and requestId typed, so a skin matches the answer to its own read (Glyph reads “stopped (fetch cancelled)”). Avoid: aborted read, failed read (read_fetch_failed is a fetch the door refused or could not complete)

Read continuation: A long read’s voice reference chained across its segments ([tts] read_continuation, default off), so the delivery does not reset at every paragraph. Every segment after the first is planned with an ICL reference made of the previous segment’s last ~4 s of rendered audio and its words, in place of the registered voice clip. The first segment, a mood change, a jump (previous, restart, a skip) and a barge-in re-read go back to the clip, and a brain reply never continues. It is traced as tts_read_continuation {segment, ref_ms, reference, reason, applied}; while the TTS worker does not accept the continuation frame, the plan is traced applied: false and the clip request is sent. Avoid: voice chaining, rolling clone (nothing is registered as a new voice by the gateway)

Turn close on the mark: How meetctl ends a far-leg speaker turn when the streaming diarizer cuts the far leg by turn (--far-cut turns): the held turn closes as soon as the stream marks the next speaker (--turn-close mark, the default) and is decoded and sent with its speaker’s label. --turn-close window instead waits for the next speaker’s first window to close. The receipt counts these as turns_closed_on_mark. A provisional line (--provisional first|every|off) may show a held turn early; the turn-close line replaces it. Avoid: end of turn, endpointing (those are the operator’s own turns)

Retracted mark: A next-speaker mark from meetctl’s streaming diarizer that the stream’s finals take back after a Turn close on the mark has acted on it. The closed line stands and is never re-sent; what the speaker says next is a new line under that speaker, starting where the closed cut ended (cutUntil), so no audio is decoded into two lines. The receipt counts these as stream_diarizer.marks_retracted, closed_cuts_revised and revised_s. Avoid: revised turn, re-diarized line (the line is not rewritten)

Playback receipt: The Glyph’s bounded read of what it has played: the last 16 or fewer segments (turn, output generation, chunks, bytes, first audible edge, end) and the live output generation, from the Client Core’s playbackRead. vulpine-glyphctl playback [--json] prints it, and vulpine-glyphctl status carries it as its playback block. Reading it never changes playback. A segment dispatched to the engine but never heard shows no audible edge. Avoid: TTS log, audio history

Diagnosis guard: A stage of the spoken-output filter (normalize_tts_text_stages) that drops any sentence diagnosing the operator before it reaches the voice (ADR 0044). Such a sentence has a second-person cue (“you sound”, “you seem”, “you look”, “you feel”, “you are”, “you’re”, “you’ve been”, “you must be”, “your voice”, “your tone”) followed within four words by a word from a fixed list of 22 affect words (stressed, anxious, depressed, upset, tired, drunk, angry, nervous, …). The list also holds the style hint’s own words, the noun forms (rushed, hurried, hurry, rush, impatient, impatience, frustration, frustrating, stress, annoyance, irritation, tension, mood) and the phrase “rough day”. The cues also include “I notice”, “I can tell”, “I (can) hear”, “I (can) sense”, “sounds / sound / seems like you…”, and a sentence opening with “Sounds like” or “Seems like” (“Sounds like a frustrating day.”). A question is never dropped (“Are you alright?”), and an affect word with no second-person cue (“it sounds stressed out there”) or followed by “of” / “from” / “that” (“if you’re tired of it”) stays. Any sentence echoing the operator style hint (its VULPINE_OPERATOR_STYLE tag or the words “operator style”, in any spelling, a question included) is dropped and counted apart as tts_style_echo_dropped {count}, even with the kill switch off. The guard runs after the markdown strip and before the hex / reference scrubs, and is on unless [tts] diagnosis_guard = false. The brain reply path writes tts_diagnosis_dropped {count}, and the Admin Speech Text projection shows the drop as a diagnosis rewrite. Avoid: affect filter, emotion scrub (it removes diagnoses, not emotion words)

Operator affect: How the operator sounds and acts across the last few turns, read to shape how Vulpine drives the conversation, never what Vulpine says about them (ADR 0044). The live signal is text and interaction cues (negation openers, a repeated request, a retried verb, a barge-in, a follow-up refusal, a failed tool), counted at commit as the operator_affect_turn row’s cues and score. Prosody (the replay’s four coach numbers plus an f0 spread, computed in Rust with no model) rides as evidence only. It has two outputs, each behind its own [operator_affect] opt-in and off by default. The operator style hint is one VULPINE_OPERATOR_STYLE line of instructions from a closed set (“keep replies short”, “say what failed”), never a state word, which the brain never repeats (inform_brain). The friction record is one private fox9.friction/v1 line on the gateway host holding the exchange’s words, tool error codes and cues, aged out by retention_days and never copied off (friction_records). Avoid: mood, emotion detection, stress score (it is a score of cues, not a reading of the operator’s state); sentiment

Utterance record: One utterance.v1 row per committed spoken utterance (docs/contracts/utterance.v1.md): its timings (segment, endpoint reason, speech end to commit, partials), its levels (level, noise floor, signal-to-floor ratio, clipping) and the live estimator’s prosody numbers, keyed by the device that heard it. Numbers only, never audio or words, computed on the blocking pool after the commit, behind [utterance] rows (off by default). It is not operator affect and holds no cue or score. Avoid: voice profile (that is the TTS voice), utterance log (it holds no words)

Scratch that: The closed gateway verb (scratch that, scratch this, delete that, delete this, and undo that when the house has nothing to put back) that erases the last dictation Vulpine typed, only if it is untouched (docs/contracts/dictation.v1.md). It is armed for 120 s after a delivery. The gateway holds the last insert’s proof by reference (receipt_id, range, length); the screen agent holds the pid, the AX element, the window and the string, and erases only while the range still reads code-unit equal to that string (eraseRange). Otherwise it refuses and Vulpine says “That text has changed; I left it.” The trace row is dictation_scratch {outcome: erase_requested | erased | changed | nothing | unverified | failed}. It sends no key events. Avoid: undo (the house undo is a different verb), delete last

Family gate: The cascade pack’s root question (benchmarks/verbs/questions-v2.json _cascade.root): which family of verbs an utterance belongs to, asked beside the branch questions so the Decision shadow reads the composed P(verb) = P(family) × P(verb | family). A verb whose family is not ranked high is gated out however well its branch ranks it. In the frozen-encoder heads, head_server.py answers it zero-shot over family descriptions. Nothing routes on it. Avoid: intent gate, root gate; the state gate is different (an option the state closes, reading when no read is open, is cut from the criteria before the ask)

Mood picker: Chooses the mood the voice reads a reply in, from the reply’s first segment, the operator’s last words and the turn kind (crates/voice_gateway/src/mood_pick.rs). It answers with one of the voice’s 13 mood names, the reply’s dialogue act and a confidence (decision.v1’s margin); a thin margin answers neutral. It is rules over cue phrases, run as a shadow: one mood_pick trace row per reply and the Admin’s gateway.mood_pick row. Its output is the name a [mood:<name>] tag carries; the brain’s own tag wins. Avoid: emotion classifier, sentiment (it picks a reading for the voice, not the operator’s feeling); mood tag (that is the brain’s own [mood:x])

Typed camera nouls: Yes/no decision.v1 questions asked of one camera frame, each answered with a probability: gate_open, dog_in_yard, package_at_door, person_at_door and car_in_drive (runtime/vision/nouls.toml, which fits jev-visual’s question schema so the five share one prefill over the frame; its _nouls table of where each can be seen is never sent). Nothing acts on a noul until it has its own lock over hand labels. Avoid: object detection, camera caption (a screenshot goes to the brain as OCR text; a camera frame is asked typed nouls)

Frame lattice: A persona’s portrait baked once into frames over five axes, mood, open, form, blink, gaze: the optional axes block of a Vigil portrait manifest (apps/vigil/src/portrait/manifest.ts), each axis listing its cells and a sparse cells map from a tuple to a frame. resolveCell draws the nearest baked cell: the state’s mood (else neutral, else the first mood with cells), then the least squared distance over open, form, blink and gaze, ties to the lowest axis-index tuple. A manifest without the block resolves as manifest v1 (the MGS sprites). Avoid: sprite sheet, talking head (nothing is rendered live), avatar (Avatar is Glyph’s presence renderer)

Wake-less window: A span in which the gateway takes the operator’s next final without the callsign, because it is waiting for an answer. Under radio the turn machine has exactly five: the Follow-up window, the Plain-speech answer window, the Home answer window, the Verb-confirm window and the Call window (crates/voice_gateway/src/turn/manager/follow_up.rs). Ahead of the turn machine, a ringing alarm’s Alarm answer window, a spoken approval card and a spoken proactive card take the final that answers them. Outside all of them a final is dropped with stt_final_dropped {reason: not_armed}. Announcements and reports open none. Avoid: follow-up (one kind of window), open mic (the mic is always open; the arm is what lapses)

Follow-up window: The wake-less window that opens when the reply to the operator’s request finishes playing. The next utterance commits without the callsign for [invocation] follow_up_window_ms (0 = off; the loadout overrides it at the bind, 5,000 ms in the operator agent’s loadouts), and for at least 8 s when the reply asked a question. Only the reply to a request opens it, never an announcement or report, and never during a call. An utterance whose speech start or a partial lands inside the window belongs to it even when its final arrives later, up to 20 s of speech. The window is traced as follow_up_window {open_ms, asked_question, reply_complete}, its take as follow_up_take, and a final it saw and did not take as follow_up_refused {reason}. Avoid: conversation mode, open mic

Wake in progress: The span from the wake (the request armed, by the detector or the callsign in a partial) until the request settles at its endpoint or the armed window closes. The announcement governor treats it as no breakpoint at any tier: a proactive line admitted inside it is held with announcement_deferred {reason: WakeInProgress} and speaks at the next quiet point after the request (the reply, then the operator-quiet window). Avoid: listening (the mic always listens), breakpoint (the opposite)

Report claim: The gateway-wide claim one bound session takes on a finished herdr agent’s task report (its pane plus the report file’s mtime) before speaking it, so the report card is spoken on one session, not every one. The session that owns the agent claims at once. An unowned sighting (the session-wide status feed) holds 1 s first, and a room device also holds the approval card’s grace, so the operator’s own device claims before a room speaker. A session that finds the claim taken traces herdr_agent_report_claimed_elsewhere and stays quiet. Avoid: report dedupe

Plain-speech answer window: The wake-less window a spoken brain question holds open (a Pi extension_ui_request dialog, such as pi_ask_operator). Once the question has finished sounding, the next final is its answer in plain words and goes back to the brain without reaching the turn machine. What the mic hears while the question still plays is ignored (brain_ui_answer_ignored {reason: question_playing}). An answer that fits none of the dialog’s choices is brain_ui_answer_unmatched. Avoid: ask-back mode, prompt reply

Ask-back budget: The per-session rule that a brain does not ask the same thing twice in a row ([brain] ask_back_budget, default off). A second consecutive ask-back on one subject inside ask_back_budget_window_secs is not spoken: the brain gets the select’s first option and the operator hears “

Home answer window: The wake-less window open while a home verb’s confirmation is asked. The session raises answer_window (traced answer_window {open}), and an unarmed final that reads as a yes or a no commits without the callsign (answer_window_take {chars}). Anything unclear needs the callsign. The same flag is raised while a brain dialog or a spoken approval card waits. Avoid: confirm mode

Verb-confirm window: The “Did you mean …?” question’s wake-less window ([turn] verb_confirm_band, off by default). A tier-3 pick whose margin sits in the band is asked about in one line and does not become a brain turn. For verb_confirm_timeout_ms, a yes routes the verb and a no sends the operator’s original words to the brain (verb_confirm_band, verb_confirm_answer). Avoid: disambiguation dialog

Call window: Vigil’s wake-free span (ADR 0037’s “Vigil is a call”). CALL, the vigil loadout’s bind, opens it (call_window_opened {call_id}, the call id being the session’s), and every wake-less final inside it is the call’s take (call_taken {chars, call_id}). HANGUP (“over and out”), the session’s end or a rebind closes it (call_window_closed {call_id, reason: hangup|ended|session_closed}). A yes or no to an open confirmation is that confirmation’s answer, and no Follow-up window opens during a call (crates/voice_gateway/src/ws/call_window.rs). After HANGUP the client’s optional call control (Vigil’s CALL key) opens it again on a call loadout (call_window_opened {reason: call}); a non-call loadout is refused call_not_capable, and [invocation] call_control = false ignores the control. Avoid: dialogue mode (it stays wake-gated under radio), always-listening

Alarm answer window: The 45 s wake-less window each ring of an alarm or timer opens (alarm_window_opened), in which a closed-grammar answer (“okay”, “stop”, “snooze five minutes”, “cancel the alarm”) settles it without the callsign (alarm_answered {alarm_id, ack, pick, ringing_left}). Each ringing alarm holds its own window until its answer or expiry (alarm_expired). A bare answer settles the most recently rung alarm (pick: newest); a named one (“cancel the pasta timer”, “stop the seven o’clock one”) settles the alarm whose label or time it names (pick: named). While another alarm still rings, the spoken confirmation names the one settled. Avoid: the alarm window (there is one per ringing alarm), alarm ack (an answer may also snooze or cancel)

Fault injection: An owner-only way to make a gateway fault happen on cue. The first is the STT fault: an owner-local Admin-socket request stt_fault_inject {session_id?, reason?} (sent by tools/gateway/stt_fault_inject.py) makes that session’s recognizer report a terminal error once (traced stt_fault_injected). The gateway honors it only when the staged config sets [stt] fault_injection = true (default false; it needs [admin] enabled = true); otherwise it refuses with stt_fault_injection_disabled. Avoid: chaos test, kill test (nothing is killed)

First-token budget: How long a voice turn may wait for the brain’s first token, from the dispatch that produced it (the speculative one included) to brain_first_token: the ttft leg of a run’s latency block (latency.md / latency.json beside its scoreboard, from tools/telemetry/felt_latency.py). The QA target is a p50 of 3,000 ms and a p90 of 5,000 ms on the voice path (tools/qa/qa_compare.py); the per-leg budgets of a live turn are in docs/contracts/turn-budget.v1.md. qa_collect marks a ttft leg over the target over_target, and qa-compare adds a ttft TARGET row (OVER_TARGET) for a p50 that moved more than 25 %. Every tool schema, policy line and envelope byte in the voice brain’s prompt is spent from it. Avoid: latency (unqualified; the block has six legs), response time (the operator hears vart, speech end to first audible)

Tool override (MCP): A per-tool entry under an MCP server’s toolOverrides in the brain’s MCP profile (catalog/agents/operator/.vulpine/mcp/<profile>.json) that replaces what the voice brain reads about that tool: a one- or two-line description (at most 300 characters) and, optionally, a narrowed inputSchema. The extension applies it by wrapping the registerTool it hands pi-mcp-adapter. It never admits a tool: an override for a tool not in directTools is refused with a warning, a write-shaped name refuses the whole profile, and a schema that drops a required parameter or invents one keeps the server’s. Deleting the entries restores the server’s own text. Avoid: tool alias, MCP shim (the tool and its server are unchanged)

Speech lanes, the Meet legs and Home Assistant (current)

Authority STT lane: The recognizer whose words are the turn’s: Parakeet TDT 0.6B v3 on the Neural Engine through crates/coreml_stt (ADR 0027), in the gateway process. Everything else that decodes speech (the Second-opinion lane, a shadow bundle) is evidence beside it, never authority. Avoid: the STT worker (there is no worker process to kill), the model

Second-opinion lane: A replay-only second decode of each committed utterance (crates/voice_gateway/src/second_opinion.rs). [shadow_stt] second_opinion_command names an external decoder that speaks transcribe --stdin --pcm-f32le and prints one receipt line. The gateway pipes it the utterance’s window from an in-memory ring (nothing on disk) and writes one stt_second_opinion trace row of agreement numbers: never text, never spoken, never authority. A confident disagreement is a dispute and an Admin event. The engines are vulpine-speech (alias speechctl, Apple SpeechAnalyzer), Qwen3-ASR and whisper-candle (tools/speech/whisper_candle_shim, Whisper base.en in Rust), whose score gives the teacher-forced dispute: greedy minus forced log-prob of the committed text. Nothing acts on it. Avoid: second STT, backup recognizer (it never replaces the Authority STT lane)

Wyoming engine: Vulpine’s voice as Home Assistant’s TTS engine over the Wyoming protocol: tools/wyoming_tts/server.py on port 10200 of the gateway host. It is not part of a Vulpine install: neither app ships it, just install does not set it up, and runtime-tools.toml marks it retire (a port to the gateway is due). Where a host’s own configuration runs it, it serves one Vulpine voice with the mood bank as its speakers, streams synthesis per sentence, refuses when busy and may relay to a --fallback (runtime/wyoming-kokoro, port 10210). HA speaks through it; Vulpine’s own turns do not. Not the wyoming transport of hardpoint.tts, which is the other way round: the gateway speaking through a Wyoming server. Avoid: HA TTS (that is whatever engine HA picks), Wyoming bridge

Meet legs: The two audio streams of a call meetctl transcribes (ADR 0039, tools/meet/): the near leg is this Mac’s microphone (the operator); the far leg is what the browser plays, taken from a Core Audio process tap (tapctl). Both are decoded. The far leg is diarized as it streams and cut per speaker turn (docs/meetctl.md), and the result enters the gateway as typed meeting events (docs/contracts/meeting.v1.md). Avoid: channels, tracks, local / remote audio

Noise floor: The room’s quiet level at a session’s microphone (crates/voice_gateway/src/noise_floor.rs): the 10th percentile of the per-100 ms minima of the client’s chunk levels over a rolling 60 s, read once per capture (a dictation hold’s settle, a spoken turn’s commit). The capture’s peak minus the floor is a lower bound on its SNR. The gateway writes it as a capture_noise_floor trace row and as noise_floor on the session’s Admin presentation row, once it has 5 s of frames. It always runs and decides nothing: no threshold, gate or behavior reads it. Avoid: the adaptive floor (ADR 0019’s 10 s playback-bleed floor in nearfield.rs, which does gate), the noise gate

Satellite control: One touch on a satellite’s physical controls: the Voice PE puck’s center button (single, double, long press), its dial and its mute switch, sent as satellite_control {control} (docs/contracts/satellite-controls.v1.md) by a bridge running --controls gateway. The frame says what was touched; the gateway decides what it means by the turn machine’s state (crates/voice_gateway/src/satellite_controls.rs). A single press is “over” while the request ear is armed and a cancel while a reply sounds or waits, a double press is “start over”, a long press toggles the mute, the mute switch sets it (presence rests in idle while muted), and the dial moves the satellite’s room volume once it rests. Every control traces one satellite_control {kind, mapped_to} row. Avoid: button events (the ESPHome telemetry the bridge reads), the puck’s mute (the device switch; the gateway’s muted state is the mirror)

Satellite state: The gateway’s settled state for a satellite’s own controls, sent back to it as satellite_state {volume?, muted?} (docs/contracts/satellite-controls.v1.md) to a kind: satellite frontend only, on bind and whenever the room volume or the mute settles to something new. volume is the satellite room’s volume on roomctl’s 0-60 scale, and muted the session’s mic mute once a switch or a long press has set it. The bridge’s output follows the volume and the puck’s Mute switch follows the mute, so the gateway is the one source of truth; the bridge swallows the switch’s report of a position the gateway asked for. Avoid: the clip volume (the bridge’s Sonos setting, which follows this), satellite status (satellitectl status, the bridge’s own socket)

The repo and the install (current)

Doctor: just doctor (vulpine-voice-gateway doctor [--json]): one read-only pass over this install that prints one OK / MISSING / WRONG line per check with its fix, and exits 1 when any check is not OK. It checks the pinned tools, the state config (present, valid, the live composition’s keys, every path it names), the two XDG roots (xdg:config / xdg:state), the config directory, the models (the Parakeet bundle, the DAF weights, the TTS talker), the launchd jobs and their ports, the secrets by name and mode (never a value), and the disk and memory floors. ~/.config/vulpine and ~/.local/state/vulpine win when they exist; an install with only an old root (~/.config/foxline; ~/.local/state/foxline, then ~/.local/state/fox9) is read from it with one WARN line. The doctor says OK on either, WRONG when the vulpine root and an old root are both real directories, and MISSING when neither exists; docs/install.md’s “Moving to the vulpine roots” has the move. An install is done when the doctor is green. Avoid: health check (that is the gateway’s live /health and Admin’s health panel), preflight

runtime/: The top-level folder of every runtime helper: runtime/<helper>/ for each binary or script the gateway, a launchd job or a roll spawns. runtime-tools.toml lists every spawned path with its language, owner and test, and runtime/README.md is the map. Avoid: services/ (folded into it), tools/ (operator tooling stays under tools/<seam>/)

Was this page helpful?