bar

name	bar
description	Fix or extend the i3status-rust status bar and its status-count poller — add/reorder blocks, tune the count pills and their thresholds, debug the bar-status-poll timer and its dunst toasts. Use for: the status/i3 bar, a bar block/icon/threshold, the alert/mail/clawgate/civitai pills, bar-status-poll, ~/.cache/bar-status, the DND/rig-control bar buttons, "the bar is wrong/stale/red".

i3status-rust status bar — operations

The workbench + laptop status bar. Migrated i3blocks (/etc/nixos) → i3status-rust under home-manager (PR #74). All bar config, block scripts, and the poller live in the devrc repo and deploy via home-manager. Point-in-time history: memory i3-bar-i3status-rust-migration + devrc/claudedocs/handoff-agent-facing-workbench-2026-07-11.md.

AirVPN host tunnel + its pill → ~/.claude/skills/bar/reference/airvpn.md (source ~/workspace/devrc/claude/skills/bar/reference/airvpn.md): the killswitch design, the 🔴 mandatory re-test protocol, apply/re-arm/bail procedures. Read it before touching anything AirVPN.

Modernization stance (standing rule — applies whenever you touch this setup)

When editing the bar / i3 / any NixOS or home-manager config here, prefer the current best-practice idiom and opportunistically modernize outdated portions you encounter — don't just pattern-match the old code. Examples: retire a bespoke i3blocks-era script when i3status-rust has a native block; use the maintained programs.*/nix/pkgs idiom over a hand-rolled one; drop /etc/nixos remnants in favour of home-manager. Guardrail (from RULES): reversibility-aware — a drop-in modernization goes ahead, but a risky/broad rewrite gets flagged before acting ("here's the outdated bit, here's the modern replacement, blast radius X — your call"). Leave the setup a little more modern than you found it; never more legacy.

Where everything lives (all in ~/workspace/devrc, $DEVRC)

Thing	Path
Bar definition (blocks, theme, icons, thresholds)	nix/graphical.nix (programs.i3status-rust.bars.top)
i3 WM config (binds, bar buttons)	nix/i3/config.nix → ~/.config/i3/config
Decoupled poller (workbench systemd-user timer)	scripts/bar-status-poll
Instant block scripts (read cache, never network)	scripts/i3status-{clawgate,mail,alerts,civitai,dnd,media,airvpn,telemetry}
🔴 ONE definition of "this cache is too old"	scripts/bar_freshness.py — a CO-LOCATED SIBLING module every cache-backed block (and the poller) loads by explicit path. Needs its OWN home.file in graphical.nix (it is deployed beside the blocks); a missing symlink turns every count pill into ? on a healthy host — true only because the load is DEFERRED (except: fresh = None, failing at use inside __main__), which is what makes the ? reachable. Pinned by test_every_block_that_loads_the_sibling_is_DEPLOYED_beside_it + test_a_block_that_cannot_load_the_SIBLING_renders_the_VISIBLE_pill
Poller output (per-source JSON)	~/.cache/bar-status/*.json (0600)
Generated bar TOML + symlinked scripts	~/.config/i3status-rust/
RETIRED — never edit	/etc/nixos/{i3config,i3blocks}.nix, /etc/nixos/i3blocks-scripts (except airvpn-sudo + airvpn-updown, which MUST stay there for the NOPASSWD sudoers rule + the tunnel PostUp/PostDown; the old Mullvad vpn-sudo is dead)

Architecture (why it's shaped this way — the CALM bar)

• Blocks render local files only. The bar NEVER queries a remote per tick. Anything remote (alert counts, mail, clawgate tasks) is fetched out-of-band by bar-status-poll (~45s systemd-user timer, workbench-only) which writes tiny JSON to ~/.cache/bar-status/ — so a slow/down source can never hang or break the bar.
• 🔴 A COUNT NEVER TRAVELS WITHOUT ITS DISCRIMINANT — every cache-backed block, not just clawgate. "0 measured" and "not measured" render differently everywhere. Four shapes, one answer (bar_freshness.unmeasured): the file is missing/corrupt, the poller wrote a stale/error marker, ts is absent or non-integral, or ts is older than MAX_CACHE_AGE_SECS (600s, from the unit: 45s re-arm + 60s systemd AccuracyUSec + 90s TimeoutStartSec = 195s worst healthy gap, ×3). Grammar, one system across all blocks: a TRAILING ? = "this is not a current measurement", and it composes with whatever the reading still says (24!2?, tlm 3?). Hide-at-zero applies to the MEASURED zero ONLY. 🔴 Fixture rule: ts must be an INT — int_or_none refuses to coerce, so a float time.time() short-circuits every case to ? and looks exactly like a code bug. Per block: mail → ? / 5?; alerts → 󰀪 ? / 󰀪 39?; civitai → 󰀪 civ ? / 󰀪 civ 146? (label kept, so you can tell WHICH prod went unreadable); telemetry → tlm ? / tlm N?; clawgate → ? / !N?; media → qBit? / CA ⚠ firewalled?; airvpn → soft-yellow icon (its discriminant is COLOUR alone — off and unknown are both an icon with empty text) / LEAK?. Every __main__ last-resort except prints the block's pill too, literal-built so it cannot depend on what just failed.

Block ↔ signal ↔ threshold map (workbench)

Block	Script	signal	--red-above	Notes
homelab alerts	i3status-alerts	13	34 (#97)	homelab backlog is noise; bumped 30→34 when it drifted to ~24-27
civitai prod alerts	i3status-civitai	14	340	CLIENT prod; its own kubeconfig. Red is CORRECT when real — do NOT tune it away. (disk-space growth, 2026-07). 🔴 left-click + its toast open the client Grafana via scripts/bar-url --open civitai_grafana, NOT a URL literal — this repo is PUBLIC, so the host lives in ~/.config/bar/urls.env (0600, untracked, civitai_grafana=<url>). A host missing that key gets bar-url exit 3 naming the key + file; the button is never silently dead. Gated by scripts/tests/test_no_client_hostnames.py
mail	i3status-mail	12	0 (0→>0)	open mail_actions rows
clawgate	i3status-clawgate	11	0 (0→>0)	Tasks needing the operator = {open, ready_for_review} plus in_progress tasks whose agent looks dead. 🔴 The predicate is NOT in the poller — it is scripts/lib/clawgate_tasks.py, shared with session-manager, and re-spelling it anywhere fails scripts/tests/test_clawgate_predicate_single_source.py. Excluding in_progress outright is what hid a four-hour-dead dispatch on all three surfaces at once. Stuck = no agent / agent error / never kicked off / silent >15m (AGENT_IDLE_THRESHOLD_SECS) / no readable timestamp; the payload always ships agent_idle_secs beside the flag. Fetch is ?summary=1 (~27x smaller). Changing the shared module requires the X-Restart-Triggers entry in graphical.nix to re-arm the unit — without a restart the pill keeps the OLD meaning across a green switch. 🔴 Text grammar: 22 = count; 22!2 = 2 of them STUCK (Critical); a TRAILING = "this is not a current measurement". So alone = the board could not be read at all (missing/corrupt// cache, or one the poller stopped refreshing — older than , 600s vs the worst healthy gap: 45 + systemd's default 60 + 90) and = 2 stuck as of the last readable poll, still Critical. 🔴 A measurement outage never makes the pill QUIETER, and that needed BOTH halves: the block's gate covers a frozen cache, and copies the last known onto a / marker — without it a clawgate outage overwrote /Critical with a bare /Warning. The carry is not a ratchet (a recovered poll's own reading wins outright) and never reaches the toast gate. : a stuck dispatch is announced nowhere else that cannot be dismissed (the toast is one-shot and dies with dunst, the notif badge clears on , is on-demand), so an unreadable board must not look like an empty one

Bars differ by host (isLaptop in graphical.nix): laptop gets batteryBlock and omits GPU

• all count blocks + poller (nebula-only, no LAN path to homelab endpoints); workbench gets GPU (RTX 5080), the count blocks, the state-driven mediaBlock (qBit/AirVPN), claudeRunsBlock (▦ — live Claude-in-tmux count, indicator only: its click launched the retired agent-ops TUI and went with it), rigcontrolBlock (⚙). loadBlock is one of the few CUSTOM blocks on both hosts (/proc/loadavg needs no poller).

🔴 Two ways a new block ships dead, both now gated. (a) A block and its home.file must be gated the SAME way in BOTH places — an ungated block whose script is mkIf (!isLaptop) renders a custom block whose command does not exist (test_bar_status.py::test_every_custom_block_script_is_DEPLOYED_UNDER_A_COMPATIBLE_GATE; it also catches a script that was never git added — but only in the nix tier, where a flake omits the untracked file so it is simply absent. A bare local pytest run sees it on disk and passes). (b) A block's icon must be a real i3status-rust icon key, not an XDG desktop-icon name — an unknown one does not degrade to a missing glyph, it renders the whole pill as a red Failed to render full text (test_every_block_ICON_is_a_REAL_i3status_rust_icon_key).

Deploy / apply

• Single host (validate an edit end-to-end): home-manager switch --flake ~/workspace/devrc --impure. This DOES restart the poller on a script change (X-Restart-Triggers).
• Both hosts (after merge): scripts/ship.sh.
• 🔴 A switch does NOT restart i3status-rs — and RENAMING or REMOVING a block script breaks the pill until you restart i3 by hand. The only X-Restart-Triggers in graphical.nix is the poller's; the bar process holds the config it parsed at startup, including each block's absolute command path, while the switch deletes the old symlink the moment the path changes. The pill then runs a path that no longer exists, on a host that reports a perfectly successful deploy. So for a block rename/removal/command change: merge → ship.sh → i3-msg restart → re-check the pill renders. i3-msg restart is right here (it re-execs i3, which re-spawns i3status-rs, and keeps the session); the display-manager caveat below applies only to changing WHICH i3 config file is authoritative. A threshold/format edit inside an existing script needs no restart — the block re-runs the same path on its next interval. Applies to this PR: i3status-agent-ops → i3status-claude-runs.
• 🔴 ADDING a block is in that same restart class — and "did it restart?" needs a real check, not an assumption. The bar holds the block LIST it parsed at startup, so a new block is simply absent until i3-msg restart, on a host reporting a fully successful deploy. Measured 2026-08-20 (the load pill): the live bar predated its own config by 26 hours. The check is the bar's start time against the config's mtime — but 🔴 pgrep -x i3status-rs finds NOTHING while it is running: comm is .i3status-rs-wr, a nix wrapper. Match on /bin/i3status-rs, and take the process whose PARENT is i3bar — orphaned copies from old sessions linger with ppid 1 and are not the bar. (pgrep -f additionally matches the checking shell itself.)

  ps -eo pid,ppid,lstart,comm,args | grep i3status-rs | grep -v grep
   -c  ~/.config/i3status-rust/config-top.toml   
  

  🔴 — its correct state is invisible. Run the block's own line from the config, then force the visible states with explicit thresholds; that is the only honest render check.

🔴 Cutover gotcha (the one that bit us)

A change that alters which i3 config file is authoritative (e.g. the /etc/nixos→HM cutover) must finish with sudo systemctl restart display-manager, NOT i3-msg restart — a running i3 has -c /etc/i3/config baked into argv, so deleting that file + in-place restart = dead session. Routine HM block/threshold edits don't need this; only config-source cutovers do.

Other gotchas

• Icon overrides need the TABLE form. settings.icons = { icons = "material-nf"; overrides.gpu = "…"; }. The icons = "…" string shortcut + an [icons.overrides] table conflict and silently drop ALL icons to text (#81). GPU is overridden to nf-md-expansion_card (material-nf maps gpu→a monitor glyph).
• Poller runs from the working tree, not a nix-store copy, so it can resolve sibling scripts/mail-actions/_db.py (loaded by explicit path — do NOT add mail-actions/ to sys.path, its llm.py shadows things).
• fuzzyclaw is UNTRUSTED as a data source (~/.tmux/tasks/*.json is stale) — nothing bar-related should depend on it.
• Poller holds standing read-only port-forwards into TWO prod clusters (homelab + civitai) every ~45s — bounded (TimeoutStartSec=90), fail-safe, cgroup-killed. Accepted.

Debugging

# is the poller healthy?
systemctl --user status bar-status-poll.timer bar-status-poll.service
journalctl --user -u bar-status-poll -n 50 --no-pager
# what does each source currently say?
for f in ~/.cache/bar-status/*.json; do echo "== $f"; cat "$f"; echo; done
# force a poll now (workbench)
systemctl --user start bar-status-poll.service
# run the poller by hand (see errors live)
python3 ~/workspace/devrc/scripts/bar-status-poll
# drive the write+signal path offline with fixtures (no live endpoint).
# SAFE by default: writes the real cache files, but fires NO toasts and does not
# touch the rising-edge latches. Add --toast only if you mean to exercise those.
~/workspace/devrc/scripts/bar-status-poll --mock-alerts alerts.json --mock-mail 3
# unit tests for the pure parse/edge functions
python3 -m pytest ~/workspace/devrc/scripts/tests/test_bar_status.py
# manually refresh one block (N = signal)
pkill -RTMIN+13 i3status-rs

• Block showing ? (or qBit? / a soft-yellow airvpn icon): it could not MEASURE. stat the cache first — if ts is more than ~10 min old the POLLER is dead (systemctl --user status bar-status-poll.timer), and every other pill will be ? too. If ts is fresh, read state/detail: "stale" means that ONE source (kubeconfig/port-forward/creds) failed — run the poller by hand to see the exception. A single ? on an otherwise normal bar is a source outage; a bar full of them is the poller.
• Block empty/invisible: that now means MEASURED and quiet, for every cache-backed block. If a pill is invisible while you believe the source is down, the bug is in the block, not the source.
• Block never refreshes on change: the block's signal in graphical.nix ≠ SIGNALS in bar-status-poll.
• All icons show as text: the [icons.overrides] / icons= shortcut conflict (see gotcha).
• Red pill you think is noise: confirm it's actually noise before bumping --red-above — homelab is noise, civitai is not. Tune the threshold in BOTH graphical.nix (--red-above) AND the poller toast env (or they drift), never suppress a real signal.

Common tasks

• Add a block: define fooBlock in graphical.nix, add it to the blocks list (order = left→right, gate with lib.optional* for host scoping), symlink any script via home.file, git add the script, switch. 🔴 If it reads a poller cache it MUST use bar_freshness.unmeasured (copy the _load_freshness bootstrap from any block) and render a visible ?-grammar pill — add it to ALL_BLOCKS/BLOCK_SCRIPTS/UNMEASURED_PILL in scripts/tests/test_bar_status.py, which are pinned two-way against each other.
• Change a threshold: edit the block's --red-above N in graphical.nix and the matching *_TOAST_ABOVE env in the poller's _toast_specs() so the toast fires on the same line; switch.
• New remote count source: add a parse_*/fetch_* to bar-status-poll, a SIGNALS entry, a fixture-tested parser, an instant block script that reads the cache, and the block in graphical.nix with the matching signal.