GLOSSARY.md

Glossary

This document owns the plain-language meaning of every term the implementation documents use in a narrower sense than ordinary English. It is the single place those meanings are written down; the other documents reference it rather than repeating a definition.

It exists because most of these words are also names in the code or on the wire. Renaming them only in prose would leave a reader unable to match a sentence to the function or field it describes, so each entry gives the plain meaning and where the name appears, and the two are meant to stay together.

../README.md and PRODUCT.md are written for someone who has never seen this repository and deliberately avoid these terms. If you are reading those two, you should not need this page.

The two sides

Term	What it means	Where the name appears
producer	The coding app that reports what it is doing — the Codex desktop app or Claude Code. Not a message queue and not a video term; it is simply whichever app is the source of events.	wire field producer, enum AgentProducer (codex, claude)
host bridge, bridge	The small Node.js program that runs on your computer, receives the coding app's hooks, and talks to the device over USB.	packages/code-chan/
firmware	The program on the CoreS3 that validates each message and decides how the character reacts.	firmware/stackchan/
relay	The short-lived command a hook actually runs. It reduces the payload and forwards it to the bridge, then exits. It is not a running service.	src/dev/agent-hook.ts

Connection

Term	What it means	Where the name appears
bridge epoch	One connection's identity. Every bridge start makes a new one, and the device accepts messages only from the epoch it agreed to, so a stale bridge cannot disturb a live one.	wire field bridgeEpoch
replica	The device's own copy of what the host last told it. The host sends complete state rather than edits, and the replica is what the device draws from.	DeviceProtocolSession
snapshot	One complete statement of the current state: which app, what it is doing, how many subagents, any pending permission. Not a partial update.	wire message snapshot, field snapshotId
activity	One tool event — a tool started, or failed. Named separately from the snapshot because it is a moment rather than a state.	wire message activity, field activity

Who owns the device

Term	What it means	Where the name appears
turn	One prompt and the response to it.	wire field turnId
foreground	The one session whose work the device is showing. Every other session keeps working normally and does not touch the device.	ForegroundCoordinator
lease	The right to drive the device, as distinct from what is currently on screen. Held while a response is running, or while work is still finishing on its own.	#holdsLease
episode	Everything belonging to one task, including work that outlives the response that started it — so a background subagent finishing later is part of the same episode, not a new one.	ForegroundTurn
admit, admission	To accept an incoming event as part of the current episode. The opposite is to ignore it, which leaves the device unchanged.	beginPrompt, apply

Why a task stays open

Term	What it means	Where the name appears
obligation	A reason the task is not finished yet, even though the response stopped. Every obligation must name the event that ends it; anything no event can end is not an obligation.	#obligations
discharge	To end an obligation by the event it named.	#obligations, #settleIfComplete
producer-dischargeable	The coding app will end it by itself — a running subagent, or a report that has not arrived yet. These keep the lease.	Obligations.producer
user-dischargeable	Only a person can end it, by prompting again. These keep the display but release the lease, so the device does not become furniture.	Obligations.user
retained	A task whose response stopped while an obligation remains. Shown as waiting.	ForegroundRecord kind draining

States on screen

agentState on the wire is one of five values. PROTOCOL.md owns the exact rules; this is what each one means to a person looking at the device.

Value	On screen	Meaning
idle	CODEX READY / CLAUDE READY	Connected to that app, nothing running.
working	WORKING, or remaining usage	A response is in progress.
needs_input	APPROVE / REJECT controls	Waiting for you to answer a permission request.
waiting	WAITING	The response stopped but the task is not finished.
error	MISS	The host and the app disagreed about something.

Completion is not a state. It is a one-shot effect and sound, played once, after which the screen returns to idle.

The scene

Term	What it means	Where the name appears
hero	The tracked mecha character. Original art, not a third-party character.	assets/sprites/hero/
drone	One escort craft standing for one running subagent, up to three slots that then upgrade in tier.	assets/sprites/drones/
decision item	The floating box shown for a permission request. Touching it does nothing; only the labeled controls answer.	assets/items/decision/
scene manifest	The tracked file that decides every word, position, control, and drawing order on screen. Firmware has no fallback constants that could override it.	assets/scenes/expedition/scene.json
scene package	The generated file set the device actually loads, built from the manifest and the art. Not tracked; produced by the builder.	firmware/stackchan/data/
compositor	The firmware part that turns one scene state into pixels at a fixed 24 frames per second.	scene_compositor.cpp
presenter	The firmware part that pushes those pixels to the panel in two horizontal strips.	display_presenter.cpp

Power and rest

Term	What it means	Where the name appears
quiescence	Everything has actually come to rest — confirmed by the panel and the motors reporting back, never by a timer expiring.	expression_lifecycle.cpp
ordinary suspension	The everyday sleep: head parked, motors off, panel off. Distinct from shutting the board down.	display_power.cpp
PMIC	The CoreS3's power management chip. The firmware can ask it to cut power; an accepted request proves the firmware reached the chip, not that the rails fell.	board_power_target.cpp

Words used strictly

Term	How it is used here
bounded	Has a declared maximum length or count that is checked before use. Never "roughly limited".
evidence	Something the coding app or the device actually reported. A state is changed by evidence, never by elapsed time.
acknowledged	The device confirmed receipt by ID. An unacknowledged delivery is a failure, not a slow success.
prove	Used narrowly. Most uses in these documents say what something does not prove, and that is deliberate.