Crate yog 

egui/eframe frontend for the lernie agent harness — the balls-oriented manager for lernie loops.

This crate is the desktop UI: a stateless renderer over on-disk state that issues user actions as lernie and bl subcommand invocations. Every render is a pure function of filesystem state at the current tick, and the public view-model API is reentrant, so a future lernie-ui-web runs concurrently against the same repo without coordination.

docs/DESIGN.md is the authority for the state inventory, the attention model, the module map, and line budgets; the module docs below stay terse and defer to it. The shape in brief: pure view-model modules (no egui) — the per-tick git_tree, the nav roster, attention, projects/ binding, start, ui_state, the inspector VMs (transcript, steps_view, jsonview, inboxview, budgets) composed by the tested inspector tab dispatch, config_edit — fronted by the thin egui glue in shell (§11). app re-exports Args, Roots, Focus, and the multi-workspace AppModel; keymap is the pure §11 key → intent table; cli_outbound execs the binaries; actions holds the message/stop/scan/close/unclaim/create/update verb surface; theme is the congeries palette — the single colour/visuals authority (§11).

The crate root is deliberately declaration-only. A root carrying a coverable impl or fn accrues an llvm-cov phantom uncovered region on its header line each time the pub mod list above it grows and shifts byte offsets (this cost 99.90% coverage after the Y2/Y7/Y15 folds). With all coverable code in submodules, new pub mod lines have no root-level line to mis-attribute, so coverage stays at 100% as modules land.

Re-exports

pub use app::AppModel;

pub use app::Args;

pub use app::Focus;

pub use app::Roots;

Modules

actions

User actions issued through cli_outbound (ARCH §3.4 / §3.5).

app

Top-level app state and the render entry points.

attention

The attention model (DESIGN §6, §15 Y10): the derived per-agent predicate, its per-signal detail for badges, the workspace/strip rollups, the jump-to-next-attention control, and the roster sort.

binding

Workspace enumeration across the three roots (DESIGN §3.1). Everything here is a pure function of injected roots plus a bounded directory walk — no env reads (roots come from crate::xdg), no writes.

budgets

Whole-tree budget-spend fold (DESIGN §5.1 #16; ARCH §6 budgets).

cli_outbound

CLI outbound: the frontend’s sole command surface to the harness. Every user action is an exec(<binary>, args) and nothing else (ARCH §3.4/§3.5; “resume” is no longer user-facing per the §2.9 amendment, bl-abf3).

config_edit

Config-editing view-models (DESIGN §9): load → edit a RAM draft → Apply = stage → (validate, where a validator exists) → hash-guard → atomic rename.

files_view

Agent-worktree file view-model (DESIGN §11 Altitude-2 Files tab).

fs_watcher

Filesystem watcher for a watched root.

git_tree

Git-tree view-model (ARCH §7.1 live view, §3.5 agent-state contract).

inboxview

Inbox deposit view-model (DESIGN §11 Inbox tab; ARCH §2.11 deposit).

inspector

The §11 Altitude-2 inspector content — the per-agent tabbed pane’s display, dispatched by InspectorTab.

jsonview

Collapsible JSON row tree + a thin egui render — the uniform “every byte inspectable” inspector widget (DESIGN §5.1 #13, §11 Altitude-2 Steps tab).

keymap

The keyboard-navigation keymap (DESIGN §11): a pure key → intent table.

login

The login flow (DESIGN §8.3 as amended, §15 M6 Z8): bz’s one interactive surface, run as the streamed-piped spawn class (§8’s third class). bz --login --provider <row> streams its device-code / URL lines live to the invoking surface — the toolchain pane, and beside an auth-failed step — verbatim (§5.3 instance-local RAM); on exit ONE outcome row lands in ops.jsonl (§4.2, the stream never logged line-by-line), and a non-zero exit carries the exact command as a run-by-hand fallback (§8.3). Credentials stay bz’s: yog renders the flow, never reads or writes a credential (§5.1 #22).

names

Workspace name minting (DESIGN §3.1): two words from an embedded wordlist, hyphenated — cobalt-gecko. The name is the workspace’s directory leaf and the --as identity of every ball claim that workspace makes (§3.2), so a fresh name must collide with neither a live workspace nor a live claim.

nav

The altitude-0 navigator view-models (DESIGN §11): the workspace tab bar (tabs) and the focused workspace’s conversation list (convs), plus the shared row/key types. No egui and no git/ui_state dependency: the caller (AppModel) derives the input facts from the snapshot map + attention + the §3.5 join, and the shell renders the outputs. Every branch is table-tested with plain data.

opslog

ops.jsonl: the durable action-outcome log (DESIGN §4.2, §15 Y15).

projects

Project (balls-clone) enumeration and nested-delivery detection (DESIGN §5.1 #1, §15 Y14).

shell

Interaction glue for the conversation-first shell (DESIGN §11 three altitudes): the top bar (attention strip + workspace tab bar), the conversation-list side panel (navigator), the selected-conversation center (workspace), the bottom composer + activity accessory, and the short-verb dispatch (input bar, §8.2).

start

The composite “start a conversation” verb (DESIGN §3.4, §8.1, §15 M6 Z3): a pure planner + a step executor, the one flow that turns Enter-in-a-box into a running lernie loop.

state

The crate’s lock chokepoint (Bootstrap rule 7): the cross-thread shared-mutable-state locks live in this one file, so the whole-crate shared-state inventory is auditable in one place. rules/locks-outside-state.yml enforces the confinement; the only carve-outs are test scaffolding and one documented exception, git_tree::probe_cache — the macOS TTL cache’s Mutex is single-thread interior mutability local to the probe stack, not cross-thread shared state, and a generic decorator folded in here would break llvm-cov’s per-line coverage (see that module’s doc). Two residents:

steps_view

Per-agent steps inspector view-model (DESIGN §11 Altitude-2 Steps tab; §5.1 #13; §15 Y13). Milestone M2’s last piece: browse every byte.

theme

The congeries palette — yog’s single colour authority (DESIGN §11).

transcript

Transcript view-model (DESIGN §5.1 #12, §11 Altitude-2 Transcript tab).

ui_state

The ui.json document (DESIGN §4.1, §15 Y8): yog’s one converging UI-state artifact — the four attention seen watermarks, pinned, collapsed, show_internal, identity_last_used.

watch

Watch registry + repaint bridge (DESIGN §7.2, §15 Y6).

world

The nested world yog composes under its own data root (DESIGN §16.2) — the pure ambient Env → world Env composition plus the <yog-data-root>/world/ subtree layout. yog reads the ambient environment once, anchors on $XDG_DATA_HOME/yog, and layers a fixed two-var override set over that snapshot; the composed result is itself an Env, so every §5.1 fold re-derives the nested location through it (balls state, lernie home, and yog’s own ui.json/ops.jsonl) while the brazen config, credential, and model-cache folds stay ambient (§16.2). This module is the pure composition layer only: it neither materializes the subtree nor wires the world into any spawn (W2/W3).

xdg

The one home for every filesystem-path derivation in yog (DESIGN §15 Y2, §5.1). Balls, lernie, brazen and yog all locate their state through XDG (or, for brazen’s credentials/cache, per-OS) folds; this module reproduces each fold once, over an injected Env snapshot.