Glossary — the names of things

Shell — the fixed chrome

The permanent frame: Sidebar on the left, the main column on the right, Status Bar across the bottom. Everything else lives inside it or floats above it. Code: src/app.tsx, src/ui/shell/.

• Sidebar — the left rail: projects → worktrees/local branches → agent sessions, live status at a glance. Focus chord alt+1 (focus.sidebar).
  • Project row — a repo under ~/Code; folds its children; rolls up the worst child status.
  • Worktree row — T branch: any checkout, root or linked — the root checkout is simply the first worktree, as git worktree list orders it (ADR-0017). Dirty state and diffstat trail it; the name takes the branch's graph-lane hue while the T stays a standard text tone. Enter opens its File Tree. ctrl-n starts an agent there.
  • Parked root — the root checkout off trunk (or detached): a faint ·root trails the name in both panes — the one state where the repo itself reads like a disposable worktree. Its menu renders Remove inert with the reason and offers Switch back to trunk, hocket's one git switch write — never forced, first unmounting a trunk mounted in a linked worktree (non-forced worktree remove, hint "unmounts trunk first"), inert only while sessions live there (ADR-0007/0017 amendments).
  • Branch row — B name, an unmounted local branch. Selection follows its graph lineage; Enter inspects its tip.
  • Merged group row — ▸ merged · N, the last row of a project: dead worktrees (merged + clean + nobody home) fold here, collapsed by default. →/enter/click expands; backspace removes all N behind one confirm — auto-prune's pass, run by hand. A dead worktree still basing live stacked work stays in place as scaffolding instead of pooling.
  • Trunk pin — trunk is always the second row of its project: the worktree mounting it, or an unmounted B main that never sinks into the sibling sort and never dims.
  • Lineage nesting — a worktree/branch forked from a non-trunk branch indents under its base (recorded branch.<name>.hocket-base, else reflog, else trunk — ADR-0017); trunk-based work stays flat. Left jumps from a stacked row to its base.
  • Session row — one agent session with its Status Glyph.
  • Other group — the header collecting orphan sessions that run outside any known worktree.
  • Type-to-filter — the transient broot-style narrowing in list panes (Sidebar, File Tree, and Processes): printables narrow, esc backs out, focus-loss ends it. A filter is never a mode.
  • Filter Session — one active narrowing: state = (query, Filter Scope); both empty ≡ off (ADR-0013). Ends by esc ladder or focus loss, restoring the full list with the place kept.
  • Filter Scope / Descend — return on a dir (or project) while filtering enters it: the pane re-roots to it for the session, the query resets, matching turns scope-relative. Esc pops one level per press.
  • Scope Breadcrumb — the faint src/core ▸ trail in the filter footer naming the scope; clicking it pops a level.
  • Status Modifier — a leading :x token in the File Tree filter restricting candidates by git state (:m modified, :a added, :d deleted, :u untracked, :c conflicted, :g any change; ADR-0021). Composes with the fuzzy query and the Filter Scope; rendered as a git-tinted chip in the filter footer. File Tree only — : in Processes is the Listener filter.
  • Unlisted Row — the … N unlisted honesty row standing in for matches the pane budget hid (broot's Pruning line). Unselectable: arrows, tab, and clicks skip it. The dir-suffix … remains the pruned-dir cue (children hidden by the filter, not the budget).
• Status Bar — the single bottom line. Quiet chrome: hints live here, not in panes.
  • Session Tally — the left segment: session count/summary and the active session.
  • Worktree Segment — active session's project/branch plus +/− diffstat.
  • Focus Segment — the quiet navigator: where focus lives now + the chord that got you there.
  • Context Hint — the rightmost teaching slot; changes with focus ("type to filter", "new agent · n", filter echo).
  • Chord Badge — a rendered keybinding hint (ctrl-n), one hyphen dialect everywhere: palette, menus, Status Bar.

Top Slot — the swappable upper surface

The upper half of the main column. Holds exactly one surface at a time: the Terminal (default) or the Graph (esc-5 swaps). "Terminal" in layout vocabulary means this slot, whichever surface it shows. Focus address esc-3 (terminal) / esc-4 (agent) (focus.main).

• Terminal — the embedded agent terminal (real PTY, our VT emulator), indistinguishable from a bare terminal. Code: src/ui/terminal/.
  • Pane Title — the top-border label: Status Glyph + session title.
  • Scrollback Pill — the "in scrollback" affordance while scrolled into history; any keypress returns to live.
  • Exit Strip — the one-line footer on a dead session ("exited 1 · enter to close").
• Graph — the worktree rails view of the followed project's history (ADR-0011). A second projection of the agent list. Code: src/ui/graph/.
  • Trunk — the leftmost lane: the main branch.
  • Lane — one colored rail per worktree.
  • Ghost — a worktree's working-tree state on the rails (ADR-0011): empty ◌ = clean slot, ring ◎ = dirty — the next commit forming, solid ● = committed. Floating vs docked is geometry only; a docked-and-clean worktree shows the bare tip dot.
  • Ghost Stub — the marker on a worktree's fork commit.
  • Spotlight — the highlighted lane mirroring the Sidebar selection.
  • Agent Glyph — a session's live Status Glyph rendered on its worktree's row.
  • Horizon — the truncation footer at the 400-commit edge; "load more" is a button in row's clothing.
  • Archived layer — the refs/archived-worktrees bookmarks, off by default, toggled with a.
• Processes — the worktree-attributed OS process manager (ADR-0012).
  • Listener filter — : typed in Processes matches listener badges; adding digits narrows to a specific TCP port.
  • Process family — one Hocket session root plus its observed descendants; agent status belongs to the root while tools and services nest beneath it.
  • Ambient process — a worktree process with no Hocket-session ancestry.

Editor Row — File Tree + Editor Pane

The lower half of the main column (or full height when zoomed). Code: src/ui/editor/.

• File Tree — the file browser for the followed worktree; git tints, status letters, indent rails; follows Sidebar selection (browse-first: opening keeps focus in the tree). Focus address esc-2 with no file open (focus.tree).
• Editor Pane — tabs + the editable surface. Focus address esc-2 with a file open (focus.editor).
  • Tab Strip — the open-buffer tabs along the top edge.
  • Buffer — the editable text surface itself (unhighlighted in v1, ADR-0010).
  • Git Gutter — per-line added/modified/deleted marks against the worktree head.
  • Overflow Chevrons — the horizontal-overflow signifiers when a long line runs off-pane in scroll mode (line wrapping remains available from the command palette).
  • Trail Bar — the pane's bottom edge when find is closed: breadcrumb (path within the worktree) + cursor position.
  • Find Bar — in-buffer find; replaces the Trail Bar while open.
  • Conflict Bar — the non-modal bar on a dirty buffer whose file an agent changed underneath (reload / keep / diff).
  • Touch Pulse — the amber border flash when an agent edits a clean buffer and it live-reloads.

Overlays — floating, key-owning surfaces

While one is open it owns every key. Code: src/ui/shell/.

• Options — the centered application-preferences panel (ctrl-,), with persisted notification and auto-prune choices plus project ordering.
• Palette — the ctrl-k command palette, backbone of all interaction.
  • Recent — cmd-e: one most-recently-used trail answering "where was I?", across worktrees. Sessions first, then the Attention Run while agents are waiting, then files, each run ranked on its own so the sections never shuffle apart under a query; a Section Divider rules them apart, and a list with one run shows none. Whatever you're in now — active session, active file — stays out, so the first row is always the place you'd flip back to. Closed tabs remain in the trail; closed sessions do not (their ids name nothing). Only a deliberate pick joins the trail — browsing a worktree never does. Repeated cmd-e advances and cmd-shift-e reverses, walking rows within a run; tab crosses between runs. Return goes; esc cancels — arrow previews and the walk's pin drift are put back the way cmd-e found them, and only a pin alt+tab set inside the list survives the close.
    • Attention Run — the attention section, present only while agents are waiting: the alt+a queue with eyes. Asking before unread — the stuck agent always outranks news — newest claim first within each, so cmd-e tab enter lands in the most urgent agent's pane. Membership freezes when Recent opens (rows hold still mid-walk) while Status Glyphs stay live — a row honestly shows its agent resumed. An agent may sit here and in the trail: "where was I" and "who needs me" are two questions, and each run answers its own. When nothing is waiting the run vanishes and tab reaches files in one hop, as ever.
    • Worktree Badge — the trailing project/T branch on a Recent row: the letter says kind in a neutral tone, the name carries the branch's graph-lane hue (ADR-0017), so a row wears the color its lane wears in the Graph and its worktree wears in the Sidebar. One surface, four modes:
  • Command mode — every registered action, with Chord Badge hints.
  • Prompt mode — one-line text input ("run in project/branch", project search needle). Recent values sit on digits below the input; when the target worktree has detached agents parked on it, the new-agent prompt continues the digit run with the pane chooser's or pick up clause — Status Glyph and name — so ctrl-n never spawns a twin the user forgot.
  • File Picker — ctrl-p: fuzzy-open a file in the followed worktree.
  • Search Results — ctrl-g project-search hits (git grep), enter jumps to file:line.
• Context Menu — right-click menu; holds the create/kill/close/delete actions that left-click (navigate-only, never create) withholds. Destructive items (project remove, worktree remove, branch delete, the graph's hard delete) always land in a confirm modal first.
  • Inert item — a faint, unselectable row explaining a withheld action; its hint slot carries the reason, not a chord (e.g. the root checkout's Remove worktree · root checkout). Arrows skip it, clicks stop at it.
• Quit Confirm — the ctrl-q modal listing live sessions by name.

Cross-cutting vocabulary

• Panel — one of four persisted pane-group configurations. It remembers pane visibility and geometry, focus, zoom, and the attached file-tree split; editor contents remain shared, while each terminal/agent pane exclusively owns its session per worktree (ADR-0018). New panes start unbound instead of cloning another Panel's agent. The bottom-right 1 2 3 4 strip marks the active Panel in both PANE and PANELS modes.
• Pane — an individual tiled surface inside a Panel: terminal, graph, processes, file tree, or editor.
• Detach — closing a terminal/agent pane releases its session binding without touching the process: the session keeps running and stays reachable from the Sidebar, Recent, and the palette. Picking it up anywhere — a Sidebar session row, a palette "Go to", or the or pick up digits of the pane chooser and the ctrl-n prompt — moves it into the choosing pane with screen and scrollback intact. Kill and Close are the only destructive session verbs.
• Status Glyph — the agent signal, same everywhere (Sidebar, Graph, Pane Title, Status Bar, Recent): spinner = working, amber ◆ = asking (needs your input), amber ● = unread (finished, results not yet seen), amber ○ = read (seen, not replied — an open thread), steel ○ = idle, ✕ = exited nonzero. Fill tracks whether you've seen it, shape tracks whether the agent needs something, amber tracks an open thread (the fill grammar rhymes with the ghost vocabulary's ◌/◎/●). One implementation behind every surface that shows it (src/ui/status-glyph.ts) — the promise is that the mark reads identically, so it is not remapped per pane.
• Focus Stop — any place focus can land: sidebar, main (top slot), graph, tree, buffer. esc-1…6 addresses jump by kind, alt+1…9/cmd+1…9 jump by column; alt+shift+arrows walk spatially. Other arrows stay local to their panel.
• Followed worktree / followed project — whatever the Sidebar selection points at; the File Tree, Graph, and Processes pane follow it (three projections, one selection).
• Visual Filter — the pinned projection context (docs/public/context-projections.md): pin a project, worktree, or branch and every projection dims what falls outside it. Entered by clicking the already-selected row or toggled with alt+tab; the esc ladder lifts it. Dims, never prunes — the opposite trade from Type-to-filter.
• Attention — the amber family, organized by who is stuck (ADR-0006). Asking (needs-attention): the agent is blocked on your input — dialog, permission, question — amber ◆, row tint, "needs you" tally; looking never clears it, answering does. Unread: a finished turn you haven't seen — amber ●, no tint; every agent turn-end lands here, even with no done signal to match (a quiet park off real work counts); clears to read when the session is displayed as the active pane for a beat while the host terminal window has focus — on another tab the fill holds. Read: seen, not replied — amber ○, quiet, holds until you type. Steel ○ idle means nothing unseen: boot screens, quiet shells, threads you've engaged. Desktop notification and finish sound fire for asking and unread; asking speaks in its own voice when an asking_sound source has audio (default: the config dir itself, finish pool as fallback). alt+a cycles asking first, then unread; Recent's Attention Run is the same queue laid out as rows (cmd-e tab), newest claim first.
• ♪ (the piano egg) — the quiet eighth-note glyph opening the sidebar header (♪ projects · …), text.muted: quiet but findable — small music glyphs render thin, so faint washed it out (2026-07-18; ♫ rejected as squished at cell size). Three alt-clicks on it, each within a beat (2s) of the last, toggle the piano sound set: stop cues draw from the config dir's piano/ and piano/asking/ pools (everyday sounds as fallback), the glyph lights in the selection accent, and the toggle answers in the new voice. A plain click is the mute toggle: cues silenced, the glyph alone wears a strikethrough (the spacing gap stays unstruck), banners and their BEL untouched — a muted hocket still waves, it just doesn't sing. Unmuting answers in the active voice; muting is silent, that's the point. A plain click also breaks the ritual count; no hover treatment — the egg half of the glyph doesn't advertise. Both bits persist as preferences; silenced cues (*_sound = false) stay silent, egg or not.
• Tab Unlock Ritual — the ♪ egg's grammar applied to editing: buffers open locked (full editor, no cursor, mutations swallowed), and three alt-clicks on a buffer's tab — each within a beat (2s) of the last — unlock it. The tab title turns git.added green (editable = gained the right to gain changes); the same ritual re-locks it. Per file, dies with the tab, never persisted. On buffers that can never take edits (branch tips, binary, oversized) the ritual answers with the status-bar notice "not able to edit". Wandering to another tab mid-ritual restarts the count there; ritual clicks never activate the tab.
• Hover Lift — the click affordance: the row under the mouse pointer lifts one background elevation (no accent bar — the bar stays the selection's mark). Sidebar today; the pattern for any clickable list row.
• Edge Bar — the PANEL-mode pane-level mark for the chromeless Sidebar: a full-height accent ▌ column at column 0, standing in for bordered panes' focused border color; the row-level selection bar quiets beneath it.
• Snap Target — a position a resized boundary is magnetic to: the workspace half-lines, alignment with other parallel boundaries, and home detents; always legality-filtered by pane minimums (ADR-0016).
• Detent — the one-repeat-tick pause a held resize takes on a Snap Target; discrete presses never pause.
• Even Out — the PANEL = action: snap every boundary to the 2×2 grid in one undoable step.