pal-e-docs

Review: Fix Steam XWayland overlay crash (re-review)

review-1652-2026-06-28-r2 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Re-review of board item #1652 after scope refinement. All [BODY] issues from the previous review (review-1652-2026-06-28) have been resolved. Only [SCOPE] items remain.

Template Completeness

Template: template-issue-bug
  • [x] Type — Bug
  • [x] Lineage — Standalone, discovered during Pal-E World Phase 2 testing on 2026-06-28
  • [x] Repo — ldraney/hyprland-config
  • [x] What Broke — Steam overlay pipe crash every 1-3 minutes on XWayland/Hyprland
  • [x] Repro Steps — 4 clear steps provided
  • [x] Expected Behavior — Present, specifies -no-overlay fix
  • [x] Environment — archbox, GTX 1070, Hyprland + XWayland, Steam stable
  • [x] File Targets — 3 targets with line numbers (added since previous review)
  • [x] Acceptance Criteria — 4 criteria (increased from 3, added docs update AC)
  • [x] Related — pal-e-world project referenced
All required Bug template sections present. File Targets section is an extension beyond the base template — well-structured.

Traceability

  • [x] story:remote-play label — present on board item
  • [ ] story note MISSING — project-pal-e-world user-stories section lists "pal-e-world" but no "remote-play" entry. [SCOPE] Add "remote-play" user story entry to project-pal-e-world user-stories section. Three board items (#1651, #1652, #1654) use this label.
  • [x] arch:infra label — present on board item
  • [ ] arch note MISSING — search for arch-infra returned zero results in pal-e-docs. [SCOPE] Create architecture note arch-infra for component infra. Multiple board items reference this label.
  • [x] Forgejo issue — ldraney/hyprland-config#14, state: open

File Targets

  • [x] hyprland.lua:137 — verified: line 137 contains hl.exec_cmd("pgrep -x steam || steam"). Fix correctly targets adding -no-overlay flag.
  • [x] docs/architecture.md:76 — verified: line 76 reads "Known limitation: Steam overlay pipe crash (pipes.cpp:900) every 1-3 minutes on XWayland. Unfixable."
  • [x] docs/gpu-sharing-gow.md:5 — verified: line 5 contains "has an unfixable Steam overlay crash (pipes.cpp:900)"
  • [ ] docs/gpu-sharing-gow.md:65 — NOT LISTED as file target. Blast radius finding: this line also says "Steam overlay pipe crash every 1-3 minutes on XWayland. Unfixable on Hyprland's XWayland." The AC "Docs updated to reflect the working fix (no longer 'Unfixable')" covers this implicitly, but adding the explicit file target would prevent a stale reference. [BODY] Add docs/gpu-sharing-gow.md:65 as a file target.

Repo Placement

OK — issue filed on ldraney/hyprland-config, all file targets (hyprland.lua, docs/) live in that repo. Single repo, no cross-repo concerns.

Dependencies

  • #1651 "Install Sunshine on archbox" (3pt, story:remote-play) — same story, independent. Sunshine streaming is a separate concern.
  • #1654 "E2E: MacBook → Moonlight → Tailscale → archbox" (2pt, story:remote-play) — soft dependency; E2E benefits from Steam stability but is not blocked.
  • #1650 "Scale down k8s Ollama to free GPU" (1pt, story:gpu-freedom) — independent, different story.
  • No items in in_progress that block this ticket. Phase 1 is in_progress but unrelated.
  • Dependencies acceptable for standalone bug — not documented in issue body, not needed.

Acceptance Criteria

4 criteria — reasonable count, under the 5 threshold.
  • "Steam launches with -no-overlay flag via hyprland.lua" — agent-verifiable (grep for flag in file).
  • "Steam runs without crashing for 30+ minutes" — manual testing only. Testable but not automatable.
  • "Docs updated to reflect the working fix (no longer 'Unfixable')" — agent-verifiable (grep for "Unfixable" should return zero hits post-fix).
  • "No regression in Hyprland session stability" — manual testing only. Testable but not automatable.
AC quality is solid. The docs AC is broad enough to cover all "Unfixable" references including the unlisted line 65.

Blast Radius

  • docs/gpu-sharing-gow.md:65 — second "Unfixable" reference in same file, not listed as file target (see File Targets section above).
  • docs/pal-e-world.md:73-94 — already documents the crash and -no-overlay solution correctly. No change needed.
  • README.md — mentions Steam but makes no "Unfixable" claims. No change needed.
  • A worktree .claude/worktrees/steam-crash-fix already exists, suggesting prior implementation work was started. Implementer should check for stale state.

Decomposition Assessment

No decomposition needed.
  • File targets: 3 files in 1 repo (plus 1 additional line in same file)
  • Acceptance criteria: 4 (under threshold of 5)
  • Estimated agent work: under 5 minutes
  • Points: 1 (correctly sized)

Recommendations

Resolved from previous review:
  • [BODY] Add file targets — RESOLVED: 3 file targets with line numbers now specified
  • [BODY] Add AC for "Unfixable" docs — RESOLVED: AC now includes "Docs updated to reflect the working fix"
Remaining:
  • [SCOPE] Add "remote-play" user story entry to project-pal-e-world user-stories section. Three board items (#1651, #1652, #1654) use this story label but no backing entry exists.
  • [SCOPE] Create architecture note arch-infra for component infra. Multiple board items reference this arch label.
  • [BODY] Minor: Add docs/gpu-sharing-gow.md:65 as a fourth file target — second "Unfixable" reference in the same file. The AC covers this implicitly, but explicit targeting prevents oversight.