feat(damask): ship flatpak overrides and background systemd service by repires · Pull Request #1187 · projectbluefin/common

repires · 2026-09-23T17:47:01Z

bluefin-common PR

What does this change?

Configures Flatpak sandbox filesystem overrides, a tmpfiles symlink, and a systemd user background service for Damask (app.drey.Damask).

Why?

Closes #1160

PR pipeline

opened ──▶ 4-review ──▶ approved ──▶ merged

A maintainer reviews and approves; merge goes through the merge queue.
Select blocked or hold to pause the work.

Checklist

PR title follows Conventional Commits (fix:, feat:, docs:, ci:, refactor:, etc.)
just check passes
pre-commit run --all-files passes
AGENTS.md / docs/SKILL.md / docs/skills/ links remain valid

AI attribution

Assisted-by: Gemini via Google Antigravity
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

— hive: backend=agy

🐝 Hive Agent: contributor | SHA: 9a3a3c0

hivecommons-hive

Read the tree at 9a3a3c0 plus #1186's branch. The unit, override and tmpfiles rule are well-formed (tests/test_damask_service.bats covers the format, and the tmpfiles L pattern matches bazaar-flatpak.conf). One thing a maintainer needs to decide before merging:

This PR and #1186 are two halves of one change and neither works alone.

#1187 ships system_files/bluefin/usr/lib/systemd/user/damask.service with [Install] WantedBy=graphical-session.target, but nothing in this PR enables it — no user-preset entry (compare system_files/shared/usr/lib/systemd/user-preset/01-brew-preinstall.preset) and no hook. On its own the unit is installed but inert.
#1186 ships user-setup.hooks.d/25-damask-setup.sh, whose last line (:29) is an unguarded systemctl --user enable damask.service — but #1186 does not ship the unit. Merged first, that hook fails with "Unit damask.service does not exist" on every first login.

The two PRs touch disjoint hunks of Justfile and .github/workflows/unit-tests.yml, so git will merge them cleanly — which is exactly why the ordering will not be caught mechanically.

Question for a maintainer: should these be squashed into one PR, or should #1187 land first and #1186's hook guard the enable with a unit-exists check? Either is fine; landing #1186 first is not.

Open question I could not verify from the repo: that flatpak run app.drey.Damask --background is a flag Damask accepts (damask.service:10). If it is not, Restart=on-failure / RestartSec=10 will keep relaunching the GUI every 10 s after first login.

Confidence: 3/5 (needs attention) — 2 medium findings

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

castrojo · 2026-09-24T17:55:15Z

Rebased cleanly onto latest main.

Conflicts resolved: Preserved all testing table entries in docs/TESTING.md.
Tests run: bats tests/test_damask_service.bats (5 passed), just check.

…nce check - Check `systemctl --user list-unit-files damask.service` before calling enable, ensuring the hook safely tolerates environments where damask.service has not yet been installed (such as during independent staging before #1187 merges). - Update Bats test suite with a test verifying graceful skip when the unit is absent.

repires · 2026-09-25T00:26:09Z

Thank you for the review!

Regarding the ordering and coupling with #1186:

We have updated feat(wallpaper): add Damask first-run setup hook and non-destructive defaults #1186 (25-damask-setup.sh) with commit 2a2a10d to check systemctl --user list-unit-files damask.service before enabling. With that guard in place, feat(wallpaper): add Damask first-run setup hook and non-destructive defaults #1186 will not fail if merged first, and feat(damask): ship flatpak overrides and background systemd service #1187 remains independently valid to merge in either order.
Regarding --background: Damask supports the background flag as documented in upstream app specs when run headlessly for wallpaper rotation services.

🐝 Hive Agent: contributor | SHA: unknown

Danathar · 2026-09-25T14:43:20Z

Flatpak ignores the override that's supposed to let Damask read the Bluefin wallpapers. So the slideshow folder that #1186 sets up will be empty inside Damask.

What I saw: Flatpak refuses to share anything under /usr with an app. It prints a warning and drops that entry. I copied this PR's app.drey.Damask override file, unchanged, into a user override for another installed app and ran it (Flatpak 1.18.0, Bluefin 44):

F: Not sharing "/usr/share/backgrounds" with sandbox: Path "/usr" is reserved by Flatpak
ls: cannot access '/usr/share/backgrounds/bluefin': No such file or directory

Inside the sandbox, /usr is the GNOME runtime, not the host. So folder-uri='file:///usr/share/backgrounds/bluefin' from #1186 points at a folder that doesn't exist as far as Damask can tell. The xdg-data/backgrounds:ro half of the override is fine.

The only way I found to reach the host's copy is host-os:ro. With that, the files show up under /run/host/usr/share/backgrounds/bluefin, and #1186's folder-uri would need to point there. That shares all of the host's /usr read-only, which is a real tradeoff, so I'm not saying it's the only answer. Issue #1160 has the same override, so this came from the plan, not from how you implemented it.

Everything else checked out:

CI on 0d596d9 is green (build, unit tests, E2E, validate), and bats tests/test_damask_service.bats passes locally, 5 of 5.
--background is a real Damask option (src/application.vala).
The two ConditionPathExists=| lines correctly cover both per-user and system installs.

Landing order with #1186: #1186's first-login hook only enables damask.service if the unit file already exists, and it marks itself done either way. If #1186 reaches an image before this PR does, nobody who logs in on that image will ever get the service enabled. So this PR should land first, or at least in the same image.

hanthor

flatpak-overrides/app.drey.Damask:2: filesystems=/usr/share/backgrounds:ro won't work, because Flatpak refuses to expose host /usr paths. Use host-os:ro instead (host /usr then shows up at /run/host/usr) and point the folder-uri in #1186 there.
damask.service:10: please confirm Damask actually accepts --background. If it doesn't, Restart=on-failure with RestartSec=10 will relaunch the GUI every 10 seconds.
Nothing enables the unit (no preset), so it only works in combination with #1186. Either squash the two PRs or make sure this one lands first.

… duplicate PRs (#1201) # bluefin-common PR ## What does this change? Adds `docs/contributing/self-collision-preflight.md` — a planning draft for a preflight step that intersects a lane's own open PRs before it files again — and links it from `CONTRIBUTING.md`, `docs/factory/agentic-model.md`, and `docs/skills/pr-review/references/duplicate-cluster.md`. ## Why? Closes #1060 The hold-gated protocol lists open PRs at kick time precisely so a lane can prove its new filing is disjoint from work already in flight. Within one lane that check failed: the quality lane opened two duplicate pairs covering identical file clusters within three days (`finpilot#285`/`#303`, `finpilot#296`/`#299`), costing four review slots for two pieces of work. **All four named PRs are already resolved** — `#285` merged 2026-09-04, `#296` merged 2026-09-05, `#299` merged 2026-09-06, `#303` closed 2026-09-06 without merge. The queue adjudicated them rather than any rule preventing the second filing, so the actionable remainder is the rule. ### Why this is a draft and not a direct edit to the hard rules The issue proposes "a lane may not open a PR whose file cluster intersects its own open hold-gated PRs." I re-audited the **31 open app-authored PRs** across the ten repositories tracked in #1058 on 2026-09-23 and found **no confirmed intra-lane duplicate cluster**. Every file-cluster intersection that exists is legitimate work the prohibition would have blocked: | Intersecting pair | Same lane? | Why it is not a duplicate | |---|---|---| | `bluefin#1227` / `#1310` | `app/mergeraptor` | Distinct dependency digest bumps (`projectbluefin/common:latest` vs `ublue-os/brew:latest`) sharing `image-versions.yml` | | `server#238` / `#239` | `app/mergeraptor` | Distinct dependency digest bumps (`projectbluefin/actions` vs `taiki-e/install-action`) sharing `.github/workflows/build.yml` | | `dakota-iso#142` / `#146` | `app/hivecommons-hive` | A cosign-verification security fix and a host-side config SSOT refactor, both touching `justfile` | | `common#1186` / `#1187` | human (`repires`) | Two human PRs closing different issues (#1161, #1160) sharing `Justfile` and `.github/workflows/unit-tests.yml` | A shared file is not proof of duplication — that is already the factory's rule at review time ([`common-rationalizations.md`](https://github.com/projectbluefin/common/blob/main/docs/skills/pr-review/references/common-rationalizations.md), [`duplicate-cluster.md`](https://github.com/projectbluefin/common/blob/main/docs/skills/pr-review/references/duplicate-cluster.md)). The real finpilot duplicates shared an *intent and closing issue*, not merely a path. So the draft proposes the evidenced alternative: **intersect, compare hunks and closing-issue sets, then either comment on the existing PR or disclose the overlap in the new body** — a disclosure rule rather than a prohibition, which keeps the judgment where the evidence is and makes it visible to the reviewer. It is drafted rather than applied because it binds filing behavior org-wide. That matches the precedent set for the sibling strategist findings: #1043 → `hold-gate-rubric.md` (#1188) and #1052 → `agent-lane-throttle.md` (#1197), both merged as drafts pending a maintainer decision. Nothing in the draft changes agent runtime behavior, adds a label, or adds a CI gate. ## PR pipeline ``` opened ──▶ 4-review ──▶ approved ──▶ merged ``` > A maintainer reviews and approves; merge goes through the merge queue. > Select `blocked` or `hold` to pause the work. ## Checklist - [x] PR title follows Conventional Commits (`fix:`, `feat:`, `docs:`, `ci:`, `refactor:`, etc.) - [x] `just check` passes - [x] `pre-commit run --all-files` passes (all 15 hooks green, including skill front-matter, `docs/SKILL.md` index, internal markdown links, and the generated `docs/skills/index.json` catalog) - [x] Skill doc updated if the change affects agent-facing conventions or behavior — `docs/skills/pr-review/references/duplicate-cluster.md` gained a prevention pointer to the draft; `docs/factory/agentic-model.md` gained a pointer from the existing duplicate-PR rule - [x] `AGENTS.md` / `docs/SKILL.md` / `docs/skills/` links remain valid (`scripts/check-doc-links.sh` passes) - [ ] CI is green after push — pending ## AI attribution This change was not authored via GitHub Copilot, so the Copilot-specific `Co-authored-by` trailer is deliberately omitted rather than asserted. The attribution trailer names the actual model: ``` Assisted-by: deepseek/deepseek-v4.1-flash via Hive ``` — hive: backend=litellm model=deepseek/deepseek-v4.1-flash --- 🐝 **Hive Agent**: `contributor` | **SHA:** `a8fcea8` Signed-off-by: sramkrishna <sramkrishna@users.noreply.github.com> Co-authored-by: sramkrishna <sramkrishna@users.noreply.github.com>

castrojo · 2026-09-25T23:12:55Z

Status update on Damask overrides and service:
Review finding by @Danathar and @hanthor:
Flatpak's sandbox refuses to bind-mount host /usr paths (Path "/usr" is reserved by Flatpak), so filesystems=/usr/share/backgrounds:ro is ignored by Flatpak at runtime and Damask cannot see the Bluefin wallpapers at that path. The suggested alternative is host-os:ro (accessing host files via /run/host/usr/share/backgrounds/bluefin), which represents a broader sandbox permission.

Awaiting maintainer/author decision on sandbox permission trade-off.

hanthor

Thanks. filesystems=host-os:ro fixes the /usr problem, and the bats assertion was updated to match.

I checked --background against upstream: src/application.vala registers it as a main option, and it's the same flag Damask's own autostart portal request uses. So that point is resolved.

Still open:

The PR conflicts with main in docs/TESTING.md, and because of that no checks have run on c611e09. Please rebase so CI runs.
The unit is still only enabled by the #1186 hook. That's fine as long as #1186 lands after this one. I'll keep the ordering in mind.

Configure host permissions and background lifecycle for Damask (`app.drey.Damask`) so it can read wallpaper directories and run in background mode when installed. Closes #1160 - The Flathub build of Damask carries strictly sandboxed finish-args with no filesystem access. - Flatpak sandbox override grants access to staged wallpapers in `/usr/share/backgrounds` and user-downloaded extras in `~/.local/share/backgrounds` (`xdg-data/backgrounds`). - Tmpfiles configuration symlinks `/usr/share/ublue-os/flatpak-overrides/app.drey.Damask` into `/var/lib/flatpak/overrides/app.drey.Damask` matching Bazaar's pattern. - Background user unit `damask.service` runs `/usr/bin/flatpak run app.drey.Damask --background` guarded by `ConditionPathExists=|` disjunction for user and system flatpak paths and `ConditionUser=!@system`. - Added `tests/test_damask_service.bats` covering override file permissions/syntax, tmpfiles symlink structure and column format, systemd unit conditions/lifecycle, and `systemd-analyze verify`. - Registered `test_damask_service.bats` in `Justfile` and CI workflow `unit-tests.yml`. - Documented `test_damask_service.bats` in `docs/TESTING.md`. - `just check` passes. - `pre-commit run --all-files` passes. - `bats tests/test_damask_service.bats` passes (5/5). - Full `just test` suite passes. Hive-Run: #1160 Hive-Plan: wallpaper-enhancements-damask Hive-Spec: wallpaper-enhancements#damask-sandbox-and-service Assisted-by: Gemini via Google Antigravity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: repires <repires@users.noreply.github.com>

…apers

castrojo · 2026-09-26T01:21:39Z

@hanthor Rebased cleanly onto current main (resolving the docs/TESTING.md conflict and incorporating the merged #1249 testing suite additions). bats tests/test_damask_service.bats, just check, and pre-commit run --all-files all pass. CI is running. Ready for your review and approval to hit +2.

hanthor

Rebase is clean. The PR's own files are unchanged from c611e09, and the docs/TESTING.md conflict resolved to a single added row for test_damask_service.bats. CI is green. Approving, and I'll hold #1186 until this lands.

repires requested review from a team, ahmedadan, castrojo and hanthor as code owners September 23, 2026 17:47

castrojo approved these changes Sep 23, 2026

View reviewed changes

hivecommons-hive Bot mentioned this pull request Sep 23, 2026

feat(wallpaper): add Damask first-run setup hook and non-destructive defaults #1186

Merged

5 tasks done

sramkrishna mentioned this pull request Sep 23, 2026

[strategist] Agent lanes self-colliding: duplicate hold-gated PRs for identical clusters (finpilot #285/#303, #296/#299) #1060

Closed

hivecommons-hive Bot reviewed Sep 24, 2026

View reviewed changes

castrojo force-pushed the feat/damask-overrides-service branch from 9a3a3c0 to 2a00df5 Compare September 24, 2026 17:54

Danathar mentioned this pull request Sep 25, 2026

feat(wallpaper): ship original looping movie for Hidamari #1207

Merged

hanthor mentioned this pull request Sep 25, 2026

feat(chairlift): add wallpaper slideshow and video wallpaper brew bundles #1185

Merged

hanthor requested changes Sep 25, 2026

View reviewed changes

repires and others added 2 commits September 25, 2026 21:21

fix(damask): use host-os:ro override so Flatpak can access host wallp…

cf6847b

…apers

castrojo force-pushed the feat/damask-overrides-service branch from c611e09 to cf6847b Compare September 26, 2026 01:21

hanthor approved these changes Sep 26, 2026

View reviewed changes

hanthor added this pull request to the merge queue Sep 26, 2026

Merged via the queue into main with commit d43aa89 Sep 26, 2026
10 checks passed

hanthor deleted the feat/damask-overrides-service branch September 26, 2026 01:52

Danathar mentioned this pull request Oct 14, 2026

Wallpaper Enhancements (Damask, Hidamari, ChairLift Bundles) #1157

Closed

10 tasks

Navigation Menu

Repository navigation

feat(damask): ship flatpak overrides and background systemd service - #1187

feat(damask): ship flatpak overrides and background systemd service#1187
hanthor merged 2 commits into
mainfrom
feat/damask-overrides-service

repires commented Sep 23, 2026

Uh oh!

hivecommons-hive Bot left a comment

Uh oh!

castrojo commented Sep 24, 2026

Uh oh!

repires commented Sep 25, 2026

Uh oh!

Danathar commented Sep 25, 2026

Uh oh!

hanthor left a comment

Uh oh!

castrojo commented Sep 25, 2026

Uh oh!

hanthor left a comment

Uh oh!

castrojo commented Sep 26, 2026

Uh oh!

hanthor left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

repires commented Sep 23, 2026

bluefin-common PR

What does this change?

Why?

PR pipeline

Checklist

AI attribution

— hive: backend=agy

Uh oh!

hivecommons-hive Bot left a comment

Choose a reason for hiding this comment

Uh oh!

castrojo commented Sep 24, 2026

Uh oh!

repires commented Sep 25, 2026

Uh oh!

Danathar commented Sep 25, 2026

Uh oh!

hanthor left a comment

Choose a reason for hiding this comment

Uh oh!

castrojo commented Sep 25, 2026

Uh oh!

hanthor left a comment

Choose a reason for hiding this comment

Uh oh!

castrojo commented Sep 26, 2026

Uh oh!

hanthor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants