pal-e-docs

Review: Fix Steam XWayland overlay crash

review-1652-2026-06-28 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Template: template-issue-bug
  • [x] Type — Bug
  • [x] Lineage — Standalone, discovered during Pal-E World Phase 2 testing
  • [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 with 3 potential solutions listed
  • [x] Environment — archbox, GTX 1070, Hyprland + XWayland, Steam stable
  • [x] Acceptance Criteria — 3 criteria
  • [x] Related — pal-e-world project referenced
All required Bug template sections are present.

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, or align the label to story:pal-e-world. Note: board items #1651 and #1654 also use story:remote-play, so adding the story entry is preferred.
  • [x] arch:infra label — present on board item
  • [ ] arch note MISSING — search for arch-infra returned zero results. [SCOPE] Create architecture note arch-infra for component infra.
  • [x] Forgejo issue — ldraney/hyprland-config#14, state: open

File Targets

The issue body does not specify file targets. Bug template does not require them, but the fix location is identifiable from codebase inspection:
  • [ ] hyprland.lua line 137 — ISSUE: Not mentioned in issue body. This is the Steam launch command (pgrep -x steam || steam) that needs a gamescope wrapper or -no-overlay flag. [BODY] Add as file target.
  • [x] docs/architecture.md line 76 — verified: currently says crash is "Unfixable" — will need update if workaround succeeds
  • [x] docs/gpu-sharing-gow.md line 5 — verified: currently says crash is "unfixable on Hyprland's XWayland" — same doc update needed
  • [x] docs/pal-e-world.md lines 73-93 — verified: documents the crash and solutions, includes code snippet

Repo Placement

OK — issue is filed on ldraney/hyprland-config, fix is in hyprland.lua which lives 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 from Steam stability.
  • #1654 "E2E: MacBook to Moonlight to Tailscale to archbox" (2pt, story:remote-play) — soft dependency; E2E test benefits from Steam being stable, but 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 "Verify & Configure Server" is in_progress but unrelated.
  • Dependencies are not documented in the issue body — acceptable for a standalone bug.

Acceptance Criteria

3 criteria — reasonable count.
  • "Steam runs without crashing for 30+ minutes" — requires manual testing (agent cannot observe runtime stability). Testable but not automatable.
  • "Working solution documented in this repo" — agent-verifiable (check for doc updates).
  • "No regression in Hyprland session stability" — requires manual testing. Testable but not automatable.
Missing AC: docs/architecture.md and docs/gpu-sharing-gow.md currently claim the crash is "Unfixable." If a workaround is applied, these docs need correcting. [BODY] Add AC: "Update docs that claim crash is unfixable."

Blast Radius

  • docs/architecture.md:76 and docs/gpu-sharing-gow.md:5 both state the crash is unfixable. A successful fix contradicts these docs.
  • gamescope window rule already exists in hyprland.lua:158, indicating gamescope was anticipated but not wired into the launch path.
  • The GOW container approach (docs/gpu-sharing-gow.md) provides an alternative path running Steam under native Xorg inside containers, avoiding this crash entirely. This fix is specifically for the native XWayland path.
  • A worktree steam-crash-fix already exists, suggesting prior work was started. No conflict risk, but the implementer should check for stale state.

Decomposition Assessment

No decomposition needed.
  • File targets: 1-2 files in 1 repo (hyprland.lua + docs)
  • Acceptance criteria: 3 (under threshold of 5)
  • Estimated agent work: under 5 minutes
  • Points: 1 (correctly sized)

Recommendations

  • [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] Add file target to issue body: hyprland.lua line 137 — Steam launch command needs gamescope wrapper or -no-overlay flag.
  • [BODY] Add acceptance criterion: "Update docs/architecture.md and docs/gpu-sharing-gow.md to remove 'unfixable' claim if workaround succeeds."