# Settings redesign — deferred test runs No contract is executed while the settings redesign is in flight: many are live harnesses that open windows, drive overlays, and run display transactions on the real desktop. Everything below runs **once, at the end of the redesign, with Gabriel's go-ahead**, and failures get fixed then. ## The run - `panama test` — the full suite (**169** contracts as of the phase 6 Sound wave; the top-level README's count line is set to match and is itself checked by `setup/readme-contract`). ## Known items to verify or investigate at the end - `quickshell/welcome-contract` — failed once ("the welcome screen did not open") during a full-suite run storming the live session; passed in isolation minutes earlier after the Welcome.qml comment edit. Suspected contention flake, not a regression. Confirm. - `setup/readme-contract` — counts contracts; keep the README number in sync as later phases add contracts (phase 2 added `phone-page-contract`). - Phase 2 additions already written and passing when last run: `my-home-settings-contract` (renamed from `home-phone-settings-contract`), `phone-page-contract`, extended `home_assistant_bridge_test.py` and `kdeconnect_bridge_test.py`. - Each later phase (Appearance, …) appends its new/changed contracts here instead of running them. ## Phase 3 (Appearance) — append below The contracts wave is done. Everything below is written and **still to be RUN**. Nothing in this list has been executed against a live harness: the static halves were checked against the tree, but every harness run and the full-suite pass are deferred to the end-of-redesign sweep. ### New contracts (3) | Contract | What it pins | |---|---| | `quickshell/theme-catalog-contract` | `config/themes.json` shape (10 themes, 6 dark / 4 light), every palette and ansi block accepted by the model's own validators, moon and day byte-identical to the shell's pre-theme literals, `ThemeCatalog.qml`'s embedded fallback carrying both, and `Theme.qml` holding no palette ternary. | | `quickshell/video-wallpaper-contract` | Three independent pause reasons (`FocusModes.gameRunning`, `Battery.acOnline` plus the preference, `manuallyPaused`) and pausing over mpv's JSON IPC; the mpvpaper argv (`hwdec=vaapi`, `no-audio`, `loop-file=inf`, `input-ipc-server=`); the hyprpaper stop/start choreography and `Wallpaper.refreshActive()`; `Wallpaper.qml`'s video routing branches; the helper's 60-file cap, depth-2 scan and mp4/mkv/webm filter; the still frame for the lock screen; `WallpaperIndicator` in `Bar.qml`'s right-hand row with its `visible` binding, spoken name and no animation; the two schema keys; the doctor check id. | | `quickshell/settings-titlebar-contract` | No minimize or maximize anywhere in the settings chrome (comments may say the words, code may not); `height: shown ? 48 : 0` so hiding collapses rather than leaving a hole; `buttonsLeft` side-awareness with exactly one anchor released per element; the close button's `activeFocusOnTab`, `Accessible.role`/`name`, Return/Space handlers and focus treatment, and that it is the only button; Escape declared on the shell rather than inside the bar; the `panamaTitlebar` schema entry and its Appearance row. | ### Updated contracts (6) | Contract | What it now pins | |---|---| | `quickshell/accent-controls-contract` | Rewritten around the new editor: the nine surviving components and their qmldir lines, `AccentPicker`/`ThemeProfilePicker` staying deleted *and* unregistered, the four wells and their single `apply()` path, one hyprpicker invocation aimed by a remembered target, `ColorWell`'s hex validation committing on Enter and focus-out but never per keystroke, the six HSV labels, the debounce (the write lives in `commitTimer`, `changeChannel` writes nothing, `releaseTimer` hands the sliders back), `commitActive` recomputing `accentName` through `nearestCuratedName` with `selectProfile`/`updateActive` both routing into it, `Theme.qml` reading `ThemeProfiles.activePalette`, the Themes and Theme editor tabs, four search labels, and the no-animation ban extended over all nine components. Live half rewritten against the rebuilt harness. | | `quickshell/theme-profiles-contract` | Node half rebuilt for the optional-field model: `shippedProfiles()` with no argument still returns the three built-in fallbacks (back-compat), the ten catalog records survive with palettes and ansi and no effects, palette/ansi/effects survive a stored record with per-key effect clamping, an invalid palette drops the FIELD not the profile, the caller's shipped list owns the id and name space, `editProfile` passes untouched fields through and a shipped fork carries the whole palette, `nearestCuratedName` mappings (mauve→orchid, gruvbox-yellow→amber, grey→slate, per scheme), and `derivePalette`/`resaturatePalette`/`deriveAnsi`/`mixHex` producing palettes the validators accept. Live half now pins the per-mode selection flow: a light/dark flip returns to the theme chosen on that side, never a forced default. | | `quickshell/desktop-style-contract` | `titlebarMaximizeButton` and `titlebarDoubleClick` asserted **gone** from the schema and from `DesktopStyle`, along with `action-double-click-titlebar`; `panamaTitlebar` added (bool, def true, group titlebar); the button layout pinned close-only on both sides with `minimize`/`maximize` banned from the function body; the Appearance greps moved to Fonts/Sizes/Rendering with exactly five `FontPicker` rows and their five role labels, plus the honest-titlebar subtitle. | | `quickshell/settings-ownership-contract` | The ColorScheme block was pinning `inactiveBorderDark`/`inactiveBorderLight`, which no longer exist. It now pins the inactive border as the active theme's `gutter`, bans a regrown literal, pins the accent border roles through the new `hyprColor(value, alpha)` signature, requires both roles to be restated on a theme change, and cross-checks Hyprland's startup literals against moon's and day's gutters in `themes.json`. | | `quickshell/lock-screen-settings-contract` | The "between Background and Shell typography" ordering check named a card that no longer exists. It now pins Background → Video playback → Lock screen order, and that all three sit on the Background tab. | | `quickshell/settings-search-contract` | Seven fixed cases added for the new surface: themes, theme editor, dark mode, Catppuccin, Gruvbox, video wallpaper, titlebar. The schema-label sweep already covers the new keys automatically. | ### Verified against the new tree, no edit needed - `quickshell/settings-hardcoded-values-contract` — its scope is `Settings.qml`, which the theme work did not touch; `Theme.qml`'s literals are covered by `theme-catalog-contract` instead. - `quickshell/wallpaper-service-contract` — already carries the video routing greps. - `quickshell/wallpaper-settings-contract`, `wallpaper-policy-contract`, `settings-nav-contract`, `settings-pages-contract`, `manual-contract`, `settings-docs-contract`, `qmldir-registration-contract`, `settings-sync-contract`, `settings-backup-contract` — checked, nothing stale. - `quickshell/panama-doctor-contract` — already lists `input.video-wallpaper`. ### Docs updated in the same wave - `modules/settings/README.md` — new **Appearance** section (Themes, Theme editor, backgrounds still and moving, the honest titlebar); the border ownership paragraph corrected to the theme's gutter. - `manual/05-making-it-yours.md` — rewritten Appearance chapter: the two galleries, per-mode memory, the four-well editor, video wallpapers, and why there is no minimize. - Top-level `README.md` — contract count 162 → 165, confirmed by `setup/readme-contract`. ### Still open before the run - The parallel pipeline wave's files (`gtk-theme-contract`, `lock-screen-theme-contract`, `palette-contract`, the two bridge tests) are not counted above. If that wave adds contracts, the README count line and the count in this file both need bumping again before the suite runs. - `AppearancePage.qml`'s `tab` property defaults to `"background"` while its own comment says Themes leads. Decide which is intended before the run; nothing currently pins it either way. ## Phase 4 (Shell category) — append below Spec: `2026-08-24-shell-category-redesign.md`. Desktop & Dock became **Shell** (Bar · Dock · Control Center · Tiling · Workspaces), System gained **Sync & Backup**, and the dock got its feature wave. Unlike phases 2 and 3, the static and stubbed contracts in this wave **were run** as they were written, and every one of them passed in isolation against the tree. Two things are still deferred. The **live-harness halves** were not run — the session was locked, and `dock-position-contract` opens a probe shell while `settings-pages-contract` starts a settings harness, so those ran static- only (`PANAMA_SETTINGS_STATIC_ONLY=1`) or not at all. And the **full-suite pass**, the only thing that catches contention between harnesses, happens next with Gabriel driving. ### New contracts (1) | Contract | What it pins | |---|---| | `quickshell/bar-visibility-contract` | The bar's own neutral family: `barFg`/`barFgDim`/`barFgMuted` exist, each forced tone is anchored on one literal with both dims mixed off it, and the `theme` branch returns `root.fg`/`fgDim`/`fgMuted` **by identity** rather than a copied colour. All thirteen bar-text files bind to those tokens and none paints neutral text with the `fg` family (`Theme.alpha(Theme.fg, …)` hover and separator fills are allowed; semantic tones were never in scope). `Bar.qml`'s scrim reads `visible: Settings.barBackdrop`, its shadow reads `layer.enabled: Settings.barTextShadow` over exactly one `MultiEffect` layer, and neither may be a literal `true` — both shipped hardcoded during the build, which is the regression this exists for. Plus the four widget gates ANDed with their state conditions, `VitalsWidget`'s whole-pill `visible`, `exclusiveZone: Theme.barHeight` still literal, no animation anywhere in `Bar.qml`, and the two right-click jumps landing on `bar`. | Mutation-checked while writing: hardcoding the shadow, returning a literal from the `theme` branch, putting one widget back on `Theme.fg`, deleting the vitals pill's own `visible`, and adding a `Behavior` to `Bar.qml` each fail it with a message naming the actual problem. ### Updated contracts (5) | Contract | What it now pins | |---|---| | `quickshell/dock-position-contract` | `DockPinsEditor` → `DockPinsStrip`: `preventStealing` moved to the strip, the retired ↑/↓ buttons replaced by the strip's own keyboard path (Left/Right move, Delete unpins), and a new section for the **live** dock's drag-to-reorder — commits once on release, and measures a slot from a real icon rather than a constant, because a `DockItem` is taller than it is wide and a constant is wrong on one orientation. | | `quickshell/settings-jump-contract` | `DockContextMenu`'s "Dock settings" now opens `dock`, not the retired `desktop`. | | `quickshell/settings-pages-contract` | Six new pages added to the page sweep (Bar, Dock, ControlCenter, Tiling, Workspaces, Sync); `vitalsIntervalMs` and the graphics ChoiceGrid now required on `BarPage` rather than `AppearancePage`, since the vitals are bar content and not surface appearance. | | `setup/projects-contract` | The saved-projects list moved from the deleted `DesktopPage.qml` to `WorkspacesPage.qml`. | | `quickshell/panama-commands-contract` | The launcher's new `dock-add-app` → `panama-action dock-pin` command. | ### Verified against the new tree, no edit needed Every one of these was **run** and passed after the phase-4 changes landed: - `quickshell/settings-search-contract` — the new `bar`/`controlCenter`/ `datetime` groups and the re-pointed `dock`/`multitasking`/`edges`/`master`/ `notices`/`focus` routes are covered by the schema-label sweep already. - `quickshell/settings-ownership-contract` — the six intentional mirrors and the eleven README literals survived the rewrite; no new mirror was introduced. - `quickshell/settings-nav-contract` — 14 categories, 38 leaves, 2 retired ids (`home-phone`, `desktop`). - `quickshell/manual-contract`, `gnome-handoff-contract` (15 handoffs against 38 pages), `control-center-contract`, `welcome-contract`, `accent-controls-contract`, `theme-catalog-contract`, `desktop-style-contract` — checked, nothing stale. `welcome-contract` passed in isolation again here, which does not settle the phase-3 flake above: that failure only appeared under a storming full-suite run. ### Docs updated in the same wave - `docs/settings.md` and the 37 `settings-*` launcher commands — regenerated by `panama-settings-docs` and `panama-settings-commands`; both `--check` modes clean and both generators verified idempotent. `settings-desktop` is deleted, `settings-bar`/`-dock`/`-control-center`/`-tiling`/`-workspaces`/`-sync` are new, and `dock-add-app` joins them. - `modules/settings/README.md` — new **Shell** section (the five tabs, the bar token design and why it exists, the pins strip and the live dock's gestures, the Control Center rule that only real sections get toggles) and a new **System › Sync & Backup** section. Appearance corrected from six tabs to five, saying where the Shell tab went. - `manual/05-making-it-yours.md` — new **Shell** chapter section (bar legibility, widget switches, why `use24Hour` is not there, the pins strip, the dock's drag/right-click/scroll/preview gestures, **Add App to Dock**, Control Center sections) plus **Carrying settings between machines**. `manual/03-windows-and-workspaces.md` — the multi-display workspace switch now points at Displays, which is where it actually is, instead of the deleted Desktop & Dock page. - Top-level `README.md` — contract count 165 → 166, recounted the way `panama test` collects (executable, or `*_test.py`, excluding fixtures and `__pycache__`). ### Still open before the run - Four contracts in the working tree changed for reasons **outside** this phase and are not accounted for above: `declared-assets-contract` (`pkill`, from the video wallpaper work), `declared-dependencies-contract` (`cmp` → diffutils), `panama-doctor-contract` (29 → 30 check ids), and `lock-screen-helper-contract` / `video-wallpaper-contract` (theme-derived literals and the mpv IPC key quoting). Confirm each belongs to a wave that intended it before the suite runs. - `tests/setup/update-command-contract` is untracked and belongs to the separate `panama update` design, not to this redesign. It **is** inside the 166. - `quickshell/dock-position-contract` has never had its **live** half run since the strip landed: it opens a probe shell, and this wave ran under a locked session. Its static half is what was verified. Run it first in the sweep. - `quickshell/settings-pages-contract` passed static-only for the same reason. Its compositor-integration half — the settings harness, its IPC, and the page-open checks — is unverified against the six new pages. - `Bar.qml` has one stray indentation glitch at its first `Row` (line 105). Cosmetic, untouched here because the file is not this wave's to reformat. - 2026-08-24 full-suite run: 166 contracts, all green except `displays-contract` and `switcher-contract`, which are live interactive tests that cannot run behind hyprlock (both passed in the same day's unlocked run; neither subsystem changed in phase 4). Re-verify after unlock. **Still pending** — and `displays-contract` has since changed (phase 5), so this run is now the first one that exercises the new material as well. ## Phase 5 (Displays) — append below Spec: `2026-08-24-displays-redesign.md`. The Displays page became canvas-first, the per-monitor record grew VRR / colour profile / bit depth / SDR trim / mirroring, and `pushLayout` stopped clobbering `monitors.lua`'s colour values. **Nothing in this wave was run.** The test window was closed while it was written: these are live harnesses that drive the real compositor through display transactions, and three agents were editing the tree concurrently. What *was* verified is listed as static below — evaluated directly against the implementation files without a harness, by loading `monitors.lua` under a stub `prefs` and by evaluating `DisplayLayout.js` in node. Everything else is deferred to the sweep. ### Contracts changed (4) | Contract | What it now pins | Verified | |---|---|---| | `quickshell/display-transaction-contract` | The extended record end to end: `applyRecord` merging one field at a time; `vrr` **omitted** when `vrrMode === -1` and emitted when it is not; neutral `sdrsaturation` omitted rather than written; a mirrored rule asking for `position = "auto"`; the mirror x/y carve-out in `matchesLayout`, and that it does not leak to an unmirrored record; a framebuffer format with no 8/10 mapping skipping the bit-depth assertion instead of blocking Keep; `confirm()` persisting the whole record; old-shape stored blobs still validating and an impossible `vrrMode` not; and seven refusals (self-mirror, primary mirroring, absent target, out-of-range vrr/profile/depth/SDR). | Bash and Python syntax; every new static grep checked against the landed `Displays.qml` (including the `vrrMode >= 0` omission branch in `monitorRule`) and against the extended harness; the fake compositor's rule parser dry-run on a real `monitorRule` payload, covering the `position = "auto"` and `mirror =` branches and the `mirrorOf: "none"` readback spelling. Every IPC assertion is **deferred**. | | `quickshell/display-arrangement-contract` | **Flipped**: the canvas is no longer hidden below two displays. The `visible: … monitors.length` gate is now asserted *absent* from the `DisplayArrangement` element (by AST-free block scan, so the selector chips and Workspaces card may keep theirs), with a solo hint string, a `draggable` flag, and an `enabled:` binding on the `DragHandler`. Plus the mirror badge: `Mirrors ` in the component, `mirrorOf` read off the rects, and two new harness fixtures — solo renders one rect with `draggable == false`, mirrored stacks rect 1 on rect 0 and flags it. | **Statically verified** against the rebuilt `DisplayArrangement.qml`: every grep hits, the `DragHandler`'s `enabled:` is found by the brace-matching helper, and the flip check was mutation-tested both ways — it fails on the pre-redesign page (where the gate sat on the enclosing card, not on the canvas) and passes once the gate is gone. The two new harness fixtures are **deferred**. | | `quickshell/display-layout-contract` | Mirror geometry in `DisplayLayout.js`: a valid mirror validates; the mirrored record keeps its stored coordinates through `normalize` (the primary's anchor does not apply to a position nothing reads back); it contributes nothing to `bounds`; `canvasRects` stacks its rect on its target's and carries `mirrorOf`/`mirrored`. Five refusals: self, absent target, mirroring primary, a two-hop chain, and a non-string. | **Statically verified** in node against the real `DisplayLayout.js` — every expected value in the two new `jq` filters came from that run, including the 3140/80 the mirrored record keeps. Harness plumbing deferred. | | `quickshell/displays-contract` | The Lua consumer half: `color_profile` / `bitdepth_value` / `vrr_value` / `sdr_value` / `mirror_value` present, `cm`/`bitdepth`/`sdrbrightness`/`vrr`/`mirror` emitted under Hyprland's own key names, a mirrored entry's `position` forced to `auto`, neutral SDR saturation and `vrrMode = -1` written as absence rather than as a value, and an entry with every new field impossible surviving with its geometry while each bad field drops. Plus the extended-record greps on `Displays.qml`. | **Statically verified**: the whole `LUA` block was run against `config/dot/hypr/monitors.lua` with a stub `prefs` and passes. The `Displays.qml` greps were checked by hand and all hit. The live compositor half is deferred. | ### Cross-agent shapes these contracts now pin Written from the spec's pinned API while agents A and B worked in parallel, and re-checked against their files as those landed: - `DisplayArrangement.canvasSnapshot()` exposes `draggable` alongside `rects`/`scale`, and passes `canvasRects`' `mirrorOf`/`mirrored` through — it returns `canvasData.rects`, not the solo-shrunk `tiles`, which is what the new fixtures assert against. Confirmed in the landed component. - The solo hint is pinned as the prefix `One display connected` rather than the full sentence, so the em dash cannot break the grep. - The mirror badge is pinned as `Mirrors ` in `DisplayArrangement.qml`. - `soloFixture`/`mirrorFixture` mutate `fixtureService.monitors` and call `resetDraft()`, which is what the component's own `onMonitorsChanged` does. Whether that ordering settles before `canvasSnapshot()` reads back is the one thing only a run can answer. ### Still open before the run - ~~`PreferenceSchema.qml`'s stale `displays` detail string~~ — resolved: the detail now names color, VRR override, and mirroring, and the matching grep in `displays-contract` was updated in the same commit. - `displays-contract` also greps `DisplaysPage.qml` for `selectedOutput`, `scalesForMode(`, `primaryFirstMonitors.map(` and `enabled: Displays.canConfirm`. All four still hit, but the page was still the pre-redesign one when this was written — re-check them once the rebuilt page lands, particularly `primaryFirstMonitors.map(`, since the spec replaces the "Connected display" picker card with selector chips. - No contract file was added or removed, so the README count line stays at **166** and `setup/readme-contract` needs nothing. - Run order for the sweep: `display-layout-contract` first (pure geometry, no compositor), then `display-transaction-contract` (fake compositor on `PATH`), then `display-arrangement-contract`, and `displays-contract` last — it is the only one that drives the physical display, and it refuses to start from a scale that does not match what `monitors.lua` ships. ## Phase 6 (Sound) — append below Spec: `2026-08-24-sound-redesign.md`. The Sound page became a complete PipeWire surface: honest device list with badges and a ghost row, per-channel speaker test, microphone test, per-app mic mute and per-app output routing, alert-sound theme, over-amplification, and native device profiles in place of the GNOME handoff. **Nothing in this wave was run.** Three agents were editing the tree concurrently and every harness here drives the live audio graph — the page harness constructs the real Sound page against the session's own PipeWire, and the services harness starts a shell. What *was* verified is listed as static below: bash syntax on every contract, the JSON and pw-metadata fixtures parsed, and each service's own parsing logic replayed in node or Python against the landed source so the expected values in the assertions are the values the code actually produces. ### New contracts (3) | Contract | What it pins | Verified | |---|---|---| | `quickshell/sound-cards-contract` | `SoundCards`' parse of `pactl -f json list cards`: profiles keyed by name becoming an ordered list sorted by pactl priority (the fixture deliberately lists them out of order, so insertion order fails), a profile pactl marked unavailable kept and flagged rather than dropped, `device.description` as the card name, the port hint naming the connected port and reading exactly `No port connected` when none is, `set-card-profile` argv, an empty card or profile name starting no write, unparseable output and a failing read both degrading into `lastError` with an array still in `cards`, and recovery on the next refresh. Plus the static grep on the live `-f json` command, which the fixture seam means nothing else exercises. | **Statically verified**: `SoundCards.parse` and `portHintFor` replayed in Python against the fixture — profile order, availability flags, descriptions and both port hints match the assertions exactly. Every IPC call is **deferred**. | | `quickshell/sound-routing-contract` | `SoundRouting`: every stream of a group moved, by `object.serial` and not by node id (both are plausible numbers in a log); a serial-less stream falling back to its node id; an empty group or unnamed sink running nothing; and `routeToDefault` releasing the pin through `pw-metadata -n default -d target.object` **and** the legacy `target.node`, never through `move-sink-input` — moving a stream to the current default pins it there, which is the bug the button undoes. Plus the id asymmetry both ways, `busy`/`lastError` on refusal, recovery, and the spec-required comment above `routeToDefault`. | **Statically verified** against the landed service: the argv shapes, the serial fallback, the two metadata keys and the early returns all read directly off `SoundRouting.qml`. The runs are **deferred**. | | `quickshell/sound-defaults-contract` | The one distinction the ghost row depends on: `default.configured.audio.sink` and not `default.audio.sink`. The fixture sets them to different values and writes the configured one first, so neither "last key wins" nor a machine whose configured device is present can make it pass by accident. Also: an unconfigured session reading as `""` rather than as the effective device, an empty store, a non-JSON value on an unrelated key not taking the read down with it, a failed read leaving nothing invented, recovery, the ghost record and its label (Bluetooth address, AirPlay hostname, USB product string, empty), and a static ban on reading `preferredDefaultAudioSink`, which is null in exactly the case the service exists for. | **Statically verified**: `SoundDefaults.parse` and `label` evaluated in node against all five fixtures — every expected string in the contract came from that run. The IPC half is **deferred**. | ### Updated contracts (4) | Contract | What it now pins | Verified | |---|---|---| | `quickshell/sound-page-contract` | Rebuilt around the new page. Kept: the two `SoundDeviceList`s, the Dictation negatives and handoff, the balance and device-row pins, the Quick Settings sharing. Dropped: `openGnomePanel("sound")` and `label: "Device profiles"` — both now asserted **absent**, replaced by the native profile card (`title:`, `SoundCards.cards`, `setProfile(`, `refresh()`, `lastError`). Added: `captureApplications` filtered by `AudioInStream` and reaching `SoundCaptureRow` with a per-app mute, a tracked `PwObjectTracker` over capture nodes, the row hiding itself when nothing is listening; the ghost row asked of `SoundDefaults.absent(root.output)`, rendering after the `Repeater`, and non-interactive by a brace-scan proving every `TapHandler`/`HoverHandler` carries `!root.ghost`; the `device.api` badges; over-amplification gated at 1.5 on the page and on Quick Settings' **output** slider only, with the >100% region marked; the four `SoundRouting` calls in `ApplicationVolumeRow`. The no-shell-out ban is unchanged on the four core files and now extended over all eleven page components. | **The whole static half was run** against the landed tree and passes. The harness half is **deferred**. | | `quickshell/application-volume-contract` | Grouping pins unchanged; new `clampVolume` case for the `max` parameter — `setVolume(group, 1.4, 1.5)` lands 1.4 and unmutes, 2.5 clamps to 1.5, **no** max clamps to 1 (the default must not quietly follow the preference), a negative clamps to 0, and a non-numeric value changes nothing and returns false. | **Statically verified**: the landed `AudioStreams.js` evaluated in node produced byte-identical output to the `jq` filter's expectations. The IPC run is **deferred**. | | `quickshell/osd-helper-contract` | Over-amplification and the blip, both out of `settings.json`. Every run now gets its own `XDG_CONFIG_HOME`, because the helper would otherwise read Gabriel's real preferences and pass or fail on which switches he has on. Pins `-l 1.5` on volume up **and down** (wpctl clamps the result, so coming down from 130% would snap to 100% without it), `-l 1` on the microphone in the same run, `-l 1` for off / key absent / file absent / malformed JSON, the blip on up/down/toggle and not on brightness or microphone, silence with `volumeChangeBlip` false, and silence with no sound file — with the OSD still shown in every degraded case. | **Bash syntax only.** The helper is agent A's and had not landed when this was written; see the open item below. | ### Cross-agent shapes these contracts pin Written from the spec's pinned API while agents A and B worked in parallel, then re-checked against their files as those landed: - `PANAMA_SOUND_CARDS_FIXTURE` and `PANAMA_SOUND_DEFAULTS_FIXTURE` are **file paths** the service `cat`s in place of the live command, read once at singleton construction. So a contract changes what the file *says* between cases rather than where it points, and deletes it to make a read fail. Confirmed against both landed services. - `sound-services-harness.qml` is new and shared by all three service contracts. Whichever contract is running sets an inert fixture for the two services it is not testing, so nothing reaches the live daemon and every line in a command log belongs to the service under test. - `SoundDeviceList` asks `SoundDefaults.absent(output)` rather than comparing configured names itself — the service owns both the comparison and the label. The contract followed B's refactor to that shape. - The ghost label is A's `SoundDefaults.label()`, so it reads `Bluetooth device (AA:BB:CC:11:22:33)` **with** parentheses. `SoundDeviceList` briefly had its own `tidyName()` producing the same string without them; the harness and the assertion track the service's version. ### Docs updated in the same wave - `services/SettingsSearch.qml` — the seven hand-written Sound entries from the spec (Balance, Speaker test, Microphone test, Alert sound, Applications using the microphone, Move an application's audio, Device profiles) on top of the four that were already there, and `groupPages` gained `"sound": "sound"` so the new schema group self-indexes. - Top-level `README.md` — contract count 166 → 169, recounted with the same `find` `setup/readme-contract` uses; that contract was run and passes. ### Still open before the run - **`osd-helper-contract` is written against a `panama-osd` that had not landed.** It assumes two things of agent A's helper: that the settings file is resolved as `${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json` (the `panama-idle` / `panama-lid` spelling, not `panama-palette`'s `PANAMA_SETTINGS` override), and that the blip's sound file can be overridden with `PANAMA_OSD_BLIP_SOUND` (matching the existing `PANAMA_OSD_*` seams in the same script), which is the only way to exercise the missing-file branch deterministically. If A spelled either differently, the env names in `run_helper` are the only lines that need changing. Reconcile before running. - The contract also now asserts `-l` on the **down** step, which the pre-redesign helper did not pass. The reasoning is in the contract; if the landed helper only limits the up step, that is a real bug at 150% and not a contract to relax. - `sound-page-contract`'s runtime half asserts `.captureApplications >= 0` and `.captureRowVisible == (.captureApplications > 0)` — true on a machine where nothing is recording, which is the ordinary case. Getting a positive capture count under test would mean holding the microphone open from the contract; the grouping itself is covered by `captureTypesValid` and by the static greps. - No contract in this wave has had its harness started. Run order for the sweep: `sound-defaults-contract`, `sound-cards-contract`, `sound-routing-contract` (all three fixture-fed and cheap), then `application-volume-contract`, then `osd-helper-contract`, and `sound-page-contract` last — it is the only one that constructs the real page against the session's own audio graph. - Nothing in this wave plays a sound on purpose, but `sound-page-contract` constructs `SoundPage`, whose microphone test and channel strip are one IPC-less click away from `pw-play`. The harness exposes no method that triggers either; keep it that way. ## Stabilization pass — 2026-08-24 — THE RUN HAPPENED Three read-only reviewers swept the whole redesign (37 findings), three fix waves applied them all, and the full suite then ran three times with Gabriel's go-ahead: 162/169, 168/169, then **169/169 green**. The seven interim failures were four suite-contention flakes (pass solo; theme-profiles hardened with a catalog-settle wait) and three contract bugs (display-layout's stale mirror expectation, osd-helper's non-atomic stub log + a set -u `local` expansion trap, sound-cards' jq context rebind). displays-contract and switcher-contract — the locked-session holdovers — both pass unlocked. Later phases append new deferred contracts below as before; this line is the baseline they diverge from. ## Phase 7 (Notifications & Focus) — append below Spec: `2026-08-24-notifications-focus-redesign.md`. Notifications & Focus became two tabs. Per-application rules grew from one bool to seven fields with a real editor behind them, Do Not Disturb gained a second exception, and focus modes got create/rename/delete/reorder plus trigger-kind editing on a page of their own. **Nothing in this wave was run.** Three agents were editing the tree concurrently, and the one runtime harness here (`notification-app-rules-contract`) boots a real Quickshell against a private D-Bus session. What *was* verified is listed as static below: `bash -n` on every changed contract, and — for the two contracts whose assertions are computed — the extracted blocks replayed in `bun` and `python3` against the landed services, so the expected values in the assertions are the values the shipped code actually produces. ### New contracts (0) None. The redesign added surface to services and pages that already had contracts, so the README count line stays at **169** and `setup/readme-contract` needs nothing. ### Updated contracts (4) | Contract | What it now pins | Verified | |---|---|---| | `quickshell/notification-app-rules-contract` | The rule shape, as two properties rather than a literal: every field past `enabled` is **optional** (an old `{enabled}`-only blob reads back with `sound`/`display`/`urgency`/`lastSeenMs`/`name`/`icon` at their defaults) and the field set is **closed** (unknown keys, the stale lock-screen pair, and out-of-vocabulary `display`/`urgency` values are all dropped; a non-numeric or negative `lastSeenMs` reads as 0). Plus: `forgetApp` deleting the key rather than writing an all-defaults rule; `rememberApplication` stamping `lastSeenMs`/`name`/`icon` from the clock; `effectiveUrgency` and all four of its consumers (`playBell`'s low check, `notificationTimeoutMs`'s critical duration, the breakthrough gate, `NotificationCard`'s critical edge); the per-app `sound` switch in `playBell`; `display: "history"` reaching history and unread but not the popup list or the bell; and the popup gate literal `!root.doNotDisturb \|\| FocusModes.allows(appId) \|\| breaksThrough` with `breaksThrough` being `Settings.criticalBreaksThrough` ANDed with effective-critical. The schema key and its `Settings` reader are pinned too. Page assertions now read the page **and** the components it delegates rows to (`NotificationAppRow.qml`), so pulling the expanded body into a component does not read as the feature being deleted. Runtime: four new fixtures — `historyOnly`, `forgetting`, `urgency`, `breakthrough` — and the two existing jq literals became field-by-field predicates, because `lastSeenMs` is a wall clock that cannot be written down. | **The whole static half was run** against the landed tree and prints PASS. The runtime half is **deferred**. | | `quickshell/focus-modes-contract` | Every existing pin is untouched and still passes: conditions-not-alarms, the midnight-crossing / malformed / zero-length schedule arithmetic, single DND ownership, the gaming hook reporting rather than silencing, the retired `gamingSilenceNotifications` key staying out of the schema, and the exception list being both consulted and editable. New: `createMode`/`removeMode`/`renameMode`/`moveMode`/`setTriggerKind`/`seedTrigger`/`uniqueId`/`hasMode` by name; a `bun` replay of `seedTrigger` (all five kinds and their seeds, handed-in fields kept, unknown kinds refused with `null` rather than stored) and of `uniqueId` (slugging, suffixing past a taken id, and the `"mode"` fallback); the "order is priority" claim having to appear on the page; and the manual-mode semantics being *preserved* rather than invented — `automatic` still filters manual-only modes out and the fall-through still carries its note. The editable-list needle moved from `NotificationsPage.qml` to the Focus surface (`FocusPage.qml` + `Focus*.qml`), because the chips live in `FocusModeRow.qml`. | **Statically verified end to end**: every grep re-run against the landed files, the schedule arithmetic replayed in `python3`, and the new API block replayed in `bun` — all green. | | `quickshell/settings-pages-contract` | `Focus` added to the component list (root type `SettingsPage`, no copied Flickable scaffold) and `focus` to the runtime page-routing sweep. The four Notifications sliders and the `zeroLabel: "Never"` rule are unchanged and still hit. | **Static half verified**: `FocusPage.qml`'s root type and the four slider regexes replayed in `python3`. The routing sweep is **deferred** — it starts an isolated shell. | | `quickshell/settings-jump-contract` | GamingPage's "Open Focus" now has to go through `ShellState.openSettings("focus")`, and assigning `ShellState.settingsPage` by hand is banned there — the old code did exactly that, which skipped `SettingsRoutes.resolve()` and so skipped this contract's own guard entirely. `NotificationCard`'s jump stays `"notifications"` and is unchanged. | **Statically verified** against the landed `GamingPage.qml` and `NotificationCard.qml`. | ### Contracts deliberately left alone - `quickshell/search-routing-contract` — needed no edit. It derives page files from `SettingsShell`'s switch, so `focus` resolved to `FocusPage.qml` the moment B landed the case and the Component. Replayed by hand against the landed tree: **144 routed settings, 0 violations** with the focus group moved. - `quickshell/settings-window-contract` — enumerates no tabs. It routes `displays` and the retired `desktop` id only. - `quickshell/settings-ownership-contract` — its duplicate-row scan and its `groupPages` parse were replayed against the edited `SettingsSearch.qml` and still pass. - `setup/readme-contract` — no contract file added or removed; `find` still counts 169 and the README still claims 169. ### Docs updated in the same wave - `services/SettingsSearch.qml` — `groupPages` `"focus"` moved from `"notifications"` to `"focus"`, plus eight hand-written entries: Do Not Disturb, Quiet hours, Critical alerts break through, Application notification rules, Forget an app's notifications, Per-app notification sound, and Banners or history (all → `notifications`), and Focus session duration (→ `focus`). Checked against `settings-search-contract`'s fixed query list: none of the new labels or details contains any of its queried substrings, so no existing top result moves. ### Still open before the run - **A live bug this wave removed, worth knowing about.** `notification-app-rules-contract` used to `perl`-graft a temporary `notificationAppRules` schema key into its copy of `PreferenceSchema.qml`, from the era before that key shipped. The key ships now, and the graft's anchor comment still exists — so the contract was defining it **twice** in the copied schema on every run. The graft is gone, replaced by an assertion that both `notificationAppRules` and `criticalBreaksThrough` are present. - `NotificationAppRulesHarness.qml`'s fake notification now spells out `urgency`, `expireTimeout` and `hints`. It previously left all three undefined, which meant the timeout path and the urgency path were exercised in their undefined branch rather than their ordinary one. If a fixture behaves differently than expected on the first run, that change is the first place to look. - The `breakthrough` fixture drives `Settings.criticalBreaksThrough` by writing the preference and reading the binding back in the same JS call. That is synchronous through `DesktopPreferences.set` (it reassigns `values` and bumps `revision` before returning), but it has not been observed. If the fixture reports `through: 0`, suspect binding timing before suspecting the gate. - **`focusDurationMinutes` is now editable on two pages**: a `SliderRow` on `WorkspacesPage.qml` and segmented chips on `FocusPage.qml`. No contract catches it — `settings-ownership-contract` only scans the five schema-bound row types and the chips are a `SegmentedRow` reading `DesktopPreferences` directly, and `search-routing-contract` only sees `setting:` rows — but it is a real ownership violation by `modules/settings/README.md`'s own rule. Decide before the run: either the Workspaces row goes, or the key's `group` moves to `focus` and the mirror gets named in `settings-ownership-contract`. - **A stale comment in `config/PreferenceSchema.qml`** above `focusDurationMinutes` still says "The focus group routes to Notifications, which is where focusModes renders." It routes to `focus` now. Left for the schema's owner rather than edited across agent lines. - Run order for the sweep: `focus-modes-contract` first (pure static, no compositor and no shell), then `settings-jump-contract` and `search-routing-contract` (also static), then `notification-app-rules-contract` (private D-Bus, isolated shell), and `settings-pages-contract` last — it starts an isolated Quickshell beside the live one and its own cleanup is what protects the running session. - Nothing here plays a sound on purpose, but every delivery fixture reaches `playBell`, which shells out through `SoundFeedback.playCommand`. That was already true of the existing `exercise` fixture; the new fixtures add four more chances for it. Keep the harness free of anything that turns the volume up. ## Phase 8 (Input) — append below Spec: `2026-08-24-input-redesign.md`. Keyboard, Mouse & Touchpad and Dictation were rebuilt around keycaps, dropdowns and a searchable shortcuts browser, and seven new compositor-backed preference keys landed with them. **Nothing here was run against a live harness.** Three agents edited the tree concurrently. What *was* verified is listed per contract below: `bash -n` on every changed contract, the two source-only contracts run end to end, and the three compositor-shape contracts replayed offline — `hyprctl descriptions` and `hyprctl getoption` are read-only queries, so their answers were captured once and the contract logic replayed against that snapshot with a stub on `PATH`, never against the running compositor mid-edit. ### New contracts (0) None. The redesign added rows, components and schema keys to surfaces that already had contracts, so the README count line stays at **169** and `setup/readme-contract` needs nothing. (`find` counts 169; the README says 169.) ### The seven new schema keys, per key Each had to satisfy three contracts at once. Replayed against the landed `PreferenceSchema.qml`, `hypr/input.lua` and a captured `hyprctl` snapshot: | Key | Hyprland option | enum-hypr-map | schema-hypr-shape | hypr-prefs | |---|---|---|---|---| | `focusOnClose` | `input:focus_on_close` | **PASS** — enum, all three published values offered | **PASS** — `readAs: "int"`, answers `int` | **PASS** — `prefs.getInt("focusOnClose", 0)`, def 0 | | `scrollMethod` | `input:scroll_method` | **PASS** — string enum, every offered word in the published list | **PASS** — `readAs: "str"`, answers `str` | **PASS** — `prefs.get("scrollMethod", "")`, def `""` | | `scrollButton` | `input:scroll_button` | n/a — `type: "int"`, not an enum | **PASS** — `readAs: "int"`, answers `int` | **PASS** — `prefs.get("scrollButton", 0)`, def 0 | | `cursorHideWhileTyping` | `cursor:hide_on_key_press` | n/a — bool | **PASS** — `readAs: "bool"`, answers `bool` | **PASS** — def false | | `cursorWarpOnWorkspaceChange` | `cursor:warp_on_change_workspace` | n/a — bool over an int option, so the enum rule does not reach it | **PASS** — `readAs: "int"`, answers `int` | **PASS** — `prefs.getInt(..., 0)` vs schema `false`; the contract's own true/false→1/0 normalization is what makes those agree | | `touchpadClickfinger` | `input:touchpad:clickfinger_behavior` | n/a — bool | **PASS** — `readAs: "bool"` | **PASS** — def false | | `touchpadTapAndDrag` | `input:touchpad:tap-and-drag` | n/a — bool | **PASS** — `readAs: "bool"` | **PASS** — def true | Two of those are decisions, not just passes, and both are recorded in the schema itself: - `focusOnClose` was specced as a two-way choice. The compositor publishes three (`{"mru":2},{"cursor":1},{"next":0}`) and **0 is what this desktop runs today**, so a two-option dropdown would have hidden the shipped default from its own control. enum-hypr-map-contract fails an enum that drops a published value, and would have caught it — verified by deleting value 0 from a copy of the schema and watching it fail with exactly that message. - `cursorWarpOnWorkspaceChange` is a switch over an option with three states. `force` (2) is deliberately unreachable from Settings. enum-hypr-map governs enums only, so nothing fails — which is the point of writing it down here. ### Updated contracts (6) | Contract | What it now pins | Verified | |---|---|---| | `quickshell/enum-hypr-map-contract` | **String-valued enums are now checked at all.** The parser only ever collected numeric `value:`s, so `accelProfile`, `masterOrientation`, `masterNewStatus` and `windowLayout` were silently skipped and `scrollMethod` would have been too. String options carry no `map`; Hyprland states their accepted words inside the description (`[2fg/edge/on_button_down/no_scroll]`), so those are parsed and checked **one way only**: an offered value the compositor does not name fails; a named value Settings does not offer does not, because that is a product decision (`accel_profile`'s `custom` needs a `scroll_points` curve and is a stated non-goal). Empty string is always allowed — it is how a schema entry says "leave the compositor's default", which is what `[[EMPTY]]` reads back as. Options with no bracket list print a line saying so and are skipped rather than failing. The numeric rules are untouched. | **Replayed offline** against a captured `hyprctl descriptions` (353 options) and the landed schema: PASS, 11 mapped enums (was 9). Both new failure directions exercised on a scratch copy — dropping `focus_on_close`'s value 0 fails, offering `"two_finger"` for `scroll_method` fails. | | `quickshell/xkb-presets-contract` | Rewritten for the Advanced disclosure. The raw `keyboardOptions`, `keyboardVariant` **and `keyboardLayout`** fields must still be editable on the Keyboard page — matched as blocks, not one-liners, so nesting them inside an expander is fine — and **collapsed-but-present passes while absent fails**: the section must be named ("Advanced") and some `onClicked`/`onTriggered`/`onToggled` handler must actually open it, and no raw field may be pinned `visible: false`. XKB *values* stay pinned exactly (`caps:escape_shifted_capslock`, `caps:ctrl_modifier`, `compose:ralt`, `grp:win_space_toggle`) because moving one changes somebody's keyboard; row *labels* are now matched loosely and case-insensitively, because "Compose key" → "Compose" is a wording decision. The category-preservation rule, both helper signatures, and the three `input.lua`/schema default needles are unchanged. | **Run end to end** against the landed tree — it is source-only and touches neither compositor nor shell. PASS. Nested-block matching and the "no handler ⇒ fail" direction both exercised. | | `quickshell/keybinds-contract` | A static presentation half ahead of the existing live count check, which a wall of 130 rows and a searchable browser pass identically. Page and `ShortcutRow.qml` are read as one source, so moving a control between them is not a failure: `Keybinds.grouped()` is what supplies the group order, `KeycapChord` is what draws chords, the filter exists and is case-insensitive and matches on `description`, a filtered list says how many of how many it is `showing`, the header count comes from `Keybinds.binds.length`, and the note explaining why there is no GNOME keyboard handoff survives. Count-match, description-completeness and chord-rendering rules are untouched. | **Static half replayed** against the landed `ShortcutsPage.qml` + `ShortcutRow.qml`: all needles hit. The compositor half is **deferred** — it boots a Quickshell harness. | | `quickshell/keybind-rebind-contract` | UI needles added to the static half (the one that already runs under `PANAMA_KEYBINDS_STATIC_ONLY=1`). Page + row read as one source: `ShortcutCapture` is still what reads key presses (a page that grew its own handler would capture SUPER as a bind of its own), `boundTo` is called **before** `rebind` on the source line order, Change/Reset/`resetBind`/`resetAll`/`isOverridden` all still exist, binds are identified by `luaChord`, and no `rebind`/`resetBind` call is keyed by `description` — the regression that once moved every bind sharing one and cost the XF86Calculator key. The restore-all row and its live differs-count are pinned on the page. Engine needles and the whole live half are untouched. | **`PANAMA_KEYBINDS_STATIC_ONLY=1` run against the landed tree: PASS (static).** All 20 needles individually replayed. Live half **deferred**. | | `quickshell/settings-pages-contract` | `Shortcuts` and `Mouse` added to the root-type/no-copied-Flickable sweep (neither page was ever in it), `mouse` added to the runtime routing sweep, and a hand-written check that all seven new keys render on `MousePage.qml` — by `setting: "key"` *or* by `commitPreference("key"`. That second spelling is why it is hand-written: dropdowns now render through `OptionPickerRow`, which takes label and options from `PreferenceSchema.spec()` and commits by name, and **has no `setting:` property at all**. Existing Home/Bar/Notifications/ScreenIntelligence pins unchanged. | **Static half run: PASS.** Routing sweep **deferred** — it starts an isolated Quickshell beside the live one. | | `setup/dictation-contract` | **Every "where text lands" pin is unchanged and none of them conflicts with the on-page test.** They live on `panama-dictate` and `keybinds.lua` — `is_speech` rejecting `[BLANK_AUDIO]`, the guard actually being called before typing, the newline collapse, `wtype` tried before `wl-copy`, one press bind and one release bind — and nothing in them constrains which window has focus. The Try-it field sends the same `start`/`stop` the hotkey sends and merely holds keyboard focus while `wtype` types. What is new is two needles for the risk the test flow *did* introduce: the page must not spell out `scripts/panama-dictate` (the service publishes that path once, and a second copy would go stale silently, since the page's status readout comes from the service and would still be right), and a page that runs a `Process` must go through `Dictation.helper`. | **Run end to end** — it is greps plus a `python3` import of the helper, no compositor and no shell. PASS, including both new needles against the landed `DictationPage.qml`. | ### Verified against the new tree, no edit needed - `quickshell/schema-hypr-shape-contract` — derives everything from `option: "...", readAs: "..."` pairs in the schema, so the seven new keys entered it the moment they landed. All seven extract cleanly and all seven `readAs` values match what `hyprctl -j getoption` answers with. Two were easy to get wrong and are worth naming: `cursor:warp_on_change_workspace` answers `int` despite being a switch in the UI, and `input:scroll_method` answers `str` despite the neighbouring `scroll_button` answering `int`. - `tests/hypr/hypr-prefs-contract` — pure static, and **run**: ok, 77 compositor-owned keys read at config time, up from 70. All seven new keys have a `prefs.get()`/`prefs.getInt()` in `config/dot/hypr/input.lua` with a fallback equal to the schema default. - `quickshell/gnome-handoff-contract` — needle-free by construction (it derives both sides). **Run**: ok, 14 handoffs checked against 39 pages. The Keyboard page still has no GNOME handoff and still explains why. - `quickshell/schema-hypr-shape-contract`, `tests/hypr/hypr-prefs-contract` and `quickshell/gnome-handoff-contract` are the three above. `setup/readme-contract` is a fourth: no contract file was added or removed, `find` still counts 169, and the README still claims 169. ### Docs updated in the same wave - `services/SettingsSearch.qml` — three hand-written entries: **Rebind a shortcut** (→ `shortcuts`), **Pointer test area** and **Connected input devices** (→ `mouse`). "Key repeat" and "Scroll method" arrive automatically from the schema, as the spec expected. Checked against `settings-search-contract`'s fixed query list: of its 27 pinned queries only `pointer` matches any new entry, and "Pointer test area" sorts *after* "Pointer focus", "Pointer size" and "Pointer speed" in the same prefix rank, so no pinned top result moves. Both new pages are leaves in `SettingsRoutes`, so the "routes to a page anyone can land on" sweep holds. - No settings docs or launcher commands were regenerated here — that is the orchestrator's step after the schema settled. ### Still open before the run - **`settings-ownership-contract` and `search-routing-contract` are now blind to dropdown rows.** Both scan for `setting: "…"` inside a fixed list of row types; `OptionPickerRow` is in neither list and carries no `setting:` property. `accelProfile`, `followMouse`, `focusOnClose` and `scrollMethod` are all invisible to them on the rebuilt `MousePage.qml`. Nothing fails today — none of those keys is a duplicate — but a duplicate introduced through a dropdown would not be caught. `settings-pages-contract` now pins the seven new keys directly as a stopgap; the real fix is teaching both scans the `PreferenceSchema.spec()` / `commitPreference()` spelling. Owner: whoever holds those two contracts next. - **`xkb-presets-contract` now requires a raw `keyboardLayout` field**, on the reading that the layout dropdown's "Custom…" has to reveal somewhere the code can actually be typed. It passes against the landed page. If the layout editor is ever folded into the dropdown itself, that needle is the one to revisit — the intent is "the raw code stays typeable", not "it is a TextEntryRow". - **`keybinds-contract` pins the literal word `showing`** in the filtered-count line, because the spec names that wording ("showing N of M"). It is the one prose needle in the new static half; everything else keys on structure. - **Dictation's Try-it field and the clipboard fallback** — handled, but worth knowing. `panama-dictate` falls back to `wl-copy` when `wtype` is missing, by design, and on the Try-it row that means the words land on the clipboard rather than in the field the page just focused. The page says so: a "Typing — Missing" row appears when `Dictation.typingAvailable` is false. Nothing to fix; worth a look during the run if a machine without `wtype` is around, since that branch has never been seen. - Run order for this phase: the two source-only contracts first (`xkb-presets-contract`, `gnome-handoff-contract`), then the static halves (`hypr-prefs-contract`, `PANAMA_KEYBINDS_STATIC_ONLY=1 keybind-rebind-contract`, `PANAMA_SETTINGS_STATIC_ONLY=1 settings-pages-contract`), then the two compositor-query contracts (`enum-hypr-map-contract`, `schema-hypr-shape-contract` — read-only, but they want the real compositor), then the harness contracts (`keybinds-contract`, `keybind-rebind-contract` in full, `settings-search-contract`), and `settings-pages-contract` last, as before: it starts an isolated Quickshell beside the live one and its own cleanup is what protects the running session. - `keybind-rebind-contract`'s live half rebinds Terminal to `SUPER + SHIFT + F9` against the **real compositor** with an isolated `XDG_CONFIG_HOME`. That was true before this phase and is unchanged, but it is the one contract in this wave that writes to the running keymap, so it wants a quiet moment. ## Phase 9 (Network & Sharing) — append below Spec: `2026-08-24-network-sharing-redesign.md`. Connections became a full network manager (per-connection details, forget, autoconnect, MAC randomization, VPN import, hotspot, enterprise Wi-Fi, airplane mode, system proxy), Firewall grew its add side and a zone browser, Printers gained per- printer defaults and job hold/release, and Sharing got copy and structure work. The last two GNOME punt rows in the app died with the "Owned by Fedora" card. **Nothing here was run against a live harness.** Three agents edited the tree concurrently. What *was* verified is listed per contract below. ### New contracts (1) `quickshell/network-tools-contract`. The README count line moves **169 → 170**; `setup/readme-contract` was run and passes ("170 contracts, as documented"), counted the same way `panama test` collects the suite. ### Verified - **`quickshell/network-tools-contract` — RUN END TO END, PASS.** It is safe to run because it never reaches the machine: `env -i` with a stub directory first on `PATH`, stubs for nmcli/gsettings/rfkill plus every D-Bus client, a PyGObject stand-in on `PYTHONPATH` whose `require_version` always raises, and both D-Bus bus addresses pointed at sockets that do not exist. It asserts the first two of those before running the helper at all, and refuses to continue if `nmcli`, `gsettings` or `rfkill` resolves anywhere but the stub directory. Checked with a debug copy that it is doing real work rather than passing vacuously: the stub's terse listing drives the shipped parse all the way to `{"ip4":"192.168.7.42/24","gateway":"192.168.7.1","dns":["192.168.7.1", "1.1.1.1"],"mac":"AA:BB:CC:DD:EE:FF","macRandomized":true,…}` while the three secret properties in the same listing are absent from it. - The libnm/D-Bus branch of `join-enterprise` is deliberately **not** exercised — running it would add a real connection profile. It is covered statically instead, by an AST walk that fails if any command list in the helper carries a password-shaped identifier. The nmcli fallback is what the dynamic half drives, and there the password is asserted present on the editor's **stdin** and absent from **argv**, stdout, stderr and disk. - **`quickshell/connectivity-contract` — static half run, and it found a bug.** See "Still open" below. The new enum check reads the member list out of the installed `quickshell-network.qmltypes` rather than a hand-kept list, so it cannot drift the way the two bugs it catches did. - **`quickshell/firewall-contract` — static half run, PASS** (everything up to the first live `firewall-cmd` read). - **`quickshell/printers-contract` — static half run, PASS.** - **`quickshell/sharing-contract` — static half run, PASS.** - **`quickshell/gnome-handoff-contract` — RUN END TO END, PASS** (source-only): "ok (12 handoffs checked against 39 pages)" with `network` and `wifi` now in OWNED. - **`quickshell/health-ui-contract` — static half run, PASS.** - **`PANAMA_SETTINGS_STATIC_ONLY=1 settings-pages-contract` — PASS.** - **`setup/readme-contract` — RUN END TO END, PASS.** - `bash -n` on every changed contract; every embedded `python3` heredoc compiled separately with `py_compile`. ### Still open before the run - **`Connectivity.qml:204` names an enum member that does not exist.** `ConnectionFailReason.Authentication` is not a member; the real ones are `NoSecrets`, `Unknown`, `WifiAuthTimeout`, `WifiClientDisconnected`, `WifiClientFailed`, `WifiNetworkLost`. QML resolves it to `undefined`, the switch arm never matches, and a wrong password is reported with the fallthrough text. `NoSecrets` is almost certainly the intended member. `connectivity-contract`'s new enum check fails on exactly this line and passes on a copy with it corrected, so the check is confirmed working and the fix is a one-word edit in a service file this phase's contract owner does not own. **This is the one item blocking a clean run.** - **The enum check is scoped to `Connectivity.qml`.** The same class of bug — a plausible enum member that does not exist, resolving to `undefined` in silence — can live anywhere that imports `Quickshell.Networking`, including `modules/quicksettings/WifiList.qml` and the bar's status cluster. Widening the sweep to every QML file that imports the module is a small change and the obvious next one. Owner: whoever holds `connectivity-contract` next. - **`network-tools-contract` cannot see the libnm branch.** That is a deliberate trade, but it means the branch that actually runs on this machine (NM 1.56, bindings present) is only ever checked by reading. A machine without PyGObject would exercise the fallback for real; nothing here has one. - **Two contracts still pin prose.** `firewall-contract` requires the add flow to say "permanent" and "ask for your password", and `sharing-contract` requires "never passes through Panama", "install it and this becomes a switch" and "does not install software". The spec names all five phrases, so they are pinned deliberately, but they are the needles a copy edit will trip. - **`printers-contract` pins the option vocabulary exactly** — `media` ∈ {Letter, A4, Legal}, `sides` ∈ {one-sided, two-sided-long-edge, two-sided-short-edge}. Adding a third settable option is meant to be a deliberate act that updates this contract, but it will read as a surprise the first time somebody tries. - **`connectivity-contract`'s live half is unchanged** and still starts a harness beside the running session, so it wants the same quiet moment it always did. `PANAMA_CONNECTIVITY_STATIC_ONLY=1` runs the new source-only half alone. - Run order for this phase: the source-only contracts first (`gnome-handoff-contract`, `PANAMA_NETWORK_STATIC_ONLY=1 network-tools-contract`, `PANAMA_CONNECTIVITY_STATIC_ONLY=1 connectivity-contract`, `PANAMA_SETTINGS_STATIC_ONLY=1 settings-pages-contract`, `setup/readme-contract`), then `network-tools-contract` in full — it is hermetic, so it can run at any time — then the read-only system contracts (`firewall-contract`, `printers-contract`, `sharing-contract`), then the harness contracts (`connectivity-contract`, `health-ui-contract`, `settings-search-contract`), and `settings-pages-contract` last, as before. ### Docs updated in the same wave - `services/SettingsSearch.qml` — the three "Managed by GNOME Settings" connectivity entries are gone, and with them the duplicate **Printers** entry that routed to `connectivity` rather than to the Printers page. Ten entries replace them, all routing to `connectivity`: **Wi-Fi**, **Bluetooth**, **VPN**, **Import a VPN**, **Hotspot**, **Airplane mode**, **Network proxy**, **IP address**, **Forget a Wi-Fi network**, **Enterprise Wi-Fi**. Wi-Fi and Bluetooth were rewritten rather than deleted: the spec lists eight additions, none of which contains the word "Bluetooth", so deleting the lying entry outright would have made a switch the page has unreachable by search. - Checked against `settings-search-contract`'s pinned query list: none of its 21 ranked queries, nor the nine leaf-routing queries, matches any new or changed entry, so no pinned top result moves. `connectivity` is a leaf in `SettingsRoutes`, so the routing sweep holds. - No settings docs or launcher commands were regenerated: this phase added no schema keys, so there is nothing for `panama-settings-docs` or `panama-settings-commands` to pick up. Verified by reading the diff — every new setting here is system state (NetworkManager, firewalld, CUPS, gsettings), not a Panama preference. ## Phase 10 (Applications, Storage & Snapshots) — append below Spec: `2026-08-24-applications-storage-snapshots-redesign.md`. Applications became an app manager (installed list with search, Flatpak uninstall, permission summaries, per-app autostart, jump chips, the `panama apps` catalog rendered natively, role dropdowns plus a single-type override). Storage grew a proportional breakdown bar and an itemized "Clean up, honestly" card, and lost the duplicate container-images row that opened a terminal. Snapshots made retention editable and moved the file browser into its own card, which fixes "browse from a collapsed volume card does nothing". Three agents edited the tree concurrently. Everything below was reconciled against the landed files at the end of the phase rather than against the spec's pinned shapes. ### New contracts (1) `quickshell/app-library-contract`. The README count line moves **170 → 171**; `setup/readme-contract` was run and passes ("171 contracts, as documented"). ### Run and passing These four are hermetic or source-only, so they were run rather than deferred: - **`quickshell/app-library-contract` — RUN END TO END, PASS.** Safe to run because it never reaches the machine: `env -i`, a stub directory first on `PATH`, recording stubs for flatpak/rpm/pkexec and screaming stubs for dnf/yum/sudo/rpm-ostree/gio, `HOME` and every XDG directory inside the scratch tree, and a fixture catalog through `PANAMA_EXTRAS_DIR`. It asserts, before running the helper at all, that the helper names no binary by absolute path and that all six commands resolve inside the stub directory. What it pins: - **Catalog agreement.** `setup/lib/extras-catalog`'s bash functions and the helper's Python parser are both run over the same fixture files and their answers compared entry by entry — id, label, kind — rather than either being read. The fixture exercises the format's corners: a labelled entry, an unlabelled Flathub id (label derived from the last dotted component), a bare dnf name, a `|`-labelled dnf name, comments, blank lines, and two indented continuation lines that must fold into the entry above. - **Ids are the catalog line verbatim.** `flatpak:org.example.Bravo`, not the stripped ref: the bare ref is in the refusal list, because handing that to `install` would be refused for every Flathub entry in the real catalog and the failure would read as "installing is broken". - **Nothing off-catalog installs**, and the empty command log is what proves the refusal came first. Off-catalog ids, an unknown category, a path escaping the catalog directory, a continuation line, and an entry that exists in the *other* category are all refused with nothing run. - **Extensions ride with their entry and nothing else does** (installing Echo reaches for Echo and its two plugins, and no other `org.example.*`). - **Removal is flatpak-only**, pinned three ways: an AST walk that fails if any command list in the helper pairs dnf/yum/rpm-ostree with a removal verb or invokes rpm for anything but a query; a second AST walk over `uninstall` itself; and a runtime check that no argument — including a dnf package name — produces a package-manager call. - **Permission buckets from data**: `filesystems=host` → "Full file system access" and `filesystems=home` → "Home folder" are checked against separate fixtures so the two cannot be conflated; `devices=all` → Camera, `sockets=pulseaudio` → Microphone, `shared=network` → Network; an unrecognized key must still appear in the output; and a sandboxed application must summarize strictly shorter than a permissive one, so the summary cannot be a constant. - **`quickshell/applications-settings-contract` — RUN END TO END, PASS** (source-only). The bun-extracted `roles` / `matchesRole` half survives B's rebuild verbatim and gained four fixtures, including the two shapes that once made Archives match nothing: categories arriving as a QML list, and as a comma-separated string. - **`quickshell/default-apps-contract` — RUN END TO END, PASS.** Already fixture-driven (its own XDG tree, stub `xdg-mime`/`xdg-settings`); the new half adds a fixture `mime/globs2` and two desktop entries that declare `MimeType`, then pins `search-types` shape, that candidates are only installed applications, that a one-character query is not a search, that `set-type` writes exactly one type, and that an unknown type, an unknown application, and a type this system does not have are each refused with nothing reaching xdg-mime. - **`setup/readme-contract`, `quickshell/search-routing-contract`, `quickshell/settings-ownership-contract` — RUN, PASS** after the nine new search entries. ### Extended contracts, new halves run in isolation (3) `disks-contract` and `snapshots-contract` each keep a first half that reads the live machine (`panama-disks snapshot`, `panama-snapshots snapshot`), so neither was run end to end. The **new** halves were extracted into scratch scripts and run on their own, and both pass: - **`quickshell/disks-contract`** (new half run, PASS). It is hermetic: `env -i`, `HOME` and `XDG_CACHE_HOME` inside the scratch tree, the block tree from `PANAMA_DISKS_LSBLK`, and recording stubs for gio/flatpak/pkexec/dnf/podman. - **Two proofs run before anything is cleaned**: `breakdown.path` must be the fixture home, and the cache segment must be the 12 × 111111 bytes this contract wrote a moment earlier. Only then is `clean cache` allowed to run — which is what makes it safe to assert that the symlink planted inside the fixture cache was unlinked rather than followed, and that the file it points at outside the cache survived. - **The arithmetic**: home + applications + caches + system == `usedBytes` exactly, `free` == `freeBytes`, every segment non-negative, and `exceedsUsed` false on the fixture. The two ways the measurement can be wrong (`complete === false`, `exceedsUsed === true`) are pinned as things the page says out loud. - **The anti-racket stance**, pinned as an absence in the cleanup card's own string literals: no "running out", "recommended", "act now", "junk", "safe to remove", "you should", no exclamation marks, and no single button that clears everything. The extractor takes the *tightest* card whose own title is the cleanup one, and scans only double-quoted literals — QML is full of `!` and none of it is shouting. - **Each cleanable does its own one thing**: `gio trash --empty` (never rm), `flatpak uninstall --unused --noninteractive`, and `pkexec dnf clean packages` — never `clean all`, never a removal. An AST walk pins that this is the *only* package-manager command in the whole helper. - **The unused-runtime size is borrowed, not recomputed**: with `PANAMA_APPLICATIONS_HELPER` pointed at a recording stub, the row must report what that stub said (780000) and the stub must have been asked. Two ideas of "unused" would show one number and free another. - `backing_device` reading findmnt's SOURCE rather than `st_dev` is pinned with the reason: btrfs gives every subvolume its own device number, and the first version of the breakdown lost the system-wide flatpak installation to exactly that. - **`quickshell/snapshots-contract`** (new half run, PASS). Retention is exercised against a recording `snapper` stub under `env -i`, after asserting snapper resolves inside the stub directory — the only way to run a write verb without changing how this machine keeps its snapshots. - Refusals here are read from the JSON `error` field, not an exit code: this helper answers a refusal with fresh state and an `error` in it. Whether a refusal happened *first* is read from the absence of a `set-config` in the log, because the helper reads the configuration list on its way back out either way. - Ceiling pinned at **50 in both places** — the helper's `RETENTION_LIMIT` and the service's `retentionMax` — because a dropdown offering a value the helper refuses fails after the user has already chosen. - The browser-card fix is pinned structurally: a brace-aware scan (strings and comments skipped) walks the QML ancestry of `Snapshots.browseEntries` and fails if the enclosing card is a delegate of the per-volume Repeater. This was checked against the OLD page first, where it correctly fails, so it is not a check that passes on anything. ### Docs updated in the same wave - `services/SettingsSearch.qml` — nine entries added, all routing to leaves that exist in `SettingsRoutes`: **Installed applications**, **Uninstall an application**, **Application permissions**, **Install applications**, **Autostart**, **File associations** → `applications`; **Clean up storage**, **Application caches** → `storage`; **Snapshot retention** → `snapshots`. Checked by evaluating the array: 154 entries, no duplicate labels, every `page` a real leaf, and none of `settings-search-contract`'s 21 ranked queries or 9 leaf-routing queries matches a new entry, so no pinned top result moves. (The first draft of the Snapshot retention detail said "each volume keeps", which put it in the result set for the pinned `volume` query; reworded.) - No settings docs regenerated: this phase adds no schema keys. Every new setting is system state (flatpak, dnf, snapper, xdg-mime), not a Panama preference — verified by reading the diff. ### Still open before the run - **`disks-contract` and `snapshots-contract` have not been run end to end.** Their first halves read the live machine, so they want the same quiet moment the other system contracts do. Nothing in the new halves depends on that order. - **`settings-search-contract` has not been run**: it starts a Quickshell harness. The nine new entries were checked statically as described above, but the schema-label sweep and the ranked queries need the live harness. - **`settings-pages-contract`, `settings-docs-contract`, `settings-jump-contract` and `settings-buttons-contract` were not run against the three rebuilt pages.** ApplicationsPage grew four new components (InstalledAppRow, FileTypePicker, SettingsChip, StorageBreakdownBar); the qmldir registration of the first three is pinned by `applications-settings-contract`, but nothing here has loaded the QML. - **`app-library-contract` pins the fixture seam `PANAMA_EXTRAS_DIR` and the permission bucket wording** ("Camera", "Microphone", "Full file system access", "Home folder", "Network", "Devices"). Both match the landed helper; changing either is meant to be a deliberate act that updates this contract, and will read as a surprise the first time somebody tries. - Run order for this phase: the hermetic and source-only ones first (`app-library-contract`, `applications-settings-contract`, `default-apps-contract`, `search-routing-contract`, `settings-ownership-contract`, `setup/readme-contract`), then the read-only system ones (`disks-contract`, `snapshots-contract`, `containers-contract`), then the harness ones (`settings-search-contract`, `health-ui-contract`), and `settings-pages-contract` last, as before. ## Phase 11 (Users & Accounts) — append below Spec: `2026-08-24-users-accounts-redesign.md`. Users grew a profile hero with a stock-avatar gallery and a Remove, a password flow with a strength meter, a live-validating add-user form, a keep-files deletion choice, and per-user management (type / reset password / unlock). Fingerprint enrollment stopped handing people to GNOME's Users panel and became native — fprintd's `EnrollStart` driven from `panama-fingerprint`, streaming one JSON line per touch — and the card learned to appear in the state that needs acting on rather than only when a reader is attached. Online Accounts gained native Nextcloud and IMAP forms, confirmed removal, and an availability that no longer collapses on a failed write. Three agents edited the tree concurrently. Everything below was reconciled against the landed files at the end of the phase, not against the spec's pinned shapes: three of the needles moved during the phase (the card-visibility expression went into the service as `cardVisible`, the add-user field became `LiveFieldRow`, and the fingerprint helper became Python) and each is pinned where it actually landed. ### New contracts (1) `quickshell/online-accounts-contract`. The README count line moves **171 → 172**; `setup/readme-contract` was run and passes ("172 contracts, as documented"). ### Run and passing - **`quickshell/fingerprint-contract` — RUN END TO END, PASS.** The whole file was reworked, because two of its needles inverted. Hermetic: `env -i`, a stub directory first on `PATH` (asserted, before the helper runs, that fprintd-list, authselect, sudo and pkexec all resolve inside it), both bus addresses pointed at sockets that do not exist, `PANAMA_PATH` pointed at a recording `panama-sudo` that runs **nothing**, and enrollment replayed from `PANAMA_FINGERPRINT_FIXTURE` with the calls it stood in for landing in `PANAMA_FINGERPRINT_LOG`. What it pins: - **The inverted needle.** `openGnomePanel("system", "users")` is now a failure rather than a requirement, checked across every settings page. `gnome-handoff-contract` lost its `UsersPage.qml:system-users` exception at the same time; this is the other half of that, said from the page's side. - **The stuck state, from the data.** With the stub fprintd reporting no devices and the stub authselect reporting `with-fingerprint`, `status` must still answer `unlockFeatureEnabled: true` — the combination that used to be unrepresentable, because the feature was only read when fprintd answered. This machine is in that state, which is how it was found. - **Card visibility followed one level of indirection.** The expression moved into `services/Fingerprint.qml` as `cardVisible: readerPresent || unlockFeatureEnabled`; the contract accepts either the page spelling it out or the page binding to a service property that does, and resolves the second rather than forbidding it. - **The enrollment stream as a stream.** A five-stage fixture with a retry in the middle produces nine lines; every one must be a JSON object on its own, the counter monotonic and inside `0..total`, `total` constant, and the retried touch must **not** have advanced the counter — a panel that counts a failed touch promises a finish that never arrives. The terminal line says which way it ended. - **Claim and Release bracket everything**, read from the call log: first call `Claim`, last call `Release`, `EnrollStart` after the claim — including on a failed enrollment, because a reader left claimed refuses the next attempt with "busy with something else" forever. - **A terminal failure is reported in words**, not in fprintd's vocabulary (`enroll-duplicate` → "That finger is already enrolled"). - **Nonsense is refused before the reader is touched**: four bad finger names against both `enroll` and `remove`, each of which must leave the call log empty. - **`remove` deletes the finger it was asked about**, and `remove-all` uses `DeleteEnrolledFingers2` with no arguments — its predecessor took a user name, which is how a typo deletes somebody else's prints. - **With no fixture and no bus it still answers in its own shape**: the page reads this stream line by line, and a traceback leaves an enrollment panel open forever. - **The stated reason survived the rewrite to Python**: the escalation must go through `panama-sudo --reason …`, and a bare `sudo`/`pkexec` in the argv log is a failure. - **Finger vocabulary**: a single id elsewhere is a default choice and is allowed; two in one file is a copy of the list, and the copy is what falls behind. - **`quickshell/user-accounts-contract` — RUN END TO END, PASS.** Its snapshot half still reads the live account service, which is read-only; every verb that would change something is pinned from the source and never invoked (`set-icon gib ""` really does clear the avatar). New halves: - **`reset-password` carries no password material**, by AST: it must call `SetPasswordMode`, must resolve its mode argument to **1** (through the named constant, so the meaning survives), must not call `SetPassword`, and its body — docstring excluded, because the docstring is allowed to say the word — must not mention stdin, openssl, crypt or passwd. - **keep-files end to end, as three separate links**, because any one of them can invert on its own: the helper derives `DeleteUser`'s boolean from its own argument (a literal there is the bug), the service's ternary is checked against the *polarity of its own parameter name* (Panama flipped this once already, `removeFiles` → `keepFiles`), and the page passes a variable rather than a constant. Both vocabularies are exercised — `keep`/`remove` and the legacy `keep-files`/`remove-files` — by reading which refusal comes back, so a vocabulary that stopped being understood shows up as the wrong message rather than as no message. - **`removeIcon` sends an empty path**, and `set_icon` recognizes it rather than handing "" to GdkPixbuf, which would fail and leave the avatar. - **The live-validation regression, two ways.** Structurally: the property the form's user-name test reads must be assigned from a per-keystroke handler, and the component that assigns it must not be `TextFieldRow`. Bluntly: the page carries no `TextFieldRow` at all. The page's regex is compared character for character against the helper's `USERNAME`, and the 31-cap must appear in the page's own text — a form that accepts a name accountsservice then refuses has no way to say why. - **The last administrator is refused helper-side too**, not only by the page that offers the control. - **Stock avatars**: shape read from a real run (`{name, path}`, absolute paths, empty list legitimate). - **`quickshell/gnome-handoff-contract` — RUN, PASS** (9 handoffs, 39 pages). The `UsersPage.qml:system-users` exception is deleted; the `OnlineAccountsPage.qml:online-accounts` one stays with its reason rewritten to name OAuth specifically — libgoa-backend ships without a GIR binding, so the provider's own dialog is the only way to obtain a token, and Nextcloud and IMAP are added on the page itself. - **`setup/readme-contract` — RUN, PASS** after the count line moved. ### Run with one half relaxed (1) - **`quickshell/online-accounts-contract` — everything passes except six input-validation cases**, which are pinned as the spec asks and which the landed `panama-accounts` does not yet satisfy. See "Still open" below. Run with those six removed, the contract passes end to end. It is hermetic: `env -i`, a stub directory first on `PATH` (gdbus/busctl/dbus-send/ gnome-control-center all resolve there, asserted before running), a `gi` stand-in on `PYTHONPATH` whose `require_version` always raises — so if the fixture seam were ever removed the contract would stop working rather than quietly start editing the session's accounts — and both bus addresses pointed at sockets that do not exist. Accounts come from `PANAMA_ACCOUNTS_FIXTURE`; what each verb would have done lands in `PANAMA_ACCOUNTS_LOG`. What it pins: - **Availability is not an error**, at the definition and at every assignment: no line that decides `available` may mention a write error, and the service must keep at least two error strings, or "GOA did not answer" and "that one change did not happen" are the same fact. This is the regression where one refused toggle replaced four working accounts with "not available". - **The same thing from the data**: a refused add must come back with the error *and* the full account list, because the page draws its list from the same answer that carries the message. - **The password on stdin, proved rather than assumed.** The log records the password's **length**, never the thing itself, so the sentinel can be checked for everywhere it might have gone (stdout, stderr, the log, the scratch home) while `passwordBytes` proves it was read at all rather than dropped. - **The listing cannot carry a credential**, read from `describe`'s own dict keys and from the GOA properties it reads, so a password property added later is caught at the source rather than after it reaches the page. - **An added account is proved, not assumed**: `call_add_account_sync` must be followed by `call_ensure_credentials_sync`, and `verify` must be able to `call_remove_sync` — GOA does not check what it is handed, so without that step a mistyped password produces an account that exists, looks correct, and never syncs, which is the exact failure this page exists to explain. - **Provider types**: `owncloud` (the fork kept the id) and `imap_smtp`. A provider type GOA does not know is not an error — AddAccount is simply never offered it. - **Both names for the listing** (`list` and `snapshot`) answer the same thing, and reading the list changes nothing. - **Removal carries the path intact** — removing the wrong account is unrecoverable and looks like a success — and is confirmation-gated on the page, read from the object block around the call rather than from a `confirming` property declared anywhere in the file. ### Docs updated in the same wave - `services/SettingsSearch.qml` — nine entries added, all routing to leaves that exist in `SettingsRoutes`: **Fingerprint**, **Enroll a fingerprint**, **Delete a user**, **Account type**, **Reset a password** → `users`; **Nextcloud**, **Google account**, **Add a mail account**, **Remove an account** → `accounts`. Checked by evaluating the array: 163 entries, no duplicate labels, every `page` a real leaf, and none of `settings-search-contract`'s 21 ranked queries or 9 leaf-routing queries changes its top result — the only new entry any of them touches at all is Fingerprint, which matches `lock` through "Unlock" and sits far below the existing first hit. - No settings docs regenerated: this phase adds no schema keys. Every new setting is system state (accountsservice, fprintd, authselect, GOA), not a Panama preference — verified by reading the diff. ### Still open before the run - **`online-accounts-contract` fails six validation cases against the landed helper**, and they are left pinned rather than relaxed, because the spec asks for them and each produces an account that exists, looks right in the list, and never syncs. `nextcloud_uris` accepts anything with a host once `https://` is prepended, and `imap_account` accepts any non-empty string as a server: - `add-nextcloud` accepts `not a url`, `https://cloud.example.org; reboot`, and `https://cloud example org`; - `add-imap` accepts `imap example com`, `imap.example.com; reboot`, and `-imap.example.com` as either server. A hostname check in `nextcloud_uris` and one applied to both hosts in `imap_account` closes all six. `''`, `ftp://…` and `https://` (no host) are already refused, and every other assertion in the file passes. - **`settings-search-contract` has not been run**: it starts a Quickshell harness. The nine new entries were checked statically as described above. - **`settings-pages-contract`, `settings-docs-contract`, `settings-jump-contract` and `settings-buttons-contract` were not run against the two rebuilt pages.** Six new components landed (LiveFieldRow, SecretFieldRow, PasswordStrengthRow, StockAvatarPicker, FingerprintEnrollPanel, OnlineAccountRow) and are registered in `qmldir`, but nothing here has loaded the QML. - **The enrollment cancel path is pinned only from the source.** The canned fprintd has no main loop, so `SIGTERM` releasing the device is exercised by neither half; what is pinned is that the release happens in a `finally` and that a *failed* enrollment still releases. - **`user-accounts-contract`'s first half reads the live account service** (`panama-users snapshot`, `stock-avatars`), so it wants the same quiet moment the other system contracts do, though nothing it does writes. - **Seams pinned by name**: `PANAMA_FINGERPRINT_FIXTURE`/`_LOG`, `PANAMA_ACCOUNTS_FIXTURE`/`_LOG`, and the log shapes (`{method, arguments}` and `{verb, arguments, passwordBytes}`). Changing either is meant to be a deliberate act that updates these contracts. - Run order for this phase: the hermetic ones first (`fingerprint-contract`, `online-accounts-contract`), then the source-only ones (`gnome-handoff-contract`, `setup/readme-contract`, `settings-ownership-contract`, `search-routing-contract`), then the read-only system one (`user-accounts-contract`), then the harness ones (`settings-search-contract`), and `settings-pages-contract` last, as before. ## Phase 12 (Privacy & Security) — append below Spec: `2026-08-24-privacy-security-redesign.md`. Privacy stopped being a page that read three device rows and pointed at GNOME for everything else. The portal model went from three hardcoded devices to six tables — camera, microphone, screencast, remote-desktop, background, location — with screencast and remote-desktop revoke-only, because their stored value is a structured GVariant describing a whole session and a switch cannot rebuild one. Traces became native: a new `panama-privacy` empties the recent-files list and the thumbnail cache, and the trash row reuses Storage's existing cleanable rather than growing a second implementation. SSH Keys learned to make a key, with the passphrase typed at ssh-keygen over a pty. The duplicated Screen-lock card was deleted and replaced with a pointer. Three agents edited the tree concurrently. Everything below was reconciled against the landed files at the end of the phase rather than against the spec's pinned shapes, and four needles moved during it: `speakers` left the permissions model, the `set` verb became `true|false` rather than `allow|deny`, the Privacy page's confirm state became `confirmingItem` (with `confirmingRevoke` and `confirmingTrace` beside it), and the passphrase turned out to travel through a helper of its own (`type_at_keygen`) rather than inside `generate`. Each is pinned where it actually landed. ### New contracts (1) `quickshell/privacy-traces-contract`. The README count line moves **172 → 173**; `setup/readme-contract` was run and passes ("173 contracts, as documented"). ### Run and passing - **`quickshell/permissions-contract` — RUN END TO END, PASS.** Rewritten: the old version set and cleared a camera permission on the REAL portal store under a probe application id and put it back afterwards. It now runs under `env -i` against a recording `busctl` first on `PATH` (asserted to resolve inside the stub directory before anything that writes runs), with `DBUS_SESSION_BUS_ADDRESS` pointed at a socket that does not exist. What it pins: - **No Set path for a structured table, three ways.** By import — the helper is loaded as a module so the table lists are read at their real values rather than pattern-matched, because they are derived from a registry and a contract that understood one spelling of that would be pinning the spelling. By AST — `SetPermission` is named exactly once in the file, inside one function, which consults a named list containing `camera`; that list must not contain `screencast` or `remote-desktop`, and the function must not name them either. And at runtime — `set screencast …` is refused **and** the call log gains no `SetPermission`, which is the assertion that survives a refactor of both of the others. - **Revoke reaches every remembered token.** The fixture store gives one application two screencast sessions; the snapshot has to fold them into ONE row carrying `grants: 2`, and `forget` has to issue two `DeletePermission` calls. Dropping the first token and leaving the row looking unchanged is the failure this catches. - **A path-shaped entry id from the store is dropped, not fed back in.** The stub's `List` answers with `"../../etc/passwd"` among the tokens; it must not appear in any subsequent call. - **Absence is still not failure**: the stub answers `No entry for microphone` on stderr with a non-zero exit, and the snapshot must report an empty microphone table with `error: ""`. - **`speakers` is gone**, pinned as an absence: no portal backend arbitrates speaker access, so the row was a permanent "nothing has asked" for a question nobody asks, and listing it made the page look wider than it is. - **`Permissions.devices` survives** as the camera/microphone compat view, and something still reads it — ApplicationsPage does, and the symptom of losing it there is an empty list rather than an error. - Validated table and application ids, each checked twice: refused *with a reason*, and having reached no call. - **`quickshell/privacy-traces-contract` — RUN END TO END, PASS.** New, and hermetic throughout: `env -i` with `HOME`, `XDG_DATA_HOME` and `XDG_CACHE_HOME` inside a scratch tree, and nothing that deletes runs until the helper has reported the fixture's own numbers back (9 × 33333 bytes of thumbnails, two recent entries). What it pins: - **Clearing recents empties the file, never unlinks it**, and what is left parses as XML with `` as its root and no bookmarks. A truncation to zero bytes fails: GTK reads a zero-length file as corrupt and stops recording history, which looks identical to success. - **Clearing thumbnails does not follow a link out.** The fixture plants both traps — a symlink to a file that must survive and a symlinked directory that must be unlinked rather than descended — and separately points a whole scratch `~/.cache/thumbnails` at a directory outside the home, which has to be refused in words. - **The seam is not a way around the guard**: `PANAMA_PRIVACY_THUMBNAILS` pointed outside the home is refused exactly as a symlink is, which is what makes the rest of this file a test rather than a way of disabling the check. - **One trash implementation**, said three ways: the page reaches `Disks.clean`/`Disks.cleanables`, the helper's *code* (docstrings excluded by AST, since they are allowed to say why) never mentions the trash, and neither does `Traces.qml`. - **No urgency language in the Traces card**, found by what the card is wired to rather than by its title, and read only from its string literals. - **`quickshell/ssh-keys-contract` — RUN END TO END, PASS.** Its read-only half is unchanged and still runs against the real configuration. The new half runs under `env -i` with `HOME` in a scratch tree and a recording `ssh-keygen` first on `PATH`, which logs its own `/proc/$$/cmdline` and `/proc/$$/environ` and then plays the two passphrase prompts. What it pins: - **The passphrase never reaches argv or the environment**, asserted against what the kernel would have shown any other process — and it DOES arrive down the terminal, twice, or ssh-keygen would have stalled at the second prompt. It is also absent from the JSON the page parses and from every file under the scratch tree. - **By AST, for every function that carries it**, not only `generate`: the pty write lives in `type_at_keygen`, and a rule that looked only at the caller would have missed the place the value actually goes. No list literal, no dict literal, no `open`/`mkstemp`/`write_text`. - **The environment ssh-keygen runs in**, read back out of `/proc`: `SSH_ASKPASS_REQUIRE=never` (this desktop sets `prefer`, which draws a graphical dialog and hangs the pty until the timeout — A found this the hard way) and `LC_ALL=C`, since the prompts are matched by their words. - **Overwrite is refused before ssh-keygen runs**, and the existing key is byte-identical afterwards. - **Ten bad key names**, each refused and each having reached no ssh-keygen, with a file outside the SSH directory left untouched and the scratch directory still holding exactly the two files it should. - **An empty passphrase needs `--no-passphrase`**, the flag exists, and nothing in the shell passes it. - **`fix-permissions` restores 0600 and is confined**: five bad names refused, and a 0644 file outside the directory still 0644. - **Removal from the agent is reachable now** — helper verb, service function, page call, all three — and `ssh-add` was never invoked by the hermetic half. - **`quickshell/secrets-contract` — RUN END TO END, PASS.** Existing pins kept. New: **the Copy button is only ever Copy.** The page used to run one confirmation state for the whole card and label the neighbouring button `confirming ? "Cancel" : "Copy"`, so arming a Forget replaced the word "Copy" in the exact place the user had just learnt to find it — and the way out of a confirmation was to press the button that copies. Pinned from the button block: its label is the literal `"Copy"`, its handler does not read `confirming`, and no button both copies and forgets. Also that the copy confirmation is tied to the row it happened on (`Keyring.copiedPath === …itemPath`) rather than being one card-wide flag. - **`quickshell/gnome-handoff-contract` — RUN, PASS** (8 handoffs against 39 pages). `privacy` joins `OWNED`, with the reason: the card that carried the door was headed "Owned by Fedora" and explained that GNOME's file-history switches would not take effect in a Hyprland session anyway. Plus the inverse, said from the page's side — `PrivacyPage.qml` contains no `openGnomePanel` at all — because the generic loop can only fail on a door that exists. - **`quickshell/settings-ownership-contract` — RUN, PASS.** The `lockMinutes`/`lockOnSleep` mirrors onto `privacy` are gone from the expected table and from the README loop; `modules/settings/README.md` lost the two mirror rows with them. That was the one mirror in the table nobody had asked for: Privacy carried a whole second Screen-lock card, so one preference had two sliders. - **`setup/readme-contract` — RUN, PASS** ("173 contracts, as documented"). - **Also run and passing, unchanged by this phase but touching the two rebuilt pages**: `qmldir-registration-contract` (185 components, including B's new `PrivacyLiveTile` and `SectionLabel`), `search-routing-contract` (144 routed settings), `settings-nav-contract`, `settings-buttons-contract`, `settings-docs-contract` (172 settings documented — the schema did not change, so no docs regeneration was needed), `settings-hardcoded-values-contract`, `settings-jump-contract`. ### Deferred, and why - **`quickshell/lock-screen-settings-contract` — NOT RUN.** Its second half daemonizes a Quickshell preview harness and counts `hyprlock` processes, which is exactly the kind of thing that should not happen underneath a live desktop session. Its first half was edited and is source-only: the "Screen lock" card must not exist on Privacy, `lockMinutes`/`lockMinutesBattery`/`lockOnSleep` must each be bound on Power and on Privacy nowhere, and Privacy must point at Power & Lock rather than silently dropping the card. All five were verified by hand against the landed `PrivacyPage.qml` and `PowerPage.qml`; the harness half was not exercised. - **`quickshell/settings-search-contract` — NOT RUN**: it starts a Quickshell harness. The nine new entries were checked statically — parsed out of `SettingsSearch.qml` and confirmed to route to `privacy` and `ssh-keys`, both of which `settings-nav-contract` confirms are leaves. - **`quickshell/settings-pages-contract` and `settings-write-sweep-contract` — NOT RUN**: both load the QML. Neither page has been rendered by anything in this phase. - **`Traces.qml` is pinned but never loaded.** Its seam (`PANAMA_PRIVACY_HELPER`) and its lack of a trash path are checked from the source; no contract here constructs the singleton. - **A deliberate duplicate label in search.** "Application permissions" now appears twice — once routing to Applications (what a Flatpak's sandbox exposes) and once to Privacy (what the portal recorded). They are different questions that share a name, both cards are titled that, and the dedupe key includes the page, so both survive. Worth a look on the rendered sidebar. - **Seams pinned by name**: `PANAMA_PRIVACY_HELPER`, `PANAMA_PERMISSIONS_HELPER`, `PANAMA_SSH_KEYS_HELPER`, `PANAMA_PRIVACY_RECENTS`, `PANAMA_PRIVACY_THUMBNAILS`. Both privacy seams re-confine against `HOME`, so a hermetic run points `HOME` at a scratch tree rather than pointing the seams out of it; `panama-ssh-keys` reads `Path.home()`, so `HOME` alone redirects it. - Run order for this phase: the hermetic ones first (`permissions-contract`, `privacy-traces-contract`, `ssh-keys-contract`), then the source-only ones (`gnome-handoff-contract`, `settings-ownership-contract`, `setup/readme-contract`, `search-routing-contract`), then the read-only system one (`secrets-contract`, which lists the live keyring), then the harness ones (`settings-search-contract`, `lock-screen-settings-contract`), and `settings-pages-contract` last, as before.