# Post-0.1.0 usability backlog Status: **open, expandable by design.** This document is not a fixed release plan. It collects items found by actually using qtmaildir after 0.1.0, and it grows as more turn up. Nothing here is scheduled; picking what ships in a given release is a separate decision. Source: usage notes taken while running the app, 2026-08-03. **Numbers here are this document's own.** The user's own notes were numbered independently and the two sequences drifted apart once items were split: what those notes called 12 is item 13 here, and item 14 here (the tag column) was never in them at all. Items 15 to 17 come from a later pass over the same notes. Cite these numbers, not the notes', and do not renumber to reconcile. **The notes are the upstream source and they keep growing.** The user adds to them while using the app, so this document goes stale on its own. Items 28 to 35 came from one such pass on 2026-08-04 and included two defects that had gone unrecorded here for a while. Items 39 to 45 came from the 2026-08-05 pass, which found one more defect (41, a message body silently dropped by the MIME walk) and one item that cannot be planned at all until the user says where the thing it manages lives (44). Compare the two at the start of a session; the procedure is in `CLAUDE.md`. Numbering is stable. New items append with the next free number and never renumber, so a note referring to "item 7" keeps meaning the same thing. An item that is dropped stays in the table marked `dropped` with a one-line reason. ## Theme 0.1.0 was built to a spec written by someone who lives in neomutt. The result is a keyboard-driven reader with almost no visible affordances. The notes below are, with few exceptions, one complaint restated in several forms: **the app does not tell the user what it can do, and it does not remember what the user told it.** Two clusters follow from that: - **Persistence.** Splitter position, font size, window geometry, and the account selection all reset on restart. Each is small on its own and aggravating every single launch. - **Discoverability.** Shortcuts are the only route to most actions, and there is no menu bar, no toolbar, and no way to see the key bindings from inside the app. Both clusters are cheap to fix. Neither was an oversight in design so much as a consequence of specifying the app as "a GUI counterpart to neomutt" and then taking that too literally. ## Status table | # | Item | Cluster | Size | Status | |---|------|---------|------|--------| | 1 | Splitter/column widths do not survive restart | persistence | S | **done** | | 2 | No way to see full message details (From/To/Cc/Subject) | information | M | **done** | | 3 | Too few clickable affordances, shortcuts are the only route | discoverability | M | **done** | | 4 | Message-pane font size does not survive restart | persistence | S | **done** | | 5 | Thread list is cramped, poor readability | presentation | S | open | | 6 | Opened message stays unread | behavior | S | **done** | | 7 | HTML view should be default for HTML messages | behavior | XS | **done** (already worked) | | 8 | No buttons or menu entries for archive, undo, etc | discoverability | M | **done** | | 9 | No in-app view of configured shortcuts | discoverability | S | **done** | | 10 | Reaching an account's inbox takes two steps | workflow | S | **postponed** (partly done) | | 11 | Icon, `.desktop` file, SlackBuild | packaging | M | **done** | | 13 | No visual feedback that an action stuck | feedback | S | **done** | | 14 | Tag column unreadable, tags need another home | presentation | M | **done** | | 15 | Attachments are parsed but unreachable from the UI | information | M | **done** | | 16 | Delete on an already-deleted thread should undelete | behavior | S | **done** | | 17 | No completion for tags in the query bar | workflow | M | **done** | | 18 | No visual cue that there are unsynced edits | feedback | S | **done** | | 19 | No prompt to sync on exit when edits are pending | behavior | S | **done** | | 20 | Thread view does not match the user's mental model | presentation | ? | open, unspecified | | 21 | Default shortcuts are not sensible enough | discoverability | S | open | | 22 | Translatability audit and i18n wiring | correctness | M | open | | 23 | No way to save a search query from the UI | workflow | M | open | | 24 | No right-click actions on the thread list | discoverability | S | **done** | | 25 | No select-all, and bulk actions are undiscoverable | workflow | S | **done** | | 26 | No way to add or remove an arbitrary tag from the UI | workflow | S | **done** | | 27 | The UI cannot see a sync it did not start | feedback | S | **done** | | 28 | Re-adding `unread` counts 2 unsynced changes, not 0 | correctness | S | **done** | | 29 | Sync button stays enabled during a background sync | feedback | XS | **done** | | 30 | The blank right pane is wasted space | presentation | M | open | | 31 | The quit prompt has no highlighted default button | discoverability | XS | **done** | | 32 | Esc does not blank the right pane | workflow | XS | **done** | | 33 | Status bar messages never expire | feedback | S | **done** | | 34 | No overview of the Maildir itself | information | M | open | | 35 | No refresh of the thread list after a sync | workflow | M | open | | 36 | `test_mainwindow` cannot reach the worker | testing | S | open, on demand | | 37 | The worker stalls on a tag edit made during a background sync | correctness | S | **done** | | 38 | `test_mainwindow` fails when a real sync holds the lock | testing | XS | **done** | | 39 | Thread list cannot be sorted by clicking a column header | workflow | S | open | | 40 | No live filter over the current view | workflow | M | open | | 41 | A message whose HTML body carries a `Content-Id` renders blank | correctness | S | open | | 42 | "Syncing..." says nothing about what is being synced | feedback | S | open | | 43 | No "Mark all read" for the current view | workflow | S | open | | 44 | No way to manage the filters applied at sync time | workflow | ? | open, unspecified | | 45 | Two Sync buttons, and only one of them works properly | correctness | S | **done** | | 46 | `uiStateSurvivesARestart` fails under the offscreen platform | testing | XS | **done** | | 47 | The query bar looks unfinished, and cannot be cleared by mouse | presentation | XS | **done** | | 48 | Removing a tag suggests every tag, not the thread's own | workflow | XS | open | Sizes are rough: XS under an hour, S a sitting, M a session. --- ## 1. Splitter and column widths do not survive restart **Observed:** resizing the thread list pane, or a column inside it, is undone by the next launch. **Cause:** `MainWindow::buildUi()` (`src/mainwindow.cpp:195`) builds the `QSplitter` fresh every launch, sets a stretch factor, and never saves state. `resize(1200, 800)` at `src/mainwindow.cpp:206` hardcodes window size too. There is no `QSettings` window-state read or write anywhere in the class. **Approach:** one `saveState`/`restoreState` pair in `MainWindow`, driven from a `QSettings` object separate from the hand-written config file. - Save on `closeEvent`, restore at the end of `buildUi()`. - Persist: `QMainWindow::saveGeometry()`, `QMainWindow::saveState()`, `QSplitter::saveState()`, `QHeaderView::saveState()` for the thread list. - Restore must be a no-op when the stored blob is absent or rejected, falling back to the current hardcoded defaults. `restoreGeometry()` returns `false` in that case; do not assume it succeeded. **Where the state file goes.** The hand-edited config lives at `~/.config/qtmaildir/qtmaildir.conf` and is the user's to own. Machine-written window blobs must not land in it: a base64 `QByteArray` appearing in a file the user edits by hand is hostile, and rewriting that file on exit risks clobbering comments and formatting QSettings does not preserve. Use a **separate** `QSettings` instance for UI state, at `~/.local/state/qtmaildir/uistate.conf` or the `QStandardPaths` equivalent, and keep `Config` untouched. **Confirmed by the user, 2026-08-03.** This decision covers items 1, 4, and 10 as well. Establish it once, in whichever lands first. **Verification:** manual. Resize both the window and the splitter, restart, confirm both held. Then delete the state file and confirm the app still starts with the 1200x800 default rather than a zero-size window. ### Outcome (done) Built as described. `MainWindow::uiStatePath()` establishes the state file the plan calls for, so items 4 and 10 inherit it. Two things worth recording: - **`QStandardPaths::StateLocation` is the wrong enum here.** It appends both the organization and the application name, and this app sets both to `qtmaildir`, so it yields `~/.local/state/qtmaildir/qtmaildir/`. The path is built from `GenericStateLocation` plus an explicit `/qtmaildir`, the same shape as `Config::defaultPath()`. A test pins the component count. - **`restoreUiState()` runs after `buildMenus()`, not at the end of `buildUi()`** as the plan proposed. `QMainWindow::restoreState()` matches toolbars by object name, so a toolbar that does not exist yet has its position silently dropped. Every restore is guarded on a non-empty blob, so absent state leaves the `buildUi()` defaults rather than producing a zero-size window. ## 2. No way to see full message details **Observed:** From, To, Cc, Subject and the rest are not visible for the selected message. **Cause:** partially true rather than wholly. `MessageView::updateHeader()` (`src/messageview.cpp:219`) shows only the thread subject and a message count. Per-message From and Date *are* rendered inside the HTML body as `.msg-header` (`src/htmlbuilder.cpp:241`), styled at 9pt grey, which is easy to miss and does not include To or Cc at all. **Check before building:** does `MimeParser` already extract To and Cc into the message struct, or does `src/types.h` / `MimeParser`'s output need extending first? If the fields are not parsed, that is the real first task and it is larger than the UI work. **Answered, 2026-08-04: they are already parsed.** `MimeParser::parse()` fills both (`src/mimeparser.cpp:344-345`, into `ParsedMessage::to` and `::cc`, declared at `src/mimeparser.h:105`). The larger task the check warned about does not exist. They are parsed and then **dropped at the renderer**: `HtmlBuilder` interpolates only `from`, `subject` and `date` (`src/htmlbuilder.cpp:216`, `:244-245`), and `to`/`cc` appear nowhere in it, in `messageview.cpp`, or in `mainwindow.cpp`. So this is UI work only, as the item's own two-part approach assumes. **Approach, two parts:** - Widen the persistent header at the top of the message pane to show the selected message's From, To, Cc, Date and Subject. This is the note's stated preference ("should appear on top in right pane"). - Add a shortcut and menu entry for a full raw-header dialog, for the cases the summary omits (Message-Id, List-Id, Received chain). Read-only, selectable text, no rendering. Both, not one: the header widget answers "who is this from" at a glance, the dialog answers "what actually happened to this message". They are different questions. ### Decided (user, 2026-08-04): the header adapts to the item count The pane shows a thread, not a message, so From/To/Cc are per-message while the header is one strip. Rather than pick a message arbitrarily, the header shows only what it can say honestly: - **One message in the thread:** From, To, Cc, Subject. The natural spot, and every field is unambiguous. - **N messages:** Subject and the thread count. Nothing more. - **Everything else** lives in the popup, reached by a **button on the right of the header** plus a keyboard shortcut. **No recipient line on a thread (user, 2026-08-04).** An earlier draft of this decision put To on the thread header too, which forced a choice between the union of recipients and their intersection: once the user has replied, message 1 is To: them and message 2 is To: the other party, so the intersection is frequently empty and the union is really a participants list wearing the wrong label. The user's call was that this is overcomplicating, and it is: the per-message detail is what the popup is for. The thread header therefore keeps showing exactly what it shows today, subject and count (`MessageView::updateHeader()`, `src/messageview.cpp:259`), and only the single-message case gains fields. **Consequence: no address parsing is needed.** `ParsedMessage::to` and `::cc` are raw header strings (`src/mimeparser.h:104-105`), and with no union or dedup to compute they can be displayed as they stand. Splitting them into address lists, which would have needed GMime's `internet_address_list_parse` to survive a display name containing a comma, is not part of this item. **Deferred, not rejected (user, 2026-08-04): a participants line for threads.** The union-of-recipients idea is worth revisiting as its own pass, where it can be designed as a participants list rather than smuggled in under a "To:" label that misdescribes it. It needs the address parsing above, so it is a genuine piece of work rather than a display tweak. Build this item as specced first. **Noted for later, not now:** the user's mental model of the thread view differs from what was built. That is a separate refactor and should not be folded into this item. **Constraint:** header values are untrusted input. The existing header label is `Qt::RichText` (`src/messageview.cpp:104`), so every value must be `toHtmlEscaped()` before interpolation, exactly as `updateHeader()` already does. A `From` display name containing markup must never be able to inject into the label. The raw-header dialog should use `Qt::PlainText` and sidestep the question entirely. ### Outcome (done) Built as decided. `MessageView::updateHeader()` branches on the item count: one message shows From, To and Cc under the subject, several show the subject and the count exactly as before. `showDetailsDialog()` lists every message's Subject, From, To, Cc, Date and Message-Id, numbered when there is more than one, in a read-only `QPlainTextEdit`. A `Details...` button sits to the right of the header, and `message_details` binds it to `Ctrl+Shift+D` (shifted because `Ctrl+D` is delete, and the destructive binding keeps the key it had). - **Rendered and inspected**, not only asserted: both header shapes were grabbed to PNG and looked at. The single-message case shows three rows under the subject, the thread case shows the count and no recipients. - **An empty Cc omits its row** rather than printing a label with nothing after it, which reads as a rendering fault. - **A test caught a latent flaw in an older test.** `attachmentButtonLabels()` identified attachment buttons by excluding the one other button's label, so the new details button was counted as an attachment the moment it existed. It now finds the bar by object name and looks only at its children, which is what it should have done: an exclusion list silently adopts every button added later. **No address parsing was needed**, as the decision above anticipated. The header prints `ParsedMessage::to` and `::cc` as they stand. ## 3, 8, 9. Discoverability: menu bar, toolbar, shortcut reference Grouped because they are one piece of work. Item 3 is the complaint, items 8 and 9 are two of its symptoms. **Observed:** for a GUI app there is almost nothing to click; every action needs a memorized key. Archive and undo have no buttons. There is no way to see the configured bindings without opening a terminal. **Cause:** `MainWindow` has no `menuBar()` and no `QToolBar`. Actions are not `QAction`s at all: `registerActions()` (`src/mainwindow.cpp:209`) fills a `QHash>` consumed by an `eventFilter`. Nothing in that structure can appear in a menu, because a menu needs `QAction` objects. **Approach: convert the action registry to `QAction`s.** This is the core of the work and everything else follows from it. - Each entry becomes a `QAction` with text, an object name matching the current action key, and a shortcut set from `KeyMap`. - `MainWindow::registeredActionNames()` and the `KeyMap::knownActions()` drift test (already noted in `mainwindow.h` as hand-maintained) must keep working. If the conversion lets both lists derive from one source, that test becomes unnecessary, which is a real win. Check whether it can. - The `eventFilter` route may become redundant once shortcuts live on the `QAction`s. Removing it is the goal, but verify: the filter may be handling focus cases (keys while the query line edit has focus) that `QAction` shortcuts resolve differently. Do not delete it on the assumption that `QAction` covers everything. - Menu bar: File (Sync, Quit), Edit (Undo, Redo), Message (Archive, Delete, Spam, Toggle unread, Toggle HTML, Load remote content), View (font size, see item 4), Help (Shortcuts, About). - Toolbar: the frequent subset only. Sync, Archive, Delete, Undo. A toolbar holding every action is as unreadable as no toolbar. - Shortcut reference (item 9): a dialog listing action, description, and current binding, generated from the same `QAction` list. Generated, never hand-written in parallel, or it drifts the way the two action lists already do. **Constraint:** undo must stay unconfirmed. `CLAUDE.md` is explicit that tag mutations get undo instead of confirmation dialogs. Adding menu entries must not smuggle in a "Are you sure?" for Delete. **Verification:** the existing keymap test must still pass unchanged, proving user bindings survive the conversion. That is the load-bearing check here. ### Outcome (done) Built as described: menu bar, toolbar, and a generated shortcut reference. Four things the plan did not anticipate, all verified by probe rather than assumed: - **The event filter was removable, but not for the stated reason.** The plan worried that `QAction` shortcuts might lose to `QAbstractItemView`'s type-to-search. They do not: shortcut dispatch runs before the focused widget sees the key. The filter is gone, and the thread view no longer needs its own. - **Qt already solves the query-bar case.** A plain-letter shortcut is suppressed while an editable widget has focus, so the `hasFocus()` guard was unnecessary. Removing it also fixed `Ctrl+Q`, which the old filter swallowed while typing a query. - **Three default bindings had never worked.** `N`, `F` and `G` stored the unshifted key, which no keystroke emits, so `toggle_unread`, `flag` and `sync` were dead in 0.1.0. Fixed in `KeyMap::normalizeSequence()` and committed separately from the menu work. - **The drift test did become unnecessary**, as the plan hoped. `registeredActionNames()` is now derived from the `QAction`s, and `defaultBindings()` is the single source for the defaults. The two tests that pinned the hand-maintained lists together were replaced by ones that check a configured binding actually reaches its action. Defaults moved to modifier shortcuts, since a single letter cannot be a menu accelerator without claiming that letter window-wide. Existing `[keys]` entries are unaffected. ## 4. Message-pane font size does not survive restart **Observed:** described as "very annoying", more so than item 1. **Confirmed by the user:** Ctrl+`+` / Ctrl+`-` do change the message pane font size. It is only the persistence that is missing. **Cause:** qtmaildir does not implement that zoom. There is no `setZoomFactor`, no zoom action, and no `Ctrl+=`/`Ctrl+-` binding anywhere in `src/`; grep finds nothing. The behavior comes from `QWebEngineView`, which handles zoom keys natively in Chromium. `htmlbuilder.cpp:26` separately hardcodes `font-size: 10pt` as the document's base size, which the browser zoom then scales. This changes the shape of the work. There is no application-side value to save, because the application never learns the zoom changed: Chromium handles the key and adjusts the factor without telling anyone. Persistence therefore requires taking ownership of zoom first, rather than hooking a save onto something that already exists. **Approach:** - Add explicit zoom in, zoom out and reset actions calling `QWebEngineView::setZoomFactor()`, tracking the current factor in `MessageView`. Use `setZoomFactor` rather than rewriting the CSS: it scales the rendered document uniformly, needs no re-render, and does not disturb `HtmlBuilder`'s output or its tests. - Bind them to the same Ctrl+`+` / Ctrl+`-` the user already has in their fingers, so the change is invisible except that it now sticks. Verify the application binding actually takes precedence over Chromium's built-in handling; if the web view swallows the key first, the action never fires and the factor silently diverges from what is on screen. This is the one real risk in the item and is worth checking before building the rest. - Persist the factor to the UI state file from item 1, and reapply it on every `setDocument()`. Do not assume zoom survives a load; `QWebEngineView` may reset it on navigation. Verify empirically. - Config entry as the user suggested: a `[general]` key for the starting zoom, with the state file remembering runtime changes on top of it. The config value is the default for a fresh profile, the state file is what the user last had. - Clamp to a sane range. An accidental 0.1 or 25.0 leaves the pane unusable and the user with no visible way back. Chromium's own limits are roughly 0.25 to 5.0; match or tighten, never widen. - Route the actions through item 3's `QAction` conversion so they appear in the View menu, which also makes the reset discoverable. ### Outcome (done) Built as described, and both of the plan's stated risks turned out not to exist. Probed rather than assumed: - **The application `QAction` wins over Chromium's native zoom key.** The plan called this "the one real risk in the item". It is not one: the action fires and the web view's own handling never runs, so the tracked factor cannot diverge from what is on screen. - **Zoom survives `setHtml()`.** The plan expected the view might reset it on navigation and asked for a reapply per render. Not needed; the web view keeps the factor, so it is the single source of truth and there is no second copy. - **Do not test key reachability with synthetic input.** A probe using `QTest::keyClick()` reported `Ctrl++` as a dead binding, and a test was written asserting it. Both were wrong: `Ctrl++` is exactly what the `+` key emits on an Italian layout, confirmed against the real keyboard, and it is the shipped default. Whether a symbol needs Shift is a property of the layout, not of Qt, and `keyClick()` reproduces neither. The test now only checks that every default parses. - `Ctrl+=` is a second binding for reset, skipped when `[keys]` gives `Ctrl+=` to something else. Ctrl+wheel zooms and Ctrl+middle-click resets, both filtered by ancestry from an application-level filter: the events land on an internal `QQuickWidget` the web view creates lazily, so a filter installed on the view itself never sees them. **A pre-existing bug surfaced while adding the config key.** `[general]` entries were read as `general/`, which matches nothing: QSettings' INI backend treats a section literally named `[general]` as its own fallback section and strips the prefix. `notmuch_config` had therefore never worked. Both keys are now read without the prefix; the file format the user writes is unchanged. Regression test in `test_config`. ## 5. Thread list is cramped **Observed:** rows are tightly packed, everything is uniform, the UI reads as "stuffed". **Approach:** presentation only, no model changes. - Row height: give the `QTableView` vertical breathing room. - Alternating row colors, or a subtle separator. - Make unread threads visually distinct (bold), which is the one distinction that carries real information and currently does not exist. - Consider dropping a column. Look at what `ThreadListModel` exposes and ask whether every column earns its width. **Caution:** do not hardcode colors. The app should follow the desktop palette; a hand-picked grey that looks right on a light theme is unreadable on a dark one. Use `QPalette` roles. This applies to `HtmlBuilder`'s CSS too, which currently hardcodes `#bbb`, `#555`, `#000`, `#666`, `#ddd` and no background, and will look wrong under a dark theme. That is arguably its own item; see item 12 below if it gets split out. ### Refined by the user, 2026-08-04 Two concrete sub-items, from using the list rather than looking at it: - **"All items look unread (bold), maybe use regular for read items?"** **Check this before changing anything.** Bold is ALREADY conditional: `ThreadListModel::data()` sets it under `Qt::FontRole` only when `thread.isUnread()` (`src/threadlistmodel.cpp:148-152`). So either the observation is that the user's list genuinely is mostly unread, in which case there is no bug and the fix is elsewhere (the density work below), or bold is leaking onto read rows through some path the model does not control. Reproduce against a query with a known mix, e.g. `tag:inbox and not tag:unread`, before touching the font logic. - **A star column for flagged threads**, mirroring the paperclip column that already exists for attachments. `ThreadSummary` carries the tags and `flagged` is an ordinary notmuch tag, so this needs no new worker query, the same way item 15's paperclip did not. Keep it narrow: an icon column, no text. ## 6. Opened message stays unread **Observed:** opening a message leaves it tagged unread; the user expects it to become read. **Decision (user, 2026-08-03): mark read after a 2 second delay, configurable.** **Approach:** - A `QTimer` started in `onThreadSelected()` (`src/mainwindow.cpp:373`), fired once, removing the `unread` tag from the displayed thread. - The timer **must** be restarted, not stacked, when the selection changes. Arrowing quickly down a list must not mark ten threads read; only the one still selected when the timer fires. - **Decided (user, 2026-08-03): the automatic mark-read does NOT go on the undo stack.** The tag change routes through `sendThreadTagChange()` directly, bypassing the `ThreadTagCommand` push, exactly as an explicit non-undoable mutation would. Rationale: a manual toggle-unread action already exists (`toggle_unread`, `src/mainwindow.cpp:242`), so a user who wants the message back as unread has a direct route and does not need undo for it. Leaving a message read after undoing an unrelated archive is acceptable; hijacking Ctrl+Z to undo an action the user never took is not. - Consequence to keep in mind: `applyTags` is the funnel for all mutations per `CLAUDE.md`, and that stays true. What changes is only whether the inverse is pushed onto the `QUndoStack`, which is a `MainWindow` decision made above the worker. Do not add a second write path to the worker for this. - Config key in `[general]`, e.g. `mark_read_delay_ms`, default `2000`, with `0` meaning "immediately" and a negative value meaning "never". Document all three in the README. - Interaction with item 3's toggle-unread action: if the user explicitly marks a message unread, the timer must not immediately re-mark it read. Cancel the pending timer on any manual unread toggle. **Verification:** unit-testable against the throwaway notmuch database the `NotmuchWorker` tests already build, but the timer logic itself is UI-side and easier to check by hand. At minimum, verify the rapid-arrow case manually. ### Outcome (done) Built as specced, including every decision recorded above: a 2000 ms default, `mark_read_delay_ms` in `[general]`, the automatic change kept off the undo stack via `sendThreadTagChange()`, and an explicit `toggle_unread` cancelling any pending timer. **The rapid-arrow case is unit-tested, not left to hand-checking.** The plan expected it to need a database and a person; it needs neither. `ThreadListModel` takes threads directly through `appendBatch()`, so a test builds three unread rows, arrows through them, and asserts one timer stays armed. The timer carries an object name so the test observes it through `findChild` rather than the window exposing it. **The three tests were verified by breaking the code**, since a passing test proves nothing until it has been seen to fail: - Removing the already-read check arms a timer for a read thread, caught. - Creating a fresh timer per selection instead of restarting one, which is precisely the stacking the plan warns about, fails two of the three. **Two guards the plan did not call for**, both from asking what happens when the timer outlives its thread. `scheduleMarkRead()` refuses to arm for a thread that is not unread, so a read thread never schedules a write that would change nothing. `markCurrentThreadRead()` re-checks that the thread it was armed for is still selected AND still unread before writing, so a timer that survives a selection change or a manual toggle does nothing rather than tagging the wrong thread. ## 7. HTML view should be default for HTML messages **Verify before doing anything.** `MessageView::m_preferHtml` is already initialized to `true` (`src/messageview.h`), and `clear()` resets it to `true` (`src/messageview.cpp:164`). HTML should already be preferred where a message offers it. Possible explanations for the observation: - The messages in question are `multipart/alternative` and `HtmlBuilder`'s `PreferHtml` mode is not selecting the HTML part correctly. - The HTML renders, but with remote content blocked it looks like plain text. - `m_preferHtml` is being reset between messages by a `clear()` the user did not intend to trigger. Reproduce first with a specific message, then decide. If it turns out to work correctly, the item becomes a documentation gap rather than a bug, and the user-preference key mentioned in the note (`prefer_html`, `[general]`) is still worth adding for people who want plain text by default. **Do not**, in the course of this, relax anything in the web view security section of `CLAUDE.md`. Preferring HTML is orthogonal to remote content, which stays blocked and per-render. ### Outcome (done, 2026-08-04): nothing was broken **Verified by the user against real mail: HTML messages do open as HTML.** The item was raised on an observation that could not be reproduced afterwards, and the code was already correct: `m_preferHtml` initialises to `true` and `clear()` resets it to `true`, so every thread starts in `PreferHtml`. No code changed. Recorded as done rather than dropped, since the behaviour the item asked for is the behaviour that ships. The `prefer_html` config key the item floated for people who want plain text by default was **not** added: nobody has asked for it, and `toggle_html` (`Ctrl+H`) already switches a thread by hand. Add it if someone wants the default flipped, not before. ## 10. Reaching an account's inbox takes two steps **Observed:** select account from the dropdown, then click inbox or unread. **Approach:** cheapest useful fix first. - Persist the selected account across restarts (uses item 1's state file). If the user reads one account 90% of the time, this alone removes most of the friction. - Then: per-account entries in a menu, or saved queries that carry their own account scope, so one action gets there. `Account::scopedQuery()` already exists in `Config`, so the composition is available; it is a UI question, not a query question. Do not build a full account sidebar for this. Persisting the selection may resolve the complaint entirely, and it is a fraction of the work. Reassess after. ### Partly done **The startup query is now chosen by name**, not by sort order. `[queries]` is read through `childKeys()`, which sorts alphabetically, so the old `savedQueries().first()` opened whichever entry happened to sort first, which is why the app came up on Inbox. `[general] startup_query` names the entry, defaults to `Unread`, and falls back to the first saved query when the name matches nothing. Only a name the user wrote is worth a warning: the built-in default naming a query they never created is not something they got wrong. Neither half of item 10 proper is done: the account selection still resets on restart, and reaching an account's inbox is still two steps. ### Postponed (user, 2026-08-04) **The user does not intend to go this route as of now.** Postponed rather than dropped: the complaint was real, and the cheap fix the item proposes (persist the account selection across restarts) is still the right first move if it is picked up again. Nothing here is invalidated, it is simply not wanted yet. Only the startup-query half shipped, in 0.3.0. Do not propose the remaining work unprompted. ## 11. Icon, `.desktop` file, SlackBuild Packaging, independent of everything above, and can proceed in parallel. - **Icon:** an SVG plus rendered PNGs at the standard hicolor sizes. Needs a design decision, not just code. - **`.desktop` file:** `Categories=Network;Email;`, `Terminal=false`, `MimeType=x-scheme-handler/mailto;` only if a `mailto:` handler is actually implemented, which it is not in 0.1.0. Do not claim the MIME type until it works; a desktop entry that registers as the mail handler and then does nothing is worse than not registering. - **CMake install rules:** icon into `share/icons/hicolor//apps/`, desktop file into `share/applications/`. Neither exists yet. - **SlackBuild:** per the global workflow, sources are authored here and the user builds. Deliverables are `qtmaildir.SlackBuild`, `.info`, `README`, `slack-desc`, plus an nvchecker stanza. Depends on a tagged release existing to point `DOWNLOAD` at, so it follows a tag rather than leading it. --- ## 13. No visual feedback that an action stuck **Observed:** selecting a thread and hitting Delete changed nothing on screen. No way to tell whether the thread was really going to be deleted on the next sync, which is bad UX for every tag action, not only delete. **Cause:** not a missing update. `ThreadListModel::applyTagChange()` already added the tag and emitted `dataChanged` across the whole row, so the Tags column did change. But `SubjectColumn` was set to `QHeaderView::Stretch` while `TagsColumn` came after it, so Subject absorbed all free width and pushed Tags out of view. The feedback existed in the one column that could not be seen. **Approach:** two changes, since the cause was two things. - Column order is now Tags, Date, From, Subject. Subject stretches and is last, so nothing sits to its right to be pushed out. The other three size to their contents. - A thread tagged `deleted` or `spam` styles its entire row: muted dark red (`#8b2c2c`) or orange (`#a85c18`) fill, white text, struck through. Applied through `Qt::BackgroundRole`, `Qt::ForegroundRole` and `Qt::FontRole` for every column, so no cue depends on a single column staying visible. Strike-through rides along with the fill deliberately: it survives a theme that overrides background colours, a colourblind reader, and a screenshot. Bold for unread still composes with it. **Decisions:** no status-bar or toast changes, the existing `tagSelected()` message stays as it is. Archive removes `inbox` and adds nothing, so an archived thread gets no row styling; whether it should disappear from an inbox query is deliberately left open rather than guessed at. **Verification:** four model tests covering the colours, the strike-through, that styling spans every column, and that undo restores a plain row. Rendered and inspected: normal, unread, deleted, spam, and deleted-plus-unread rows. --- ## 14. Tag column unreadable **Observed:** with tags spelled out per row the column ran to 500 pixels of mostly repeated text (a 33-character account tag followed by "attachment flagged inbox passed replied"), dominated by the account prefix, and consumed most of the list's width. **Cause:** presentation, not data. 96 tags in this database, many hierarchical (`shopping/amazon`, `mailing-list/SBo`), rendered as a joined string. **Approach:** the column is gone. Tags now render as coloured chips in two places, split by taxonomy: - The **account tag** says which mailbox a thread came from. It draws as a chip in front of the subject, coloured and labelled from its own `[account.]` stanza via new `color` and `label` keys. `label` is display-only; the notmuch tag is never renamed. - **Functional tags** say what state a thread is in. They fill a single row under the message pane, with overflow collapsing into a `+N` chip whose tooltip lists the hidden ones. A single row keeps the message area from shifting between threads with different tag counts. Colours resolve exact tag first, then top-level prefix, so one `shopping` entry covers the hierarchy without listing all 96. Unconfigured tags fall back to a hash of the name, stable so a chip never changes colour as the list scrolls. **Defect found while building:** QSettings treats `/` in a key as a group separator, so `shopping/amazon` becomes a nested key that `childKeys()` never returns. Reading `[tagcolors]` with `childKeys()` silently dropped every hierarchical tag, and each fell through to its prefix colour. Fixed by reading `allKeys()`, with a regression test. The same gotcha is already documented in `CLAUDE.md` for `[account.work]` section names. **Deferred:** clicking a chip to search that tag. Display only for now. ## 15. Attachments are parsed but unreachable from the UI **Observed, 2026-08-03, with a screenshot.** A thread known to carry attachments shows the `attachment` chip and a body that refers to them, but there is no way to download or open one. The user also has no way to tell a message has an attachment before opening it. **Cause: the attachment bar is an empty placeholder.** `MessageView` creates `m_attachmentBar` and gives it a layout (`src/messageview.cpp:130`), adds it to the pane (`:142`), and then **nothing ever puts anything in it**. `m_attachmentBar` appears nowhere else in the codebase, and neither `render()` nor `showThread()` reads `ParsedMessage::attachments`. The bar has never displayed an attachment. This is a gap in the UI only. The backend is complete and already hardened: `MimeParser` fills `attachments`, and `Attachment` has `safeFilename()`, `saveTo()` and `isPathInsideDirectory()` with the path-traversal guard `CLAUDE.md` describes. None of that work needs redoing; it needs calling. **Approach, two independent pieces.** - *Populate the bar.* For each attachment on each rendered message, one button showing the safe filename and the size. Clicking saves, through a `QFileDialog` for the target directory, then `Attachment::saveTo()`. Report the written path in the status bar, since a silent save is the same UX failure as item 13. - *A paperclip column in the thread list*, so an attachment is visible before opening. `ThreadSummary` already carries the thread's tags and notmuch applies `attachment`, so the column can be driven from the existing tag data with **no new worker query**. Keep it narrow: an icon column, no text. **Constraints.** - **Filenames are untrusted.** Display `safeFilename()`, never the raw `filename`, and never interpolate either into rich text without escaping. The save path must go through `saveTo()`, which is where the boundary check lives. - **Do not add "open in default application" in the same change.** That means handing a file from a stranger to `xdg-open`, which is a materially different security decision from writing it to a directory the user picked. If it is wanted, it is its own item with its own reasoning. - A thread renders as one document, so the bar must make clear which message an attachment belongs to once a thread has several. Grouping by message, or a per-message row inside the HTML, are both plausible; decide when building. **Verification:** a message with a known attachment saves a byte-identical file. A message with an attachment named `../../etc/passwd` writes inside the chosen directory under a sanitised name and nowhere else. ### Outcome (done) Both halves built. The paperclip column needed no new worker query, as the plan expected: notmuch applies the `attachment` tag itself, so `ThreadSummary::hasAttachment()` reads what is already there. **The bar holds ONE button, not one per file.** The plan's "one button showing the filename and size" was built first and was wrong: a thread with sixteen attachments made the bar as wide as the window, pushed the splitter over, and left the thread list a few pixels wide. It is now `Attachments (N)...` opening a dialog that lists message number, filename and size with a `Save...` each, plus `Save all...` when there is more than one. No filename reaches the bar, so no filename length can resize anything. **`Save all` writes into a new subdirectory** named ` `, inside a parent the user picks. Chosen over zipping: Qt ships no zip API, so a real `.zip` meant either a new build dependency (quazip, libzip) or shelling to `/usr/bin/zip` at runtime, and the actual requirement was "do not drop sixteen files loose among hundreds of others". The picker's title names the subfolder before the user commits to a location. **Two defects found only by using it, both silent:** - **`saveTo()` overwrites, which destroyed six of sixteen files.** Several messages in one thread commonly attach the same filename; each write landed on the previous one and every one reported success, so the status line said 16 while the directory held 10. `saveWithoutOverwriting()` now backs the batch path, appending " (2)" before the extension and keeping a compound extension whole. `saveTo()` still overwrites, which is right for a single save the user just chose a location for. - **`Qt::RFC2822Date` rejects a date carrying a timezone comment.** A header ending `+0200 (CEST)` is legal per RFC 5322 and common in real mail, and Qt refuses the whole string rather than the comment, so every such message lost its date prefix. Comments are stripped before parsing. **The subject is untrusted and becomes a directory name.** `attachmentFolderName()` lives beside the other guards in `mimeparser.cpp`, strips separators, control characters and leading dots, caps length at 120, and falls back to a generated name. Its test drives `../../etc`, `/etc/passwd`, `..`, `.hidden`, a backslash and a null byte, then asserts each result still resolves inside the parent through `isPathInsideDirectory()`. **Deferred, as the plan required:** opening an attachment in its default application. That hands a stranger's file to `xdg-open` and is a separate decision from writing it to a directory the user chose. ## 16. Delete on an already-deleted thread should undelete **Observed:** hitting Delete twice on the same message is a natural way to express "no, put it back", but the second press does nothing visible because adding a tag that is already present is a no-op. **Approach:** make `delete` a toggle, the way `toggle_unread` already is. Deleting a thread that already carries `deleted` removes it instead. **Constraints.** - **A multi-row selection must not split.** If some selected threads are deleted and others are not, toggling each independently leaves the selection in two states from one keystroke, which is worse than either outcome. Decide one direction for the whole selection: the natural rule is "if every selected thread is already deleted, undelete them all; otherwise delete them all." - Undo already covers the mistake case, so this is a convenience, not a safety fix. It must not grow a confirmation dialog. - The same question applies to `spam` and `flag`. Do not change those in this item; note whether the answer generalises once `delete` is built. ### Outcome (done) Built as specced, including the all-or-nothing rule: undelete only when every selected thread already carries `deleted`, otherwise delete the whole selection. A test covers the mixed case and passed before the change, since the old always-delete behaviour satisfies it; it is there to stop a later "improvement" from toggling per row. **It generalises to `spam` and `flag`, and they were still left alone.** The same shape would work, but neither has been asked for, and `flag` in particular is already reachable both ways through the tag dialog. ## 17. No completion for tags in the query bar **Observed:** typing a query means remembering the exact tag name, including hierarchy (`shopping/amazon`). **Approach:** a `QCompleter` on the query bar, offering tag names after `tag:`. **Cause of the work being larger than it looks:** there is **no way to list tags today**. `NotmuchWorker` has no all-tags call, so this needs a new worker request and result signal, following the existing generation-counter pattern. `notmuch_database_get_all_tags()` is the underlying call. **Constraints.** - The tag list must be fetched on the worker thread like everything else. No `notmuch_*` pointer crosses the thread boundary; the result is a `QStringList`. - Refresh after a sync, since a sync can introduce tags. Do not refetch per keystroke. - Completion should trigger on the `tag:` prefix specifically rather than on every word, or it will offer tag names where a `from:` value belongs. --- ## 18. No visual cue that there are unsynced edits **Observed (user, 2026-08-04):** tagging changes the notmuch index immediately, but nothing in the UI says those changes have not reached the mail store. The user cannot tell, at a glance, whether quitting now would leave work stranded. **Cause: nothing tracks it, and the obvious candidate cannot.** `MainWindow` holds a `QUndoStack` (`src/mainwindow.h:142`) which looks like a record of pending edits, but it is **cleared on every query** (`src/mainwindow.cpp:805`, in the query-start path) because undo entries refer to rows the new result set is about to discard. Tag a thread, then run any query, and the stack is empty while the database change is still unsynced. The same clear happens on a failed write (`:902`). So `QUndoStack::isClean()` is **not** usable as the signal here, and neither is `canUndo()`. This needs its own counter, one that only a successful sync resets. **Approach:** - Count confirmed mutations, incremented where `tagsApplied` is handled (the same place that already clears `m_pendingChange`), and reset to zero on `MailSync::finished(true, ...)`. A count, not a bool, so the indicator can say how many. - Show it in the status bar, next to the existing sync status rather than as a new widget competing with it. Wording should name the unit the user thinks in: threads or messages changed, not "mutations". - Nothing modal, nothing blocking. This item is the passive cue only; the question of interrupting the user belongs to item 19. **Constraints:** - **A failed sync must not clear the count.** `finished(false, ...)` means the edits are still unsynced, and clearing there would assert the opposite. - The count must survive a query, which is the whole reason it cannot ride on the undo stack. Do not tie its lifetime to the model. - An external `notmuch new` from the user's cron can sync changes without the app knowing. The count is therefore a lower bound on confidence, not a guarantee, and the wording should not promise more than it knows. **Verification:** tag a thread, run an unrelated query, confirm the cue survives. Then sync and confirm it clears. Then make the sync fail and confirm it does not. ### Outcome (done) Built as specced. `m_pendingEdits` counts confirmed mutations, incremented in `onTagsApplied()` and reset only by `onSyncFinished(true, ...)`. The count is shown as a permanent status-bar widget, hidden entirely at zero. **Counted where a write is confirmed, not where one is sent.** An optimistic update the worker later rejects must not leave the indicator claiming an edit that never landed, so the increment sits in the `tagsApplied` handler. That handler was a lambda; it is now a named slot, which is both better structure and what lets a test drive it. An earlier draft tried to reach the worker with `findChild` to emit the real signal: the worker is deliberately parentless because it moves to its own thread, so that cannot work, and contorting the test to reach it was the wrong instinct. What matters is the counter's behaviour, not the signal's origin. **Both tests were verified by breaking the code.** Clearing the count on any sync outcome is caught, and so is clearing it where the undo stack is cleared, which is the naive design this item exists to avoid. ## 19. No prompt to sync on exit when edits are pending **Observed (user, 2026-08-04):** quitting with unsynced edits is silent. The user asked for a blocking prompt offering to sync first, and suggested a `sync_on_exit` config option. **Depends on item 18.** Both need the same "are there pending edits" counter, and 18 establishes it. Build 18 first; this is the interruption layer on top. **Cause:** `MainWindow::closeEvent()` (`src/mainwindow.cpp:145`) saves UI state and accepts unconditionally. It never consults sync state, and cannot today, for the reason item 18 documents. **Approach:** - On close with a non-zero pending count, a modal question: sync now, quit without syncing, or cancel. Three options, not two: a user who hit Quit by mistake needs a way back that is not "sync". - `[general] sync_on_exit`, as the user suggested. Sensible values are `ask` (default, the prompt above), `always` (sync without asking), and `never` (quit silently, today's behavior). A bare true/false cannot express all three. - Choosing to sync means the window must stay alive until `MailSync::finished` arrives, since killing the process mid-sync is exactly the data loss the prompt exists to prevent. Ignore the close event, show progress, and close on the finished signal. **Constraints:** - **This is not a destructive-action confirmation** and does not contradict `CLAUDE.md`'s rule against those. That rule is about tag mutations, which keep undo instead of a dialog. This asks about *losing* work at a point where undo no longer helps, which is the opposite situation. - A sync that fails on exit must not silently discard the user's choice. Report it and leave the window open rather than quitting as if it had worked. - Quitting must remain possible when the sync command is not configured at all. `MailSync::isAvailable()` is already false in that case, so the prompt should degrade to a plain warning with no sync option rather than offering one that cannot run. **Verification:** by hand. Tag, quit, take each of the three branches. Then set each `sync_on_exit` value and confirm the behavior matches. Then quit with a deliberately broken sync command and confirm the app neither hangs nor lies. ### Outcome (done) Built as specced, with the user confirming the three-value key over their original on/off idea. `closeEvent()` consults the count, and a sync started for exit holds the window open until `finished` arrives rather than being killed mid-run. **A failed exit-sync does not quit.** It restores the window, shows the log and says what happened. Quitting there would discard the user's choice silently, which is the exact failure the prompt exists to prevent. **With no sync command configured the prompt degrades** to a warning offering Discard or Cancel, rather than offering a sync that cannot run. `MailSync::isAvailable()` is already false in that case. **Testing a modal needs care, and the first attempt was wrong.** A test that sends a close event hangs forever if an unexpected dialog opens, because the modal spins its own event loop. The first version appeared to pass in 19 seconds; it had actually opened a real dialog on the user's screen, and the user dismissed it. `CloseProbe` now polls for `activeModalWidget()`, closes it, and records that one appeared, turning "a dialog opened" into an assertion instead of a hang or a prompt for whoever is watching. **One mutation test was a dud and is worth recording.** Removing the `Never` guard from `closeEvent` did NOT make the test fail, because the branches below match only `Ask` and `Always`, so `Never` fell through to closing anyway. The guard is redundant belt-and-braces rather than load-bearing. Confirming the probe really detects a prompt needed the config mutated to `ask` instead, which does fail it. ## 20. Thread view does not match the user's mental model **Observed (user, 2026-08-04), in passing while deciding item 2:** "My view for the thread visualization was different than what was built, but that's ground for a small refactor later." **Unspecified on purpose.** What the user pictured has not been described yet, so there is nothing here to design against. Recorded now only so the remark is not lost, and because item 2 touches the same surface and might otherwise be mistaken for having addressed it. **What exists today**, as the starting point for that conversation: a thread is one HTML document in one web view, messages stacked in chronological order, each with a small grey `.msg-header` carrying From and Date (`src/htmlbuilder.cpp:241`). Messages that did not match the query render as stubs (`MessageRef::matched`, `src/types.h:63`). It is deliberately flat: `CLAUDE.md` records that reply structure is available from notmuch but is not drawn as an indented tree. The single-document design is not incidental and constrains any redesign: a `QWebEngineView` per message would spawn a Chromium render process each, which is why the thread is one document and why `cid:` references are namespaced per message. A refactor that splits messages into separate views has to answer that cost first. **Next step: ask the user what they pictured** before proposing anything. Do not design this item from the description above, which says only what is, not what was wanted. ## 21. Default shortcuts are not sensible enough **Observed (user, 2026-08-04):** "improve the default shortcuts to some sensed defaults." **Unspecified in detail**, so ask which bindings feel wrong before proposing a table. What is worth recording is the history, because the defaults have already moved once and the reasons still constrain any second pass. **Where the current defaults came from.** 0.1.0 used bare letters. They were replaced in the 0.2.0 menu work for two reasons that have not gone away: a single letter cannot be a menu accelerator without claiming that letter window-wide, and a bare capital such as `N` parses to an unshifted `Key_N`, which no keystroke emits, so `toggle_unread`, `flag` and `sync` were dead keys that appeared to be bound. See `KeyMap::defaultBindings()` and `normalizeSequence()`. **Constraints on any new default.** - **Do not test reachability with synthetic input.** `QTest::keyClick()` does not reproduce a keyboard layout: it reported `Ctrl++` as dead when it is exactly what the `+` key emits on the user's Italian layout. Verify against the real keyboard, as `CLAUDE.md` records. - Every binding is overridable in `[keys]`, so this is about what a fresh install feels like, not about what is possible. - `Return` is a special case already resolved: it belongs to `open_thread` but the query bar claims it back while focused, so a proposal that moves it must not resurrect that bug. ## 22. Translatability audit and i18n wiring **Observed (user, 2026-08-04):** "a full check of the codebase and wiring up of the i18n system." **This is a debt `CLAUDE.md` already records.** The rule that every user-facing string must be wrapped in `tr()` was added while building query completion, and that file states plainly that "pre-existing code has not been audited against this rule". This item is that audit, plus the loading machinery which does not exist at all. **Two halves, and they are different sizes.** - *The audit.* Every user-visible string in `src/` checked for `tr()`, with the translation context correct: a string in a free function needs `Q_DECLARE_TR_FUNCTIONS`, since calling `QObject::tr()` compiles but files it under the wrong context. `lupdate` output is the evidence here, not reading. - *The wiring.* Nothing loads a `.qm` file today: there is no `QTranslator` in `main.cpp`, no `.ts` files in the tree, and no CMake rule to build or install them. Until that exists, a translated string has nowhere to come from. **Constraint:** query syntax is not user-facing text. notmuch keywords such as `tag:` and `date:` are wire format and must never be translated, only the prose describing them. The completion vocabulary is exactly this trap: the values are literal, the descriptions are prose. **Verification:** run `lupdate` and read the generated `.ts`. A string that does not appear there is not translatable, whatever the source looks like. ## 23. No way to save a search query from the UI **Observed (user, 2026-08-04):** saved queries live in the config file only. There is no way to keep a query you have just written without editing `qtmaildir.conf` by hand. **Approach, and one real design question.** - A "save this query" action that names the current query bar contents and adds it to `[queries]`. - The user's own suggestion for presentation: **a few sensible ones as buttons, the rest behind a menu.** Today `SavedQueryBar` shows them all, which does not scale past a handful. **The design question is where the write goes.** `qtmaildir.conf` is hand-edited and owned by the user, and item 1 established the rule that machine-written state belongs in `uistate.conf` instead, precisely because QSettings preserves neither comments nor key order and would quietly reformat the file on write. Saved queries are not machine state though: they are user intent, they belong with the hand-written ones, and splitting them across two files so the UI can avoid touching one would be worse than either option. Decide explicitly, and say so in the README whichever way it goes. **Relation to item 10.** Item 10 is postponed, but its second half proposed exactly this: "saved queries that carry their own account scope, so one action gets there". If saved queries gain an account scope here, item 10 may be answered as a side effect rather than needing its own work. ## 24. No right-click actions on the thread list **Observed (user, 2026-08-04):** "right click actions on the list (left pane)". **Cause: there is no context menu anywhere in the application.** No `contextMenuEvent` override and no `Qt::CustomContextMenu` policy in `src/`; grep finds neither. Right-clicking a thread does nothing at all. **Approach.** The actions already exist as `QAction`s from item 3, so this is presentation rather than new behaviour: set `Qt::CustomContextMenu` on the thread view and build the menu from `m_actions`, exactly as `buildMenus()` already does. Nothing should be reachable from the context menu that is not reachable from the menu bar, or the two drift. **Constraints.** - **Show the shortcut in the menu**, which a `QAction` does for free. The context menu is where a mouse user discovers the key for next time, and this backlog exists because the app did not teach its own bindings. - The menu must act on the **selection**, not on the row under the cursor, or right-clicking inside a multi-row selection would silently act on one thread. Qt does not do this for you: right-clicking does not change the selection, so the row under the cursor and the selected rows can differ. - Include the destructive entries (archive, delete, spam) without a confirmation dialog, per `CLAUDE.md`. Undo covers them. ## 25. No select-all, and bulk actions are undiscoverable **Observed (user, 2026-08-04):** "bulk select/select all for defined actions? tags, read/unread, archive, delete". **Cause: half of this already works, and nothing says so.** The thread view is already `QAbstractItemView::ExtendedSelection` (`src/mainwindow.cpp:408`), and `tagSelected()` already acts on every `selectedRows()` entry, resolving them in ONE combined query per `CLAUDE.md`. Ctrl+click and Shift+click therefore do bulk tagging today. What is genuinely missing is smaller than the item sounds: - **No select-all action.** `selectAll` appears once in `src/`, on the query bar, not the thread list. There is no `Ctrl+A` for the list and no menu entry. - **No indication that multi-select exists.** With no context menu (item 24) and no selection count anywhere, a user has no reason to think Ctrl+click will do anything useful. **Approach.** Add a `select_all` action bound to `Ctrl+A`, scoped to the thread list rather than the window, so it does not steal Ctrl+A from the query bar. Then surface the selection size: the status bar already reports "%1: %n thread(s)" after a tag action, and saying how many rows are selected before one is the same idea a moment earlier. **Constraint: verify what a large selection costs before encouraging one.** Select-all over a 10k-thread query makes `tagSelected()` build a 10k-id list and `applyTagsToThreads()` one enormous `thread:a or thread:b or ...` query. The combined-query design is what makes this plausible at all, but "plausible" is not "measured", and this item is the one that turns a rare accident into a routine keystroke. Measure it against a real query before shipping the binding. ## 26. No way to add or remove an arbitrary tag from the UI **Observed (user, 2026-08-04), as a question:** "as it is today, how do I add a new tag to a message?" The answer is that you cannot. The only route is `notmuch tag` in a terminal, or the companion `mailctl`. **Cause: every tagging action writes a hardcoded tag name.** `registerActions()` offers exactly five: `archive` (removes `inbox`), `delete` (adds `deleted`), `spam` (adds `spam`, removes `inbox`), `flag` (adds `flagged`) and `toggle_unread`. Nothing accepts a tag the user types. For an application whose entire purpose is organising mail by tag, that is a conspicuous hole, and it is the reason this item exists at all rather than being folded into item 25. **The machinery is already complete.** `tagSelected(add, remove, description)` takes arbitrary lists and is the single funnel every mutation already uses; `applyTagsToThreads()` resolves a multi-row selection in one combined query; undo works through `TagChange::inverted()`; and `QueryCompleter` already holds every tag in the database, refreshed on the worker thread. This item is a dialog and two actions, not new plumbing. **Approach.** - An `add_tag` action opening a small dialog with a line edit, and a `remove_tag` counterpart. Both act on the whole selection, like every other tag action. - **Complete against the known tag list.** The completer's tag vocabulary is the same data, so offering it here costs nothing and prevents the obvious failure mode: typing `shoppping` and silently creating a new tag next to `shopping`. This is the strongest argument for the dialog over a free-text prompt. - Removing should offer the tags actually present on the selection rather than every tag in the database, since removing a tag that is not there is a no-op the user cannot see. **Constraints.** - **A tag name is not free text.** notmuch accepts a lot, but a leading `-`, an embedded space or an empty string will produce confusing results or a failed write. Validate before sending, and say what was rejected. - No confirmation dialog, per `CLAUDE.md`; undo covers a mistyped tag. - A tag the user invents is new to the completer, and `onTagsApplied()` already refreshes the list when a mutation introduces an unknown tag, so that path is in place and should be relied on rather than duplicated. ### Outcome (done) Built as the user chose: one **Edit tags** dialog on `Ctrl+T` rather than separate add and remove actions, since filing something under a new tag while dropping `inbox` is one thought. `TagDialog` is pure UI in `qtmaildir_lib`. It is handed the vocabulary and the selection's current tags and returns two lists; it contacts no worker and holds no database handle, which is what lets fifteen tests run without a notmuch database. Integration is one call to the existing `tagSelected()`, so undo, the optimistic model update, the one-query multi-row resolution and the completer refresh all come for free. **Tri-state is the part that needed the tests.** With several threads selected a tag can be on some, and `PartiallyChecked` means "leave alone" rather than "apply to all". The opposite reading silently tags threads the user never looked at. `m_fullyTagged` exists for the neighbouring case: a tag already on every thread and left checked is not a change and must not be sent as one. **Validation is a free function** so the rules are testable directly. It rejects empty, a leading `-` (notmuch's CLI reads that as removal, so such a tag is a trap), whitespace, and control characters. Nothing is applied until every name passes, since a half-applied change is worse than none: the user cannot tell which half landed. **One test assumption was wrong and the code was right.** A case asserted that `QStringLiteral("null\0byte")` truncates at the null and reads as Empty. It does not; the literal is kept whole, so the null is caught as a control character. The test was corrected, not the validator. Rendered and inspected rather than only asserted. ## 27. The UI cannot see a sync it did not start **Observed (user, 2026-08-04), as a question:** "will the status bar be aware of cronjob fired syncs?" It is not. The progress bar and the busy state are driven by `MailSync`'s own `QProcess`, so they know only about syncs this window started. The user's cron timer fires every ten minutes and the application is blind to it. **The lock file is already the signal; no new file is needed.** `mailsync.sh` does `exec 200>"$LOCKFILE"` and then `flock -n 200` on `/tmp/mbsync.lock`. Another process can test whether that lock is held, without disturbing it, by opening the same path on its own descriptor and attempting `flock(LOCK_EX | LOCK_NB)`: the attempt fails exactly when someone holds it, and succeeds otherwise, in which case the tester drops it again immediately. This is better than the status file first proposed. A kernel lock **cannot go stale**: it is released when the holding process dies, however it dies. A status file written by the script survives a `kill -9` and would leave the UI claiming a sync is running forever, which then needs a heartbeat and a staleness timeout, none of which the lock needs. **Decided (user, 2026-08-04): poll continuously, not only while quitting.** A narrower version that polled only during the exit prompt was offered and declined: the user wants the status bar informed at all times, not only at the one moment it changes a decision. **Approach.** - A `syncLockHeld()` helper: `open()` the lock path, `flock(LOCK_EX|LOCK_NB)`, close. Held when the attempt fails with `EWOULDBLOCK`. - A `QTimer` polling it. **One second is finer than this needs**; a sync runs for tens of seconds, so two seconds is plenty and halves a wakeup that never stops. - When the lock is held and `MailSync` is NOT the holder, show the busy state with wording that says so: "Syncing (started elsewhere)". The existing `setSyncBusy()` covers the widgets; this adds a third state between "idle" and "we are syncing". - On the exit path, this replaces a hedge with a fact. Today, quitting while cron syncs says the window "cannot see it finish". With the lock watched it can wait for the lock to clear and then quit, which is what the user actually wants to happen. **Verify before building, both cheap and both the kind of assumption this project has been bitten by twice:** - **That the lock is observable at all.** `flock` semantics across processes, where the holder opened the file with `exec 200>`, are an assumption about Linux behaviour, not a certainty. A twenty-line probe settles it. Do not design on top of it unproven. - **That polling it cannot disturb notmuch.** `mailsync.sh` runs `notmuch new`, and notmuch's write lock is process-exclusive. Touching `/tmp/mbsync.lock` should be unrelated, but the interaction is worth one look rather than an assumption. **Constraints.** - The lock path becomes a contract between the script and the application, where today the application knows nothing about it. It has to be documented on both sides, and the script cannot move or rename it casually afterwards. - The poll must not run a query or touch the database. It reports what another process is doing; the existing `runCurrentQuery()` on a completed sync of our own already handles refreshing, and a cron sync that finishes will be picked up the next time the user runs a query. - Do not report an externally-started sync as one this window can cancel. The Sync button should be disabled while the lock is held, since starting one would only produce the `EX_TEMPFAIL` skip. ### Outcome (done, 0.8.0) Both probes the item demanded were run before any code, and one of them changed the design. **The lock is observable, but only through `/proc/locks`**, and two of the three plausible ways to read it are wrong: - **`flock -n`, which this item proposed, is the one that must not be used.** It acquires in order to test, so polling every two seconds opens a window every two seconds in which a starting `mailsync.sh` is refused the lock and exits 75. It would cause the very skips the script reports. The item's own approach section specified this; it was wrong. - `fcntl(F_OFD_GETLK)` never acquires and looks ideal, but reports UNLOCKED against a lock held by `flock(2)`: separate lock namespaces in the kernel, which cannot see each other. A silent false negative. - `/proc/locks` is a pure read, matched by inode. It observes `flock(2)` correctly and takes no lock, which also answers the second probe: 200 reads left the lock table unchanged and the polling process holding nothing, so it cannot contend with the Xapian write lock `notmuch new` holds in the same run. `SyncMonitor` keeps the parsing separate from the polling so the parsing is testable, and reports **Unknown** rather than Idle where `/proc/locks` cannot be read. "No sync is running" is the claim that would let the window quit, so it is never guessed. **It reports rather than refreshes**, which is narrower than the item implies. `runCurrentQuery()` clears the undo stack, the selection and the message pane: right for a query the user typed, hostile for one a cron timer fired six times an hour. The status bar says a background sync finished and suggests pressing Enter. See item 35 for the non-destructive refresh this defers. **One constraint above was not built: the Sync button is still enabled while an external sync holds the lock.** That is item 29, split out rather than left buried here. **A defect found by hand testing, after the feature was believed done.** A sync this window started reported itself as a background one, a moment after it finished. Ownership of a lock period was decided when the lock was RELEASED, by asking `MailSync::isRunning()`, but the process exits before the next poll sees the lock gone, so the answer was always "not ours". Ownership is now latched when the lock appears, and handed back on exit 75, since a skip means the lock was never ours. **That fix has no regression test, deliberately recorded.** Reproducing it needs `isRunning()` true at one transition and false at the next, which needs a configured sync command and a live child process; that attempt left a process running for the length of the suite and popped a dialog on the user's screen. It was verified against a standalone model of both code paths instead. A real test needs the notmuch fixture. --- ## 28. Re-adding `unread` counts 2 unsynced changes, not 0 **Observed (user, 2026-08-04):** open a thread, wait the two seconds for the automatic mark-read, then press **Ctrl+U** to put `unread` back. The indicator reads **2 unsynced changes**. The mail store is in exactly the state it started in, so the honest answer is 0. **Cause: the counter counts writes, not net state.** `onTagsApplied()` does a bare `++m_pendingEdits` (`src/mainwindow.cpp:1293`) for every confirmed mutation, and nothing ever decrements. The automatic mark-read is one confirmed write, the manual toggle back is a second, so a round trip that cancels itself out reads as two outstanding changes. This is not specific to mark-read. Any add-then-remove of the same tag inflates it the same way: archive then undo, flag then unflag. Mark-read is simply the one path that fires without the user asking, which is why it surfaced here. **The design question this item has to answer first.** "Unsynced changes" can mean two different things and the fix depends on which: - *Writes the index has taken that a sync has not carried over.* Two writes did happen, notmuch's database did change twice, and `notmuch new` will still visit those messages. On this reading 2 is correct and the wording is what is wrong. - *Net difference between the index and the mail store.* On this reading the answer is 0 and the counter needs to track state, not events. The user's expectation is clearly the second. Note that item 18 chose the first deliberately: it counts at the point a write is **confirmed**, precisely so an optimistic update the worker rejects is not counted. That reasoning stays valid; what it did not consider is a write that undoes an earlier one. **Approach, if net state is the answer.** Track the set of (thread, tag) changes rather than a count, and collapse a pair that cancels. `TagChange` already carries add and remove lists and already knows how to invert itself (`TagChange::inverted()`, used by the undo stack), so the machinery for recognising an inverse exists. **Constraints.** - **A sync must still reset it to zero**, and a failed sync must still not, per item 18. Whatever replaces the counter keeps both properties. - The indicator is a lower bound on confidence, not a guarantee: an external `notmuch new` can carry changes across without this window knowing. Do not let a more precise counter imply more certainty than it has. - Do not fix this by not counting the automatic mark-read. It is a real write to the index, and hiding it would make the count wrong in the other direction. ### Outcome (done) **Decided by the user, 2026-08-04: net state.** "If I undo delete it's 0 edits, not 2." The counter is replaced by a `QHash` keyed `"\n"`, and a pair that reverts is **erased** rather than stored with the new direction, so an edit and its inverse leave nothing behind and the map cannot grow without bound over a long session of tagging and untagging. **Keyed per (message, tag), not per message.** Removing `unread` and adding `flagged` on one message are two independent changes; a per-message key would have cancelled them against each other. A test pins this, and it passed before the change, so it exists to stop a later simplification from over-netting. **A change carrying no message ids still counts**, tracked in a separate `m_unnettablePendingEdits`. It cannot be netted against anything, and dropping it would understate the indicator, which is the direction that costs the user work. This also keeps the older tests honest: they emit a `TagChange` with no ids, and would otherwise have started reporting zero. Both properties item 18 established survive: a successful sync clears everything, a failed one clears nothing. ## 29. Sync button stays enabled during a background sync **Observed (user, 2026-08-04):** while a cron sync runs, the Sync button is still clickable. Pressing it starts a run that can only be refused. **Cause: a constraint of item 27 that was specified and then not built.** That item states plainly that "the Sync button should be disabled while the lock is held, since starting one would only produce the `EX_TEMPFAIL` skip". `setSyncBusy()` (`src/mainwindow.cpp:1357`) is the only thing that touches `m_syncButton->setEnabled()`, and it is called only from this window's own sync path. `onExternalSyncStateChanged()` shows the progress bar and writes the status text but never touches the button. **Approach.** Have the external handler drive the same enable/disable that `setSyncBusy()` does, rather than duplicating the rule. The two paths already share the progress bar; the button is the piece that was missed. **Constraints.** - **Re-enable on `Unknown`, not only on `Idle`.** Where `/proc/locks` cannot be read the monitor claims nothing, and a button left permanently disabled on a platform that cannot observe the lock is worse than one that occasionally offers a run that gets skipped. - The button must not end up enabled during this window's own sync because the external handler ran last. Both paths write the same widget, so whichever fires second wins; make the rule a single function of both states rather than two independent assignments. - Exit 75 handling stays. Disabling the button makes the skip rarer, not impossible: cron can take the lock between the poll and the click. ### Outcome (done) `updateSyncControls()` is the single function the constraint called for, taking `m_localSyncBusy` and `m_externalSyncBusy` and writing both the progress bar and the button. Neither sync path touches those widgets directly any more. **The external state is tracked as its own flag rather than read back from `SyncMonitor`.** An earlier version called `m_syncMonitor->state()` inside the update, which meant the handler received a state and then ignored it in favour of re-reading the source. Acting on what you were told is both easier to follow and testable without a live monitor. Unknown clears the busy flag exactly as Idle does, per the constraint. Verified by reverting that half: leaving it set on anything but Idle strands the button disabled, and the test catches it. ## 30. The blank right pane is wasted space **Observed (user, 2026-08-04):** with no thread selected the message pane is empty. The user wants it to carry something useful, and named three things: the application logo, tips and tricks, and messages about the current action, giving "N messages selected" as the example. **Assets exist.** The user has produced `assets/images/qtmaildir-light.png` and `qtmaildir-dark.png` (924x540 each) for this item. **Cause:** `MessageView::clear()` leaves the web view showing nothing. Since 0.8.0 the pane is also blanked deliberately whenever more than one thread is selected, which makes this item more visible than it was: multi-select is now a routine gesture that produces an empty pane every time. **Approach.** A placeholder document rendered into the existing web view when there is nothing to show, rather than a second widget stacked behind it. `HtmlBuilder` already produces the pane's HTML and `MessageView` already knows how to hand it a document, so the placeholder is a third document shape alongside "one message" and "a thread". **The selection-count half is the one with real value**, and it pairs with the status-bar count added in 0.8.0. The pane already blanks on a multi-row selection; saying "3 threads selected" there answers the question the blank raises. **Constraints.** - **Two images, because the pane must follow the desktop theme.** Item 5 already records the rule against hardcoded colours, and a light-theme logo on a dark desktop is exactly that fault in image form. Pick by palette, not by guessing. - **Do not load the logo over `file:`.** The web view runs with `LocalContentCanAccessFileUrls` false and an interceptor that blocks every request by default, per `CLAUDE.md`. The image has to arrive as a `data:` URI or through the existing `qtmaildir:` scheme handler, and the interceptor's document-URL exemption must still match exactly. - Tips and tricks is the weakest of the three and should be built last, if at all. A tip nobody can dismiss becomes noise on the hundredth launch. - The placeholder must not appear between a selection and its render, or every thread open flashes a logo first. ## 31. The quit prompt has no highlighted default button **Observed (user, 2026-08-04):** "quit popup has no Predefined answer (there's no highlighted button)." **Needs a repro before any change: the code says otherwise.** The three-button prompt sets one explicitly, `box.setDefaultButton(sync)` (`src/mainwindow.cpp:191`), and the no-sync-command variant passes `QMessageBox::Cancel` as its default argument (`:167`). Both should render a highlighted button. Possible explanations, in the order worth checking: - The dialog the user saw was neither of those. There are five other `QMessageBox` calls in `MainWindow` (`:205`, `:224`, `:991`, `:1260`, `:1277`), and the two sync-failure ones appear on the exit path, so a failed exit-sync shows a second dialog immediately after the first. - The default is set but the style draws no visible focus ring, which is a platform theme question rather than a code one. - `setDefaultButton()` is being overridden by the button roles: a `DestructiveRole` button can take precedence in some styles. **Approach: reproduce first, and record which dialog.** If it is one of the sync-failure boxes, the fix is to give those an explicit default. If it is a theme issue the item becomes a documentation note rather than a change. **Constraint:** whatever default is chosen must be the safe one. On a prompt about losing unsynced work, Enter must not fall on "Quit anyway". ### Outcome (done): the code was right, the theme draws nothing Reproduced from a screenshot: it is the three-button `ask` prompt. Probed rather than guessed, and Qt agrees the default is set. On that dialog `isDefault()` and `hasFocus()` are both true on "Sync and quit", and `defaultButton()` returns it. **The active style is `qt6ct-style`, which draws no visible default-button decoration.** The GIMP dialog the user compared against is GTK drawing its own focus ring, a different toolkit, so the two are not comparable and this was never a qtmaildir bug. Fixed by naming the default in the button text rather than restyling it. Overriding a button's appearance means fighting the user's chosen theme, which is a worse outcome than one word. The safe option was already the default, per the constraint above, so no behaviour changed. ## 32. Esc does not blank the right pane **Observed (user, 2026-08-04):** "Esc in the main window should blank the right pane." **Cause:** nothing binds Escape at window level. `Key_Escape` appears once in `src/`, in `QueryCompleter` (`src/querycompleter.cpp:474`), where it dismisses the completion popup. The main window has no handler. **Approach.** A registered action like any other, so it reaches the menus, the shortcut reference and `[keys]`, calling the same `MessageView::clear()` the multi-select path already uses. `m_currentThreadId` must be cleared with it, or a late-arriving `threadLoaded` will paint the thread straight back, which is the race documented in `CLAUDE.md` and fixed in 0.8.0. **Constraints.** - **Escape must not be stolen from the completer.** A window-level shortcut outranks the focused widget, which is exactly how `Return` broke for the query bar and needed an event filter to claim back (item 21 records this). Verify the popup still dismisses before shipping. - Blanking is a view change, not a mail change: it must not clear the selection, the query, or the undo stack. - Decide what Escape does when the pane is already blank. Doing nothing is fine; clearing the selection as a second step would be surprising. ### Outcome (done) A `clear_pane` action bound to `Esc`, registered like every other action so it reaches the menus, the shortcut reference and `[keys]`. It clears `m_currentThreadId` alongside the pane, and cancels any pending mark-read: a thread blanked from view must not be marked read two seconds later. **The completer keeps its Escape, verified by probe rather than by reading the code.** A popup consumes the key before a window-level shortcut sees it: with the popup open the popup's filter fires and the action does not, and with it closed the action fires. This was the one real risk in the item, since `Return` had already been lost to a window shortcut this way (item 21). Blanking is a view change only: the selection, the query and the undo stack are untouched, which a test pins. ## 33. Status bar messages never expire **Observed (user, 2026-08-04):** "the status bar should return to default status after showing a message for N seconds." **Cause:** every message is written with a bare `m_statusLabel->setText()`, eighteen call sites in `MainWindow`, and nothing ever clears one. Whatever was written last stays until something else overwrites it, so a transient message like "Sync complete" persists as though it described the current state. **Approach.** Route transient messages through one helper that sets the text and arms a single-shot timer to restore a default, rather than adding a timer per call site. `QStatusBar::showMessage()` already implements exactly this with a timeout argument, and the label is a custom widget added with `addWidget()` rather than the status bar's own message area, so switching to it is worth considering before writing a bespoke timer. **The item's real question is what "default" means.** Candidates: the thread count from the last query (`onQueryFinished` already writes this), or empty. The count is more useful and is what the user already sees after a query completes. **Constraints.** - **Not every message is transient.** The selection count added in 0.8.0 describes current state and must persist while the selection does; expiring it would be a regression. Distinguish state from events rather than putting a timeout on everything. - The 0.8.0 selection-count code already takes back only a message it wrote itself, comparing against `m_selectionMessage`. Any general mechanism should generalise that rather than defeat it. - An error must not vanish before it is read. Sync failures already open the log pane, which does persist, but the status text should outlast a two-second timeout. ### Outcome (done) `showTransientStatus()` sets the text and arms a 6 s single-shot timer that restores the last query's thread count. Messages were classified rather than blanket-timed, which is the whole substance of the item: - **Events expire:** "Sync complete", "Nothing to undo", "Sync already running", the skip notice, the background-sync notice, and the per-action "Archive: 3 threads". - **State persists:** "Searching...", "Syncing...", "Syncing before quitting...", "Background sync running...", the selection count, and **"Sync failed (exit N)"**, per the constraint that an error must not vanish before it is read. **A test caught a real mistake while routing them.** Making the per-action message transient armed the timer during `selectAll()`, because `tagSelected()` runs on a selection that `onSelectionChanged()` had just described. The count is state and must outlive any transient still counting down, so writing it now cancels the timer. `QStatusBar::showMessage()` was considered and not used: the label is added with `addWidget()` alongside permanent widgets, so switching would mean reworking that arrangement for the same behaviour. ## 34. No overview of the Maildir itself **Observed (user, 2026-08-04):** wants "info on the maildir": total messages, number of accounts, and possibly more. **Cause:** nothing in the UI reports database-level facts. Every query returns a thread count for that query (`onQueryFinished`), but there is no path that asks notmuch about the database as a whole. **Approach.** A dialog, reached from Help or File, showing what notmuch can answer cheaply. `notmuch_database_get_all_tags()` is already wired for the completer (item 17), so the tag count is free. A total message count needs a new worker call. **Constraints.** - **This is a worker query like any other.** No `notmuch_*` pointer crosses the thread boundary; the result comes back as plain values, per `CLAUDE.md`. - **The account count comes from config, not from notmuch.** notmuch does not model accounts at all, which is why per-account subdirectories are configured in the first place. Do not try to derive it from the database. - Counting every message in a large database is not free. Measure before putting it somewhere that opens on every launch; a dialog the user asks for is the right shape, a status-bar field refreshed continuously is not. ## 35. No refresh of the thread list after a sync **Observed (user, 2026-08-04):** "auto refresh list after sync." **Cause: half of this works and the other half was deliberately not built.** A sync this window starts already refreshes: `onSyncFinished()` calls `runCurrentQuery()` on success. A background sync does not, and 0.8.0 chose that on purpose, because `runCurrentQuery()` clears the undo stack (`src/mainwindow.cpp`, the query-start path), the selection and the message pane. Firing it when a cron timer finishes would discard undo history and close the thread being read, up to six times an hour, with no action from the user. The status bar suggests pressing Enter instead. **So the work is a non-destructive refresh**, not a call to the existing one. That is a real piece of work and is why this is its own item rather than a flag. **Approach.** Re-run the query and reconcile the result against the current model instead of clearing it: keep rows that are still present, add new ones, remove the gone. The generation counter already distinguishes a stale result from a current one, so the plumbing for a second concurrent query exists. **Constraints.** - **The undo stack is cleared on query for a real reason.** Its entries refer to rows the new result set discards, and a stale entry inverts into a model update that does nothing while the database change still happens, leaving undo half-applied. A refresh that keeps the stack has to keep those references valid, which is the hard part of this item and the reason it is sized M. - The selected thread must stay selected and stay open if it survives the refresh. Losing your place is the failure this item exists to avoid. - Scroll position likewise. - A refresh must not re-trigger mark-read for the thread already on screen. ## 36. `test_mainwindow` cannot reach the worker **Observed:** twice in one session (0.8.0), a defect could not be given a regression test because `MainWindow` in tests has no notmuch database, so its `NotmuchWorker` never emits `threadLoaded`. Both were verified by hand and by a standalone model instead: - A queued `threadLoaded` repainting a pane that a multi-row selection had just blanked. The fix guards `onThreadLoaded()`, and that guard is untested: the test passes with it reverted. - A local sync reporting itself as a background one. Staging it needs `MailSync::isRunning()` true at one transition and false at the next, which needs a configured sync command and a live child process. That was tried and abandoned: it left a process running for the length of the suite and popped a dialog on the user's screen. **The machinery already exists and is not the gap.** `tests/notmuchfixture.h` builds a throwaway Maildir in a `QTemporaryDir`, runs `notmuch new` with `NOTMUCH_CONFIG` scoped to the test process, and `addMessage()` takes message-id, subject, from, date, body, unread and in-reply-to, so threads come from real `In-Reply-To` chains. `test_notmuchworker` uses it. `test_mainwindow` does not. **Explicitly rejected: a corpus built from the user's real mail.** Considered and declined 2026-08-04. The global rule against personal data in fixtures forbids it, git hooks enforce it, and this repository is public. Scrubbing is also the fragile path: one surviving `In-Reply-To` or `References` header names a real correspondent, and a scrubbed message no longer demonstrates what the real one did. Where a real message exposes a parser bug, hand-write a minimal `.eml` reproducing its **shape**, as `truncated.eml` and `hostile_filename.eml` already do. **Approach.** Give `test_mainwindow` the fixture and point the window's worker at it, so a test can select a thread and let a real `threadLoaded` arrive. **Do this when a defect needs it, not before** (user, 2026-08-04). Wiring it with nothing to test proves nothing. The two defects above are already fixed; this item is the note that the next one of its kind should be tested properly rather than modelled. **Constraint:** every existing `test_mainwindow` case constructs a bare `MainWindow` and must keep working. The fixture is per-test, not a suite-wide `initTestCase`, or every case pays for a `notmuch new`. ## 37. The worker stalls on a tag edit made during a background sync **Observed:** the user's note asks whether edits made while a background sync is running are carried by that same job or need a manual sync afterwards. The answer splits in two, and the second half is a defect rather than a question. **This entry was rewritten on 2026-08-04 after its original cause was disproved by measurement.** It first claimed the read-write open *fails* during a sync and the edit is discarded. It does not fail. That claim was written from the plausible reading of the error path at `src/notmuchworker.cpp:298-305` without ever provoking the condition, and a fix was built on it before anyone checked. Recorded here rather than quietly corrected, because the same false-cause-from-a-plausible-error-path mistake is cheap to repeat. **Cause, part one: reaching the disk is not the problem.** `applyTags` calls `notmuch_message_tags_to_maildir_flags()` (`src/notmuchworker.cpp:327`) immediately after thawing, so a `seen`/`flagged` change renames the file in the Maildir at edit time. No manual sync is needed for the change to exist on disk. Whether the *running* mbsync carries it is a matter of ordering: mbsync scans each mailbox once per run, so an edit landing after that box was scanned goes out on the next run. That is expected behaviour, not a bug, and the ten-minute cron interval bounds the delay. This half of the note is a question, answered. **Cause, part two: the write blocks, it does not fail.** Measured 2026-08-04 against Slackware's notmuch, with the lock held deliberately rather than by racing cron: - `notmuch_database_open_with_config(NOTMUCH_DATABASE_MODE_READ_WRITE, …)`, the exact call `applyTags` makes, **blocks until the lock is free and then returns `NOTMUCH_STATUS_SUCCESS`**. A C probe against a lock held for 12s returned after 9.158s with status 0; the same call with no lock held returns in 0.001s. It was never observed to return an error or to time out. - The `notmuch` CLI behaves identically (waits 3.6s and 13.2s against 5s and 15s holds, always exit 0), so this is libnotmuch's behaviour and not a wrapper's retry loop. - Therefore the error branch at `src/notmuchworker.cpp:298-305` is **not reachable through lock contention at all**. It fires only for a genuinely broken open: bad permissions, a corrupt index, a missing database. **The real defect is a stall.** `applyTagsToThreads` is invoked on the worker thread through a queued connection (`src/mainwindow.cpp:1788`), so a blocking open freezes *the worker*, not the UI. The window keeps painting and the rows show the optimistic update, but every later query, thread load and tag write sits behind that open in the worker's event queue until the lock frees. Nothing is lost and no error appears; the application simply stops responding to selections for the duration. **How bad in practice.** Bounded by how long `notmuch new` holds the lock, which on this user's already-indexed Maildir is a fraction of a second at roughly T+32s into a ~35s run (measured from `~/.local/state/mailsync.log`: runs start at :00 and reach "Processed N total files" 32-40s later). The stall is therefore usually invisible, and becomes user-visible only when `notmuch new` has real work: a first index, a large delivery, a `notmuch reindex`. That is also why it cannot be reproduced by clicking during a normal sync, and why the reproduction below holds the lock on purpose. **Reproducing it.** Racing cron does not work. Hold the lock deliberately: `notmuch tag --batch` keeps the write lock for a whole session and releases it when stdin closes, so feeding it a slow stream of no-op tag commands holds the lock for a controllable time. Verified: a competing writer blocks for exactly the remaining hold. **Approach.** Do not send a write the worker will block on. `SyncMonitor` (item 27) already reports whether a sync holds the lock, so `MainWindow` can hold the edit while `State::Running` and send it on the transition to `Idle`, which is a signal that already exists and already fires. The rows keep showing the change meanwhile, which is honest: it is what the user asked for and it is going to be applied. **Explicitly rejected: retrying on error.** That was the first implementation and it is dead code against this cause, since the error it keys off never arrives from lock contention. Keying on the monitor's state is also strictly better: it avoids the stall rather than recovering from it. **Constraints.** The optimistic-update-then-revert contract must survive: a held edit is still unsynced and must keep counting toward the pending indicator, or the quit prompt will let the user leave on work that never landed (the failure item 28 and the 0.9.0 net-state fix were both about). Do not widen the write window by holding the read-write handle open, per the read-only-by-default rule in `CLAUDE.md`. A held edit must re-resolve its thread ids when it is finally sent: `notmuch new` may have renamed files underneath it. And `SyncMonitor::State::Unknown` must not gate writes, or a platform that cannot read `/proc/locks` would never send an edit at all. **What the stall looks like, observed 2026-08-04.** Confirmed by hand with the Xapian lock held deliberately: switching between threads left the message pane showing the FIRST thread selected, and when the lock released the pane stepped through the three or four threads selected in the meantime, in sequence. That is the worker's queue draining, and it is the user-visible shape of this defect. **Reads are NOT blocked by the write lock.** Measured the same day, and it bounds how bad this is. A read-only open and a 200-thread query take 0.001s and 0.015s whether or not another process holds the write lock, identical to baseline. So `loadThread` never blocks on the lock itself. The stall is purely head-of-line blocking on the single worker thread: one blocked `applyTags` holds up every read queued behind it. Do not "fix" this by making reads lock-aware; there is nothing there to fix. **Residual gap: the 2s polling window. Accepted for now (user, 2026-08-06), and deliberately left open rather than closed.** `SyncMonitor` polls every two seconds, so a sync that starts between polls is invisible to the window for up to 2s, and a tag edit in that window is still sent straight into a blocking open. The window is 2s wide, `notmuch new` holds the lock for well under a second on an already-indexed Maildir, and reads are unaffected either way, so the exposure is small and the shipped behaviour is the pre-existing one. **The option stays on the table, to revisit:** check the lock at send time. `SyncMonitor::lockHeldIn()` is already a static, pure function over `/proc/locks` content, so `sendThreadTagChange` can call it for the cost of one small file read per tag action. That closes the window entirely. It was not taken now because it would add untested code to a change that had just been verified by hand, which is the wrong order. ### Hand test (2026-08-06): passed Verified against a real blocking open, which the unit tests cannot reach: they drive the deferral through the meta-object and never take a lock. Both locks held for 100s by the throwaway scaffold, with a tag edit made during the hold. All six expected behaviours confirmed by the user: the row kept the tag, the status message did not expire, the unsynced indicator rose, the Sync button was disabled, **the window stayed responsive**, and the held edit sent itself on release without a click. The responsiveness check is the one that mattered. The stall observed on 2026-08-04 left the message pane frozen on the first thread selected and replayed the queue on release; that no longer happens. **Related:** item 35 (refresh after sync) touches the same `Idle` transition, and both want a non-destructive path that does not clear the undo stack. ## 38. `test_mainwindow` fails when a real sync holds the lock **Observed 2026-08-04:** `theSyncButtonIsDisabledWhileABackgroundSyncHoldsTheLock` failed once during a full run and passed on every rerun. The cause is not ordering or pollution between tests: the user's cron sync happened to be running at that moment. **Cause (verified in code).** `MainWindow::buildUi()` constructs a real `SyncMonitor` on `SyncMonitor::defaultLockPath()` and the live `/proc/locks` (`src/mainwindow.cpp:467`) and starts it. Every `MainWindow` a test builds therefore observes the machine's actual sync state. The test asserts `button->isEnabled()` on a freshly built window, which is false whenever a real sync holds `/tmp/mbsync.lock`. With cron firing every ten minutes and a run lasting ~35s, roughly 6% of test runs land inside one. **Not caused by the item 37 work**, though that is when it was noticed. The test and the monitor both predate it; confirmed by stashing the item 37 changes and seeing the suite pass, then reproducing the failure with a sync live. **Approach.** The monitor is already injectable: its constructor takes a `locksPath` precisely so tests can drive transitions without real locks (`src/syncmonitor.h:59-64`), and `test_syncmonitor` uses that. `MainWindow` does not expose it. Either let the window take a locks path (config or a setter used only by tests), or have the test point `SyncMonitor` at a temporary file. The existing tests that drive `onExternalSyncStateChanged` through the meta-object are unaffected either way; it is only the construction-time state that leaks in. **Constraint:** do not simply stop starting the monitor in tests. The construction-time state IS the behaviour under test for this case, and a window that never polls would pass the assertion for the wrong reason. ### Outcome (done) `MainWindow::setLocksPathForTesting()` / `locksPath()` give the window the seam `SyncMonitor` already had, and the test points it at an empty file in its own `QTemporaryDir` so construction observes no sync. The constraint above is respected: the monitor is still constructed and still started, it simply reads a lock table the test controls. **A test seam, deliberately not a config key.** `/proc/locks` is not something a user would ever set, and a wrong value fails silently by disabling background sync detection rather than loudly. A `[general]` key was considered and rejected for that reason. **The override is process-wide and is reset at the end of the test**, since the `QTemporaryDir` holding the file is destroyed with it; leaving it set would point every later window at a path that no longer exists. **Verified by reproducing the original failure rather than waiting for cron.** Running the suite under `flock -n /tmp/mbsync.lock` fails the assertion exactly as reported when the seam is bypassed, and passes with it in place. The first mutation attempted was a dud worth recording: writing `MUTANT` into the injected lock table does not fail the test, because it is not a parseable `/proc/locks` line and `lockHeldIn()` correctly finds no lock in it. ## 39. Thread list cannot be sorted by clicking a column header **Observed (user, 2026-08-05):** "left pane columns order by clicking on the column header." **Cause (verified in code):** nothing sorts. `setSortingEnabled` appears nowhere in `src/`, no `QSortFilterProxyModel` exists, and `ThreadListModel` implements no `sort()`. The order is whatever the worker emitted, and that is fixed: `NotmuchWorker::runQuery()` calls `notmuch_query_set_sort(..., NOTMUCH_SORT_NEWEST_FIRST)` (`src/notmuchworker.cpp:135`). Clicking a header does nothing because the header was never made interactive. **Approach.** Sort in the model, not in the query. The worker's sort is over notmuch's own ordering and cannot express "by From" or "by Subject" at all, and re-querying per header click would send the user's place away for a presentation change. - `ThreadListView::setSortingEnabled(true)` plus a `sort()` on the model, or a `QSortFilterProxyModel` between them. - Persist the sort column and order into `uistate.conf`, per item 1's rule. A sort that resets on restart is item 1 restated. **Constraints.** - **Batched appends are the real difficulty.** Threads arrive in batches of 200 through `appendBatch()` while the query is still running, so a sorted view is re-sorted on every batch and rows move under a selection the user is already working in. Decide explicitly: sort only once the query completes, or accept the movement. A proxy model makes this worse rather than better, since it re-sorts on every insert by default. - The date column is displayed text but must sort as a timestamp, not as a string. `ThreadSummary` carries the real value; sort on that, not on the rendered cell. - Row styling (item 13) and the unread bold are per-row, so they follow the row and need nothing here. Verify anyway after a proxy is introduced: a proxy that forwards only `DisplayRole` drops them silently. ## 40. No live filter over the current view **Observed (user, 2026-08-05):** "search in current view", spelled out as two things: "a light filter applied live on the current view", and "a search bar appearing as soon as we type while no entry box is focused". **Cause (verified in code):** the only search is the query bar, which runs a notmuch query and replaces the result set. There is no client-side filtering of an existing result: no `QSortFilterProxyModel` anywhere in `src/`, and `ThreadListModel` has no filter of its own. Narrowing the current view therefore means writing a new notmuch query and losing the view. **Approach.** Distinct from the query bar, and the distinction is the point: this filters rows already fetched, without touching notmuch. - A filter over the model's loaded rows, matching subject and from, case insensitively. No worker round trip. - A filter strip that appears on the first keystroke while no entry box has focus, and disappears on Escape, restoring the full result set. **Constraints.** - **Type-to-filter competes with the plain-letter shortcuts.** Item 3's outcome records that a plain-letter `QAction` shortcut is suppressed only while an editable widget has focus, which is exactly the state this feature does not start in. Any binding that is a bare letter would be swallowed by the filter strip or would swallow it. Check the current defaults before choosing the trigger, and prefer appearing only for characters no action claims. - Escape already blanks the message pane (item 32). If Escape also closes the filter, decide the precedence explicitly rather than letting whichever handler runs first win. - The filter is presentation only: it must not clear the selection, the undo stack, or the query, and the pending-edit count must not move. - Interaction with item 39: a filter and a sort over the same rows want the same proxy. Whichever is built first should leave room for the other. ## 41. A message whose HTML body carries a `Content-Id` renders blank **Observed (user, 2026-08-05):** a specific message from a bulk sender opens blank, and the app reports it has no HTML part. **Cause (verified in code): the inline-part branch runs before the body branches, and returns.** `collectParts()` in `src/mimeparser.cpp` tests `g_mime_part_get_content_id()` at `:133` and, whenever a part has one, files it into `out.inlineParts` and returns at `:139`. The `text/plain` and `text/html` assignments at `:142-146` are never reached for that part. Setting a `Content-Id` on the `text/html` body part is legal and common in bulk-sender output. Such a message parses with an empty `htmlBody` and an empty `plainBody`, so `ParsedMessage::hasHtml()` (`src/mimeparser.h:115`) is false, `HtmlBuilder` falls through to a plain body that is also empty (`src/htmlbuilder.cpp:208`), and the pane renders nothing. Both halves of the user's observation follow from one wrong ordering. **Approach.** A `Content-Id` makes a part *referenceable*, not non-displayable. The two are independent, and the current code treats them as exclusive. - Register the part in `inlineParts` as today, and then still let a `text/plain` or `text/html` part fill the corresponding body slot when that slot is empty. Do not return early on the presence of a content id alone. - The existing "first one wins" rule (`out.htmlBody.isEmpty()`) already keeps a genuinely inline image from displacing a real body, so a part that is not text is unaffected by this change. **Constraints.** - **Do not use `Content-Disposition: inline` as the discriminator.** It is absent far more often than it is correct, and a body part commonly carries no disposition at all. The `attachment` check above it (`:116-117`) is already the right test for "not a body" and should stay the only one. - A part that is both the body and a `cid:` target must remain reachable under its id, or a sibling referencing it breaks. Register first, then assign. - This is `MimeParser`, which is fixture-tested: the fix needs a fixture message whose `text/html` part carries a `Content-Id`, asserting both that the body renders and that the id still resolves. Write the fixture by hand rather than from real mail, per the no-personal-details rule. **Verification:** the user's original message renders. The `cid:` rewriting of item 15's namespacing is unaffected, which the existing mimeparser tests already cover. ## 42. "Syncing..." says nothing about what is being synced **Observed (user, 2026-08-05):** the only feedback during a manual sync is "Syncing" in the status bar. The user asked for the account being synced (e.g. `Syncing provider-work`) and the operation in progress (mbsync, notmuch). **Cause (verified in code): the information is already arriving and is thrown away.** `assets/mailsync.sh` streams every mbsync and `notmuch new` line, timestamped, through `tee` (`assets/mailsync.sh:75-96`), and `MailSync` emits each chunk as `outputReceived` (`src/mailsync.cpp:65-74`), which fills the sync log pane. The status label is set once to `tr("Syncing...")` (`src/mainwindow.cpp:1569`) and never updated until the run finishes. So this needs no change to the script and no new channel; it needs the existing stream read for state. **Approach.** Derive a short status from the output already being received. - Recognise the phase from the stream: lines before `notmuch new` starts are mbsync's, and `notmuch new` announces itself. Show "Syncing mail (mbsync)" then "Reindexing (notmuch)". - mbsync prints the channel it is working on, which is the account name the user wants to see. Take it from the output rather than from config, so what is shown is what is actually happening. **Constraints.** - **Sync output is untrusted-ish input.** It comes from a local script, but it is interpolated into a status label; keep it plain text and truncate it, so a long or hostile line cannot resize the status bar or inject markup. - The status label is shared with transient messages, which expire (item 33). A sync phase is not transient and must not be cleared by that timer, nor clobber a message the user is reading. - Do not parse the output to decide success or failure. The exit status is the authority, deliberately (`assets/mailsync.sh:101-108`), and a second opinion derived from text would eventually disagree with it. - Match loosely. mbsync's exact wording varies by version, and a status line that goes blank because a string moved is worse than the current fixed one. ## 43. No "Mark all read" for the current view **Observed (user, 2026-08-05):** a "Mark All Read" button next to Sync, Archive, Delete and Undo, applying to the current view. **Cause (verified in code):** no such action exists. The registered actions are the list at `src/mainwindow.cpp:590-756`; there is `toggle_unread`, which acts on the selection, and nothing that acts on a whole result set. **Approach.** The machinery is already there and this is mostly a question of scope. `applyTagsToThreads` resolves a multi-thread selection in one combined query, per `CLAUDE.md`, so marking many threads read is one write, not N. - An action removing `unread` from every thread in the current view, routed through the same funnel, with its inverse pushed onto the undo stack as a single command. - Item 25 already established select-all, so "select all, then toggle unread" is the manual route today. Decide whether this item is that, or genuinely view-wide regardless of selection. **Constraints.** - **"The current view" is not the same as "the loaded rows".** Threads arrive in batches and a large query may still be running, so an action taken mid-load would silently skip whatever has not arrived. Either act on the model's rows and say so, or wait for the query to complete. Do not describe it as "all" if it is not. - One undo entry for the whole operation, not one per thread. A user who marks 400 threads read and then hits Ctrl+Z expects one press to be enough. - No confirmation dialog, per `CLAUDE.md`, even though this touches many threads. Undo is the answer here as everywhere else. - The pending-edit count must move by the real number of threads changed, or the quit prompt understates the work at risk. ## 44. No way to manage the filters applied at sync time **Observed (user, 2026-08-05):** "manage filters to be applied when syncing (view existing, edit, delete, create new, copy as new, dry-run)." **Unspecified, and blocked on a question the user has to answer first: there are no such filters in this application.** Nothing in `src/` applies rules at sync time; `MailSync` runs one configured command and shows its output, and `assets/mailsync.sh` is mbsync plus `notmuch new` under a lock, with no rule engine anywhere in it. So the item is not "expose the existing filters in the UI". It is one of: - **A UI over rules that live somewhere else**, e.g. the companion `mailctl` project or a hand-written notmuch tagging script the user runs after `notmuch new`. If those exist, this item is an editor for that file and its shape follows that file's format. - **A rule engine in qtmaildir**, which is a materially larger piece of work and a change to what this application is: v1 is read-and-organize over an index someone else fills. **Next step: ask the user which, and where the rules live today.** The dry-run request is the strongest hint that they have something in mind that already runs, since a dry run only makes sense against rules that exist. **Constraint if it is built here:** `CLAUDE.md` records that this project does no network protocol work at all and that fetching is external. A filter engine that rewrites the Maildir would not violate that literally, but it would put qtmaildir in the business of moving mail, which is a decision to take deliberately rather than by implementing a dialog. ## 45. Two Sync buttons on the main window **Observed (user, 2026-08-05):** "there's currently 2 Sync buttons on the main interface. UX redundant." **Cause (verified in code): they are two separate widgets built by two separate passes.** `m_syncButton` is a `QPushButton` created in `buildUi()` (`src/mainwindow.cpp:441`) and placed in the query bar row. Independently, the `sync` action registered at `:721` appears on both the File menu and the toolbar, from item 3's menu work. Nothing removed the original button when the toolbar gained one, so the window shows both. ### Revised 2026-08-06: this is a defect, not a cosmetic cleanup **The two controls do different things**, which the original write-up assumed away by treating them as duplicates. Confirmed in code after the user reported that the toolbar one "doesn't perform a sync": - The `QPushButton` handler (`src/mainwindow.cpp:464`) starts the sync, clears the log pane, shows it, disables the button, and reports "Sync already running" when `start()` returns false. - The `sync` QAction handler (`src/mainwindow.cpp:721`) is `if (m_sync->isAvailable()) m_sync->start();` and nothing else. No log pane, no disable, and the return value is discarded, so a rejected start is silent. So the toolbar button most likely *does* start a sync; every piece of evidence that it did lives in the other handler. That is item 13's failure restated: the feedback exists where the user cannot see it. **Worse, item 29 shipped for one widget only.** `onExternalSyncStateChanged` disables `m_syncButton` during a background sync (`src/mainwindow.cpp:1606`) and never touches the action. During a cron sync the toolbar Sync stays clickable and can only produce the EX_TEMPFAIL skip, which is the exact behaviour item 29 exists to prevent. The user's note about "2 sync buttons" is therefore sitting on top of a live defect rather than a redundancy. **The user's preference (2026-08-06):** keep the top-left one, next to Archive, Delete and Undo. The one beside the query bar reads instinctively as a Search button, which is a real misaffordance given what sits next to it. **Approach.** Not "pick a survivor". Move the button's handler onto the action, so the two behave identically, then drop the now-redundant `QPushButton`. The action carries its shortcut, its enabled state and its menu entry from one place, which is the whole point of item 3's conversion; the loose button is the last widget that predates it. Route the enabled state through the action too, so `setEnabled` has one target rather than two that can disagree. `QAction::setEnabled` propagates to every widget showing it, which is what makes this smaller than it looks. **Constraints.** - **The button is not just a button today.** It is disabled while a sync runs, including one started externally (item 27/29), and `test_mainwindow` asserts on it by name. Whatever replaces it has to carry that state, and the tests need pointing at the action rather than at the widget. Three tests find it via `findChild("syncButton")`, including the one item 38 just fixed, so they move together with the widget. - **A test must cover the toolbar path specifically.** The whole defect is that one of two controls was never given the behaviour, and a test that drives only the surviving widget would have passed throughout. Assert on the action's enabled state during a background sync, which is the half that silently never worked. ### Outcome (done) Built in the order the user asked for: make the toolbar control work, prove it, then remove the other one. `startSync()` is now the single handler behind every route in, the toolbar, the File menu, the shortcut and, until it was removed, the button. The old action handler was `if (m_sync->isAvailable()) m_sync->start();`, which cleared no log, opened no pane, disabled nothing and discarded `start()`'s return value, so a rejected start was silent. It now also reports when no sync command is configured rather than doing nothing at all. `setSyncBusy()` sets the enabled state on the QAction, which reaches the toolbar button, the menu entry and the shortcut at once. That was the actual defect: item 29 set a separate QPushButton and never touched the action. **Verified red first, then load-bearing.** `theSyncActionIsDisabledWhileABackgroundSyncHoldsTheLock` fails before the fix with the action still enabled during a background sync, and fails again when the action's `setEnabled` is removed afterwards. The pre-existing button test passed throughout, which is exactly why the defect survived item 29: it drove the half that worked. **Confirmed by hand before the widget was removed**, per the user's condition: reading mail grew the unsynced count, the toolbar Sync ran the sync, and the app refreshed and reported "Sync complete" at the end. **Then the QPushButton went.** Its unavailable-command tooltip moved to the action, since with no command configured the control is disabled and the tooltip is the only thing that says why. The old button test was deleted rather than repointed, being an exact duplicate of the new action test, and the unobservable-lock-table test now asserts on the action. - Check for other loose widgets doing the same thing before touching this one, so the fix is not repeated per widget later. - Removing a visible control is the kind of change that looks like a regression. Confirm with the user which of the two survives; the note says redundant, not which one is wanted. ## 46. `uiStateSurvivesARestart` fails under the offscreen platform **Observed 2026-08-06:** the full suite is green on the user's Wayland session but `TestMainWindow::uiStateSurvivesARestart` fails under `QT_QPA_PLATFORM=offscreen`, which is how the suite is run when a session must not open windows on the user's screen. Only the width is wrong: ``` Actual (reopened.size()): QSize(798x620) Expected (resized) : QSize(940x620) ``` **Cause (verified by probe, not assumed).** The offscreen platform reports an 800x800 screen. `QMainWindow::restoreGeometry()` clamps a restored window to the available screen area, so the test's 940 width comes back as 798 while its 620 height, which fits, restores untouched. That asymmetry is the tell: the state file is written and read correctly, and the zoom factor in the same test restores fine. Nothing is broken in item 1's persistence. **Not a state-file collision.** The test already scopes itself properly with `QStandardPaths::setTestModeEnabled(true)` and removes the file at both ends (`tests/test_mainwindow.cpp:229-255`), so it never touches `~/.local/state/qtmaildir/uistate.conf`. An earlier reading of this failure blamed the real state file being held by a running app; that was wrong, and the test source disproves it. **Approach.** Pick a size the smallest plausible test screen can hold, well under 800x800, and assert on that. The test is about persistence, not about large windows, so the specific number carries no meaning and only needs to differ from the default. **Constraint:** do not "fix" this by widening the assertion to a tolerance or by skipping under offscreen. Both would hide a genuine restore failure later, and the property under test (the size that went in comes back out) is exact. **Related:** the same class as item 38. Both are tests that silently depend on the machine they run on, and both were found by running the suite in a context its author had not tried rather than by reading it. ### Outcome (done) The asserted size is now 640x560, which fits the offscreen platform's 800x800 screen. Nothing in `MainWindow` changed: the persistence was never broken, only the test's choice of a window wider than the smallest screen it runs against. Verified both ways round, since this one passed on Wayland throughout: 45 of 45 under offscreen where it previously failed, and still green on the real platform. ## 47. The query bar looks unfinished, and cannot be cleared by mouse **Observed (user, 2026-08-06), immediately after item 45 removed the Sync button:** the bar "having no button seems kind of incomplete", and the user asked whether a clear icon could be shown in it. **Cause:** the query field was the last stretching item in its row, so with the Sync button gone it ran flush to the window edge with nothing terminating it. Clearing it needed the keyboard; `QLineEdit` does not draw a clear button unless asked. **Approach, and what was deliberately NOT built.** The user's first instinct was a "🔎 Search" button. That was argued against and dropped: Return already runs the query, and a button beside a text field is exactly what read as Search and got removed in item 45. Adding one back would restate items 13 and 45 in a new spot. What was built instead: - `setClearButtonEnabled(true)` on the query field. Qt draws the ✕ inside the field, shows it only when there is text, and themes it from the desktop. One line, no icon asset, no new widget. - The saved-query buttons moved from their own row onto the query row, after the field, so the bar is framed by the account dropdown on the left and the saved queries on the right. The row they left is gone and the thread list gains that vertical space. This was the user's own proposal and it addresses the "incomplete" reading directly, without adding a control. **Constraints.** - **`[queries]` is unbounded.** Three entries fit comfortably; enough of them would squeeze the field. No overflow handling was built, marked with a `ponytail:` comment pointing at item 23, which already specifies buttons-plus-menu and is where that belongs. - Button order follows `childKeys()`, which sorts alphabetically, so the buttons read Flagged, Inbox, Unread regardless of the order written in the config. Pre-existing, and its own item if it matters. **Known behaviour, accepted:** clicking ✕ focuses the field, and an empty field makes `QueryCompleter` offer everything, so the popup opens. Confirmed by the user as acceptable; suppressible if it becomes annoying in daily use. **Verification:** by hand. The tests do not click the ✕, which is a mouse path. The user confirmed the icon renders correctly, is themed, and clears the field. ## 48. Removing a tag suggests every tag, not the thread's own **Observed (user, 2026-08-06):** "when removing a tag from a thread using the input box, I get suggested all tags, not only those relevant to the message being edited." **Cause (verified in code):** both fields share one completer setup. `TagDialog`'s constructor loops over `{ m_addEdit, m_removeEdit }` and builds `new QCompleter(knownTags, edit)` for each (`src/tagdialog.cpp:163-164`), and `knownTags` is every tag in the database. That is right for Add, where the point is to reach any tag and even create one, and wrong for Remove, where the only tags that can be removed are the ones the selected threads already carry. **The data is already in the dialog.** The constructor takes `currentTags`, a `QHash` of tag to how many selected threads carry it (`src/tagdialog.h:66-67`), and uses it at `:212` to render the existing-tag display. It is simply never given to the remove field's completer, so this needs no new plumbing and no worker query. **Approach.** Build the two completers from different vocabularies rather than in one loop: `knownTags` for Add, `currentTags.keys()` for Remove. **Constraints.** - **Keep the setWidget/prefix machinery exactly as it is.** Both fields hold a comma-separated list, and `QLineEdit::setCompleter` is the documented trap this dialog already works around, hit twice in this codebase. Only the candidate list changes; the wiring does not. - **Completion stays a suggestion, not a whitelist.** The dialog's own comment records that a tag absent from the list is exactly what it exists to create. For Remove that matters less, but typing a tag not in the list must still be possible rather than blocked, so nothing may start validating input against the candidates. - On a multi-thread selection `currentTags` is the union across the selection, with counts. That is the right set to offer, since removing a tag two of three threads carry is meaningful. Do not filter to tags every thread has. **Verification:** a test can construct the dialog with a known `currentTags` and assert the remove field's completer offers only those. The keys must be typed, not `setText()`, since `setText` does not drive a completer at all, which `CLAUDE.md` records. ## Deferred, unsized, or split out Items noted while triaging but not part of the original list. Same numbering sequence, appended as they arise. | # | Item | Why here | |---|------|----------| | 12 | `HtmlBuilder` CSS is light-theme only | Split from item 5. Hardcoded greys and no background color; a dark desktop theme will render message bodies badly. Fix likely means passing palette-derived colors into the CSS, which affects `HtmlBuilder`'s tests. | ## Adding to this document Append a row to the status table with the next free number, then a section using the same shape: **Observed** (what the user saw), **Cause** (the code, with file and line, verified not assumed), **Approach**, **Constraints**, and **Verification** where it is not obvious. Do not renumber. Do not delete: mark `dropped` with a reason.