Advance redbear-full Wayland, greeter, and Qt integration

Consolidate the active desktop path around redbear-full while landing the greeter/session stack and the runtime fixes needed to keep Wayland and KWin bring-up moving forward.
2026-04-19 17:59:58 +01:00
parent 370d27f44d
commit 9880e0a5b2
137 changed files with 14176 additions and 2016 deletions
@@ -103,12 +103,16 @@ bounded-hardware, or release-grade completeness.
 - MCFG handling was removed from `acpid` and replaced with the `pcid /config` path.
 - Shutdown eventing via `/scheme/kernel.acpi/kstop` is implemented and consumed by
  `redbear-sessiond`.
+- `acpid` now models `S1` / `S3` / `S4` / `S5` explicitly in userspace, and the current `_S5`
+  shutdown path routes through that model instead of a special-case magic value.

 ### Weak today

 - Sleep-state transitions beyond `\_S5` are unsupported.
 - Sleep eventing is unsupported.
 - `SLP_TYPb` remains incomplete for broader sleep-state handling.
+- Non-`S5` sleep targets are now represented explicitly, but they remain groundwork-only and do not
+  imply implemented suspend/resume support yet.
 - AML init order is still tied to PCI FD registration timing.
 - Some physmem / opregion failure paths are still not explicit enough.
 - DMAR remains orphaned in `acpid` source: present, not wired, not fully transferred.
@@ -44,7 +44,7 @@ take 5+ years.
 | x2APIC | ✅ Works | Auto-detected via CPUID, APIC/SMP functional |
 | HPET | ✅ Works | Timer initialized from ACPI |
 | IOMMU | 🚧 In progress | `iommu` daemon now builds, auto-discovers common IVRS table paths, reaches unit detection plus `scheme:iommu` registration in the QEMU/AMD-IOMMU validation path, and now has a guest-driven first-use self-test that initializes both discovered units and drains events successfully in QEMU; real hardware validation is still missing |
-| AMD GPU | 🚧 In progress | MMIO mapped, DC port compiles, MSI-X wired, no hardware validation yet |
+| AMD GPU | 🚧 In progress | MMIO mapped, bounded Red Bear display glue path builds, MSI-X wired; imported Linux AMD DC/TTM/core remain under compile triage; no hardware validation yet |
 | Wi-Fi/BT | 🚧 In progress | Repo now carries bounded wireless scaffolding: one experimental in-tree Bluetooth slice exists, and a bounded Intel Wi-Fi scaffold exists elsewhere, but validated wireless connectivity support is still incomplete |
 | USB | ⚠️ Variable | Some USB controllers work, others don't |

@@ -259,22 +259,27 @@ ONLY the display/modesetting portion first, using linux-kpi headers.
 | MSI-X interrupt support | ✅ | `local/recipes/gpu/redox-drm/source/src/drivers/interrupt.rs` — shared MSI-X/MSI/legacy abstraction with quirk-aware fallback |
 | Intel pcid-spawner config | ✅ | `local/config/pcid.d/intel_gpu.toml` — auto-detect Intel GPUs |

-### P2: AMD GPU Display — COMPLETE (compiles, no HW validation)
+### P2: AMD GPU Display — BOUNDED PATH BUILDS (imported Linux AMD DC/TTM/core still under compile triage)

 | Component | Status | Files |
 |-----------|--------|-------|
 | redox-drm daemon | ✅ | `local/recipes/gpu/redox-drm/source/` — DRM scheme daemon |
 | AMD driver (Rust) | ✅ | `local/recipes/gpu/redox-drm/source/src/drivers/amd/mod.rs` |
-| AMD DisplayCore (FFI) | ✅ | `local/recipes/gpu/redox-drm/source/src/drivers/amd/display.rs` |
-| AMD PCI stubs (dynamic) | ✅ | `local/recipes/gpu/amdgpu/source/redox_stubs.c` — populated from Rust via FFI |
-| AMD DC init (C) | ✅ | `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` — modesetting, connector detect |
-| AMD glue headers | ✅ | `local/recipes/gpu/amdgpu/source/redox_glue.h` — Linux compat surface |
+| AMD DisplayCore (FFI surface) | ✅ bounded | `local/recipes/gpu/redox-drm/source/src/drivers/amd/display.rs` |
+| AMD PCI stubs (dynamic) | ✅ bounded | `local/recipes/gpu/amdgpu/source/redox_stubs.c` — populated from Rust via FFI |
+| AMD DC init / modeset glue (C) | ✅ bounded | `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` — modesetting, connector detect |
+| AMD glue headers | ✅ bounded | `local/recipes/gpu/amdgpu/source/redox_glue.h` — Linux compat surface for the retained path |
 | GTT manager | ✅ | `local/recipes/gpu/redox-drm/source/src/drivers/amd/gtt.rs` |
 | Ring buffer | ✅ | `local/recipes/gpu/redox-drm/source/src/drivers/amd/ring.rs` |
 | GEM buffer mgmt | ✅ | `local/recipes/gpu/redox-drm/source/src/gem.rs` |
 | DMA-BUF | ✅ | `local/recipes/gpu/redox-drm/source/src/scheme.rs` (PRIME export/import via opaque tokens) |
 | Intel driver | ✅ | `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs` + `display.rs` |

+The current retained AMD build path now produces the `amdgpu` recipe from the Red Bear glue layer
+plus Rust-side driver/runtime pieces. The broad imported Linux AMD display, TTM, and amdgpu core
+trees are no longer treated as compile-complete deliverables; they remain under compile triage until
+the bounded path proves a concrete need to re-introduce them.
+
 For bounded runtime display validation, Red Bear now uses the shared
 `local/scripts/test-drm-display-runtime.sh` harness, with `local/scripts/test-amd-gpu.sh` as the
 AMD wrapper.
@@ -282,6 +287,27 @@ AMD wrapper.
 Human-readable PCI naming for AMD/Intel devices now comes from the shipped `pciids` database rather
 than from hand-maintained GPU name tables in local runtime tools.

+#### Historical P2 implementation snapshot
+
+The old standalone `P2-AMD-GPU-DISPLAY.md` milestone record is now folded into this AMD-specific
+reference.
+
+Important historical P2 details that still matter:
+
+- **Architecture:** `userspace apps -> scheme:drm -> redox-drm daemon -> AMD DC (C code,
+  linux-kpi) -> MMIO`
+- **Build integration:** the Red Bear GPU path is rooted in `local/recipes/gpu/redox-drm/` and
+  `local/recipes/gpu/amdgpu/`, with PCI auto-detection from `local/config/pcid.d/amd_gpu.toml`
+  and the imported Linux AMD driver tree in `local/recipes/gpu/amdgpu-source/`
+- **Historical P2 boot sequence:** kernel PCI init -> `pcid` AMD GPU detection -> `redox-drm`
+  launch -> BAR/MMIO mapping -> firmware load via `scheme:firmware` -> AMD DC init -> connector
+  detect / EDID -> `scheme:drm/card0` registration
+- **Historical implementation closure:** the scoped P2 implementation task was compile-complete for
+  display-side bring-up, but hardware validation remained and still remains a separate evidence gate
+
+That milestone should now be read through the current GPU/DRM plan and current desktop status docs
+rather than as a standalone execution authority.
+
 ### Build Verification

 All crates compile with `cargo check` (0 errors):
@@ -0,0 +1,363 @@
+# AMDGPU DC Compile Triage Plan
+
+**Date:** 2026-04-18
+**Scope:** Triage of the current Red Bear amdgpu AMD Display Core compile path, specifically the
+decision between growing the Linux compatibility surface and narrowing the imported display/DC
+source set to the bounded path actually needed for first display bring-up.
+
+> **Planning authority note (2026-04-18):** this file is a focused amdgpu/DC compile-triage and
+> execution document. It does not replace `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` as the
+> canonical GPU/DRM plan. Use the DRM modernization plan for overall execution order, Intel/AMD
+> parity criteria, and broader acceptance gates. Use this file for the specific question of how to
+> triage the current amdgpu DC compile break without drifting into open-ended compatibility work.
+
+> **Status update (2026-04-18):** Phase 1B has now been carried out in bounded form. The `amdgpu`
+> recipe builds successfully on the retained Red Bear glue path (`amdgpu_redox_main.c` +
+> `redox_stubs.c`), while the imported Linux AMD display, TTM, and amdgpu core trees remain
+> explicitly outside the retained compile surface and still under compile triage.
+
+## Title and intent
+
+Red Bear currently compiles the imported AMD display tree too broadly for the evidence-backed goal
+it actually has today.
+
+The immediate goal is **not** to prove that the full imported AMD Display Core tree compiles on
+Redox. The immediate goal is to unblock the bounded display path needed for first display-side
+bring-up while preserving a maintainable route toward broader DC closure later.
+
+This document exists to prevent two failure modes:
+
+1. treating the first compile error as if it justifies unconstrained `linux-kpi` expansion, and
+2. claiming progress from a narrowed compile path without documenting exactly what was excluded and
+   why.
+
+## Current grounded state
+
+### Bottom line
+
+The original broad-tree failure was **not** a `freesync.c`-specific logic bug. It exposed a broader
+mismatch between the imported AMD DC / TTM / amdgpu trees and the current Red Bear compatibility
+strategy.
+
+After narrowing the recipe to the actual retained first-display path, the `amdgpu` recipe now
+builds successfully from the Red Bear glue layer alone. That is the current truthful state: the
+bounded retained path builds, while the imported Linux trees remain under compile triage rather than
+being claimed as compile-complete.
+
+### Confirmed evidence
+
+| Area | Current evidence | Repo grounding |
+|---|---|---|
+| Historical broad-path rule | The old recipe compiled all `display/*.c` files and failed in optional AMD DC code before the retained path was proven | historical recipe state + `local/recipes/gpu/amdgpu/target/x86_64-unknown-redox/build/freesync.o.log` |
+| Current retained build rule | The current recipe compiles only the bounded Red Bear glue path and links `libamdgpu_dc_redox.so` from that retained surface | `local/recipes/gpu/amdgpu/recipe.toml` |
+| Historical first hard failure | `freesync.c -> dm_services.h -> dm_services_types.h -> os_types.h -> linux/kgdb.h` | `local/recipes/gpu/amdgpu/target/x86_64-unknown-redox/build/freesync.o.log` |
+| Current shim posture | Compatibility surface is partial, not absent | `local/recipes/drivers/linux-kpi/source/src/c_headers/`, `local/recipes/gpu/amdgpu/source/redox_glue.h` |
+| Small retained-path shim probes attempted | Added minimal `linux/export.h` and `linux/refcount.h` while testing whether imported TTM belonged on the retained path | `local/recipes/drivers/linux-kpi/source/src/c_headers/linux/export.h`, `.../linux/refcount.h` |
+| Switch criterion outcome | Imported TTM immediately fanned into broader Linux-kernel surfaces (`__cond_acquires`, `iosys-map`, and related header fallout), so the retained path was narrowed again instead of growing shims further | retained build logs during TTM probe |
+| Current Red Bear need | First display bring-up needs a bounded display path, not proof that all optional AMD DC subtrees compile | `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md`, `local/docs/AMD-FIRST-INTEGRATION.md` |
+
+### Why the current approach is unstable
+
+The current amdgpu recipe uses a broad compile rule that effectively says:
+
+> compile the imported display tree first, then see what breaks.
+
+That is useful for discovery, but it is a poor default execution strategy for bounded bring-up.
+
+It pulls optional and advanced display code into the same compile surface as the first modeset path,
+which means a failure in a module such as FreeSync can block the entire experiment even when that
+module is not yet proven necessary for the first Red Bear display target.
+
+## Triage question
+
+Red Bear needs an explicit answer to this question before continuing:
+
+> Should the repo first grow the Linux compatibility layer until the full imported AMD display tree
+> compiles further, or should it first narrow the imported source set to the display path Red Bear
+> actually needs today?
+
+This document answers:
+
+- **Start with Strategy B** — narrow the DC source set.
+- Use **Strategy A** — minimal shim additions — only as a controlled fallback when the retained,
+  bounded display path still proves a small required compatibility gap.
+
+## Strategy comparison
+
+| Strategy | What it does | Best when | Success criteria | Main failure mode |
+|---|---|---|---|---|
+| **A. Minimal shim additions** | Add the smallest Linux compatibility surface needed to expose the next blocker | The real retained display path is already known, and the missing API surface stays small and generic | Each shim advances the build by one blocker class without broadening scope dramatically | Header whack-a-mole grows into de facto kernel-environment emulation |
+| **B. Narrow the DC source set** | Replace broad full-tree compile with an explicit bounded file list aligned to the actual first display goal | Optional or advanced modules are being pulled into the build before their necessity is proven | The reduced source set compiles further or reveals the next blocker on the true bring-up path | False confidence if the narrowed claim is not documented precisely |
+
+## Recommendation
+
+### Recommendation summary
+
+Start with **B: narrow the compiled DC source set to the bounded display path Red Bear actually
+uses today**.
+
+That recommendation has now been implemented in bounded form. The retained path was narrowed far
+enough to prove that the current Red Bear bring-up surface does not need the imported Linux AMD
+display, TTM, or amdgpu core trees in order to build the shipped `amdgpu` recipe.
+
+The current evidence supports that recommendation because:
+
+1. the recipe compiles the entire imported display tree,
+2. the first blocker sits in a dependency cone that likely contains several more Linux/DRM header
+   and semantic assumptions, and
+3. Red Bear's current need is bounded display bring-up, not immediate proof that every imported
+   AMD DC subsystem compiles under Redox.
+
+### Why A is not the first move
+
+The first hard failure (`linux/kgdb.h`) is shallow enough to tempt a quick shim fix. That is useful
+only if the retained path is already known. Right now it is not. Without narrowing the source set
+first, each new shim risks paying compatibility cost for files Red Bear may not need for first
+bring-up.
+
+That is the main hidden cost of Strategy A at this stage: it can create real maintenance debt before
+the repo has proven that the affected code is on the first bring-up path at all.
+
+## ULW execution plan
+
+## Phase 0 — Freeze the baseline
+
+### Goal
+
+Create one canonical failure snapshot that all later triage work can refer back to.
+
+### Actions
+
+- Record the current broad display compile rule in the amdgpu recipe.
+- Record the first failing translation unit and full include chain.
+- Record the current bounded Red Bear display objective and the currently targeted ASIC/runtime
+  surface.
+
+### Exit criteria
+
+One written baseline exists showing:
+
+- the current full-tree compile behavior,
+- the current first hard failure at `linux/kgdb.h`, and
+- the current bounded display objective.
+
+### Current status
+
+- complete enough to proceed
+
+## Phase 1B — Narrow-source probe
+
+### Goal
+
+Identify the minimum imported display/DC source set required for current Red Bear display bring-up.
+
+### Required mindset
+
+The question in this phase is not “what can Linux build?”
+
+The question is:
+
+> what does Red Bear actually need compiled now to support its present display-side target?
+
+### Actions
+
+- Replace broad `find .../display -name '*.c'` behavior with an explicit bounded file list.
+- Treat the first retained file list as a **probe hypothesis**, not as a proven final minimum.
+- Keep only the C sources required for the current Red Bear bring-up surface hypothesis:
+  - device initialization,
+  - connector detection and mode enumeration,
+  - bounded modeset path,
+  - cleanup,
+  - and the currently targeted ASIC families.
+- Exclude obvious scope inflators first unless the call graph proves they are required:
+  - `modules/freesync/*`,
+  - untargeted DCN generations,
+  - `amdgpu_dm/*`,
+  - optional feature modules not on the first display path.
+
+### Verification
+
+- The reduced file list is explicit and reviewable.
+- The reduced build is re-run.
+- The next failure is checked to confirm that it occurs on the retained bounded path rather than in
+  an excluded optional subtree.
+
+### Exit criteria
+
+One of the following becomes true:
+
+1. the narrowed set compiles meaningfully further than the current build, or
+2. the next blocker appears on the real retained path and is therefore a justified compatibility
+   problem.
+
+### Failure signal
+
+If the narrowed set cannot be described cleanly because the retained path immediately drags in broad
+optional subsystems, stop and move to the decision gate rather than continuing to guess.
+
+### Current status
+
+- complete — the retained path is now explicit and builds
+
+## Phase 1A — Minimal-shim probe
+
+### Goal
+
+Expose the next blocker with the smallest justified compatibility addition.
+
+### Entry condition
+
+Only do this after Phase 1B has established a retained bounded path, or after the narrowed path
+proves that a small missing Linux primitive is genuinely required.
+
+### Allowed shim order
+
+Add one shim family at a time, in this rough priority order:
+
+1. `linux/kgdb.h`
+2. `asm/byteorder.h`
+3. `linux/vmalloc.h`
+4. `ktime_get_raw_ns` / timekeeping support
+5. `div64_u64` / `div64_u64_rem`
+6. `linux/refcount.h`
+
+### Rules
+
+- One shim family per change.
+- No speculative shim batches.
+- No ad hoc amdgpu-only workaround when the gap clearly belongs in `linux-kpi`.
+- If a shim exposes a large new Linux subsystem expectation rather than a narrow primitive, stop and
+  reconsider the strategy.
+
+### Verification
+
+- Re-run the build after each shim family.
+- Confirm that the build advances by one blocker class.
+- Confirm that the next failure remains on the retained bounded path.
+
+### Exit criteria
+
+- The build advances by exactly one blocker class, and
+- the next failure still belongs to the retained bounded path.
+
+### Failure signal
+
+If one shim immediately reveals several unrelated Linux subsystem requirements, stop and return to
+Strategy B.
+
+## Phase 2 — Decision gate
+
+### Stay on Strategy B if
+
+- the blocker sits in optional or advanced code such as FreeSync,
+- narrowing quickly reduces the blocker surface,
+- failures outside the retained path disappear,
+- or the retained path becomes understandable and controllable.
+
+### Switch from B to A if
+
+- **all** of the following are true:
+  - an explicit retained file list has been written down,
+  - the failure reproduces on that retained path after the narrowing pass,
+  - the missing piece is a small generic primitive or header family rather than a broad subsystem
+    expectation,
+  - and the same compatibility gap is visible across multiple retained core files or one retained
+    shared include chain.
+
+### Abort A and return to B if
+
+- more than one or two unrelated shim families are required before reaching a meaningful compile
+  milestone,
+- missing APIs are dominated by files outside the retained runtime path,
+- or the work starts resembling unconstrained kernel-environment emulation.
+
+## Phase 3 — Continue on the chosen path
+
+### If B wins
+
+- Keep the bounded file list explicit.
+- Document exactly what the bounded claim covers.
+- Do not quietly re-expand the tree.
+- Add excluded modules back only behind explicit proof of need.
+- Treat success here as **compile-triage progress only**. It does not imply full DC feature closure,
+  optional-module completeness, or runtime readiness.
+
+### If A wins
+
+- Expand `linux-kpi` deliberately rather than scattering shims through amdgpu-local code.
+- Keep each new shim family generic and reusable where possible.
+- Track each new compatibility family as maintenance debt that must justify itself.
+
+## Commit slicing
+
+Recommended commit order:
+
+1. narrow source set only,
+2. first shim family only,
+3. one blocker family per follow-up change.
+
+Never mix broad source pruning and broad compatibility growth in the same commit.
+
+## Red / Green / Refactor loop
+
+### Red
+
+The historical full-tree display build failed at `linux/kgdb.h` while compiling `freesync.c`.
+
+### Green
+
+Either:
+
+- the narrowed source set compiles further, or
+- one small shim advances the retained path to the next blocker.
+
+Current green state:
+
+- the bounded retained path now builds successfully,
+- and the imported Linux AMD display / TTM / amdgpu trees remain explicitly excluded pending proven
+  need.
+
+### Refactor
+
+Codify the smallest proven source set and execution path before adding more compatibility surface.
+
+## Hidden failure modes
+
+### Strategy B hidden failure mode
+
+Strategy B can produce false confidence if the repo narrows the file list but does not write down
+what functionality is now intentionally out of scope.
+
+That is why every narrowing step must be paired with an explicit bounded claim.
+
+### Strategy A hidden failure mode
+
+Strategy A can feel productive because each header addition removes one hard stop. But that can hide
+the fact that the repo is drifting into long-term Linux-environment emulation for code that the
+current Red Bear target may not even need.
+
+That is why A must stay subordinate to a retained, justified source set.
+
+## Definition of done
+
+This triage plan is complete when:
+
+- the repo has an explicit choice between bounded source narrowing and compatibility expansion,
+- the choice is backed by compile evidence,
+- optional AMD DC modules are not silently treated as required for first bring-up,
+- and compatibility growth, if needed, is happening in the right long-term layer.
+
+For clarity, done here means the compile-triage path is explicit and justified. It does **not** mean
+that the full AMD DC tree is complete, that excluded optional modules are unnecessary in all future
+phases, or that runtime display validation is closed.
+
+## Immediate next action
+
+Do this next:
+
+1. keep the retained `amdgpu` build path explicit and bounded,
+2. do not quietly re-introduce imported Linux AMD display / TTM / core sources,
+3. re-introduce imported subsystems only behind concrete runtime or feature evidence,
+4. if a future re-introduction attempt fans into broad Linux-kernel compatibility work again,
+   treat that as a new triage pass rather than as proof that the broader tree belongs in the
+   default retained build.
@@ -9,13 +9,15 @@
 This is the single authoritative plan for the Red Bear OS path from console boot to a
 hardware-accelerated KDE Plasma desktop running on Wayland.

-It consolidates and replaces the planning role previously held by:
+It consolidates and replaces the top-level planning role previously held by:

- `docs/03-WAYLAND-ON-REDOX.md` (historical Wayland rationale)
 - `docs/05-KDE-PLASMA-ON-REDOX.md` (historical KDE rationale)
 - `local/docs/AMD-FIRST-INTEGRATION.md` (AMD-specific hardware detail)
 - Prior revisions of this document (v1, which used a different Phase 1–5 breakdown)

+`local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` now serves as the canonical Wayland subsystem plan
+beneath this top-level desktop path.
+
 Those documents remain useful for subsystem detail, porting history, and design rationale.
 The earlier reassessment bridge is now retired, and its reconciliation role is covered here together
 with `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` and `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md`.
@@ -71,12 +73,12 @@ Rules:
 | Area | State | Evidence | Notes |
 |---|---|---|---|
 | AMD bare-metal boot | validated | Boot, ACPI, SMP, x2APIC all work | Bounded to current tested hardware |
-| relibc Wayland/Qt unblockers | builds | signalfd, timerfd, eventfd, open_memstream, F_DUPFD_CLOEXEC, MSG_NOSIGNAL, bounded waitid, bounded RLIMIT, bounded eth0 networking, shm_open, bounded sem_open, bounded sys/ipc.h, bounded sys/shm.h | Runtime pressure from real consumers still untested |
+| relibc Wayland/Qt unblockers | builds + targeted runtime proof | signalfd, timerfd, eventfd, open_memstream, F_DUPFD_CLOEXEC, MSG_NOSIGNAL, bounded waitid, bounded RLIMIT, bounded eth0 networking, shm_open, bounded sem_open, bounded sys/ipc.h, bounded sys/shm.h | Strict relibc Redox-target runtime proof now exists for the fd-event slice; broader real-consumer semantics still need confirmation |
 | redox-driver-sys | builds | Driver substrate | |
 | linux-kpi | builds | Linux kernel API compatibility layer | |
 | firmware-loader | builds, boots | scheme:firmware registers at boot | |
 | redox-drm (AMD + Intel) | builds | DRM scheme daemon | No hardware runtime validation |
-| amdgpu C port | builds | AMD DC + TTM + linux-kpi compat | No hardware runtime validation |
+| amdgpu retained C path | builds | Red Bear display glue retained path + linux-kpi compat; imported Linux AMD DC/TTM/core remain under compile triage | No hardware runtime validation |
 | evdevd | builds, boots | scheme:evdev registers at boot | |
 | udev-shim | builds, boots | scheme:udev registers at boot | |
 | libwayland 1.24.0 | builds | No compositor proof yet | |
@@ -578,7 +580,7 @@ This is the canonical document for the desktop path. It does not replace subsyst
 | `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` | Short current-state desktop truth summary |
 | `local/docs/RELIBC-COMPLETENESS-AND-ENHANCEMENT-PLAN.md` | relibc completeness detail + patch ownership |
 | `local/docs/INPUT-SCHEME-ENHANCEMENT.md` | Input-path design if structural cleanup needed |
-| `local/docs/P2-AMD-GPU-DISPLAY.md` | AMD display status + validation targets |
+| `local/docs/AMDGPU-DC-COMPILE-TRIAGE-PLAN.md` | AMD DC compile-triage + bounded source-set strategy |
 | `local/docs/DMA-BUF-IMPROVEMENT-PLAN.md` | DMA-BUF scheme detail |
 | `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` | Controller/IRQ/IOMMU quality work |
 | `local/docs/PROFILE-MATRIX.md` | Profile roles + support-language reference |
@@ -600,8 +602,8 @@ continuity, not as future work.
 |---|---|---|
 | AMD bare-metal boot (ACPI, SMP, x2APIC) | ✅ Boot-baseline complete | Prior to this plan; see `local/docs/ACPI-IMPROVEMENT-PLAN.md` for ongoing ownership and robustness work |
 | Driver infrastructure (redox-driver-sys, linux-kpi, firmware-loader) | ✅ Builds complete | Prior to this plan |
-| AMD GPU display (redox-drm, amdgpu C port) | ✅ Builds complete | Prior to this plan |
-| relibc POSIX unblockers (signalfd, timerfd, eventfd, etc.) | ✅ Builds complete | Prior to this plan |
+| AMD GPU display (redox-drm + bounded amdgpu retained path) | 🚧 Partial build completion | Imported Linux AMD DC/TTM/core remain under compile triage; no hardware runtime validation yet |
+| relibc POSIX unblockers (signalfd, timerfd, eventfd, etc.) | ✅ Builds + targeted runtime proof complete | Prior to this plan |
 | Qt6 base stack (qtbase, qtdeclarative, qtsvg, qtwayland) | ✅ Builds complete | Prior to this plan |
 | D-Bus 1.16.2 | ✅ Builds + bounded runtime | Prior to this plan |
 | All 32 KF6 frameworks | ✅ Builds complete | Prior to this plan |
@@ -1,6 +1,6 @@
 # Red Bear OS Desktop Stack — Current Status

-**Last updated:** 2026-04-18
+**Last updated:** 2026-04-19
 **Canonical plan:** `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0)

 ## Purpose
@@ -15,7 +15,7 @@ Its job is to answer:
 - and what still blocks a trustworthy Wayland/KDE session claim.

 For the execution plan (phases, timelines, acceptance criteria), see the canonical plan above.
-For historical design rationale, see `docs/03-WAYLAND-ON-REDOX.md` and `docs/05-KDE-PLASMA-ON-REDOX.md`.
+For subsystem planning detail, see `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md`; for historical KDE rationale, see `docs/05-KDE-PLASMA-ON-REDOX.md`.

 ## Where We Are in the Plan

@@ -25,15 +25,18 @@ The canonical desktop plan uses a three-track model:
 - **Track B (Phase 3–4):** KWin Session → KDE Plasma — **blocked on Track A**
 - **Track C (Phase 5):** Hardware GPU — **can start after Phase 1**

-**Current position:** Build-side gates are crossed. Phase 1 (Runtime Substrate Validation) is the
-next work target. The repo has not yet started systematic runtime validation.
+**Current position:** Build-side gates are crossed. Phase 1 (Runtime Substrate Validation) is still
+the next broad desktop target, but the repo now also carries an experimental Red Bear-native
+greeter/auth/session-launch stack on the `redbear-full` desktop path.

-## Tracked Default and Evidence Boundary
+## Active Target Surface and Evidence Boundary

- The tracked default build now resolves to `CONFIG_NAME?=redbear-kde`.
- the bounded Phase 2 validation profile remains available.
- `redbear-kde` is the tracked KWin Wayland desktop direction, but runtime-proven compositor/
-  session claims still remain incomplete.
+- The supported compile targets are `redbear-mini`, `redbear-live-mini`, `redbear-full`, and `redbear-live-full`.
+- Desktop/graphics are available only on `redbear-full` and `redbear-live-full`.
+- Older names such as `redbear-kde`, `redbear-wayland`, and `redbear-minimal*` still appear in
+  historical or staging material, but they are not the supported compile-target surface.
+- The greeter/login path is currently an **experimental build/integration surface** on `redbear-full`;
+  it is not yet a runtime-validated end-to-end desktop-login claim.

 ## Status Matrix

@@ -48,8 +51,15 @@ next work target. The repo has not yet started systematic runtime validation.
 | Mesa EGL+GBM+GLES2 | **builds** | Software path via LLVMpipe proven in QEMU; hardware path not proven |
 | libdrm amdgpu | **builds** | Package-level success only |
 | Input stack | **builds, enumerates** | evdevd, libevdev, libinput, seatd present; evdevd registers scheme at boot |
-| D-Bus | **builds, usable (bounded)** | System bus wired in `redbear-full` and `redbear-kde`; D-Bus plan + sessiond complete (DB-1), Qt 6.11 D-Bus coverage documented (Section 14), DB-2/3/4 service daemons implemented as stubs (notifications, upower, udisks, polkit) |
-| redbear-sessiond | ✅ Scaffold | org.freedesktop.login1 D-Bus session broker — Rust daemon (zbus 5), config wired in redbear-kde.toml, acpi_watcher with edge detection |
+| D-Bus | **builds, usable (bounded)** | System bus wired in `redbear-full`; D-Bus plan + sessiond complete (DB-1), Qt 6.11 D-Bus coverage documented (Section 14), DB-2/3/4 service daemons implemented as stubs (notifications, upower, udisks, polkit) |
+| redbear-sessiond | **builds, scaffold** | org.freedesktop.login1 D-Bus session broker — Rust daemon (zbus 5), wired on the `redbear-full` desktop path; now includes runtime control updates used by the greeter/auth session handoff |
+| redbear-authd | **builds** | Privileged local-user auth daemon; `/etc/passwd`/`/etc/shadow`/`/etc/group` parsing, SHA-256/SHA-512 crypt verification, bounded lockout, target-side recipe build proven |
+| redbear-session-launch | **builds** | User-session bootstrap tool; runtime-dir/env setup, uid/gid handoff, dbus-run-session → `redbear-kde-session`, target-side recipe build proven |
+| redbear-greeterd | **builds, experimental** | Root-owned greeter orchestrator; UI/auth socket protocol, bounded restart policy, return-to-greeter daemon logic, crate tests pass; end-to-end runtime proof still pending |
+| redbear-greeter UI | **builds, experimental** | Qt6/QML unprivileged login surface now ships in-tree; bounded runtime proof remains narrower than a full trusted KDE desktop-login claim |
+| redbear-validation-session | **builds, bounded helper** | Still staged as a validation launcher/helper, but no longer the primary `redbear-full` display-service owner |
+| Greeter runtime checker | ✅ implemented (bounded checker) | `redbear-greeter-check` asserts greeter binaries, assets, service files, socket reachability, hello protocol, invalid-login handling, and a validation-only successful-login/session-return loop inside the guest; current graphical runtime proof is still blocked below the greeter slice by guest-side Qt shared-plugin parsing |
+| Greeter QEMU harness | ✅ implemented (bounded harness) | `test-greeter-qemu.sh` boots `redbear-full`, logs in on the fallback console, and runs the in-guest greeter checker for hello, invalid-login, and bounded successful-login return-to-greeter proof; the compositor leg is presently blocked by guest-side Qt plugin loader failure rather than missing greeter artifacts |
 | redbear-notifications | ✅ Scaffold | org.freedesktop.Notifications — logs to stderr, no display integration yet |
 | redbear-upower | ✅ bounded real | org.freedesktop.UPower — enumerates real AC adapters/batteries from `/scheme/acpi/power`; desktop machines with no battery report line power only |
 | redbear-udisks | ✅ bounded real | org.freedesktop.UDisks2 — enumerates real `disk.*` schemes and partitions into read-only D-Bus objects; no fabricated mount/serial metadata |
@@ -61,36 +71,37 @@ next work target. The repo has not yet started systematic runtime validation.
 | GPU acceleration | **blocked** | PRIME/DMA-BUF ioctls and bounded private CS surface implemented; real vendor render CS/fence path still missing |
 | validation compositor runtime | **experimental** | Reaches early init in QEMU; no complete session |
 | validation profile | **builds, boots** | Bounded Wayland runtime profile |
-| `redbear-full` profile | **builds, boots** | Broader desktop plumbing profile |
-| `redbear-kde` profile | **builds** | Tracked KWin desktop-direction profile |
-| `redbear-live` profile | **builds** | Live image following the tracked KWin desktop target |
+| `redbear-full` profile | **builds, boots** | Active desktop/graphics compile surface; now owns the experimental greeter/auth/session-launch integration path |
+| `redbear-live-full` profile | **builds** | Live image following the active desktop/graphics target |
+| `redbear-mini` profile | **builds** | Minimal non-desktop compile target |
+| `redbear-live-mini` profile | **builds** | Minimal live image target |

 ## Profile View

-### Validation profile
-
- **Role:** Phase 2 Wayland compositor validation target
- **Current truth:** Builds and boots in QEMU; bounded compositor initialization reaches early init but no complete session
- **Use for:** Compositor/runtime regression testing, not broad desktop claims
-
 ### `redbear-full`

- **Role:** Broader desktop/network/session plumbing
- **Current truth:** Carries D-Bus and broader integration pieces; VirtIO networking works in QEMU, and the bounded Phase 5 network/session checker is evidence-backed there
- **Use for:** Desktop integration testing beyond the narrow Wayland slice
+- **Role:** Active desktop/graphics compile target and current greeter-integration surface
+- **Current truth:** Carries D-Bus, sessiond, broader integration pieces, and the experimental Red Bear-native greeter/auth/session-launch stack; VirtIO networking works in QEMU, the bounded Phase 5 network/session checker is evidence-backed there, and the repo now includes a bounded greeter checker/harness for the login surface. `redbear-validation-session` remains staged only as a bounded helper, not the active `20_display.service` owner on this target.
+- **Use for:** Desktop integration testing, greeter/login bring-up, and bounded desktop/network plumbing validation
 - **Do not overclaim:** This profile proves bounded QEMU desktop/network plumbing only. It does not by itself close the Wi-Fi implementation plan's later real-hardware Phase W5 reporting/recovery gate.

-### `redbear-kde`
+### `redbear-live-full`

- **Role:** Phase 3–4 KDE/Plasma session bring-up
- **Current truth:** Carries KWin/session wiring and KDE-facing package set; experimental but selected as the tracked default desktop target
- **Use for:** KDE session surface testing once Phase 2 completes
+- **Role:** Live/demo/recovery image layered on the active desktop target
+- **Current truth:** Follows `redbear-full`; desktop/graphics-capable live image, but the greeter/login surface remains experimental until end-to-end proof exists
+- **Use for:** Demo, install, and bounded live-media validation on the current desktop surface

-### `redbear-live`
+### `redbear-mini`

- **Role:** Live/demo/recovery image layered on the tracked desktop profile
- **Current truth:** Inherits `redbear-kde`, so live media now follows the tracked KWin desktop target
- **Use for:** Demo, install, and recovery workflows based on the current shipped desktop surface
+- **Role:** Minimal non-desktop target
+- **Current truth:** No desktop/graphics path; recovery and non-desktop integration surface only
+- **Use for:** Minimal runtime bring-up, subsystem validation, and non-desktop packaging checks
+
+### `redbear-live-mini`
+
+- **Role:** Minimal live image target
+- **Current truth:** No desktop/graphics path; live/recovery-oriented minimal image surface
+- **Use for:** Minimal live boot and recovery workflows

 ## Current Blockers

@@ -104,7 +115,31 @@ Phase 1 exists specifically to close this gap.
 A bounded compositor initialization reaches early startup but does not complete a usable Wayland compositor session.
 This blocks all desktop session work.

-### 3. KWin reduced build is now dependency-honest, but runtime proof is still missing (Phase 3 gate)
+### 3. Greeter/login path now exists, but runtime proof is still missing (desktop-login gate)
+
+The repo now carries the main non-visual pieces of the Red Bear-native greeter/login plan:
+
+- `redbear-authd`
+- `redbear-session-launch`
+- `redbear-greeterd`
+- `redbear-greeter-services.toml`
+- `redbear-greeter-check`
+- `test-greeter-qemu.sh`
+
+Current truth for that slice:
+
+| Piece | Current state | Remaining limitation |
+|---|---|---|
+| `redbear-authd` | Target-side recipe build proven; unit tests cover passwd/shadow parsing, SHA-crypt verification, lockout, approval checks | No bounded in-guest login proof yet |
+| `redbear-session-launch` | Target-side recipe build proven; unit tests cover env/runtime-dir/argument handling | Real session handoff still depends on full greeter/runtime proof |
+| `redbear-greeterd` | Crate tests cover protocol-facing state strings, installed asset paths, bounded restart policy, and now own successful-login session launch directly after response delivery | Full desktop-login trust still depends on wider KDE runtime proof plus the unresolved guest-side Qt plugin-loader defect |
+| Greeter validation helpers | `redbear-greeter-check` + `test-greeter-qemu.sh` exist and are wired for bounded runtime proof | The successful-login path is validation-only and does not replace broader KDE session proof; current graphical proof is blocked by guest-side Qt plugin parsing rather than by greeter protocol/packaging gaps |
+| `redbear-greeter` packaging | Builds in-tree | Qt/QML UI binary, compositor wrapper, and branded assets are packaged; broader runtime trust still remains experimental because the guest-side Qt plugin loader currently rejects shared platform plugins (`libqminimal.so`, KWin QPA) as invalid ELF during metadata scan |
+
+This means Red Bear now has a credible **build-visible login boundary**, but not yet a runtime-trusted
+graphical login surface.
+
+### 4. KWin reduced build is now dependency-honest, but runtime proof is still missing (desktop-session gate)

 The reduced KWin path now builds with honest provider linkage for `libepoxy`, `lcms2`, `libudev`,
 and `libdisplay-info`.
@@ -121,7 +156,7 @@ Current truth for that slice:
 Additionally, two packages still need more honest session-ready treatment: kirigami (stub-only),
 kf6-kio (heavy shim).

-### 4. Hardware acceleration missing GPU CS ioctl (Phase 5 gate)
+### 5. Hardware acceleration missing GPU CS ioctl (Phase 5 gate)

 PRIME/DMA-BUF buffer sharing is implemented at the scheme level, and a bounded private CS
 surface now exists for shared-contract work. Real vendor render command submission and shared
@@ -139,9 +174,10 @@ exercised on real Intel and AMD hardware.
 |---|---|
 | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Canonical desktop path plan (v2.0, Phase 1–5) |
 | This document | Current build/runtime truth summary |
+| `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` | Canonical GPU/DRM execution plan beneath the desktop path |
 | `local/docs/QT6-PORT-STATUS.md` | Qt/KF6/KWin package-level build status |
 | `local/docs/AMD-FIRST-INTEGRATION.md` | AMD-specific hardware/driver detail |
-| `docs/03-WAYLAND-ON-REDOX.md` | Historical Wayland design rationale |
+| `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` | Canonical Wayland subsystem plan |
 | `docs/05-KDE-PLASMA-ON-REDOX.md` | Historical KDE design rationale |
 | `local/docs/PROFILE-MATRIX.md` | Profile roles and support-language reference |

@@ -149,8 +185,9 @@ exercised on real Intel and AMD hardware.

 The Red Bear desktop stack has crossed major build-side gates:
 - All Qt6 core modules, all 32 KF6 frameworks, Mesa EGL/GBM/GLES2, and D-Bus build
- Three tracked desktop profiles exist and at least boot in QEMU
+- Four supported compile targets exist, with desktop/graphics on `redbear-full` and `redbear-live-full`
+- the non-visual Red Bear-native greeter/login pieces now build and test
 - relibc compatibility is materially stronger than before

-The remaining work is **runtime validation, session assembly, and the remaining KDE session/runtime proof work**.
-Phase 1 (Runtime Substrate Validation) remains the immediate next target, while the KWin reduced path still lacks runtime compositor/session proof.
+The remaining work is **runtime validation, greeter/UI completion, session assembly, and the remaining KDE session/runtime proof work**.
+Phase 1 (Runtime Substrate Validation) remains the immediate broad target, while the new greeter/login path and the KWin reduced path both still need bounded runtime proof before stronger claims are safe.
@@ -7,7 +7,6 @@
 **Supersedes as planning authority:**

 - `local/docs/AMD-FIRST-INTEGRATION.md` for forward execution order
- `local/docs/P2-AMD-GPU-DISPLAY.md` for future-task sequencing
 - `local/docs/HARDWARE-3D-ASSESSMENT.md` for roadmap ordering
 - `local/docs/DMA-BUF-IMPROVEMENT-PLAN.md` for PRIME/render dependency ordering

@@ -54,7 +53,7 @@ The repo has real progress in shared DRM/KMS, GEM, PRIME, firmware plumbing, int
 | KMS ioctl surface | Implemented in shared scheme layer | `local/recipes/gpu/redox-drm/source/src/scheme.rs` |
 | GEM allocation and mapping | Implemented in shared scheme and GEM manager | `local/recipes/gpu/redox-drm/source/src/gem.rs`, `local/recipes/gpu/redox-drm/source/src/scheme.rs` |
 | PRIME and DMA-BUF style sharing | Implemented at scheme level | `local/docs/HARDWARE-3D-ASSESSMENT.md`, `local/docs/DMA-BUF-IMPROVEMENT-PLAN.md`, `local/recipes/gpu/redox-drm/source/src/scheme.rs` |
-| AMD display backend | Build-visible, firmware-aware, interrupt-aware | `local/recipes/gpu/redox-drm/source/src/drivers/amd/mod.rs`, `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` |
+| AMD display backend | Build-visible on the bounded retained path, firmware-aware, interrupt-aware | `local/recipes/gpu/redox-drm/source/src/drivers/amd/mod.rs`, `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` |
 | Intel display backend | Build-visible, GGTT and ring scaffolding present | `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs`, `.../intel/ring.rs` |
 | Mesa userland base | Builds with EGL, GBM, OSMesa, software Gallium path | `recipes/libs/mesa/recipe.toml` |

@@ -255,6 +254,8 @@ quirk path. Do not use the Linux quirk extractor as a substitute for PCI naming
 - the raw `(crtc_id, vblank_count)` IRQ tuple path has been replaced with a small shared driver-event model for internal driver → main loop → scheme transport.
 - `scheme.rs` now owns event ingestion through a shared helper, so page-flip retirement remains tied to explicit vblank events while non-vblank events do not pretend to be render completion.
 - both Intel and AMD now forward shared hotplug events through the same internal event path instead of backend-specific side handling.
+- `scheme.rs` now turns shared hotplug and vblank events into a queued scheme-visible `EVENT_READ` surface for `card0`, and hotplug also targets the matching connector handle.
+- unit tests now cover card-level hotplug readiness, connector-targeted hotplug readiness, queued vblank delivery, and event draining, while preserving the rule that non-vblank events do not retire pending page flips.
 - this is structural groundwork only; real fence objects, sync waits, and backend-proven render completion semantics are still not implemented.

 ### Workstream C, Intel backend maturation
@@ -276,7 +277,7 @@ quirk path. Do not use the Linux quirk extractor as a substitute for PCI naming

 ### Workstream D, AMD backend maturation

-**Goal:** Turn the AMD path from code-complete display work plus amdgpu port scaffolding into an evidence-backed modern AMD track.
+**Goal:** Turn the AMD path from a bounded retained display build plus broader imported amdgpu/DC triage into an evidence-backed modern AMD track.

 **Tasks:**

@@ -0,0 +1,876 @@
+# Red Bear OS Greeter / Login Implementation Plan
+
+**Version:** 1.0 — 2026-04-19
+**Status:** Active plan with experimental implementation in progress on `redbear-full`
+**Scope:** Red Bear-native graphical greeter, authentication boundary, and session handoff for the KDE-on-Wayland desktop path
+**Parent plans:** `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0), `local/docs/DBUS-INTEGRATION-PLAN.md`
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#1-executive-summary)
+2. [Scope and Non-Goals](#2-scope-and-non-goals)
+3. [Evidence Model](#3-evidence-model)
+4. [Current State Assessment](#4-current-state-assessment)
+5. [Decision Record: Login-Manager Direction](#5-decision-record-login-manager-direction)
+6. [Architecture Principles](#6-architecture-principles)
+7. [Architecture Design](#7-architecture-design)
+8. [Component Specifications](#8-component-specifications)
+9. [Protocols and Session Contracts](#9-protocols-and-session-contracts)
+10. [Phased Implementation](#10-phased-implementation)
+11. [Testing and Validation](#11-testing-and-validation)
+12. [Risks and Mitigations](#12-risks-and-mitigations)
+13. [Relationship to Other Plans](#13-relationship-to-other-plans)
+14. [File and Recipe Inventory](#14-file-and-recipe-inventory)
+15. [Open Questions](#15-open-questions)
+
+---
+
+## 1. Executive Summary
+
+Red Bear OS currently has enough session substrate to start **one fixed KDE Wayland session**, but it does
+not yet have a real graphical login path.
+
+What exists today:
+
+- `dbus-daemon` on the system bus
+- `redbear-sessiond` exposing a minimal `org.freedesktop.login1` subset for KWin
+- `seatd` as the seat/libseat backend
+- a direct session launcher (`redbear-kde-session`) that starts `kwin_wayland`
+- fallback text `getty` surfaces on VT2 and `/scheme/debug/no-preserve`
+
+What does **not** exist today:
+
+- no display manager
+- no graphical greeter
+- no authentication daemon
+- no session-launch privilege boundary
+- no PAM-backed or systemd-logind-shaped login stack
+
+This plan defines the forward path for the missing layer:
+
+1. **Do not adopt SDDM first.** Upstream KDE convention points to SDDM, but the current Red Bear
+   session/auth substrate is not yet shaped like a conventional Linux desktop-login environment.
+2. **Build a Red Bear-native minimal greeter/login path first.** The system should present one
+   graphical login surface for one session only: **KDE on Wayland**.
+3. **Keep the architecture narrow.** Separate:
+   - `redbear-sessiond` → login1/session compatibility for KWin
+   - `redbear-greeter` → login UX and session orchestration
+   - `redbear-authd` → credential verification and privilege boundary
+   - `redbear-session-launch` → user-session bootstrap only
+
+This plan intentionally avoids generic display-manager scope. Red Bear wants **one desktop direction**,
+not a multi-session desktop-manager framework.
+
+---
+
+## 2. Scope and Non-Goals
+
+### 2.1 In Scope
+
+- One graphical login surface for the Red Bear KDE-on-Wayland desktop path
+- A Red Bear-native greeter daemon, greeter UI, authentication daemon, and session launcher
+- Integration with existing `dbus-daemon`, `redbear-sessiond`, `seatd`, `inputd`, and `redbear-kde-session`
+- Explicit VT ownership and handoff on the desktop VT
+- A narrow local-user authentication model backed by `/etc/passwd`, `/etc/shadow`, and `/etc/group`
+- Branding integration using Red Bear assets from `local/Assets/`
+- Packaging and config wiring under `local/recipes/system/` and tracked `config/redbear-*.toml`
+
+This plan applies only to the **graphical desktop path**. It does **not** replace console-first or
+minimal non-desktop configurations. Existing text and debug console surfaces remain part of the
+recovery model.
+
+### 2.2 Out of Scope
+
+- X11 login surfaces
+- multiple desktop environments
+- session chooser UI
+- remote authentication
+- PAM/NSS plugin ecosystems
+- LDAP/SSO/smartcard/fingerprint login
+- graphical lock screen / unlock manager
+- full Plasma session-manager semantics (`ksmserver`, multi-user desktop switching)
+
+### 2.3 Policy Assumption
+
+This plan assumes the Red Bear desktop direction converges on **one KDE-on-Wayland path**.
+
+Current implementation answer: the first tracked owner is `redbear-full` (and therefore
+`redbear-live-full` for live media). Older names such as `redbear-kde` may still appear in
+historical or staging material, but they are not the supported compile-target surface for this plan.
+
+---
+
+## 3. Evidence Model
+
+This plan uses the same evidence language as the canonical desktop plan.
+
+| Class | Meaning | Safe to say | Not safe to say |
+|---|---|---|---|
+| **builds** | Package compiles and stages | "builds" | "works" |
+| **boots** | Image reaches prompt or known runtime surface | "boots" | "desktop works" |
+| **enumerates** | Service/register surface appears and answers basic queries | "enumerates" | "usable end to end" |
+| **usable** | Bounded runtime path performs its intended task | "usable for this path" | "broadly stable" |
+| **validated** | Repeated proof on the intended target class | "validated" | "complete everywhere" |
+| **experimental** | Partial, scaffolded, or unproven | "experimental" | "done" |
+
+Rules:
+
+- A greeter binary that compiles is only **builds**.
+- A VM image that reaches a graphical login surface is only **boots**.
+- A greeter that hands off to KDE on Wayland in bounded QEMU proof is **usable (bounded)**.
+- Nothing is **validated** until it repeats reliably on the intended target class.
+
+---
+
+## 4. Current State Assessment
+
+### 4.1 What Exists and Works
+
+| Component | Location | Status | Detail |
+|---|---|---|---|
+| system D-Bus | `config/redbear-full.toml` | ✅ usable (bounded) | `12_dbus.service` starts `dbus-daemon --system` on the active desktop target |
+| login1 compatibility | `local/recipes/system/redbear-sessiond/` | ✅ scaffold | Minimal `org.freedesktop.login1` broker for KWin |
+| seat backend | `config/redbear-full.toml` | ✅ builds, wired | `13_seatd.service`; session env exports `LIBSEAT_BACKEND=seatd` |
+| display VT activation | `29_activate_console.service` in desktop configs | ✅ usable (bounded) | `inputd -A 3` activates desktop VT |
+| fallback text login | `30_console.service` | ✅ boots | `getty 2` on VT2 |
+| debug console | `31_debug_console.service` | ✅ boots | `getty /scheme/debug/no-preserve -J` |
+| direct KDE session launcher | `/usr/bin/redbear-kde-session` | ✅ builds, experimental | Starts session bus if needed, then `exec kwin_wayland --replace` |
+| authentication daemon | `local/recipes/system/redbear-authd/` | ✅ builds, experimental | Local-user auth boundary with `/etc/passwd` / `/etc/shadow` / `/etc/group` parsing and SHA-crypt verification |
+| session launcher boundary | `local/recipes/system/redbear-session-launch/` | ✅ builds, experimental | User-session bootstrap with bounded environment/runtime-dir setup |
+| greeter daemon scaffold | `local/recipes/system/redbear-greeter/` | ✅ builds, experimental | Root-owned greeter orchestrator, socket protocol, bounded restart policy |
+| greeter config fragment | `config/redbear-greeter-services.toml` | ✅ builds, experimental | Adds `19_redbear-authd.service`, `20_greeter.service`, compatibility `20_display.service`, and fallback console dependencies |
+| bounded validation launcher | `/usr/bin/redbear-validation-session` | ✅ retained helper | Still available for older bounded validation flows, but no longer the primary `redbear-full` display-service path |
+| branding assets | `local/Assets/images/` | ✅ present | `Red Bear OS loading background.png`, `Red Bear OS icon.png` |
+
+### 4.2 What Exists But Is Incomplete
+
+| Component | Status | Gap |
+|---|---|---|
+| `redbear-sessiond` seat switching | ⚠️ scaffold | `Seat.SwitchTo` is currently logged/delegated externally to `inputd -A` |
+| KDE runtime services | ⚠️ partial | D-Bus substrate exists, but broader Plasma session services remain incomplete |
+| `redbear-full` greeter flow | ⚠️ experimental | Non-visual pieces are implemented, but final packaged UI and bounded runtime proof are still pending |
+| greeter runtime validation | ⚠️ partial | `redbear-greeter-check` + `test-greeter-qemu.sh` exist, but final proof still depends on the packaged greeter UI |
+
+### 4.3 What Does Not Exist
+
+| Missing piece | Why it matters |
+|---|---|
+| packaged graphical greeter UI | no complete user-visible graphical login surface is staged yet |
+| bounded end-to-end login proof | build-side pieces exist, but runtime-trusted login/session handoff is not proven yet |
+| shared login protocol extraction | current protocol is encoded directly in the first-cut daemon/checker implementations |
+| display-manager package integration | no SDDM/greetd/lightdm/ly path in repo |
+
+### 4.4 Baseline Conclusion
+
+The current Red Bear desktop path can **start a session**, but it cannot yet **own a login flow**.
+
+The missing work is not “port more KDE packages.” The missing work is the **login boundary**:
+
+1. graphical greeter surface,
+2. authentication boundary,
+3. session-launch privilege drop,
+4. clean handoff into the existing KDE Wayland session path.
+
+That login boundary must be added **without** replacing the current seat/session substrate and
+without removing existing console recovery paths.
+
+---
+
+## 5. Decision Record: Login-Manager Direction
+
+### 5.1 Recommendation
+
+The best fit for Red Bear OS **today** is a **Red Bear-native minimal single-session greeter/launcher**.
+
+This is closer in class to **greetd-style minimal orchestration** than to **SDDM-style full desktop
+manager behavior**, but the forward path should be **Red Bear-specific**, not a generic Linux deployment.
+
+### 5.2 Why Not SDDM First
+
+SDDM is the standard answer for a conventional KDE distribution, but Red Bear is not yet a conventional
+Linux-shaped session/auth environment.
+
+The repo evidence today shows:
+
+- no SDDM integration,
+- no PAM path,
+- no mature general-purpose display-manager substrate,
+- a deliberately minimal `login1` compatibility layer,
+- a fixed single desktop direction.
+
+Adopting SDDM first would force Red Bear to emulate a broader environment before the current narrower
+session path is runtime-trusted.
+
+### 5.3 Ranked Direction
+
+| Rank | Direction | Verdict |
+|---|---|---|
+| 1 | Red Bear-native minimal greeter | **Primary** |
+| 2 | Current direct session launcher | bring-up baseline only |
+| 3 | SDDM-class integration | future option after session/auth substrate matures |
+| 4 | GDM/LightDM/elogind-shaped path | reject |
+
+### 5.4 Future Revisit Trigger
+
+Revisit SDDM-class integration only if Red Bear later decides it needs:
+
+- richer multi-user semantics,
+- session chooser behavior,
+- broader desktop-manager policy surface,
+- significantly fuller login/session accounting than the current `redbear-sessiond` contract.
+
+---
+
+## 6. Architecture Principles
+
+### 6.1 One Desktop, One Session Path
+
+The greeter must launch exactly one session target:
+
+- **KDE on Wayland**
+
+There is no session chooser in v1.
+
+### 6.2 Keep the Existing Session Substrate
+
+Reuse existing pieces rather than replacing them:
+
+- `dbus-daemon`
+- `redbear-sessiond`
+- `seatd`
+- `inputd`
+- `redbear-kde-session`
+
+The greeter layer sits **above** them.
+
+`seatd` remains the **seat/device authority** for this design. The greeter stack consumes the existing
+seat/libseat path; it does not introduce a second seat/session-manager authority.
+
+### 6.3 Separate Login UX, Authentication, and Session Bootstrap
+
+Do not collapse these roles into one process.
+
+| Component | Responsibility |
+|---|---|
+| `redbear-sessiond` | login1/session compatibility for KWin |
+| `redbear-greeterd` | login flow orchestration |
+| `redbear-greeter-ui` | graphical login UX |
+| `redbear-authd` | credential verification and privilege boundary |
+| `redbear-session-launch` | drop privileges, set env, start user session |
+
+`redbear-sessiond` is therefore **not** the login/auth/session-launch authority. It remains the
+KWin-facing session compatibility broker defined by the D-Bus plan.
+
+### 6.4 Avoid a PAM Clone
+
+Red Bear should not build a new generic PAM/NSS plugin ecosystem merely to satisfy display-manager
+expectations. For this path, use a narrow local account model first.
+
+### 6.5 Stop-and-Start Handoff Is Acceptable
+
+The greeter and the user session do not need an in-place seamless transition in v1.
+
+It is acceptable to:
+
+1. stop the greeter UI,
+2. start the user session cleanly,
+3. return to the greeter after session exit.
+
+### 6.6 Branding Is Part of the Product Surface
+
+Use committed Red Bear assets as the default greeter look.
+
+Source-of-truth art files in the repo are:
+
+- background: `local/Assets/images/Red Bear OS loading background.png`
+- icon: `local/Assets/images/Red Bear OS icon.png`
+
+At runtime, the greeter must use **installed asset paths**, not source-tree paths.
+
+---
+
+## 7. Architecture Design
+
+### 7.1 Stack Overview
+
+```text
+┌────────────────────────────────────────────────────────────────────┐
+│ KDE Wayland user session                                          │
+│ redbear-kde-session → kwin_wayland → later Plasma services        │
+├────────────────────────────────────────────────────────────────────┤
+│ redbear-session-launch                                            │
+│ drop privileges, set env, start session bus, exec session         │
+├────────────────────────────────────────────────────────────────────┤
+│ redbear-authd                         redbear-greeter-ui          │
+│ local auth + privilege boundary       Qt6/QML login surface       │
+├────────────────────────────────────────────────────────────────────┤
+│ redbear-greeterd                                                   │
+│ login state machine, VT3 ownership, auth/session orchestration     │
+├────────────────────────────────────────────────────────────────────┤
+│ dbus-daemon --system    redbear-sessiond    seatd    inputd        │
+├────────────────────────────────────────────────────────────────────┤
+│ Redox schemes / system services                                    │
+│ scheme:input, scheme:acpi, scheme:drm, debug scheme, etc.          │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 Boot-to-Login Sequence
+
+```text
+boot
+  → 12_dbus.service               (system D-Bus)
+  → 13_redbear-sessiond.service   (login1 subset)
+  → 13_seatd.service              (seat backend)
+  → 20_greeter.service            (start redbear-greeterd on VT3)
+  → 29_activate_console.service   (inputd -A 3)
+  → 30_console.service            (fallback getty 2 on VT2)
+  → 31_debug_console.service      (debug getty)
+  → redbear-greeter-ui shows login surface on VT3
+  → successful login
+  → redbear-session-launch
+  → dbus-run-session -- redbear-kde-session
+  → kwin_wayland
+```
+
+### 7.3 Session Return Path
+
+```text
+user session exits or crashes
+  → redbear-greeterd observes session root exit
+  → greeter-specific cleanup
+  → reactivate VT3
+  → respawn redbear-greeter-ui
+  → return to login surface
+```
+
+### 7.4 Why This Shape Fits the Repo
+
+- matches existing `VT=3` display path
+- preserves fallback text login on VT2
+- reuses `redbear-sessiond` instead of replacing it
+- does not assume a broader Linux-style session-manager stack than the repo currently has
+- avoids dead-end graphical boot behavior by preserving text/debug fallback paths
+
+---
+
+## 8. Component Specifications
+
+### 8.1 `redbear-greeterd`
+
+**Type:** root-owned orchestrator daemon
+
+**Responsibilities:**
+
+- own the login state machine,
+- own greeter/UI lifecycle,
+- talk to `redbear-authd`,
+- start the user session via `redbear-session-launch`,
+- monitor the session root process,
+- return to greeter after logout/session crash.
+
+**Must not do:**
+
+- parse or verify passwords directly unless `redbear-authd` is intentionally collapsed into it,
+- render the login UI,
+- absorb generic session-manager policy.
+
+### 8.2 `redbear-greeter-ui`
+
+**Type:** unprivileged Qt6/QML frontend
+
+**Responsibilities:**
+
+- render Red Bear background and icon,
+- collect username/password,
+- present Login / Shutdown / Reboot,
+- show bounded status (`Authenticating`, `Login failed`, `Starting session`).
+
+**Must not do:**
+
+- read `/etc/shadow`,
+- own power/device/session policy,
+- choose alternate desktop sessions.
+
+### 8.3 `redbear-authd`
+
+**Type:** privileged authentication daemon
+
+**Responsibilities:**
+
+- read local user data,
+- verify password hashes,
+- check lock/disable rules,
+- perform narrow privileged actions (`login`, optional `shutdown`, optional `reboot`),
+- spawn `redbear-session-launch` for a verified user.
+
+**Must not do:**
+
+- own the greeter UI,
+- own compositor startup policy,
+- become a general identity platform.
+
+`redbear-authd` is the **only** component in this plan allowed to read password-hash data
+(` /etc/shadow`-equivalent runtime content). Neither UI nor session launcher may touch it.
+
+### 8.4 `redbear-session-launch`
+
+**Type:** small bootstrap tool
+
+**Responsibilities:**
+
+- create/fix `XDG_RUNTIME_DIR`,
+- drop to target uid/gid and supplementary groups,
+- construct a minimal KDE/Wayland environment,
+- launch the user session bus,
+- exec `redbear-kde-session`.
+
+`redbear-session-launch` is intentionally thin. It must not duplicate KDE session policy already owned
+by `redbear-kde-session`.
+
+### 8.5 `redbear-sessiond`
+
+This plan does **not** replace `redbear-sessiond`.
+
+It remains responsible for:
+
+- `org.freedesktop.login1` subset for KWin,
+- session/seat compatibility surface,
+- bounded power/sleep integration already assigned in the D-Bus plan.
+
+---
+
+## 9. Protocols and Session Contracts
+
+### 9.1 UI ↔ Greeter Daemon Protocol
+
+Transport:
+
+- Unix socket at `/run/redbear-greeterd.sock`
+- JSON messages, versioned
+
+Minimum message set:
+
+```json
+{ "type": "hello", "version": 1 }
+{ "type": "submit_login", "username": "alice", "password": "secret" }
+{ "type": "request_shutdown" }
+{ "type": "request_reboot" }
+```
+
+Example reply:
+
+```json
+{ "type": "hello_ok", "background": "/usr/share/redbear/greeter/background.png", "icon": "/usr/share/redbear/greeter/icon.png", "session_name": "KDE on Wayland" }
+```
+
+### 9.2 Greeter Daemon ↔ Auth Daemon Protocol
+
+Transport:
+
+- Unix socket at `/run/redbear-authd.sock`
+- JSON messages, versioned
+
+Minimum message set:
+
+```json
+{ "type": "authenticate", "request_id": 17, "username": "alice", "password": "secret", "vt": 3 }
+{ "type": "start_session", "request_id": 17, "username": "alice", "session": "kde-wayland" }
+```
+
+### 9.3 State Machine
+
+`redbear-greeterd` uses this state set:
+
+1. `Starting`
+2. `GreeterReady`
+3. `Authenticating`
+4. `LaunchingSession`
+5. `SessionRunning`
+6. `ReturningToGreeter`
+7. `PowerAction`
+8. `FatalError`
+
+Rules:
+
+- one greeter UI process at a time,
+- one session launch in flight,
+- one supported session only: `kde-wayland`,
+- greeter UI never survives into `SessionRunning`.
+
+### 9.4 Local Account Storage Contract
+
+Use a simple Unix-like model first:
+
+- `/etc/passwd`
+- `/etc/shadow`
+- `/etc/group`
+
+This plan explicitly rejects inventing a new account database format for v1.
+
+The local-account model is a **runtime contract**. Source-tree examples or provisioning helpers may live
+elsewhere, but the greeter/auth path must interact only with installed runtime account files.
+
+### 9.5 Session-Launch Environment
+
+`redbear-session-launch` should set a minimal explicit environment:
+
+- `HOME`
+- `USER`
+- `LOGNAME`
+- `SHELL`
+- `PATH=/usr/bin:/bin`
+- `XDG_RUNTIME_DIR=/run/user/$UID`
+- `XDG_SESSION_TYPE=wayland`
+- `XDG_CURRENT_DESKTOP=KDE`
+- `KDE_FULL_SESSION=true`
+- `WAYLAND_DISPLAY=wayland-0`
+- `XDG_SEAT=seat0`
+- `XDG_VTNR=3`
+- `LIBSEAT_BACKEND=seatd`
+- `SEATD_SOCK=/run/seatd.sock`
+
+Preferred launch form:
+
+```text
+dbus-run-session -- redbear-kde-session
+```
+
+If `dbus-run-session` proves unreliable on Red Bear, use the current `dbus-launch` pattern as a bounded
+fallback.
+
+### 9.6 Branding Contract
+
+Stage the current assets at stable runtime paths:
+
+- `/usr/share/redbear/greeter/background.png`
+- `/usr/share/redbear/greeter/icon.png`
+
+Use:
+
+- `Red Bear OS loading background.png` as the full-screen wallpaper
+- `Red Bear OS icon.png` above the login form
+
+The greeter runtime must reference only the installed `/usr/share/redbear/greeter/*` paths.
+`local/Assets/...` remains the source-of-truth location in the repo, not a runtime lookup path.
+
+### 9.7 Failure and Fallback Contract
+
+Greeter failure must never create a dead-end boot surface.
+
+Required behavior:
+
+- VT2 `getty` remains available as text recovery,
+- debug `getty` remains available,
+- greeter failures return control to a recoverable state,
+- repeated greeter/UI restart failures must stop escalating after a bounded retry count,
+- the system must prefer a reachable fallback console over an infinite graphical restart loop.
+
+---
+
+## 10. Phased Implementation
+
+### Phase G0 — Scope Freeze and Wiring Baseline
+
+**Goal:** Freeze the architectural split and identify the tracked desktop profile(s) that will own the
+greeter path.
+
+| # | Task | Acceptance criteria |
+|---|---|---|
+| G0.1 | Freeze component boundaries | `sessiond`, `greeterd`, `authd`, `session-launch` responsibilities documented without overlap |
+| G0.2 | Freeze single-session policy | Only `kde-wayland` is named as the supported graphical session |
+| G0.3 | Freeze branding inputs | Runtime asset paths and source asset files documented |
+
+**Exit criteria:**
+
+- architecture split is documented,
+- session policy is explicit,
+- asset source of truth is explicit.
+
+### Phase G1 — Service Skeleton and Boot Wiring
+
+**Goal:** Add daemon/package skeletons and init wiring without claiming a usable login flow.
+
+| # | Task | Acceptance criteria |
+|---|---|---|
+| G1.1 | Create recipe skeletons | `redbear-greeter`, `redbear-authd`, `redbear-session-launch`, optional `redbear-login-protocol` build and stage |
+| G1.2 | Add config fragment | A tracked config fragment wires `20_greeter.service` and supporting files |
+| G1.3 | Replace direct display launch in the chosen profile | Desktop profile starts `redbear-greeterd` instead of directly starting `redbear-kde-session` |
+| G1.4 | Keep text/debug recovery path | VT2 `getty` and debug `getty` still boot |
+
+**Exit criteria:**
+
+- packages build,
+- boot wiring is in place,
+- image still boots,
+- fallback text surfaces remain reachable.
+
+### Phase G2 — Auth Foundation
+
+**Goal:** Prove the local account/authentication boundary independent of the full greeter UI.
+
+| # | Task | Acceptance criteria |
+|---|---|---|
+| G2.1 | Implement passwd/shadow parsing | Local users can be parsed from the chosen account files |
+| G2.2 | Implement password verification | Valid and invalid credentials are distinguished correctly in tests |
+| G2.3 | Implement lock/disable rules | Locked/disabled users are rejected predictably |
+| G2.4 | Implement session-spawn authorization boundary | Only `redbear-authd` can approve session launch |
+| G2.5 | Implement bounded failure handling | Retry throttling / lockout policy is documented and covered by tests |
+
+**Exit criteria:**
+
+- auth parser tests pass,
+- credential checks pass,
+- negative cases pass,
+- no UI process reads auth data,
+- repeated auth failure behavior is bounded and explicit.
+
+### Phase G3 — Greeter UI and Daemon State Machine
+
+**Goal:** Bring up the graphical greeter surface and daemon orchestration.
+
+| # | Task | Acceptance criteria |
+|---|---|---|
+| G3.1 | Start greeter UI on VT3 | QEMU image reaches a Red Bear-branded graphical greeter surface |
+| G3.2 | Implement UI/daemon socket protocol | UI can submit login and power requests |
+| G3.3 | Implement daemon state machine | State transitions are test-covered for success and failure paths |
+| G3.4 | Implement bounded login error UX | Invalid credentials return cleanly to `GreeterReady` |
+| G3.5 | Implement failure fallback behavior | Greeter/UI restart failure yields reachable fallback behavior rather than infinite restart |
+
+**Exit criteria:**
+
+- greeter surface boots,
+- UI/daemon protocol works,
+- failure returns to the login screen,
+- no session starts yet without auth success,
+- fallback console path remains reachable under greeter failure.
+
+### Phase G4 — Session Handoff to KDE on Wayland
+
+**Goal:** Replace direct session startup with authenticated session launch.
+
+| # | Task | Acceptance criteria |
+|---|---|---|
+| G4.1 | Implement `redbear-session-launch` env/bootstrap path | Session runs with correct uid/gid/groups/runtime dir/env |
+| G4.2 | Implement greeter teardown before session launch | Greeter UI exits before KDE session becomes active |
+| G4.3 | Implement session-monitor return path | Session exit returns to the greeter |
+| G4.4 | Keep bounded D-Bus/sessiond compatibility intact | KWin still sees the required login1 subset |
+
+**Exit criteria:**
+
+- successful login reaches `redbear-kde-session`,
+- session uses intended env/runtime dir,
+- session exit returns to greeter,
+- fallback VT2 login still works.
+
+### Phase G5 — Desktop Integration and Product Surface Hardening
+
+**Goal:** Move from “bounded login proof” to a product-quality Red Bear login surface.
+
+| # | Task | Acceptance criteria |
+|---|---|---|
+| G5.1 | Implement reboot/shutdown path | Greeter can trigger bounded power actions |
+| G5.2 | Hardening | rate limiting, buffer clearing, socket permission checks, retry behavior |
+| G5.3 | Packaging and profile cleanup | Target desktop profile wiring is canonical and documented |
+| G5.4 | Validation tooling | scripted QEMU/runtime proof exists for greeter boot/login/logout loop |
+
+**Exit criteria:**
+
+- login loop is repeatable,
+- power actions are bounded and explicit,
+- hardening checks pass,
+- documentation matches shipped surface.
+
+### Critical Path
+
+```text
+G0 (scope)
+  → G1 (wiring)
+  → G2 (auth boundary)
+  → G3 (greeter surface)
+  → G4 (session handoff)
+  → G5 (product hardening)
+```
+
+---
+
+## 11. Testing and Validation
+
+### 11.1 Unit and Component Tests
+
+| Component | Tests |
+|---|---|
+| `redbear-login-protocol` | message encoding/decoding, version checks |
+| `redbear-authd` | passwd parsing, shadow parsing, hash verification, lockout logic |
+| `redbear-session-launch` | env construction, runtime-dir creation, argument validation |
+| `redbear-greeterd` | state transitions, socket protocol handling, session-monitor behavior |
+| `redbear-greeter-ui` | smoke only; no auth logic in UI tests |
+
+### 11.2 Integration Checks
+
+The first bounded integration proofs should answer these questions in order:
+
+1. does the image boot to a graphical greeter surface on VT3?
+2. does invalid login return to the greeter surface?
+3. does valid login reach `redbear-kde-session`?
+4. does session exit return to the greeter?
+5. do VT2 and debug login remain available as recovery paths?
+6. does greeter failure still leave a recoverable console path instead of looping forever?
+
+### 11.3 Suggested Validation Commands / Harnesses
+
+This plan expects a bounded QEMU harness similar in style to existing Red Bear runtime proofs.
+
+Expected future surfaces:
+
+- `local/scripts/test-greeter-qemu.sh`
+- in-target checker such as `redbear-greeter-check`
+
+The exact script names are implementation details, but the proof style should match existing bounded
+runtime validation patterns already used elsewhere in the repo.
+
+### 11.4 Definition of Done
+
+This plan is only substantially complete when **all** of the following are true:
+
+- a Red Bear-branded graphical greeter boots on the tracked KDE desktop path,
+- credentials are verified through a narrow privileged boundary,
+- valid login reaches KDE on Wayland,
+- invalid login returns cleanly to the greeter,
+- session exit returns to the greeter,
+- VT2 fallback and debug console remain available,
+- greeter/UI failure does not trap the machine in an unrecoverable restart loop,
+- the bounded login/logout proof repeats reliably on the intended target class.
+
+---
+
+## 12. Risks and Mitigations
+
+| ID | Risk | Likelihood | Impact | Mitigation |
+|---|---|---:|---:|---|
+| R1 | `redbear-sessiond` login1 subset proves too thin for stable KWin session ownership | Medium | High | keep greeter plan explicitly dependent on D-Bus/sessiond validation; widen only the needed contract |
+| R2 | Auth layer grows into a PAM replacement by accident | Medium | High | freeze v1 to local users + passwd/shadow only |
+| R3 | Greeter UI becomes privileged by convenience | Medium | High | keep UI unprivileged and enforce daemon/auth socket boundary |
+| R4 | VT/session handoff is flaky on real targets | Medium | High | keep VT2 fallback path and validate QEMU before broader claims |
+| R5 | Profile ownership confusion (`redbear-kde` vs `redbear-full`) delays integration | High | Medium | keep profile naming a policy question separate from greeter architecture |
+| R6 | Branding/assets are staged inconsistently | Low | Medium | stage stable runtime paths under `/usr/share/redbear/greeter/` |
+| R7 | Session launch inherits too much ambient environment | Medium | Medium | start from a clean explicit environment in `redbear-session-launch` |
+| R8 | Greeter restart policy creates boot loops | Medium | High | bound retries and prefer console fallback after repeated failures |
+
+---
+
+## 13. Relationship to Other Plans
+
+| Document | Role relative to this plan |
+|---|---|
+| `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Parent desktop-path authority; this plan fills the graphical login boundary beneath it |
+| `local/docs/DBUS-INTEGRATION-PLAN.md` | Parent session/D-Bus authority for `redbear-sessiond` and related service model |
+| `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` | Current truth source for what the desktop stack actually builds/boots today |
+| `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` | Wayland/compositor subsystem plan beneath the desktop path |
+| `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` | Repo-wide product/profile/workstream framing |
+
+This document does **not** replace any of the above. It fills a missing subsystem-planning gap:
+the login/greeter boundary between a booted desktop substrate and a real KDE session surface.
+
+---
+
+## 14. File and Recipe Inventory
+
+### 14.1 Existing Files This Plan Builds On
+
+- `config/redbear-full.toml`
+- `config/redbear-greeter-services.toml`
+- `local/recipes/system/redbear-sessiond/`
+- `local/recipes/system/redbear-dbus-services/`
+- `local/Assets/images/Red Bear OS loading background.png`
+- `local/Assets/images/Red Bear OS icon.png`
+
+### 14.2 Proposed New Recipe Layout
+
+```text
+local/recipes/system/
+├── redbear-authd/
+├── redbear-session-launch/
+└── redbear-greeter/
+```
+
+Current implementation status:
+
+- `redbear-authd/` — implemented (experimental, target-side recipe build proven)
+- `redbear-session-launch/` — implemented (experimental, target-side recipe build proven)
+- `redbear-greeter/` — implemented as an experimental bounded surface; daemon, Qt/QML UI, compositor wrapper, staged assets, and bounded runtime checks now exist, while broader KDE runtime trust still remains open
+- Current blocker after the greeter/UI packaging work: guest-side Qt shared-plugin loading on Red Bear still rejects platform plugins during metadata scan (`libqminimal.so`, `qwayland-org.kde.kwin.qpa.so`) even though the plugin files are present in the image and their on-disk ELF headers read correctly via non-Qt tools. This blocks the bounded graphical compositor proof below the greeter slice.
+- `redbear-login-protocol/` — optional follow-up extraction, not required for the first bounded runtime proof
+
+### 14.3 Proposed New Runtime Files
+
+```text
+/usr/bin/redbear-greeterd
+/usr/bin/redbear-greeter-ui
+/usr/bin/redbear-authd
+/usr/bin/redbear-session-launch
+/usr/share/redbear/greeter/background.png
+/usr/share/redbear/greeter/icon.png
+/run/redbear-greeterd.sock
+/run/redbear-authd.sock
+/usr/bin/redbear-greeter-check
+```
+
+Bounded validation helper currently landed:
+
+```text
+local/scripts/test-greeter-qemu.sh
+```
+
+### 14.4 Proposed Config Fragment
+
+This plan expects a tracked config include fragment such as:
+
+```text
+config/redbear-greeter-services.toml
+```
+
+That fragment should own:
+
+- package inclusions for greeter/auth/session-launch,
+- `20_greeter.service`,
+- any bounded init-service overrides needed to replace direct session startup.
+
+The greeter **recipe**, not the config fragment, should own staged runtime artifacts such as:
+
+- `/usr/bin/redbear-greeter-ui`
+- `/usr/share/redbear/greeter/background.png`
+- `/usr/share/redbear/greeter/icon.png`
+- compositor/helper payloads that the greeter package installs under `/usr/share/redbear/greeter/`
+
+---
+
+## 15. Open Questions
+
+1. Which tracked profile should own the canonical desktop greeter path first:
+   `redbear-kde`, `redbear-full`, or a unified future target?
+2. Which password-hash scheme should Red Bear standardize on for v1 local users?
+3. Should reboot/shutdown requests go through `redbear-authd` or a separate narrow power helper?
+4. Is `dbus-run-session` reliable enough on Red Bear, or should the current `dbus-launch` path remain the first shipped session-bus strategy?
+5. At what point should the project consider SDDM-class integration again, if ever?
+
+Current answer to (1): **`redbear-full` first**, with `redbear-live-full` inheriting that path for
+live media.
+
+Current answer to (2): **traditional `/etc/shadow` SHA-512-crypt / SHA-256-crypt first** (`$6$` / `$5$`),
+with narrower support preferred over premature multi-format sprawl.
+
+Free/libre policy note for (2): the current verifier path uses the pure-Rust `sha-crypt` crate,
+which is licensed `MIT OR Apache-2.0`; for Red Bear policy purposes it is treated under the MIT
+option, keeping the greeter/login stack within a free/open-source dependency surface. The intended
+implementation direction remains **pure-Rust verification crates first**, not `crypt(3)` FFI.
+
+Current answer to (3): **through `redbear-authd` in the first cut**, to preserve one narrow privileged
+boundary until runtime evidence justifies a separate helper.
+
+Current answer to (4): **`dbus-run-session` remains the preferred first shipped path**, with fallback
+conservatism retained in validation/docs until broader runtime proof exists.
+
+Current answer to (5): **not before the Red Bear-native greeter path is runtime-trusted and the
+session/auth substrate is materially stronger than it is today.**
@@ -42,7 +42,7 @@ GPU hardware (AMD RDNA / Intel Gen)
 | Component | Status | Lines | What's Implemented |
 |-----------|--------|-------|-------------------|
 | DRM/KMS modesetting | ✅ Code complete | ~500 | 16 KMS ioctls, CRTC/connector/encoder/plane |
-| AMD Display Core | ✅ Compiles | ~1400 | DC init, CRTC programming, firmware loading, HPD |
+| AMD display backend (bounded retained path) | ✅ Builds | ~2 C glue files + Rust FFI surface | Red Bear display glue (`amdgpu_redox_main.c`, `redox_stubs.c`) plus the Rust FFI consumer build; imported Linux AMD DC/TTM/core remain under compile triage |
 | Intel Display Driver | ✅ Compiles | ~800 | Display pipe, GGTT, forcewake |
 | GEM buffer management | ✅ Full | ~350 | create/close/mmap with DmaBuffer |
 | GEM scheme ioctls | ✅ Wired | ~100 | GEM_CREATE, GEM_CLOSE, GEM_MMAP |
@@ -167,5 +167,5 @@ platform priority.

 - `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — Phase 5 covers hardware GPU enablement
 - `local/docs/AMD-FIRST-INTEGRATION.md` — AMD-specific GPU driver details
- `local/docs/P2-AMD-GPU-DISPLAY.md` — Display driver code-complete status
+- `local/docs/AMDGPU-DC-COMPILE-TRIAGE-PLAN.md` — AMD DC compile-triage and bounded source-set strategy
 - `docs/04-LINUX-DRIVER-COMPAT.md` — linux-kpi architecture reference
@@ -2,7 +2,7 @@

 **Purpose**: Implementation-ready hardware register and data structure reference for Red Bear OS IOMMU support. Based on AMD IOMMU Specification 48882 Rev 3.10 and Intel Virtualization Technology for Directed I/O (VT-d) Rev 5.0.

-**Status**: The `iommu` daemon now builds in-tree, but hardware validation is still missing in the AMD-first integration plan (see `AMD-FIRST-INTEGRATION.md`). This document provides the register and data-structure reference for finishing AMD-Vi and Intel VT-d bring-up.
+**Status**: The `iommu` daemon now builds in-tree, owns AMD-Vi runtime initialization, and also detects the presence of a kernel ACPI `DMAR` table so Intel VT-d runtime ownership can converge here instead of remaining conceptually stranded in `acpid`. Hardware validation is still missing in the AMD-first integration plan (see `AMD-FIRST-INTEGRATION.md`). This document provides the register and data-structure reference for finishing AMD-Vi and Intel VT-d bring-up.

 ---

@@ -78,6 +78,9 @@ Red Bear OS already has a meaningful low-level controller and interrupt foundati
  including PCI scheme-entry parsing bounds, I/O BAR port conversion safety, and MSI-X BAR window
  helper validation. This should be treated as **source + host-test evidence**, not as runtime
  controller proof.
+- `redox-driver-sys` fast PCI enumeration now preserves capability-chain data from config-space
+  bytes instead of returning empty capability lists, and exposes a quirk-aware interrupt-support
+  summary (`none` / `legacy` / `msi` / `msix`) for downstream policy convergence.
 - `redox-drm` already contains a shared interrupt abstraction with MSI-X-first and legacy-IRQ
  fallback paths for GPU drivers.
 - The AMD-Vi / Intel VT-d reference material and the in-tree `iommu` daemon establish a serious
@@ -328,6 +331,9 @@ Open enhancement items:
 - the repo now has a bounded PS/2 runtime-proof path via `redbear-phase-ps2-check` and
  `local/scripts/test-ps2-qemu.sh --check`, which proves serio node presence and a successful
  handoff into the existing Phase 3 input-path checker inside a guest
+- `ps2d` controller init now also drains stale controller output during probe and around the core
+  init/self-test path, which is the current bounded Red Bear-native equivalent of Linux i8042 flush
+  discipline before broader PS/2 suspend/resume work exists.

 ### USB xHCI controller interrupt path

@@ -12,6 +12,43 @@ This document answers a specific Red Bear question:

 This plan is intentionally **Red Bear-native**. It does **not** propose importing Linux subsystem architecture into Red Bear.

+## Current implementation status snapshot (2026-04-18)
+
+The software-only, bounded slices from this plan that are now implemented in code are:
+
+- **Phase A — PCI / IRQ substrate**
+- shared PCI config-space parsing now preserves capability chains in `redox-driver-sys`
+- shared quirk-aware interrupt support summary exists (`none` / `legacy` / `msi` / `msix`)
+- `pcid` now consumes the shared PCI parser in its header path for interrupt-support reporting,
+  which starts the planned downstream convergence onto the shared substrate instead of keeping all
+  capability interpretation local.
+- **Phase B — ACPI / IOMMU groundwork**
+  - `acpid` now has an explicit userspace sleep-target model for `S1` / `S3` / `S4` / `S5`
+  - `_S5` shutdown routes through that model, while non-`S5` targets remain groundwork-only
+  - `iommu` now detects kernel ACPI `DMAR` presence, establishing the Intel VT-d ownership seam
+- **Phase C — PS/2 / USB / storage**
+  - `ps2d` now flushes stale controller output during probe and around core init/self-test
+  - `xhcid` now tracks active alternate settings and resolves endpoint descriptors through that map
+  - `usbscsid` now has a bounded `SYNCHRONIZE CACHE(10/16)` heuristic behind `needs_sync_cache`
+- **Phase D — Wi-Fi / DRM shared-core**
+  - `redbear-wifictl` transport probing now uses the shared PCI parser and interrupt-support summary
+  - `redox-drm` now exposes queued shared hotplug/vblank events through a real scheme `EVENT_READ` surface
+
+The work that still remains is the larger **vendor/backend maturation and hardware-validation** side:
+
+- full ACPI sleep/resume implementation beyond groundwork
+- full Intel VT-d runtime support beyond DMAR ownership discovery
+- deeper PCI / `pcid` convergence on shared helpers
+- broader PS/2 resume/wake policy
+- broader USB architecture/runtime maturation beyond the bounded helper slices already implemented
+- deeper Wi-Fi transport/helper extraction beyond probing
+- Intel and AMD DRM backend maturation and real hardware validation
+
+This document should therefore be read as:
+
+- **implemented now** for the bounded shared-core and software-only slices listed above
+- **still in progress** for backend maturation and hardware-backed acceptance phases
+
 ## Hard rules

 1. **Linux suspend/resume is reference-only.** Red Bear should study Linux ordering and edge cases, but implement its own suspend/resume support in the Red Bear architecture.
@@ -285,6 +322,15 @@ Keep only:
 - unit tests for malformed capability chains and BAR layout
 - interrupt mode logged deterministically

+**Current implementation progress (2026-04-18)**
+- `redox-driver-sys` fast PCI enumeration now parses capability chains from config bytes in the
+  read-only path, so enumerated `PciDeviceInfo` records no longer default to empty capability
+  lists.
+- `PciDeviceInfo` now exposes a quirk-aware interrupt support summary (`none`, `legacy`, `msi`,
+  `msix`) that can serve as the common policy input for future `pcid`/driver convergence.
+- Host-runnable unit coverage exists for capability-chain parsing, malformed next-pointer handling,
+  and interrupt-support selection behavior.
+
 ### Phase B — ACPI / suspend / IOMMU

 **Primary targets**
@@ -304,6 +350,19 @@ Keep only:
 - explicit sleep phase machine exists
 - IOMMU ownership clarified and moved out of `acpid`

+**Current implementation progress (2026-04-18)**
+- `acpid` now has an explicit `SleepTarget` / `SleepPhase` model in userspace, covering `S1`, `S3`,
+  `S4`, and `S5` as named Red Bear sleep targets.
+- The real shutdown path now routes through that target model, while non-`S5` targets are
+  recognized but reported as groundwork-only rather than silently ignored.
+- Unit coverage exists for sleep-target parsing, AML sleep-object naming, and the current
+  Red Bear-native rule that only `S5` is treated as an implemented soft-off path today.
+- This is still groundwork only: there is no claim of full suspend/resume or sleep eventing yet,
+  and Linux suspend sequencing remains reference material rather than imported structure.
+- The `iommu` daemon now also detects the presence of a kernel ACPI `DMAR` table and reports that
+  Intel VT-d runtime ownership should converge there instead of remaining conceptually attached to
+  the old transitional `acpid` DMAR code.
+
 ### Phase C — PS/2 / USB / storage

 **Primary targets**
@@ -321,6 +380,33 @@ Keep only:
 - xHCI and USB maturity proofs remain green
 - no Linux USB/input-core structure imported

+**Current implementation progress (2026-04-18)**
+- `xhcid` now tracks active alternate settings per interface and resolves endpoint descriptors using
+  that active-alternate map instead of flattening all interface descriptors in a configuration.
+- Direct unit coverage exists for default-alternate endpoint selection and alternate-setting-aware
+  endpoint remapping, closing the most explicit in-tree USB interface-selection TODO without
+  importing Linux USB-core structure.
+- `xhcid` now also preserves previously selected alternates on the same configuration and applies a
+  requested interface/alternate override before endpoint planning, so alternate-setting
+  reconfiguration no longer silently falls back to all-zero defaults.
+- `xhcid` endpoint-direction lookup now also follows the active interface/alternate selection state
+  instead of reading from the first configuration/interface pair unconditionally.
+- `xhcid` driver spawning now also follows the selected configuration and active alternate map
+  instead of hardcoding the first configuration and ignoring non-zero alternates.
+- `xhcid` now also has a preserve-and-grow event-ring path in the IRQ reactor, so `EventRingFull`
+  recovery no longer drops unread event TRBs while resizing the primary event ring.
+- `usbhubd` and `xhcid` now propagate USB 2 hub TT Think Time from the parent hub descriptor into
+  the xHCI Slot Context TT information bits using a bounded Linux-compatible encoding path.
+- `xhcid` endpoint-context calculations are now protocol-speed-aware for SuperSpeedPlus, so
+  interval and ESIT-payload selection distinguish SSP paths from generic SuperSpeed using the
+  resolved port protocol speed rather than only endpoint companion presence.
+- `usbscsid` now has a bounded native `SYNCHRONIZE CACHE(10/16)` heuristic gated by the existing
+  `needs_sync_cache` storage quirk, directly reflecting the planned Linux `sd.c` donor usage without
+  importing Linux SCSI midlayer structure.
+- `ps2d` now performs an explicit controller-output flush during probe and at the key controller
+  reinitialization boundaries in `Ps2::init()`, matching the Linux `i8042_flush()` discipline in a
+  bounded Red Bear-native way without importing Linux input-core structure.
+
 ### Phase D — Wi-Fi and GPU/DRM

 **Primary targets**
@@ -337,6 +423,16 @@ Keep only:
 - DRM display-vs-render boundary remains explicit
 - no claim of full AMDGPU rewrite or Linux wireless-architecture import

+**Current implementation progress (2026-04-18)**
+- `redbear-wifictl` transport probing now uses the shared `redox-driver-sys` PCI parser and the
+  shared quirk-aware interrupt-support summary instead of relying only on local raw-config logic.
+- This is a bounded helper extraction only: the native Wi-Fi control plane remains authoritative,
+  and there is still no import of Linux wireless subsystem structure.
+- `redox-drm` now turns shared hotplug and vblank events into a queued scheme-visible
+  `EVENT_READ` surface for `card0`, with hotplug also reaching the matching connector handle.
+  That makes shared DRM event delivery observable without conflating it with render-fence
+  semantics.
+
 ## 4. Subsystem-specific code guidelines

 ### ACPI / suspend
@@ -1,143 +0,0 @@
-# Historical Phase P2: AMD GPU Display Output
-
-## Status: Historical implementation milestone complete — hardware validation pending
-
-> **Planning authority note (2026-04-18):** this file is an AMD display implementation/status
-> reference. For current GPU/DRM execution order, Intel/AMD parity criteria, and future task
-> sequencing, use `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md`.
-
-The original P2 implementation task was completed and compile-validated for its scoped deliverables.
-This file is now a historical AMD display implementation/status reference rather than the canonical
-GPU planning document. Hardware validation remains a separate milestone requiring physical AMD GPU
-hardware.
-
-## Goal
-Enable AMD GPU display output (modesetting) on Redox OS via a DRM scheme daemon
-that ports the AMD Display Core (DC) from Linux kernel 7.0-rc7.
-
-## Architecture
-
-Userspace apps → scheme:drm → redox-drm daemon → AMD DC (C code, linux-kpi) → MMIO
-
-## Components
-
-### redox-drm (local/recipes/gpu/redox-drm/)
-DRM scheme daemon. Registers scheme:drm/card0.
- PCI enumeration for AMD GPUs (vendor 0x1002)
- MMIO register mapping via redox-driver-sys
- KMS: connector detection, mode getting, CRTC programming
- GEM: buffer object create/mmap/close
- Dispatches to AMD driver backend
-
-### amdgpu C port (local/recipes/gpu/amdgpu/source/)
-AMD GPU driver source extracted from Linux 7.0-rc7:
- drivers/gpu/drm/amd/ — full AMD driver (269k lines)
- drivers/gpu/drm/ttm/ — TTM memory manager
- include/drm/ — DRM core headers
- include/linux/ — Linux kernel headers (reference)
-
-### amdgpu build recipe (local/recipes/gpu/amdgpu/)
-Compiles AMD DC display code against linux-kpi headers with -D__redox__:
- recipe.toml — custom build template
- redox_glue.h — type compatibility, function stubs, macro replacements
- redox_stubs.c — C implementations of Linux kernel API stubs
- amdgpu_redox_main.c — daemon entry point replacing module_init
-
-## Build Integration
-
-Config: config/redbear-desktop.toml (includes desktop.toml + Red Bear GPU packages)
- Includes redox-drm and amdgpu packages
- filesystem_size = 8196 (8GB, needs space for firmware blobs)
-
-pcid: local/config/pcid.d/amd_gpu.toml
- Auto-detects AMD GPU (vendor 0x1002, class 0x03)
- Launches redox-drm with PCI device location
-
-## Boot Sequence (P2)
-
-1. Kernel boots, initializes PCI subsystem
-2. pcid detects AMD GPU (vendor 0x1002)
-3. pcid-spawner launches: redox-drm $BUS $DEV $FUNC
-4. redox-drm opens PCI device, verifies AMD GPU
-5. redox-drm maps MMIO BAR0 (GPU registers)
-6. redox-drm loads PSP firmware via scheme:firmware
-7. redox-drm initializes AMD DC (Display Core)
-8. AMD DC detects connectors, reads EDID
-9. scheme:drm/card0 registered
-10. Userspace can begin bounded display-side probing (for example `modetest`) once runtime validation is available; this is not yet a hardware-backed support claim by itself
-
-## Verification
-
-### Code Complete (P2 implementation task)
- [x] scheme:drm/card0 daemon compiles and registers scheme
- [x] KMS ioctl dispatch handles all 15 DRM ioctls
- [x] GEM buffer lifecycle: create/mmap/close with ownership tracking
- [x] FB lifecycle: ADDFB/RMFB with size validation, per-fd ownership
- [x] Page flip: one outstanding per CRTC, vblank-gated retirement
- [x] Firmware: Rust cache validates blob availability at startup; C code loads via request_firmware() from scheme:firmware at runtime
- [x] GTT page tables: free-list reuse, TLB-safe error rollback
- [x] Original implementation pass received repeated review of resource lifecycle, ownership, GTT, and page-flip behavior
- [x] All 4 Rust crates build with zero errors, zero warnings
- [x] C glue files pass gcc -fsyntax-only
- [x] Build symlinks and config files in place
-
-### Hardware Validation (requires physical AMD GPU)
- [ ] modetest -M amd shows connector info and modes
- [ ] modetest -M amd -s 0:1920x1080 sets mode and shows test pattern
- [ ] Works on real AMD hardware (RDNA2/RDNA3)
-
-Current bounded runtime harness:
- `redbear-drm-display-check` is now the in-guest bounded display checker.
- `local/scripts/test-amd-gpu.sh` now wraps the shared `local/scripts/test-drm-display-runtime.sh` harness.
- The checker now proves connector/mode enumeration directly and can perform a bounded direct modeset proof.
- A successful harness run is still display-only evidence, not render proof.
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| local/recipes/gpu/redox-drm/ | DRM scheme daemon |
-| local/recipes/gpu/amdgpu/ | Build recipe + integration glue |
-| local/recipes/gpu/amdgpu/source/ | AMD driver C port source (from Linux 7.0-rc7) |
-| config/redbear-desktop.toml | Build config |
-| local/config/pcid.d/amd_gpu.toml | PCI auto-detection (AMD) |
-| local/recipes/gpu/redox-drm/source/src/drivers/interrupt.rs | MSI-X/legacy interrupt abstraction |
-| local/config/pcid.d/intel_gpu.toml | Intel GPU PCI auto-detection |
-| local/patches/base/P0-pcid-config-endpoint.patch | pcid /config file endpoint |
-| local/scripts/build-redbear.sh | Canonical build wrapper |
-| local/scripts/test-amd-gpu.sh | Test script |
-
-## Dependencies (P1)
-
-| Crate | Status | Provides |
-|-------|--------|----------|
-| redox-driver-sys | ✅ | MmioRegion, PciDevice, IrqHandle, DmaBuffer |
-| linux-kpi | ✅ | C headers, FFI stubs (kmalloc, mutex, spinlock...) |
-| firmware-loader | ✅ | scheme:firmware daemon |
-
-## P1/P2 Changes Since Initial Implementation
-
-### pcid /config endpoint (T1)
- Added `Config { addr: PciAddress }` handle to pcid scheme
- Routes `/scheme/pci/{addr}/config` to raw PCI config space read/write
- Enables redox-driver-sys PciDevice to access config space for MSI-X, BAR parsing
-
-### MSI-X interrupt support (T2-T4)
- Created shared `InterruptHandle` enum in `redox-drm/src/drivers/interrupt.rs`
- Tries MSI-X first (find capability → parse → map table → mask_all → enable → request_vector)
- Falls back through MSI and then legacy IRQ, with `NO_MSIX`, `NO_MSI`, and `FORCE_LEGACY_IRQ` quirk gates applied before transport selection
- Both AMD and Intel drivers use `InterruptHandle::setup()`
-
-### Dynamic PCI device info (T6)
- Replaced hardcoded `redox_pci_find_amd_gpu()` stub with `redox_pci_set_device_info()`
- Rust side passes real PciDeviceInfo (vendor, device, revision, IRQ, BAR0/BAR2) to C via FFI
- C layer validates the struct is populated before `amdgpu_redox_init()` uses it
-
-### linux-kpi quirk consumption (current)
- `redox-drm` now also passes the real PCI BDF into the amdgpu C glue so linux-kpi quirk lookups resolve against the actual GPU, not a guessed location
- `amdgpu_redox_main.c` now calls `pci_get_quirk_flags()` / `pci_has_quirk()` in the live Redox init path
- firmware gating now stays at the Rust-side GPU driver boundary, while the AMD C backend logs quirk-driven IRQ expectations (`NO_MSI`, `NO_MSIX`, `FORCE_LEGACY`) via linux-kpi lookups on the real GPU BDF
-
-### Intel GPU support (T4-T5)
- Intel driver switched to shared `InterruptHandle` (MSI-X / MSI / legacy with quirk-aware fallback)
- Added `local/config/pcid.d/intel_gpu.toml` for auto-detection (vendor 0x8086, class 0x03)
@@ -258,7 +258,7 @@ Plus: QML debug plugins, QtQuick/QML modules staged.

 Recent relibc implementation progress in this repo now also includes:

- source-visible `signalfd`, `timerfd`, `eventfd`, `open_memstream`, `F_DUPFD_CLOEXEC`, and `MSG_NOSIGNAL`
+- source-visible plus strict Redox-target runtime-tested `signalfd`, `timerfd`, `eventfd`, `open_memstream`, `F_DUPFD_CLOEXEC`, and `MSG_NOSIGNAL`
 - a bounded `waitid()` path in relibc, replacing the old Qt-side waitid stub workaround
 - a bounded `eth0`-backed `net_if` / `ifaddrs` path in relibc
 - a minimal source-visible `resolv.h` surface in relibc
@@ -307,7 +307,7 @@ Current downstream build proof in this repo now includes:
  - Non-udev shim (libudev stub for HAVE_UDEV=0)
  - Vendored Linux input.h selection for __redox__
  - strtod_l() fallback
-  - timerfd fallback (tracks expiry without timerfd fd)
+- timerfd path still warrants broader consumer-confidence review, but relibc now has strict Redox-target runtime proof for the bounded timerfd harness
  - Linux-only tool binaries skipped on Redox

 ### Phase 3 — KF6 Frameworks (✅ ALL 32 BUILT)
@@ -49,7 +49,8 @@ The Red Bear USB stack consists of:
 - native USB observability (`lsusb`, `usbctl`, `redbear-info`)
 - a low-level userspace client API through `xhcid_interface`
 - a hardware quirks system that applies USB device-specific workarounds at runtime
- three QEMU validation harnesses covering interrupt delivery, full stack, and storage autospawn
+- four QEMU validation harnesses covering interrupt delivery, bounded device lifecycle hotplug,
+  full stack, and storage autospawn
 - an in-guest scheme-tree checker (`redbear-usb-check`)

 ### Red Bear xHCI Patch Layer
@@ -104,12 +105,9 @@ source:
 Even with the Red Bear patch applied:

 - HID is still wired through the legacy mixed-stream `inputd` path
- SuperSpeedPlus differentiation requires Extended Port Status (not yet implemented)
- TTT (Think Time) in Slot Context hardcoded to 0 — needs parent hub descriptor propagation
- Composite devices and non-default alternate settings use first-match only
-  (`//TODO: USE ENDPOINTS FROM ALL INTERFACES`)
- `grow_event_ring()` swaps to a new ring but does not copy pending TRBs from the old one; under
-  sustained event-ring-full conditions this may lose in-flight events
+- Any remaining USB composite/device-model issues now sit above the bounded helper fixes already
+  landed for active alternates, endpoint direction, real interface/alternate hub configuration, and
+  SSP-aware endpoint-context calculations.
 - ~57 TODO/FIXME comments remain across xHCI driver files
 - usbhubd: interrupt-driven change detection implemented; 1-second polling retained as fallback
 - usbscsid: `ReadCapacity16` now implemented with automatic fallback from `ReadCapacity10`
@@ -168,6 +166,7 @@ Key files and their sizes:

 | Script | What it tests | Limitations |
 |---|---|---|
+| `test-xhci-device-lifecycle-qemu.sh --check` | Bounded xHCI hotplug lifecycle proof: runtime attach → configure → driver spawn → detach for HID and storage devices | QEMU-only; monitor-driven hotplug; not a broad hardware stress test |
 | `test-usb-qemu.sh --check` | Full stack: xHCI interrupt mode, HID spawn, SCSI spawn, bounded sector-0 readback, BOS processing, crash errors | QEMU-only; log-grep based; no guest-side write proof |
 | `test-usb-storage-qemu.sh` | USB mass storage autospawn + sector-0 readback + crash patterns | No guest-side write proof yet; no multi-LUN; no UAS |
 | `test-xhci-irq-qemu.sh --check` | xHCI interrupt delivery mode (MSI/MSI-X/INTx) | No devices attached during check; single log grep |
@@ -262,6 +261,12 @@ hardware; controller enumerates attached devices reliably across repeated boot c
 - USB 3 hub endpoint configuration stall handled
 - `endp_direction` off-by-one fixed (`checked_sub(1)`)
 - `cfg_idx` assigned after validation
+- xHCI lifecycle gating prevents new I/O from entering while a port is detaching
+- `attach_device()` no longer leaves a published partially-enumerated `PortState` on attach failure
+- `detach_device()` now waits for in-flight lifecycle operations before removing the port state
+- `configure_endpoints_once()` is transactional: endpoint state is staged locally, input-context
+  mutations are snapshotted, and rollback is attempted if `CONFIGURE_ENDPOINT` or
+  `SET_CONFIGURATION` fails
 - `CLEAR_FEATURE` uses correct USB endpoint address from descriptor
 - `usbhubd` status_change_buf sizing and bitmap parsing fixed
 - Hub interrupt EP1 status change detection replacing polling
@@ -314,6 +319,9 @@ replug do not collapse all USB HID into one anonymous stream.
 - `usbscsid` SCSI layer: `plain::from_bytes().unwrap()` replaced with typed `ScsiError` and fallible `parse_bytes`/`parse_mut_bytes` helpers
 - `usbscsid` main.rs: fallible `run()` helper, event loop continues on individual failures
 - `ReadCapacity16` implemented with automatic fallback when `ReadCapacity10` returns max LBA (0xFFFFFFFF)
+- `usbscsid` now issues bounded `SYNCHRONIZE CACHE(10/16)` commands when the runtime storage quirk
+  set includes `needs_sync_cache`, using Linux `sd.c` sync-cache behavior as a donor reference for
+  command selection and tolerant error handling.

 **Remaining** (all require hardware or design decisions):
 - Runtime I/O validation: prove stall recovery works under real device I/O (requires hardware)
@@ -359,6 +367,7 @@ scope.
 - `test-usb-qemu.sh` — full USB stack validation harness (6 checks)
 - `test-usb-storage-qemu.sh` — USB mass storage autospawn check
 - `test-xhci-irq-qemu.sh` — xHCI interrupt delivery mode check
+- `test-xhci-device-lifecycle-qemu.sh` — bounded xHCI attach/configure/detach hotplug proof
 - `USB-VALIDATION-RUNBOOK.md` — operator documentation with Paths A and B
 - `redbear-usb-check` — in-guest scheme-tree checker (now installed in image)
 - `lsusb` — full USB scheme walk with descriptor parsing and quirks integration
@@ -367,7 +376,7 @@ scope.
 **Remaining** (all require hardware):
 - Add hardware-matrix coverage for target controllers and class families
 - Add USB storage data I/O validation (read/write to block device)
- Add hot-plug stress testing harness
+- Add repeated hardware hot-plug stress testing beyond the bounded QEMU lifecycle slice

 **Exit criteria**: at least one profile can honestly claim a validated USB baseline for named
 controller/class scope; USB support language in docs matches real test evidence.
@@ -613,24 +622,49 @@ zero `unwrap()`/`expect()` panics), interrupt-driven hub change detection, `Read
 for large disk support, and a USB quirk table expanded from 8 to 146 entries with 22 quirk flags
 mined from Linux 7.0.

+Recent bounded maturity progress:
+
+- `xhcid` now tracks active alternate settings per interface in `PortState` and resolves endpoint
+  descriptors through that active-alternate map instead of flattening all interface descriptors
+  indiscriminately.
+- Direct unit coverage now exists for both default-alternate endpoint selection and
+  alternate-setting-aware endpoint remapping.
+- `xhcid` now also preserves previously selected alternates on the same configuration and applies a
+  requested interface/alternate override before endpoint planning, so alternate-setting
+  reconfiguration no longer silently falls back to all-zero defaults.
+- `xhcid` endpoint-direction lookup now also follows the active interface/alternate selection state
+  instead of reading from the first configuration/interface pair unconditionally.
+- `xhcid` driver spawning now also follows the selected configuration and active alternate map
+  instead of hardcoding the first configuration and ignoring non-zero alternates.
+- `xhcid` now keeps per-port lifecycle state so detach blocks new transfer/configure/suspend/resume
+  work, waits for in-flight operations to drain, and removes the published port state only after
+  slot disable succeeds.
+- `xhcid` endpoint configuration is now transactional: software endpoint bookkeeping stays staged
+  until `CONFIGURE_ENDPOINT` and optional `SET_CONFIGURATION` succeed, and the input context is
+  restored with an explicit rollback attempt on failure.
+- the xHCI IRQ reactor now replaces the old `TODO: grow event ring` stub with a preserve-and-grow
+  path that copies unread event TRBs into a larger event ring and reprograms ERST registers instead
+  of dropping pending events during `EventRingFull` recovery.
+- `usbhubd` now derives USB 2 hub TT Think Time from the hub descriptor using the same bounded
+  Linux-compatible encoding and passes it through `ConfigureEndpointsReq`, and `xhcid` now writes
+  that value into the Slot Context TT information bits for hub devices.
+- xHCI endpoint-context calculations are now protocol-speed-aware for SuperSpeedPlus, so interval
+  and ESIT-payload selection use the resolved port protocol speed instead of relying only on
+  endpoint companion presence.
+
 All validation is QEMU-only. No real hardware USB testing exists.

-The remaining gaps fall into three categories:
+The remaining gaps now fall into two categories:

-**Still-open software work (implementable without hardware):**
- Composite-device endpoint selection across interfaces (xHCI scheme.rs — `//TODO: USE ENDPOINTS FROM ALL INTERFACES`)
- Non-default configuration and alternate-setting support (xHCI scheme.rs)
- SuperSpeedPlus differentiation via Extended Port Status
- TTT (Think Time) propagation from parent hub descriptor into Slot Context
- Event ring growth does not copy pending TRBs from old ring (may lose events under sustained load)
-
-**Architectural redesign (cross-cutting, not USB-internal):**
+**Broader architectural work (cross-cutting, not a small bounded USB-only fix):**
+- Any remaining USB composite/device-model issues now belong to wider device-model/design cleanup
+  rather than one more isolated helper patch.
 - HID producer modernization: per-device streams, hotplug add/remove (requires inputd redesign)
 - Userspace USB API: `libusb` WIP, no coherent native story

 **Hardware-dependent or design decisions:**
 - Real hardware validation: no controller tested outside QEMU
- Hot-plug stress testing
+- Hot-plug stress testing beyond the new bounded QEMU lifecycle harness
 - Storage write validation (bounded sector-0 readback proof now exists in QEMU via `test-usb-storage-qemu.sh`, but guest-side write verification to the USB-backed block device is still open)
 - usbhubd 1-second polling fallback (only exercisable with real hub hardware)
 - Modern USB scope decision: device mode / USB-C / PD
@@ -1,365 +0,0 @@
-# Red Bear OS USB Storage, Speed, and Device Integration
-
-## Purpose
-
-This document covers USB subsystem areas that the main USB implementation plan
-(`USB-IMPLEMENTATION-PLAN.md`) treats at a higher level: mass storage quality, filesystem
-integration, device speed handling, backwards compatibility, and integrated USB device paths.
-
-It is a companion document, not a replacement. Read both together for the complete USB picture.
-
-## Current Headline
-
-USB mass storage is **present in the codebase but disabled**. The driver table entry for
-`usbscsid` is commented out in `drivers.toml` with the note "#TODO: causes XHCI errors". HID
-(keyboard/mouse) and hub handling are enabled and functional in QEMU.
-
-## USB Mass Storage
-
-### Architecture
-
-```
-USB device → xhcid (scheme:usb) → usbscsid → driver_block::DiskScheme → /scheme/disk.usb-*
-                                                                         → filesystem (redoxfs/ext4d)
-```
-
-| Layer | Component | Status |
-|---|---|---|
-| Transport | BOT (Bulk-Only Transport) | ✅ Implemented — CBW/CSW signatures validated, tag matching, stall recovery |
-| Protocol | SCSI SBC | ⚠️ Partial — READ(16)/WRITE(16) only, missing READ(10)/WRITE(10) |
-| Block device | driver_block::DiskScheme | ✅ Functional — registers as `/scheme/disk.usb-{scheme}+{port}-scsi` |
-| Partitions | partitionlib (MBR/GPT) | ✅ Parsed on init — exposes `0p0`, `0p1`, etc. |
-| Filesystems | redoxfs, ext4d | ✅ Can mount USB block devices via scheme path |
-
-### BOT Transport Quality
-
-The BOT transport in `usbscsid/src/protocol/bot.rs` is well-implemented:
-
- **CBW handling**: Correct signature (`0x43425355`), per-command tag increment, direction bit, LUN field
- **CSW handling**: Signature validation, tag matching, residue tracking, short packet tolerance
- **Stall recovery**: `ClearFeature(ENDPOINT_HALT)` on both endpoints, `Bulk-Only Mass Storage Reset`
-  class request (0xFF) for full reset recovery, re-check for persistent stalls
- **Phase errors**: Detected and reported via `ProtocolError`
-
-### SCSI Command Completeness
-
-| Command | CDB Size | Status | Notes |
-|---|---|---|---|
-| INQUIRY | 6 | ✅ | Standard + vendor inquiry data |
-| REQUEST SENSE | 6 | ✅ | Fixed-format sense data |
-| READ CAPACITY(10) | 10 | ✅ | 32-bit LBA, used as first probe |
-| READ CAPACITY(16) | 16 | ✅ | 64-bit LBA, auto-fallback from RC(10) max |
-| READ(16) | 16 | ✅ | Primary read path |
-| WRITE(16) | 16 | ✅ | Primary write path |
-| MODE SENSE(6) | 6 | ✅ | Block descriptor fallback |
-| MODE SENSE(10) | 10 | ✅ | Primary block size/count source |
-| READ(10) | 10 | ❌ **Missing** | Required for older/simpler devices |
-| WRITE(10) | 10 | ❌ **Missing** | Required for older/simpler devices |
-| SYNCHRONIZE CACHE | 10 | ⚠️ Opcode only | Never issued |
-| START STOP UNIT | 6 | ⚠️ Opcode only | Never issued |
-| TEST UNIT READY | 6 | ⚠️ Opcode only | Never issued |
-| REPORT LUNS | 12 | ❌ **Missing** | Needed for multi-LUN devices |
-| MODE SELECT(6/10) | 6/10 | ❌ **Missing** | Needed for parameter negotiation |
-| FORMAT UNIT | 6 | ❌ **Missing** | Rarely needed |
-
-**Critical gap**: READ(10)/WRITE(10) are not implemented. The daemon uses 16-byte CDBs exclusively.
-Devices that only support 10-byte SCSI commands (some older USB flash drives, embedded firmware
-devices) will fail. Adding READ(10)/WRITE(10) with automatic fallback (similar to how
-READ CAPACITY(10)→(16) already works) is a concrete, bounded improvement.
-
-### LUN Support
-
-`get_max_lun()` reads the device's max LUN count via class-specific request, but the daemon
-hardcodes `cbw.lun = 0` for all commands. Multi-LUN devices (card readers, multi-slot adapters)
-will only expose the first LUN. Supporting multiple LUNs requires:
-
-1. Iterating from 0 to max_lun
-2. Creating separate `UsbDisk` instances per LUN
-3. Registering separate `DiskScheme` paths per LUN
-
-### UAS (USB Attached SCSI)
-
-UAS is not implemented. The protocol factory in `protocol/mod.rs` only matches protocol 0x50 (BOT).
-Protocol 0x62 (UAS) is absent. UAS provides:
-
- Multiple simultaneous command pipes (vs BOT's single serialize-execute-wait)
- Stream-based transfers for higher throughput
- Better error recovery semantics
-
-For USB 3.0 SuperSpeed devices, UAS can provide significantly higher throughput than BOT.
-
-### Transfer Size Limitations
-
- BOT max transfer: 64KB per command (driver_interface.rs hard limit)
- Stream transfer chunk: 32KB per iteration (hardcoded in TransferStream)
- No scatter-gather: all data must fit in a single buffer (explicit TODO in scsi/mod.rs)
-
-### Why usbscsid is Disabled
-
-The comment says "#TODO: causes XHCI errors". This likely relates to:
-
-1. Bulk endpoint configuration issues in the xHCI driver
-2. The 64KB transfer limit causing multi-block reads to fragment incorrectly
-3. Missing endpoint stall handling during initial enumeration
-
-**Re-enabling usbscsid is a prerequisite for USB storage validation.**
-
-## USB Speed Handling
-
-### Speed Detection
-
-The xHCI driver detects device speed via PORTSC register bits 10–13. The `ProtocolSpeed` struct
-(in `xhci/extended.rs`) classifies speeds:
-
-| Speed | Bitrate | Detection | Status |
-|---|---|---|---|
-| Low Speed | 1.5 Mbps | `is_lowspeed()` | ✅ Detected |
-| Full Speed | 12 Mbps | `is_fullspeed()` | ✅ Detected |
-| High Speed | 480 Mbps | `is_highspeed()` | ✅ Detected |
-| SuperSpeed Gen1 x1 | 5 Gbps | `is_superspeed_gen1x1()` | ✅ Detected |
-| SuperSpeedPlus Gen2 x1 | 10 Gbps | `is_superspeedplus_gen2x1()` | ✅ Detected |
-| SuperSpeedPlus Gen1 x2 | 10 Gbps x2 | `is_superspeedplus_gen1x2()` | ✅ Detected |
-| SuperSpeedPlus Gen2 x2 | 20 Gbps x2 | `is_superspeedplus_gen2x2()` | ✅ Detected |
-
-### Default Control Pipe Max Packet Size
-
-The driver sets the default control pipe max packet size based on speed:
-
-| Speed | Max Packet Size | Location |
-|---|---|---|
-| Low/Full Speed | 8 bytes | mod.rs:1128 |
-| High Speed | 64 bytes | mod.rs:1131 |
-| SuperSpeed | 512 bytes | mod.rs:1134 |
-
-### Transfer Type Support
-
-| Transfer Type | USB Role | Status | Notes |
-|---|---|---|---|
-| Control | Configuration, enumeration | ✅ Works | Endpoint 0 only |
-| Bulk | Mass storage, network | ✅ Works | Used by usbscsid |
-| Interrupt | HID, hub status | ✅ Works | Used by usbhubd, usbhidd |
-| Isochronous | Audio, video | ❌ ENOSYS | `scheme.rs` explicitly returns `ENOSYS` |
-
-Isochronous transfers are required for USB audio devices, webcams, and streaming applications.
-The driver returns `ENOSYS` (function not implemented) for all isochronous endpoint requests.
-
-## Backwards Compatibility
-
-### Transaction Translator (TT) Handling — STUBBED
-
-USB 1.x Low Speed and Full Speed devices connected behind USB 2.0 High Speed hubs require a
-Transaction Translator (TT) to convert between USB 1.x and USB 2.0 protocols. The xHCI
-specification handles TT internally in the controller, but the driver must provide correct
-parent hub information in the Slot Context during device addressing.
-
-**Current state**: All TT-related fields are hardcoded:
-
-| Field | Value | Should Be | Location |
-|---|---|---|---|
-| `mtt` (Multi-TT) | `false` | Read from parent hub descriptor | mod.rs:1057 |
-| `ttt` (TT Think Time) | `0` | Encoded from parent hub descriptor | mod.rs:1114 |
-| `needs_parent_info` | `true` (forced) | Based on actual device speed topology | mod.rs:1070 |
-
-The TODOs at mod.rs:1066–1068 explicitly state the values need to be determined from actual
-device speed and hub topology. Without correct TT information:
-
- Low Speed devices (1.5 Mbps) behind USB 2.0 hubs may not enumerate correctly on real hardware
- Full Speed devices (12 Mbps) behind USB 2.0 hubs may fail during bulk transfers
- Multi-TT hubs with multiple LS/FS devices attached may have timing violations
-
-### USB 1.x Compatibility
-
- **Low Speed (1.5 Mbps)**: Speed detection works. Default control pipe size correct (8 bytes).
-  TT handling stubbed — may fail on real hardware behind HS hubs.
- **Full Speed (12 Mbps)**: Speed detection works. Default control pipe size correct (8 bytes).
-  Same TT limitation.
-
-### USB 2.0 Compatibility
-
- **High Speed (480 Mbps)**: Primary tested speed in QEMU. Bulk, Interrupt, Control all functional.
-  Max packet size 64 bytes correctly set.
-
-### USB 3.x Compatibility
-
- **SuperSpeed (5 Gbps)**: Protocol speed detection works. BOS descriptor fetching implemented.
-  Max packet size 512 bytes correctly set. SuperSpeed Companion Descriptor parsed.
- **SuperSpeedPlus (10–20 Gbps)**: Protocol speed detection works. SuperSpeedPlus Isochronous
-  Companion Descriptor parsed. No functional testing.
-
-### Speed-Specific Gaps
-
- No speed-specific timeout or retry tuning — all controller-level timeouts are 1-second hardcoded
- No burst transaction support for SuperSpeed bulk endpoints (burst field parsed but not used in
-  transfer scheduling)
- No streams support for USB 3.0 bulk endpoints (Stream ID capability parsed but not exercised)
-
-## Integrated USB Devices
-
-### Device Autospawn Flow
-
-```
-1. Device plugs in
-2. xhcid detects port status change
-3. xhcid resets port, enumerates device, reads config descriptor
-4. spawn_drivers() iterates interfaces:
-   - For each interface with alternate_setting == 0:
-     - Match class code (+ optional subclass) against drivers.toml
-     - If match: spawn daemon with $SCHEME, $PORT, $IF_NUM/$IF_PROTO
-5. Each spawned daemon opens its USB interface via xhcid_interface
-6. Daemon registers its own scheme or connects to existing schemes
-```
-
-### Driver Table (`drivers.toml`)
-
-```toml
-# Mass Storage — DISABLED (#TODO: causes XHCI errors)
-#[[drivers]]
-#name = "SCSI over USB"
-#class = 8; subclass = 6
-#command = ["usbscsid", "$SCHEME", "$PORT", "$IF_PROTO"]
-
-[[drivers]]
-name = "USB HUB";    class = 9;  subclass = -1
-command = ["usbhubd", "$SCHEME", "$PORT", "$IF_NUM"]
-
-[[drivers]]
-name = "USB HID";    class = 3;  subclass = -1
-command = ["usbhidd", "$SCHEME", "$PORT", "$IF_NUM"]
-```
-
-### Supported Device Paths
-
-| Device Class | Daemon | Scheme Path | Integration |
-|---|---|---|---|
-| **Hub** (class 9) | `usbhubd` | Manages child ports via xhci scheme | Triggers nested device enumeration |
-| **HID** (class 3) | `usbhidd` | Writes to `/scheme/input/producer` via inputd | Legacy display/input consumers read `/scheme/input` |
-| **Mass Storage** (class 8) | `usbscsid` | Registers `disk.usb-{scheme}+{port}-scsi` | Filesystems mount via scheme path |
-
-### HID Integration Detail
-
-```
-USB keyboard/mouse → xhcid → usbhidd → inputd (scheme:input) → display/input consumer
-                                                      ↑
-                                           /scheme/input/producer  (drivers write here)
-                                           /scheme/input/consumer  (display server reads here)
-                                           /scheme/input/handle/{name}  (per-device handles)
-```
-
- `usbhidd` implements boot protocol HID (keyboard, mouse, scroll, button)
- Events: `orbclient::KeyEvent` for keyboards, `orbclient::MouseEvent`/`ButtonEvent`/`ScrollEvent`
- The `inputd` multiplexer collects from all input producers (USB HID, PS/2 via `ps2d`, etc.)
-
-### Storage Integration Detail
-
-```
-USB flash drive → xhcid → usbscsid → DiskScheme → /scheme/disk.usb-usb+1-scsi
-                                                           ↓
-                                                   redoxfs/ext4d mount
-                                                           ↓
-                                                   /scheme/file/{mount-point}
-```
-
- `DiskScheme` from `driver-block` provides block I/O via scheme
- Partition table parsing via `partitionlib` (MBR + GPT)
- Partitions exposed as `0p0`, `0p1`, etc. under the disk scheme
-
-### Composite Device Handling
-
-Composite USB devices (e.g., keyboard+mouse combo, keyboard+trackpad) are partially supported:
-
- xhcid iterates **all interfaces** in the first configuration
- Each interface matching a `drivers.toml` entry spawns its own daemon process
- Alternate settings (`alternate_setting != 0`) are explicitly skipped
- No vendor/product ID matching — class code only
-
-**What works**: A keyboard+mouse combo with two HID interfaces will spawn two `usbhidd` processes,
-each handling one interface. Both produce input events through inputd.
-
-**What doesn't work**: Devices requiring alternate settings for full functionality. Devices needing
-vendor-specific drivers.
-
-### Unsupported Device Classes
-
-These USB device classes have no driver in Red Bear OS:
-
-| Class | Name | Use Case | Blocker |
-|---|---|---|---|
-| 0x01 | Audio | USB headsets, speakers | Isochronous transfers not implemented (ENOSYS) |
-| 0x0E | Video | Webcams | Isochronous transfers not implemented |
-| 0x02 | CDC/ACM | USB serial, modems | No driver written |
-| 0x0A | CDC-Data | USB networking | No driver written |
-| 0x0B | Chip Card | Smart card readers | No driver written |
-| 0x0D | Content Security | Conditional access | No driver written |
-| 0x0F | Personal Healthcare | Medical devices | No driver written |
-| 0x06 | Still Image | Cameras (PTP/MTP) | No driver written |
-| 0x07 | Printer | USB printers | No driver written |
-| 0x10 | Audio/Video | AV devices | Isochronous required |
-| 0x11 | Billboard | USB-C alternate mode | No driver written |
-| 0x12 | USB Type-C Bridge | USB-C muxes | No driver written |
-| 0xDC | Diagnostic | USB debug | No driver written |
-| 0xE0 | Wireless Controller | Bluetooth, Wi-Fi dongles | Separate (redbear-btusb) |
-| 0xEF | Miscellaneous | Firmware update, etc. | No driver written |
-| 0xFF | Vendor Specific | Custom devices | No driver written |
-
-## Implementation Priorities
-
-### Priority 1: Re-enable USB Mass Storage
-
-The most impactful single change. Requires diagnosing and fixing the "causes XHCI errors" issue.
-Likely causes:
-
-1. Bulk endpoint configuration in scheme.rs — endpoint type mismatch during configuration
-2. Transfer size handling — the 64KB limit may fragment BOT CBW/CSW sequences
-3. Missing stall recovery during initial BOT reset
-
-### Priority 2: Add READ(10)/WRITE(10)
-
-Implement 10-byte CDB variants with automatic fallback. Pattern already exists for READ CAPACITY.
-Required for device compatibility:
-
-```rust
-// Proposed fallback pattern (matching existing RC10→RC16 pattern):
-pub fn read(&mut self, lba: u64, buf: &mut [u8], protocol: &mut dyn Protocol) -> Result<()> {
-    if lba <= u32::MAX as u64 && buf.len() <= u32::MAX as usize {
-        // Try READ(10) first — wider device compatibility
-        let cmd = self.cmd_read10()?;
-        *cmd = cmds::Read10::new(lba as u32, ...);
-        ...
-    }
-    // Fall back to READ(16) for large addresses
-}
-```
-
-### Priority 3: Fix Transaction Translator Handling
-
-Replace hardcoded TT values with actual parent hub descriptor data. This is required for real
-hardware where LS/FS devices sit behind HS hubs.
-
-### Priority 4: Multi-LUN Support
-
-Iterate device LUNs and create separate disk scheme instances per LUN. Required for card readers
-and multi-slot adapters.
-
-### Priority 5: Isochronous Transfers
-
-Implement the Isoch TRB path in scheme.rs to enable USB audio and video device classes.
-
-### Priority 6: UAS Transport
-
-Add USB Attached SCSI protocol support for SuperSpeed storage devices. Higher throughput than BOT
-but requires stream ID support in the xHCI driver.
-
-## Summary
-
-USB mass storage exists in the codebase with a well-implemented BOT transport, proper SCSI command
-set (with gaps in READ/WRITE(10)), and functional block device integration — but it is **disabled**
-due to xHCI errors during device configuration. The most impactful work is diagnosing and fixing
-that issue, then adding READ(10)/WRITE(10) for wider device compatibility.
-
-Speed handling covers the full range from Low Speed (1.5 Mbps) to SuperSpeedPlus (20 Gbps) at the
-detection level, but TT handling is stubbed and isochronous transfers return ENOSYS. Backwards
-compatibility for USB 1.x devices behind USB 2.0 hubs requires TT fix work.
-
-Device integration supports hubs and HID via autospawn. Composite devices get all interfaces
-handled. No vendor/product matching exists. No audio, video, serial, or networking USB device
-classes have drivers.
@@ -0,0 +1,353 @@
+# Red Bear OS Wayland Implementation Plan
+
+**Version:** 1.0 (2026-04-19)
+**Status:** Canonical Wayland subsystem plan
+**Supersedes:** `docs/03-WAYLAND-ON-REDOX.md` as the active Wayland planning document
+
+## Purpose
+
+This is the single authoritative Red Bear Wayland subsystem plan.
+
+It replaces the planning role previously held by `docs/03-WAYLAND-ON-REDOX.md` and consolidates the
+current Wayland story into one document that answers four questions clearly:
+
+1. what in the Wayland stack actually builds,
+2. what has runtime proof,
+3. what still blocks a trustworthy compositor/session claim,
+4. and what work must happen next, in what order, to close those gaps.
+
+This plan is subordinate to the canonical desktop path in
+`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` and to the current build/runtime truth in
+`local/docs/DESKTOP-STACK-CURRENT-STATUS.md`, but it is the canonical subsystem plan for the
+Wayland layer beneath that desktop path.
+
+## Truth Statement
+
+Red Bear Wayland is **partially complete and still experimental**.
+
+What is true today:
+
+- the base package stack is substantially build-visible: `libwayland`, `wayland-protocols`, Mesa
+  EGL/GBM/GLES2, Qt Wayland, libinput, seatd, and KWin-related package surfaces all build in some
+  form,
+- the tracked Wayland validation profile, `redbear-wayland`, builds and boots in QEMU,
+- the bounded validation path reaches compositor early init, xkbcommon initialization, and Redox EGL
+  platform selection,
+- `qt6-wayland-smoke` is a real bounded client-side proof target,
+- but there is still **no complete Wayland compositor session**, **no runtime-trusted input/session
+  path**, and **no hardware-accelerated Wayland proof**.
+
+This means Wayland is no longer blocked mainly by package absence. It is blocked by the gap between
+**build-visible packaging** and **runtime-trusted compositor/session behavior**.
+
+## Scope
+
+This plan covers the Red Bear Wayland subsystem from protocol/runtime substrate up to a bounded
+working compositor session, and then its handoff into the KWin desktop path.
+
+In scope:
+
+- `libwayland`, `wayland-protocols`, protocol generation, and residual patch reduction,
+- the `redbear-wayland` validation profile,
+- compositor runtime validation,
+- evdevd / udev-shim / libinput / seatd integration as they affect Wayland,
+- Mesa/GBM/EGL software-path proof and the Wayland-facing graphics runtime,
+- KWin as the intended production Wayland compositor path,
+- local overlay ownership decisions for Wayland components and validation harnesses.
+
+Out of scope:
+
+- full KDE Plasma session assembly beyond its Wayland-facing dependencies,
+- hardware GPU render enablement strategy in detail (owned by the DRM plan),
+- Wi-Fi, Bluetooth, USB, and low-level controller work except where they directly block Wayland
+  runtime trust.
+
+## Authority Chain
+
+Use the doc set in this order:
+
+1. `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — top-level desktop sequencing authority
+2. `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` — current desktop/Wayland truth
+3. `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` — Wayland subsystem plan beneath the desktop path
+4. `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` — GPU/DRM execution detail
+5. `local/docs/QT6-PORT-STATUS.md` — Qt/KF6/KWin package-level build status
+
+The following are historical or reference-only after this plan:
+
+- `docs/05-KDE-PLASMA-ON-REDOX.md` — historical KDE rationale
+- older WIP compositor notes such as the `smallvil` path — historical bounded validation references
+
+## Evidence Model
+
+This plan uses the same strict evidence classes as the canonical desktop path:
+
+| Class | Meaning | Safe to say | Not safe to say |
+|---|---|---|---|
+| **builds** | package compiles and stages | “builds” | “works” |
+| **boots** | image reaches prompt or known runtime surface | “boots” | “desktop works” |
+| **enumerates** | scheme/device node appears and answers bounded queries | “enumerates” | “usable end to end” |
+| **usable** | bounded runtime path performs intended task | “usable for this path” | “broadly stable” |
+| **validated** | repeated proof on intended target class | “validated” | “complete everywhere” |
+| **experimental** | partial, scaffolded, or runtime-untrusted | “experimental” | “done” |
+
+Rules:
+
+- compile-only success is still only **builds**,
+- QEMU-only success stays QEMU-bounded,
+- a compositor that reaches early init but never completes a session is still **experimental**,
+- KWin and Plasma build success does not imply Wayland session viability.
+
+## Current State Assessment
+
+### Stable enough to rely on for planning
+
+| Area | Current state | Notes |
+|---|---|---|
+| `redbear-wayland` profile | builds, boots | bounded validation profile only |
+| `libwayland` | builds | still carries Redox-specific recipe/source rewriting and residual patching |
+| `wayland-protocols` | builds | protocol packaging is not the blocker |
+| Qt6 Wayland client path | builds, partial runtime | `qt6-wayland-smoke` is installed, runs in the bounded harness, and leaves runtime markers; visible in-compositor window proof is still open |
+| Mesa EGL + GBM + GLES2 | builds | software path via LLVMpipe proven in QEMU |
+| evdevd / udev-shim / firmware-loader / redox-drm | builds, boots, enumerate | runtime trust still bounded |
+| libinput | builds | udev disabled in recipe; runtime integration still open |
+| seatd | builds | runtime trust still open; lease path still unproven |
+| KWin reduced path | experimental build | honest reduced dependency path, but runtime/session proof missing |
+
+### What remains incomplete
+
+| Area | Current gap |
+|---|---|
+| Compositor runtime | no complete Wayland compositor session |
+| Input path | no end-to-end proof that evdevd → libinput → compositor is trustworthy |
+| Session path | no runtime-trusted seat/session proof for KWin path |
+| Hardware graphics | no hardware-accelerated Wayland proof |
+| KWin truthfulness | build is reduced and partially dependency-honest, but still not a runtime-ready session |
+| WIP ownership | upstream WIP recipes and local overlays are mixed; forward path is not always explicit |
+
+## Stability / Completeness Verdict
+
+### Stability
+
+Wayland is **not stable enough** for a broad support claim.
+
+Reason:
+
+- runtime proof is still limited to a bounded QEMU validation harness,
+- the compositor path reaches early init but not a complete session,
+- input/session integration is not yet runtime-trusted,
+- the intended production path (KWin) is still runtime-incomplete.
+
+### Completeness
+
+Wayland is **build-substantially-complete but runtime-incomplete**.
+
+The stack is no longer missing its main package layers. It is missing:
+
+- complete compositor runtime proof,
+- complete input/session integration proof,
+- hardware-path proof,
+- and a cleaner local ownership story for the forward path versus historical references.
+
+## Main Gaps and Blockers
+
+### G1. Runtime trust trails build success
+
+This is the biggest real blocker.
+
+Current examples:
+
+- `libwayland` builds, but runtime behavior is not yet trusted as a full compositor foundation,
+- libinput builds, but its runtime path through evdevd/udev-shim is still open,
+- seatd builds, but the compositor/session path still lacks runtime proof,
+- `redox-drm` enumerates and supports bounded display tooling, but Wayland compositor runtime is not
+  yet trusted on top of it.
+
+### G2. No complete compositor session
+
+The bounded validation compositor path is still an **early-init harness**, not a working session.
+
+Current proof stops at:
+
+- launch surface present,
+- xkbcommon init reached,
+- Redox EGL platform selected,
+- Qt smoke markers present.
+
+That is useful, but it is still not the same thing as:
+
+- a visible, durable Wayland session,
+- a client that connects and stays usable,
+- input routing proven through the compositor,
+- or a trustworthy handoff into KWin session work.
+
+### G3. KWin remains the intended path, but it is still runtime-incomplete
+
+KWin is the forward compositor direction, not smallvil or COSMIC.
+
+Current truth:
+
+- the recipe exists,
+- the reduced path is more honest than before,
+- but it still carries disabled features and incomplete runtime/session proof,
+- therefore it must not yet be described as a working compositor path.
+
+### G4. The input/session stack is build-visible but still operationally incomplete
+
+Key issues:
+
+- libinput is still built with udev disabled,
+- seatd runtime proof is still open,
+- compositor-side device discovery and hotplug behavior remain bounded or incomplete,
+- `seatd-redox` remains a live local TODO and not a closed runtime path.
+
+### G5. Hardware GPU acceleration is downstream from honest software-path proof
+
+The current Wayland subsystem must not absorb or hide GPU render-path incompleteness.
+
+Current truth:
+
+- software-path Mesa/GBM/EGL is the valid bounded proof path,
+- hardware acceleration remains blocked on shared GPU/DRM work outside the Wayland package layer,
+- therefore hardware claims must stay in the DRM plan, not be implied by Wayland package success.
+
+## Ownership and Forward Path
+
+### Red Bear-owned forward path
+
+The forward path is now:
+
+- `redbear-wayland` for bounded compositor/runtime validation,
+- `redbear-kde` for the intended KWin Wayland desktop direction,
+- local overlay ownership for validation harnesses and any shipping-critical Wayland recipe deltas.
+
+### Historical or non-forward references
+
+These should not be treated as the forward path:
+
+- `smallvil` — historical bounded validation compositor reference only,
+- the generic upstream WIP compositor set (`wlroots`, `sway`, `hyprland`, etc.) — useful inputs, not
+  trusted Red Bear shipping surfaces,
+- `docs/03-WAYLAND-ON-REDOX.md` — retired as a planning document.
+
+## Implementation Plan
+
+This plan keeps Wayland aligned with the canonical desktop path, but narrows the work specifically to
+Wayland subsystem needs.
+
+### Wave 1 — Runtime substrate closure for Wayland consumers
+
+**Goal:** turn the Wayland substrate from build-visible into runtime-trusted.
+
+**Must prove:**
+
+1. `libwayland` runtime behavior against the current relibc event/fd surfaces,
+2. evdevd → libinput → compositor-facing input viability,
+3. udev-shim enumeration sufficient for current Wayland-facing consumers,
+4. firmware-loader + `redox-drm` + bounded KMS/display evidence adequate for the validation path.
+
+**Acceptance criteria:**
+
+- bounded relibc/libwayland runtime smoke is repeatable,
+- bounded input path reaches compositor-facing consumers without hand-wavy assumptions,
+- bounded display path still passes the current runtime harness after the input/session wiring is
+  tightened,
+- no current claim depends on a package merely compiling.
+
+### Wave 2 — Complete the bounded compositor validation path
+
+**Goal:** convert the current early-init harness into a real bounded software compositor proof.
+
+**What success means:**
+
+- compositor runs for a bounded interval without crashing,
+- `WAYLAND_DISPLAY` is live,
+- a client connects and survives,
+- the current `qt6-wayland-smoke` path remains a visible bounded proof target,
+- input is proven through the active compositor surface, not just through lower-layer scheme checks.
+
+**Important rule:**
+
+This wave is still a **validation compositor** wave, not a claim that KWin or Plasma is working.
+
+### Wave 3 — KWin runtime truthfulness
+
+**Goal:** turn the current reduced KWin build into an honest runtime target.
+
+**Required work:**
+
+- keep dependency honesty explicit,
+- prove which remaining stubs/shims are still acceptable for bounded runtime work,
+- establish one bounded KWin session proof before any Plasma support claim,
+- keep disabled features and bounded providers visible in the support language.
+
+**Acceptance criteria:**
+
+- KWin starts as the compositor on the tracked path,
+- the runtime session survives for a bounded interval,
+- session/login1/D-Bus surfaces needed by KWin are observable,
+- support claims still remain profile-scoped and bounded.
+
+### Wave 4 — Ownership cleanup and stale-path retirement
+
+**Goal:** make the doc/recipe story match the real forward path.
+
+**Required work:**
+
+- retire old planning authority from historical Wayland docs,
+- demote or remove stale historical compositor references from the active guidance path,
+- make the WIP recipe guidance reflect current truth instead of older partial states,
+- keep local overlay ownership explicit wherever Red Bear is still the effective shipping owner.
+
+**Acceptance criteria:**
+
+- one canonical Wayland subsystem plan exists,
+- stale planning references are removed,
+- historical references are clearly marked historical,
+- no active doc suggests that smallvil or generic upstream WIP compositor recipes are the forward
+  Red Bear desktop path.
+
+## What This Plan Supersedes
+
+This plan supersedes the active planning role previously held by:
+
+- `docs/03-WAYLAND-ON-REDOX.md`
+
+It also reduces ambiguity in these adjacent surfaces:
+
+- `recipes/wip/AGENTS.md` Wayland status notes,
+- `docs/02-GAP-ANALYSIS.md` Wayland references,
+- current-status and canonical-plan references that still pointed to the old Wayland roadmap.
+
+## Docs To Keep vs. Retire
+
+### Keep
+
+- `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` — canonical Wayland subsystem plan
+- `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` — current truth summary
+- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — canonical desktop path
+- `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` — GPU/DRM execution detail
+- `local/docs/QT6-PORT-STATUS.md` — Qt/KF6/KWin package build status
+
+### Retire or demote
+
+- `docs/03-WAYLAND-ON-REDOX.md` — remove as an active planning document
+- stale WIP Wayland status text that still implies `smallvil` is current or that package build status
+  equals runtime viability
+
+## Definition of Done
+
+Wayland can be called substantially complete for the current subsystem scope only when all of the
+following are true:
+
+- the bounded Wayland runtime path completes a usable software compositor session,
+- runtime input/session/device-enumeration behavior is trusted enough to support that claim,
+- KWin has at least one honest bounded runtime proof path,
+- current docs describe the same truth with no stale forward-path confusion,
+- hardware acceleration remains either separately proven or explicitly outside the claim.
+
+## Current Bottom Line
+
+Red Bear Wayland is no longer blocked primarily by package absence. It is blocked by runtime trust,
+compositor completion, session/input integration, and honest ownership of the forward path.
+
+That is the real work. This plan makes that explicit.
@@ -278,6 +278,14 @@ The best Red Bear Wi-Fi path is **native-first**:
 - Narrow `linux-kpi` glue only where useful (93 tests, 17 modules)
 - Native `smolnetd` / `netcfg` / `dhcpd` reused after association

+Current bounded extraction progress:
+
+- `redbear-wifictl` transport probing now consumes the shared `redox-driver-sys` PCI parser
+  instead of relying only on ad hoc raw-config interpretation.
+- Transport status now reports quirk-aware interrupt support (`none` / `legacy` / `msi` / `msix`)
+  from the shared substrate, which is the intended convergence direction for future GPU/Wi-Fi-only
+  donor usage under `linux-kpi`.
+
 The codebase has 119 tests passing (93 linux-kpi + 8 redbear-iwlwifi + 18 redbear-wifictl), no production `unwrap()` in the Wi-Fi daemon request loop (startup uses `expect()`), atomic command
 handling, proper timer cancellation, honest timeout reporting, and real 802.11 frame parsing.
 The structural skeleton is solid. The next required step is **real hardware validation** with an
@@ -0,0 +1,360 @@
+# xhcid Device-Level Improvement Plan
+
+## Purpose
+
+This document defines the implementation sequence for hardening `xhcid` at the device level in
+Red Bear OS.
+
+It is a focused companion to `local/docs/USB-IMPLEMENTATION-PLAN.md`. The USB plan remains the
+subsystem-wide authority; this document narrows scope to the `xhcid` device lifecycle,
+configuration, teardown, PM behavior, enumerator robustness, and bounded proof coverage.
+
+## Scope
+
+In scope:
+
+- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/device_enumerator.rs`
+- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/mod.rs`
+- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/scheme.rs`
+- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/irq_reactor.rs`
+- bounded QEMU validation scripts under `local/scripts/`
+- canonical USB documentation under `local/docs/`
+
+Out of scope:
+
+- generic USB redesign
+- unrelated class-driver feature work
+- hardware-validation claims beyond what the repo can currently prove
+
+## Repo-Fit Note
+
+Technical implementation targets live in upstream-owned source under
+`recipes/core/base/source/...`, but durable Red Bear preservation belongs in
+`local/patches/base/`. This plan names the technical work locations, not a recommendation to leave
+ work stranded only in upstream-owned trees.
+
+## Current Audited Findings
+
+The current `xhcid` tree has already improved materially:
+
+- lifecycle gating exists through `PortLifecycle` and `PortOperationGuard`
+- `configure_endpoints_once()` is now transactional relative to earlier behavior
+- detach waits before removing published state
+- a bounded QEMU lifecycle proof exists
+
+Remaining risks:
+
+- partial attach visibility still exists around publication timing
+- detach can still depend on bounded-but-incomplete purge semantics
+- suspend/resume is still mainly software gating
+- rollback failure is not yet a fully hardened degraded-state path
+- enumerator logic still relies on timing- and assumption-heavy behavior
+- proof coverage is still QEMU-bounded and misses key interleavings
+
+## Design Invariants
+
+The implementation should satisfy these invariants:
+
+1. No half-attached device is publicly usable.
+2. No new work is admitted after detach begins.
+3. Detach always reaches a bounded terminal outcome.
+4. Failed configure leaves either the old config intact or the device explicitly
+   degraded/reset-required.
+5. PM transitions reflect actual usable state, not only software policy.
+6. Enumerator behavior is bounded and diagnosable, not panic-driven.
+7. Validation claims match what scripts actually prove.
+
+## Phase 1 — Proof-First Expansion
+
+### Goal
+
+Make the current blind spots reproducible before changing behavior.
+
+### Work
+
+- extend `test-xhci-device-lifecycle-qemu.sh`
+- extend `test-usb-qemu.sh`
+- extend `test-xhci-irq-qemu.sh`
+- add bounded injection hooks in `xhcid` for configure-failure and attach/detach timing cases
+
+### Required Cases
+
+- repeated attach/detach
+- detach during storage startup
+- transfer-during-detach surrogate
+- configure failure injection
+- suspend/resume admission checks
+- rapid event ordering cases
+
+### Per-File Focus
+
+#### `local/scripts/test-xhci-device-lifecycle-qemu.sh`
+
+- add repeated HID/storage attach-detach loops
+- add detach-during-driver-start for storage
+- add storage attach long enough to exercise startup/read activity before unplug
+- require explicit attach-entered, attach-finished, detach-completed evidence
+
+#### `local/scripts/test-usb-qemu.sh`
+
+- separate boot progress from proof failure
+- keep result lines distinct for xHCI init, HID spawn, SCSI spawn, bounded readback, and crash scan
+- add repeated full-stack run mode or bounded loop count if needed for ordering-sensitive regressions
+
+#### `local/scripts/test-xhci-irq-qemu.sh`
+
+- verify interrupt-mode evidence still holds under actual attached-device pressure, not only empty-controller boot
+
+#### `xhci` test hooks
+
+- add bounded test-only failure hooks in `scheme.rs` / `mod.rs` for:
+  - fail after `CONFIGURE_ENDPOINT`
+  - fail after `SET_CONFIGURATION`
+  - optional delay before final attach commit
+- current bounded implementation uses one-shot guest-side commands written to
+  `/tmp/xhcid-test-hook`, consumed by `xhcid` on the next matching lifecycle point
+
+### Exit Criteria
+
+- scripts are syntax-clean
+- new cases fail meaningfully on current gaps
+- failures identify the specific missed milestone
+
+## Phase 2 — Atomic Attach Publication
+
+### Goal
+
+Prevent half-built devices from becoming publicly reachable.
+
+### Work
+
+- refactor `Xhci::attach_device`
+- split attach staging from published `PortState`
+- narrow lifecycle exposure so scheme paths cannot reach a device before final commit
+- make attach cleanup direct for prepublication failure
+
+### Key Targets
+
+- `xhci/mod.rs::Xhci::attach_device`
+- `xhci/mod.rs::PortLifecycle::*`
+- `xhci/device_enumerator.rs::DeviceEnumerator::run`
+
+### Per-File Focus
+
+#### `xhci/mod.rs`
+
+- stop inserting into `port_states` before all attach substeps complete
+- keep slot, input context, EP0 ring, quirks, and descriptors in a private staging carrier
+- commit published `PortState` in one final block
+- keep prepublication cleanup separate from `detach_device()` where possible
+
+#### `xhci/device_enumerator.rs`
+
+- ensure duplicate connect handling still treats `EAGAIN` or equivalent as "already published" rather than "half-built staging state"
+
+### Exit Criteria
+
+- no public state before attach commit
+- attach failure leaves no published device and no child driver
+
+## Phase 3 — Bounded Detach and Purge
+
+### Goal
+
+Make teardown bounded, dominant, and safe against stale completions.
+
+### Work
+
+- bound `PortLifecycle::begin_detaching()`
+- reject all new work immediately once detach starts
+- purge or tombstone pending transfer/reactor state
+- separate graceful drain from forced teardown
+- preserve correct slot-disable/remove ordering
+- ensure child-driver shutdown cannot wedge detach
+
+### Key Targets
+
+- `xhci/mod.rs`
+- `xhci/irq_reactor.rs`
+- transfer bookkeeping in `xhci/scheme.rs`
+
+### Per-File Focus
+
+#### `xhci/mod.rs`
+
+- add timeout or bounded wait to detach drain logic
+- distinguish graceful drain from forced teardown
+- keep `port_states.remove(...)` after terminal teardown outcome
+
+#### `xhci/irq_reactor.rs`
+
+- add per-port invalidation or tombstone behavior so stale completions cannot target removed state
+
+#### `xhci/scheme.rs`
+
+- ensure operation-entry helpers fail immediately once detach starts
+
+### Exit Criteria
+
+- detach cannot hang forever
+- no stale completion can target removed device state
+- unload-under-activity proof passes
+
+## Phase 4 — Configure Rollback Hardening
+
+### Goal
+
+Make configuration changes fully transactional and recoverable.
+
+### Work
+
+- formalize stage/program/commit boundaries
+- ensure snapshots cover all mutated controller-facing state
+- promote rollback failure into explicit degraded-state handling
+- define deterministic behavior for post-`SET_CONFIGURATION` failure
+- keep alternate/config bookkeeping coherent after rollback
+- quarantine or reset on unrecoverable ambiguity
+
+### Key Targets
+
+- `xhci/scheme.rs::configure_endpoints_once`
+- `restore_configure_input_context`
+- `configure_endpoints`
+- `set_configuration`
+- `set_interface`
+
+### Per-File Focus
+
+#### `xhci/scheme.rs`
+
+- keep endpoint/ring state staged until commit
+- verify snapshots cover every mutated slot/endpoint field
+- treat rollback failure as a first-class degraded state
+- ensure post-failure descriptor and alternate bookkeeping still reflect live state
+
+### Exit Criteria
+
+- injected configure failure preserves old state or explicitly degrades/resets device
+- no staged endpoint state leaks into live software state
+
+## Phase 5 — Real PM Sequencing
+
+### Goal
+
+Replace software-only PM gating with meaningful quiesce/resume semantics.
+
+### Work
+
+- define richer PM transition states
+- quiesce before suspend
+- tie resume to controller/device validity
+- define PM interaction with detach
+- define PM interaction with configure
+- add bounded PM proof cases
+
+### Key Targets
+
+- `xhci/scheme.rs::suspend_device`
+- `xhci/scheme.rs::resume_device`
+- `xhci/scheme.rs::ensure_port_active`
+- supporting helpers in `xhci/mod.rs`
+
+### Exit Criteria
+
+- suspend blocks new I/O only after quiesce starts
+- resume only returns success from a genuinely usable state
+- PM/detach/configure interleavings are deterministic
+
+## Phase 6 — Enumerator Cleanup and Timing Hardening
+
+### Goal
+
+Remove panic-style and magic-delay behavior from the enumerator path.
+
+### Work
+
+- remove panic-class assumptions from `DeviceEnumerator::run`
+- replace fixed sleeps with bounded readiness checks
+- make duplicate/out-of-order event handling explicit
+- align enumerator decisions with the new attach/detach state machine
+- improve logging for reset/attach/detach milestones
+
+### Key Targets
+
+- `xhci/device_enumerator.rs`
+- supporting interactions in `xhci/mod.rs`
+
+### Exit Criteria
+
+- no ordinary event path panics
+- no unnecessary fixed sleep remains
+- rapid event-order tests pass in QEMU
+
+## Phase 7 — Final Validation, Docs, and Preservation
+
+### Goal
+
+Close the loop with evidence, canonical docs, and durable patch carriers.
+
+### Work
+
+- rerun the full bounded proof matrix on a rebuilt image
+- run source-level verification (`lsp_diagnostics`, `cargo check`, `cargo test`)
+- update canonical docs:
+  - `local/docs/USB-IMPLEMENTATION-PLAN.md`
+  - `local/docs/USB-VALIDATION-RUNBOOK.md`
+- refresh durable patch carriers under `local/patches/base/`
+- delete only clearly stale, superseded docs after link sweep
+
+### Exit Criteria
+
+- all bounded USB/xHCI proofs pass on a fresh image
+- changed files are diagnostics-clean
+- canonical docs match actual proof scope
+- patch carrier is refreshed and reapplicable
+
+## Validation Matrix
+
+Required final proofs:
+
+- `bash ./local/scripts/test-xhci-device-lifecycle-qemu.sh --check <tracked-target>`
+- `bash ./local/scripts/test-usb-qemu.sh --check <tracked-target>`
+- `bash ./local/scripts/test-xhci-irq-qemu.sh --check`
+- `bash ./local/scripts/test-usb-maturity-qemu.sh <tracked-target>`
+
+Required source checks:
+
+- `lsp_diagnostics` on all changed files
+- `cargo check` / `cargo test` for `xhcid`
+- `cargo check` for any touched class daemon or helper crate
+
+## Commit Strategy
+
+1. proof/harness expansion
+2. atomic attach publication
+3. bounded detach and purge
+4. configure rollback hardening
+5. PM sequencing
+6. enumerator cleanup
+7. docs, patch preservation, stale-doc cleanup
+
+## Canonical Doc Authority
+
+Authoritative docs after cleanup:
+
+- `local/docs/USB-IMPLEMENTATION-PLAN.md`
+- `local/docs/USB-VALIDATION-RUNBOOK.md`
+
+This xhcid plan is a focused implementation document beneath those subsystem-level authorities.
+
+## Completion Standard
+
+This work is complete only when:
+
+- all seven phases are done in order
+- no changed-file diagnostics remain
+- `xhcid` builds/tests cleanly
+- bounded QEMU proof matrix passes on a rebuilt image
+- canonical docs are synchronized
+- durable patch carrier is refreshed
+- remaining gaps, if any, are explicitly documented as future or hardware-only work