Nomarchy/agent/BACKLOG.md

# Backlog — the prioritized task queue

**This is the only executable work list for agents.** Product themes and
v1.0 intent live in [`docs/VISION.md`](../docs/VISION.md); design history
in [`docs/ROADMAP.md`](../docs/ROADMAP.md); map in
[`docs/README.md`](../docs/README.md) and [`agent/README.md`](README.md).

**Rules:**
- Agents take the topmost actionable item (see LOOP.md). Finished items
  are **deleted** here — the journal + git log are the record; durable
  design notes get a ✓-entry in docs/ROADMAP.md (and/or a note in VISION)
  if worth keeping.
- Item numbers are **stable IDs** — never renumbered or reused. A gap in
  the sequence means shipped (or dropped) work; new items take the next
  free number regardless of tier.
- Tags: `[blocked:hw]` needs real hardware (see HARDWARE-QUEUE.md) ·
  `[human]` needs Bernardo · `[stuck]` two failed attempts, needs help ·
  `[big]` must be split before starting.
- Agents may append to **PROPOSED** and **Decisions** freely (include
  `VISION § …` or `ROADMAP § …` when relevant); only Bernardo moves items
  *out* of PROPOSED into the tiers.

---

## NOW

### Live ISO / install hardware findings — Acer Aspire M5-481T + Dell XPS 9350

Bernardo, real installs 2026-07-13–14 (photos of the install end screens and
post-boot sessions). Preserve separation: the installer bake failure and the
flake pin are different root causes even when they show up on the same machine.
(Terminal / Ghostty-on-Acer → shipped as Kitty-only, #95.)

### 127. `[blocked:hw]` The idle brick's CAUSE — reopened; the fix shipped, the diagnosis did not

**Restored 2026-07-16, same day it was deleted.** It was deleted as shipped on
the strength of a diagnosis that was retracted hours later. The **fix** is real,
proven and stays (`misc:{key_press,mouse_move}_enables_dpms`, a2151f4): the wake
path had a genuine single point of failure — hypridle's `on-resume` was the only
caller of `dpms on` in the session — and it is gone. Verified end-to-end on the
incident hardware, including a real 10-min idle blanking and waking clamshell
(`done enabled=1 first=DP-2`, 19:32). **None of that explains the brick.**

**What the incident was:** docked clamshell, idle → black, external keyboard and
mouse woke nothing, unplugging the external did not light the panel, Caps Lock
LED still toggled (machine alive), and **Ctrl+Alt+F3 gave no usable TTY**.

**What has been ruled OUT (all on hardware, 2026-07-16):**
- *DPMS-off is not the trigger.* With hypridle driving the blank, input wakes it
  in every geometry — undocked lid-open, clamshell-docked on the sole live
  output, docked with both outputs live. The clamshell skip was reverted on this.
- *The hypridle deadlock is not the trigger.* This was the published cause and it
  was wrong: at the incident (before 12:51:34 on Jul 15) hypridle had **no
  disconnect at all** and had been healthy since Jul 14 13:09. The "19 in 11
  days" rate that made the theory look strong was normal-teardown noise
  (see #146). It should have fired `on-resume`.
- *The #100 undock latch* explains symptom 2 (unplugging not restoring the panel)
  and is fixed (ff5017e) — but not the blackout itself.

**The lead is Ctrl+Alt+F3, and it always was.** Neither DPMS-off nor a dead
hypridle can break VT switching; a wedged compositor still holding DRM master
can, and it would explain the black screen *and* the dead TTY in one stroke.
Every theory so far has been about the wake path — i.e. about a *symptom of the
screen being black* — and none of them touch the TTY. Start there instead.
Bernardo does not recall whether the machine had been relogged-in between Jul 14
13:09 and the incident; that would say whether hypridle was ever a suspect.

**Note the fix makes this much harder to reproduce** (input now wakes the screen
compositor-side), which is a good trade but means a repro may need the options
temporarily off. It has not recurred since.

## NEXT

### 143. Rofi keeps the selected *row number* when the search changes, so the highlight lands on an unrelated entry

Bernardo 2026-07-16, and his repro is exact: open the app menu, type `ca`, move
the selection two items right (onto ChatGPT), press backspace once (query is
now `c`). The list re-expands — first entry is now Slack — but the highlight
stays on the **third row**, which is now GHex, an app that has nothing to do
with what he typed. Enter at that moment launches the wrong thing.

**Cause — upstream rofi (2.0.0, `source/widgets/listview.c`), not our config.**
A filter change ends in `listview_set_num_elements()`, which does not reset the
selection; it re-asserts the old one:

```c
lv->req_elements = rows;
listview_set_selected(lv, lv->selected);   /* the *previous* index */
```

and `listview_set_selected()` only clamps it to the new bounds:

```c
lv->selected = MIN(selected, lv->req_elements - 1);
```

So what is preserved is the **row number**, not the entry — nothing checks that
row 2 still holds the thing that was selected, or that it matches the query at
all. Typing *more* hides this (the list shrinks, the clamp usually drags the
highlight along); **backspacing exposes it**, because the list grows back
underneath a stationary index. There is no option for it: `-dump-config` has
nothing about selection-on-refilter, and `auto-select` is a different feature
(it fires only when exactly one row survives).

**One correction to the report:** it is not the app menu. `listview` is the
widget behind **every** rofi surface we ship, so our text menus (Recovery,
System, Preferences…) do the same. It is merely far more visible in drun, where
the list is long and — because we set `sort = true` — reorders on every
keystroke, so a stationary index points somewhere new each time. In a short
text menu you would probably see it and correct without noticing why.

**Reported upstream 2026-07-16: https://github.com/davatorium/rofi/issues/2317**
(open, filed as `bemagri`, with the 2.0.0 line numbers and the observation that
`rofi_view_set_selected_line` already maps a stable id through `line_map` — so
the fix reuses an existing primitive rather than inventing one). No patch was
sent: the scoping call is the maintainer's, since keeping the index across a
*reload* looks deliberate (#1064 asked for exactly that, and got it in 1.7.4).
No duplicate found before filing.

**Decided 2026-07-16 (Bernardo): wait for upstream. Do not carry a patch.** The
overlay option was real but priced badly — our derivations are in no binary
cache, so a patched rofi means **every machine compiles rofi from source**, on
every lock bump, to fix a highlight. That is a permanent, distro-wide install
cost for an annoyance with a free workaround (glance before you press Enter).
**This item is now a watch, not work:** the only thing to do is check
rofi#2317, and take the fix when a release carries it. If it is still open at
the next lock bump, that is fine — nothing here rots meanwhile.
*Last checked 2026-07-17: open, no maintainer response, no linked PR.*

### 134. `unstable.<pkg>` in the downstream — decided, build it

**Decided 2026-07-17 (Bernardo): Nomarchy carries the channel.** Add a
`nixpkgs-unstable` input to the distro flake and expose it through
`overlays.default` as an `unstable` attrset, so
`home.packages = [ unstable.lmstudio ];` just works — downstream stays one
locked input and `nomarchy-pull` still moves it. Scope is **home packages
only**; no `unstable.*` surface in system.nix, no `stable.` synonym for now.
The input rides in the eval unconditionally (an unused input still locks +
fetches — accepted). Original diagnosis stands: `mkFlake` has no overlay
seam and `homeConfigurations` uses mkFlake's own `pkgs`, so nothing short of
the distro carrying the channel keeps the user out of `fetchTarball` pinning.

Costs accepted with the ruling, to be stated in docs, not hidden: lock bumps
now move two channels (VERIFICATION §5 full-checklist applies to both); a
user who reaches for `unstable.` pays a second stdenv/glibc in their closure
(measured: lmstudio shares only ~690 of ~3.7–4k paths); and nothing upstream
tests pinned-Nomarchy + unstable-app together — the README needs an explicit
"you own this combination" paragraph. Ship with a commented example in
`templates/downstream/home.nix` (opt-in convention) and a README table note.
Pass = flake check green + a V1 build of the template HM closure with one
`unstable.` package enabled. Related: #133.

## LATER

- **Wallpapers artifact split** (ROADMAP § Faster switches — decided,
  deferred): pinned `Nomarchy-wallpapers` input so a state write stops
  re-copying 86 MB. Follow-on: pre-built theme variants if switches are
  still slow after.
- **Installer round 2** (ROADMAP § Installer): multi-disk BTRFS RAID,
  impermanence, BIOS/legacy boot.
- **Boot-from-snapshot**: a systemd-boot equivalent of grub-btrfs.
- **MIPI/IPU software-ISP camera** support (no-UVC machines).
- **NixOS release bump → v2** `[human]`: deliberate, hand-edited, never
  automated; the previous attempt was discarded (2026-06-22) over a
  Hyprland OOM blocker — see MEMORY.md before retrying.

## FUTURE (decided deferred — not the agent queue head)

Work we **intend** someday but explicitly **not** NEXT. Agents do not
pick these unless Bernardo promotes one into NEXT/NOW.

### 20. KVM runner → VM suite in CI `[human]`
**Status (2026-07-10):** keep **eval-only** CI on the current Gitea
stack (act_runner in docker-compose on the 4c/4 GB IONOS VPS). Nested
KVM + RAM headroom on that host are a poor fit next to Gitea; full
`checks.*` VMs stay local / promotion-time until a **separate**
KVM-capable machine exists.

**When ready:** register a second runner (host-mode nix + `/dev/kvm`,
label `nix-kvm` — not the existing docker eval runner), then uncomment
the `vm-checks` job in `.gitea/workflows/check.yml` (`runs-on: nix-kvm`,
`nix flake check` + toplevel/HM builds). Do not enable the job until
that label is online (Gitea queues forever otherwise).

### Formatter — adopt later `[human]`
**Intent:** add a Nix formatter (likely `nixfmt-rfc-style`) in a dedicated
pass: reformat the tree once, document in CONVENTIONS, optional CI
check. **Not** the queue head — no drive-by reformats until that pass.

## PROPOSED (agent suggestions — await human triage)

*Agents: append here with a one-paragraph pitch (what/why/cost). Do not
implement. Bernardo moves accepted items into a tier.*

*Open work only. Shipped exam/A–C items (#47–#63, #14, #52 theme
high-ROI, etc.) live in the journal + ROADMAP — not here.*

### Product / day-2

### 146. `[watch]` hypridle hangs instead of exiting when its compositor vanishes

**Rewritten 2026-07-16, hours after filing: the premise was disproven and almost
nothing survives.** As filed it said hypridle "dies silently ~2×/week — 19 times
in 11 days", with Jul 14 as the clean example ("`CRITICAL` at 13:08:17, then
eleven hours of silence"). Every number there was an artifact of the
measurement. **18 of the 19** `Disconnected from pollfd id 1` lines are
hypridle's noisy goodbye while systemd *deliberately stops it* — each bracketed
by `Stopped hypridle` / `Started hypridle` with a healthy replacement seconds
later. The "eleven hours of silence" came from grepping **one PID**: systemd
logged `Stopped hypridle` 13:08:17, `Started hypridle` 13:09:00, and PID 1678
ran fine all evening where the filter could not see it. Do not re-derive the old
rate; it counts normal shutdown noise.

**What is real, and it is small.** Exactly one genuine zombie has been observed
(2026-07-16 17:25:39), verified by process inspection rather than logs — `ps`
(alive 9h36m), `ss` (48 KB unread on its D-Bus socket, i.e. not reading),
`NRestarts=0` while `systemctl --user is-active` said `active (running)`. That
is upstream hyprwm/hypridle#171 ("Possible deadlock in pollThr when compositor
exits?", open since 2025-09, in neither 0.1.7 nor main) and it is a true bug:
hypridle hangs rather than exits, so `Restart=always` never fires.

**But its impact path is closed, which is why this is `[watch]` and not work.**
The zombie only *persists* if systemd never stops the unit — which needed the
user manager to survive logout, i.e. the stray pre-migration linger removed in
#147. Without linger, logout tears the manager down and takes any zombie with
it; the Jul 14 trace above shows the healthy path (`Stopped` → `Started`) doing
exactly that. A Hyprland death ends the logind session anyway (2026-07-16:
`Session 2 logged out` → greeter), so there is no known route left to a
surviving zombie.

**Do before building anything:** re-measure. Count only disconnects with **no**
`Stopped/Started hypridle` around them and **no** logind session event, and
confirm by `ps`/`ss` that the process is really wedged — not by grepping a PID.
If that count is zero over a few weeks post-linger, **close this unbuilt**. If it
is not, the upstream issue has sat ten months on vaxerski's "that will cause a
segfault no?" and a reproducer would be worth more than a local guard.

### 149. `[watch]` Waybar's exec-once workaround may be defending against nothing post-linger

Spun out of #147 (shipped 2026-07-17) so its loose thread survives the entry:
`modules/home/hyprland.nix` runs Waybar from `exec-once` rather than a systemd
unit because the unit "raced Hyprland's IPC on a **warm** relogin ... never
retried, so the bar vanished" — and a warm relogin is exactly what linger
created. With the stray linger removed (2026-07-16) that workaround may be
defending against nothing. Do not rip it out on this note alone: it works, and
the claim needs a real relogin without linger to test (V3 — the same relogin
that verifies #148's watcher fix would answer it).

### 120. A netinstall ISO, next to the fat offline one

**Deferred to PROPOSED 2026-07-16 (Bernardo): not now.** Nothing below is
stale — the measurements stand and the decision it needs is unchanged. It sits
here because it is the only genuinely large item left, and because the gotcha
at the bottom (no binary cache for our own derivations) probably makes a
cachix the real first step, not the ISO.

Bernardo 2026-07-14, after seeing the measured size: **keep the current ISO
exactly as it is** — the guaranteed offline install is the feature it buys —
and ship a **much lighter netinstall variant alongside it**. Two products, one
distro: "works on a plane" and "8 GiB is absurd to download" are both true, and
a second target settles them without compromising either.

**Measured facts (2026-07-14), so this starts from numbers, not vibes.**
*(These stand as measured: #121 would have cut ~0.67 GiB of duplicate chromium
from them, but it was **reverted** — decided against, ROADMAP § one chromium,
not two. If a netinstall ships, revisit it: the duplicate is worth ~195 MiB of
**download**, which is this item's whole currency, even though it is worth
almost nothing on disk or on the ISO.)*

> **Read this before using the numbers below.** They are **closure arithmetic**,
> and #121 proved the hard way that closure size is neither disk size nor image
> size: removing a 687 MiB path shrank the ISO by **8 KiB**, because
> **mksquashfs dedupes duplicate files** and **`auto-optimise-store` hardlinks**
> them on disk. So a change that looks like it sheds gigabytes of closure can
> shed nothing off the actual image. **Measure the artifact — build the ISO and
> `stat` it.** The corollary cuts the other way and is the good news for this
> item: what dedupe cannot help is the **wire**, so a netinstall's download is
> the one figure closure/NAR size predicts honestly (`nix path-info --store
> https://cache.nixos.org --json` gives the real `downloadSize`).
- Current ISO **8.078 GiB** compressed; **18.03 GiB** of store uncompressed
  (`zstd -19`, 2.23:1 — compression is already near-max, not the lever).
- The offline pin (`system.extraDependencies`, 60 roots: a representative
  installed system + the template HM closure + all flake inputs) is **4.02 GiB
  uncompressed of that — only ~22%**. Dropping it entirely still leaves a
  **~13.3 GiB** desktop → roughly **6 GiB** compressed at the same ratio.
  **So "no pin" alone is NOT the lighter ISO** — this is the trap to avoid.
- The desktop's own top weights: libreoffice 1457 MiB, initrd 1369,
  linux-firmware 770, chromium 1391 (two builds — #121, left in), llvm-lib 540,
  bibata-cursors 322, mesa 264, mbrola-voices 259, nerd-fonts ~420 combined.
  Note what that list implies: no single lever gets a desktop ISO under ~4 GB —
  which is the case for (b) below.

**So the real decision is what a netinstall ISO IS**, and it should be settled
first (`[human]`): (a) the full try-before-install desktop minus the pin
(~6.3 GiB — barely lighter, probably not worth a second target); (b) a **TUI
installer only, no desktop** (~1 GiB, the actual "netinstall" in the Debian
sense) which drops "try before install" from that medium — the fat ISO still
offers it; (c) a middle desktop (no libreoffice/chromium — but note #103 just
put those there deliberately, and a *demo* desktop that can't browse is the
bug #103 fixed).

**The gotcha that decides feasibility:** without the pin, a netinstall target
fetches from `cache.nixos.org` for stock nixpkgs paths — but **Nomarchy's own
derivations are in no binary cache**, so they would build *from source on the
user's machine* during install. That is the same failure `tools/vm/gap-analysis.py`
exists to diagnose (and #113 is a live instance of). So this item probably
depends on a public binary cache (cachix) for the flake's own outputs, or it
trades an 8 GiB download for a 40-minute install. Establish that before
building the target.

Pass = a second, documented ISO target that is *substantially* smaller (state
the measured number, both ISOs built from one tree), installs successfully with
a network in a QEMU run, says clearly at boot that it needs one, and leaves the
offline ISO's behaviour untouched (`checks.*` for the offline path stay green).
- **NVIDIA first-class options** — **deferred past v1** (Bernardo
  2026-07-10). Keep #59 commented install guidance; no
  `nomarchy.hardware.nvidia.*` until a hybrid maintainer + queue.

_(#80–#83 + #85–#88 shipped 2026-07-11. Theme A day-2 + neon-glass finish
  shipped — VISION ✓. Dock/hibernate V3 → HARDWARE-QUEUE. Parallel
  fingerprint-or-password shipped 2026-07-12 (Bernardo promoted it live;
  `fingerprint.parallel`, pam-fprint-grosshack) — reader V3 →
  HARDWARE-QUEUE.)_

### v1.0 pointer

See **VISION**. Open PROPOSED: NVIDIA deferred past v1; IR portal (b)/(c)
need T14s (HARDWARE-QUEUE § T14s). Standing calls: browser = Chromium;
power = PPD. (Post-install hardware hints shipped 2026-07-17.)

## Decisions `[human]`

Open calls only Bernardo can make; agents add options/evidence but never
decide. **Resolved** entries stay for history; agents treat them as closed.

### Resolved (2026-07-17)

- **#120 netinstall** — stays deferred in PROPOSED (re-affirmed). When it
  is promoted, a public binary cache (cachix) is the likely first step.
- **#134 unstable packages** — build it: Nomarchy carries the
  `nixpkgs-unstable` input, `unstable.*` via the overlay, home-scope only.
  Moved to NEXT with the full decided shape.
- **#114 greeter layouts** — document only: a VT has one keymap by design,
  so tuigreet cannot honour per-device layouts. Shipped as the README
  "Greeter keyboard layout" note + a RECOVERY.md pointer; entry deleted.

### Resolved (2026-07-10)

- **Docs site vs Markdown-in-repo** — **markdown in-repo for now**
  (`docs/`, README). A rendered docs site is FUTURE if wanted.
- **Default browser** — **ship Chromium** in
  `templates/downstream/home.nix`; mime → `chromium-browser.desktop`.
  Opt out: delete the line / override mime.
- **Default power backend** — **keep PPD** (`nomarchy.system.power.backend`
  default). TLP remains the one-line opt-in. Rationale: stability + live
  profile API for menu/Waybar; Omarchy’s TLP experiment reverted.

### Resolved (2026-07-10, more)

- **Formatter adoption** — **yes, but not now.** Tracked as FUTURE
  (below). Nix-source style only (`nixfmt-rfc-style` or similar); one
  bulk reformat + CI/check when promoted. Until then: hand-aligned
  style per CONVENTIONS.

- **Hibernation** — **want by default** (product intent). Needs a
  disk-backed swap (file or partition) sized for resume; not zram alone.
  **Shipped as #76**; V3 power-cycle PASSED on TuringMachine 2026-07-12
  (ROADMAP § Hibernation + zram by default).

### Resolved (2026-07-10, #76 design)

- **Swap sizing** — **exactly RAM** (installer default, unchanged). Hibernate
  image ≤ RAM; zram takes day-to-day paging. **`swapSize=0`** stays no-swap.
- **Migration** — **docs runbook** (`docs/MIGRATION.md`), not a tool.
- **No-swap Hibernate** — keep the menu row; **notify on failure**.