diff --git a/docs/testing/wine-proton-phases.md b/docs/testing/wine-proton-phases.md new file mode 100644 index 0000000..4eb3be7 --- /dev/null +++ b/docs/testing/wine-proton-phases.md @@ -0,0 +1,412 @@ +# Wine/Proton phase handoffs + +Status: Draft execution ledger. This document is operational, not +normative. The settled decisions, scope boundary, and done checklist +live in [wine-proton.md](wine-proton.md); if this handoff document and +that contract ever disagree, the contract wins and this document must +be corrected. + +Creating a branch or a session does not activate a phase. A phase +starts only when the maintainer explicitly activates it in that +phase's session. + +## Branch and session model + +- Keep each repository's `hunter` branch as the public integration + branch. Do implementation work only on the active phase branch. +- Merge a phase into `hunter` only after its tests and human review + pass and the maintainer says that step may land. Do not merge phase + branches directly into `testing`; `testing` receives the work only + through the maintainer's chosen later integration from `hunter`. +- Create one fresh Muse Code session per phase, just in time. Do not + fork phase sessions from the long planning session; a fork inherits + its history, while a fresh session can be briefed from the contract + and the relevant phase entry below. +- A lean coordinator session may track status and review handoffs, + but it should not be a second writer. Name live sessions stably, + for example `wine-master-` and + `wine--`, so they can be found again. +- A Muse session does not own a Git branch or checkout. If two + writing sessions are live at once, each needs its own worktree. If + work is strictly serial in one checkout, the active session must + verify the repository, branch, and working-tree state before it + edits anything. +- Local graph and patch artifacts are not phase deliverables. Leave + untracked `graphify-out/`, format-patch files, and other local + material untouched and unstaged unless the maintainer opens a + separate hygiene task for them. + +## Maintainer amendments for this batch (2026-11-01, master session) + +These rulings override conflicting text below and conflicting +repository synchronization procedure for this batch of work only. +Subordinate (phase) sessions must honor them: + +- Cross-repository work is permitted. A phase session may touch both + Cthulhu and wine-access as its scope requires; the two repositories + are not gated apart for this batch. +- Serial work in the single existing checkout of each repository is + the approved model, for coherent interactive validation and + testing. Separate worktrees are not required. The active session + must still verify repository, branch, and working-tree state + before editing. +- Synchronization is waived for this batch. Do not run + `git pull --ff-only`, `git fetch`, or merges of `origin/testing` + or `hunter`, and do not "refresh" a placeholder branch, whether + repository guidelines (`AGENTS.md`, `CONTRIBUTING.md`) or this + ledger's phase entries say to. Those instructions are to be + disregarded by subordinate sessions for this batch. Start from + the recorded branch tips; if a branch lacks a named prerequisite + commit, stop and report to the master session instead of fixing + it by merging. +- Pre-Phase-0 work is stacked under the Phase 0 commits: both + repositories' phase branches sit on their then-current `hunter` + tips, and later sessions pick that base up from the branch tips. + At the maintainer's direction the master session fast-forward + merged wine-access `wine/native-hook-exclusions` (`78b70e1`) into + `hunter` and stacked `wine/ready-and-spawn-evidence` on it. No + push was made. Cthulhu needed no merge: `hunter` and every + placeholder already share `6ed0e36`. +- The master/coordinator session may update this ledger once a + phase handoff report is accepted. + +## Known branch state when this ledger was created + +Recorded on 2026-11-01. Re-verify every value when a phase is +activated; this section is a snapshot, not a substitute for Git. + +### Cthulhu + +- `hunter`: `6ed0e36`, seven commits ahead of `origin/hunter` and + then equal to `origin/testing`. +- Placeholder branches, all also at `6ed0e36` when created: + `wine/ready-and-spawn-evidence`, `wine/live-settings`, + `wine/preferences-tab`, and `wine/verification`. +- The contract was an untracked working-tree file when the branches + were created, so it followed checkouts in this working tree rather + than belonging to any one branch's history. + +### Wine-access + +- `hunter`: `0db42de`, equal to `origin/hunter` when checked. +- `wine/native-hook-exclusions`: `78b70e1` + ("Add native per-program hook exclusions"), committed locally and + not yet landed on `hunter`. +- `wine/ready-and-spawn-evidence`: `0db42de`; it does not yet contain + `78b70e1`. + +Superseded for wine-access by the Phase 0 merges recorded in the +maintainer amendments above: `hunter`, +`wine/native-hook-exclusions`, and `wine/ready-and-spawn-evidence` +all stand at `78b70e1`, not pushed. + +## Phase activation checklist + +At the start of every phase session: + +1. Read the repository guidelines for each repository the phase will + touch, then read the contract decisions named in the phase entry. +2. Inspect `git status --short --branch` in each touched repository. + Preserve unrelated changes and untracked files; never make the + tree look clean by discarding, stashing, or hiding them. +3. Confirm the checked-out branch is exactly the branch named for + the phase. Stop if it is `hunter`, another phase branch, or a + different worktree than the session was briefed for. +4. Confirm the phase's base includes every prerequisite commit named + below. Per the maintainer amendments above, synchronization is + waived for this batch: do not pull, fetch, refresh, recreate, or + merge other branches to repair a stale base. If a prerequisite + commit is missing, stop and report to the master session. +5. Record the starting commit of each touched repository in the + phase's handoff notes before editing. +6. Work only inside the phase scope. Do not commit, merge, push, or + announce readiness to another maintainer unless the maintainer + explicitly asks for that exact act in that session. + +## Phase index + +| Phase | Purpose | Cthulhu branch | Wine-access branch | Status | +|---|---|---|---|---| +| 0 | Native exclusion foundation | none | `wine/native-hook-exclusions` | Fast-forward merged into wine-access `hunter`; not pushed | +| 1 | Ready record, spawn evidence, mixed-prefix spawn semantics | `wine/ready-and-spawn-evidence` | `wine/ready-and-spawn-evidence` | Accepted and merged into `hunter` in both repositories; not pushed | +| 2 | Live Wine settings | `wine/live-settings` | none | Not started | +| 3 | Wine preferences tab | `wine/preferences-tab` | none | Not started | +| 4 | Live verification and final results | `wine/verification` | Defect branch only for a proven helper cause | Not started | + +## Phase 0: native hook-exclusions foundation + +Status: committed locally on `wine/native-hook-exclusions` as +`78b70e1`. On 2026-11-01, at the maintainer's direction, the master +session fast-forward merged it into wine-access `hunter` and +fast-forward stacked `wine/ready-and-spawn-evidence` on the same +commit. Not pushed. + +Contents: the helper parses repeated `--exclude-hook-program` +arguments, withholds foreground native hooks from listed processes, +suppresses dialog reading for their windows, forwards the list to +the 32-bit hook host, and the then-current Orca extension emits the +flags. Native and manager regression tests and user documentation +were included. + +Gate into Phase 1: satisfied. `78b70e1` is now the tip of +wine-access `hunter`, `wine/native-hook-exclusions`, and +`wine/ready-and-spawn-evidence`, so the Phase 1 wine-access base +contains it. Do not begin Phase 1 wine-access work from a base that +lacks this commit; if a checkout shows otherwise, stop and report +to the master session (do not merge to repair it; synchronization +is waived for this batch). + +## Phase 1: ready record, spawn evidence, mixed-prefix semantics + +Status: not started. Contract decisions: 2, 5, 16, 17, 18, 24. + +Branches: `wine/ready-and-spawn-evidence` in both repositories, +after the Phase 0 gate above and after the Cthulhu branch has been +refreshed from the then-current `hunter`. + +In scope: + +- Wine-access helper only: add the `hook_exclusions` count to the + ready record, with targeted helper coverage. No Orca manager work. +- Cthulhu: recognize the plain exclusion-count startup line as info, + keep the invalid-exclusion line a warning, parse the ready count, + and include the mirrored `programs=[...] extra=[...]` text in the + helper-start record. +- Cthulhu: stop passing prefix-wide `--no-dialog-reader` merely + because a listed program is present. Other programs in the prefix + retain dialog reading while the listed program is gated natively. +- Cthulhu: retain wholesale mode only for the global + controller-only switch, the environment override, and a helper + whose ready record does not confirm the exclusions sent. Remember + an unconfirmed binary so later spawns do not double-start. +- Cthulhu: when a newly listed, currently discovered program lacks + its flag in the running helper, restart that helper once in the + same mode to deliver the flag. Never downgrade a running helper + when a listing is removed or the global switch is cleared. + +Out of scope: live-settings plumbing beyond what spawn decisions +already read, the preferences tab, any new D-Bus protocol surface, +and any Orca change or Orca acceptance gate. + +Required evidence before handoff: + +- Focused Cthulhu tests for diagnostics, spawn arguments, and the + mixed-prefix transition: launcher only, listed game appears, + ordinary program remains readable by construction of the launch + arguments and mode, listed game disappears without a downgrade. +- The wine-access helper build and CTest suite. +- Test suites for every other Cthulhu package actually touched. +- A maintainer-run live smoke check is useful here, but the stage's + formal live acceptance remains Phase 4. + +Stop boundary: report the diff and evidence. Do not proceed into +live settings or preferences work in the same session. + +### Accepted handoff (2026-11-01) + +- Session: `wine-1-corpsegrinder` (`fir-aphelion`, + 01a19a46-8ac2-7e80-b847-5a8574f85dd9); coordinated from the master + session (`still-enceladus`). +- Starting commits: Cthulhu `6ed0e36`; wine-access `78b70e1`. +- Committed after maintainer acceptance: Cthulhu `7109328` + ("Add Wine ready-record and mixed-prefix spawn semantics") on + `wine/ready-and-spawn-evidence`, 5 files under `internal/wine`, + +459/-55; wine-access `20d2169` ("Report hook exclusion count in + ready record") on `wine/ready-and-spawn-evidence`, 3 files, + +32/-1. This ledger and the contract ride a separate docs commit + on the Cthulhu phase branch. Both phase branches were then merged + into `hunter` in their repository at the maintainer's direction. + Not pushed. +- Automated evidence (phase session; `internal/wine` suite + independently re-run green by the master session): race-enabled + `go test ./internal/wine/` including mixed-prefix, + unconfirmed-helper, diagnostics, and start-record tests; + `go build ./...`, `go vet ./internal/wine/`, gofmt clean; + `go test ./internal/config/`; wine-access build and CTest 7/7. + One `internal/app` failure (`TestEchoSpeakerSwitchesBothVoicesTransactionally`) + was reproduced on clean HEAD under the sandbox (unix socket listen + not permitted) and is recorded as pre-existing environmental, not + a Phase 1 regression. +- Live evidence, by kind: installed-binary — maintainer-rebuilt + Cthulhu from the phase tree. Audible speech — maintainer smoke + check, 2026-11-01: with Diablo IV running under Proton (app + 2344520) and excluded, `protontricks-launch --appid 2344520 + notepad` spoke in the same prefix, and Diablo IV remained running + (interval not timed; formal normal-session and per-application + acceptance remain Phase 4). A first attempt the same evening was + invalid: it ran a stale pre-Phase-1 reader binary, whose helper + correctly showed the old wholesale `--no-dialog-reader` behavior. + Physical input beyond launching, and Braille-display evidence: + none this phase. +- Not exercised: full live regression corpus, Braille regression, + preferences round trip (all Phase 4); full `go test ./...`. +- Known limitation carried to Phase 2: decision 17's restart is + implemented and tested, but the governing list is still the + manager's startup snapshot until live settings land. +- Ready for maintainer review: yes. Accepted by the maintainer on + 2026-11-01 ("sufficiently satisfied"), who directed the commits + above and their merge into `hunter` in each repository. + +## Phase 2: live Wine settings + +Status: not started. Contract decisions: 3, 4, 16, 17, 19. + +Branch: `wine/live-settings` in Cthulhu only, refreshed from +`hunter` after Phase 1 has landed there. + +In scope: + +- Replace the Wine manager's startup snapshot with the reader's live + settings, read at poll and spawn, so Apply and equivalent reload + paths need no reader restart. +- Read the active/global profile's Wine values only. Per-application + profile switching must never change which Wine list governs a + prefix. +- Preserve decision 17's "at the moment it matters" restart for a + newly listed running program, and the absolute no-downgrade rule + for removals. +- Exercise the behavior through TOML/settings application before the + preferences tab exists. + +Out of scope: any preferences UI, any Orca work, and any helper +protocol change. + +Required evidence: focused tests proving that additions take effect +without a reader restart, removals do not downgrade a running +helper, and moving focus between applications with different +profiles cannot change the governing Wine list. + +Stop boundary: report the diff and evidence. Do not begin the +preferences tab in the same session. + +## Phase 3: Wine preferences tab + +Status: not started. Contract decisions: 6, 9, 13, 19. + +Branch: `wine/preferences-tab` in Cthulhu only, refreshed from +`hunter` after Phase 2 has landed there. + +In scope: + +- A global-preferences Wine tab modeled on the Pronunciation page: a + controller-only checkbox and an editable program list with New + and Delete. +- Entries are typed only. No running-program picker and no file + browser. +- Validate each entry as edited; name the offending entry and block + Apply for paths, blanks, and overlong names. Collapse + case-insensitive duplicates. Never silently drop an invalid entry. +- Preserve the repository's preferences accessibility rules, + including focus traversal, popup behavior where applicable, and + settings round-tripping through persistence and the runtime. + +Out of scope: per-application Wine editing, any helper or manager +behavior change, and any Orca work. + +Required evidence: automated preferences/persistence coverage and a +keyboard-only round trip in Phase 4—Tab and Shift+Tab through the +tab, edit the list, Apply, and confirm a newly started helper uses +the result with no reader restart. + +Stop boundary: report the diff and evidence. Do not begin the live +regression in the same session. + +## Phase 4: live verification and final results + +Status: not started. Contract decisions: 7, 8, 10, 11, 12, 14, 15, +24. + +Branch: `wine/verification` in Cthulhu, refreshed from `hunter` +after Phase 3 has landed there. Open a narrow wine-access defect +branch only if the regression proves a root cause there; do not +create one speculatively. + +Fixed live corpus: + +- Diablo IV: excluded, anti-tamper path; controller speech by ear + and a normal-length session. +- Mistworld: controller-endpoint sensitivity; no avoidable helper + restart while it is running. +- Wine Notepad: menus and plain edits, including the mixed-prefix + case while an excluded program is present and unaffected. +- Notepad++: Scintilla edits. +- Battle.net bootstrapper: the UIA path. + +Also required: + +- The full physical-Braille Wine regression—review cursor, window + titles, menus, and edits across the corpus—passing clean. Every + failure blocks, whenever it was introduced, and is fixed wherever + its root cause lies. There is no baseline carve-out and no escape + hatch. +- The keyboard-only preferences round trip from Phase 3. +- Per-application results written into the contract document, not + left only in a session transcript or terminal scrollback. +- Separate reporting of automated, installed-binary, + physical-input, audible-speech, and Braille-display evidence. A + log line never substitutes for the maintainer hearing or reading + the result. + +If a corpus application becomes unusable for reasons unrelated to +the reader, stop and have the maintainer choose and record its +replacement. Never silently shrink the corpus. + +Stop boundary: the stage is done only when every item in the +contract's done checklist passes. Marking the contract Final is a +separate maintainer act after those results are recorded. + +## Fresh-session startup template + +Adapt the phase number, branches, and decision list. Keep the rest +verbatim unless the maintainer directs otherwise in that session. + +```text +Implement only Phase from +docs/testing/wine-proton-phases.md. + +Before editing, read the repository guidelines for every repository +you will touch and the named decisions in +docs/testing/wine-proton.md. Verify the current directory, +repository, branch, starting commit, and working-tree state. Stop +and report if the checkout is not on the exact phase branch, if the +branch lacks a named prerequisite commit, or if unrelated changes +would be overwritten. Synchronization is waived for this batch: +do not run git pull or git fetch, and do not merge origin/testing, +hunter, or any other branch, even if repository guidelines say to. + +Work only within this phase's scope. Run the evidence named for the +phase. Stop at its boundary and report the diff, tests, blockers, +and anything not exercised. Do not commit, merge, push, switch to +another phase, or announce readiness unless I explicitly tell you +to in this session. +``` + +If the phase session runs in a separate worktree where this file is +absent, paste the relevant phase entry into its startup prompt or +point it at the copy in the coordinator's checkout. Do not assume +an untracked document followed it there. + +## Handoff report template + +Each phase session ends by filling this in, in chat and, once the +maintainer accepts the report, in the phase entry above: + +```text +Phase: +Session name: +Repositories and branches: +Starting commits: +Ending commits or diff state: +Files changed: +Behavior changed: +Tests and checks run, with results: +Live evidence, reported separately by kind: +Not exercised, and why: +Blockers or surprises: +Ready for maintainer review: yes/no +Merged into hunter: no, unless explicitly directed otherwise +``` + +Update statuses only from observed evidence. "Implemented," +"committed locally," "merged into hunter," "pushed," and "landed in +testing" are different states; never use one to imply another. diff --git a/docs/testing/wine-proton.md b/docs/testing/wine-proton.md new file mode 100644 index 0000000..ae8fe41 --- /dev/null +++ b/docs/testing/wine-proton.md @@ -0,0 +1,249 @@ +# Steam/Proton and controller-only verification + +Status: Draft. Settled decisions from the 2026-11-01 grilling session are +recorded here as they land; unresolved questions stay visibly marked. +Per decision 15, contract acceptance settles the decisions but keeps +this document Draft; it becomes Final only when the done checklist +passes and the per-application results are written in. + +Execution is split into separately reviewed phases: Phase 0, the +already-committed native-exclusion foundation; Phase 1, ready +record, spawn evidence, and mixed-prefix semantics; Phase 2, live +Wine settings; Phase 3, the Wine preferences tab; and Phase 4, live +verification and final results. Branch assignments, activation +rules, fresh-session startup text, and handoff reporting live in +[wine-proton-phases.md](wine-proton-phases.md). That ledger is +operational only; this contract remains normative if they differ. + +## Established facts (verified live, 2026-11-01) + +- Cthulhu sends one `--exclude-hook-program ` argument per entry in + the profile's `wine.excluded-hook-programs` setting, plus + `--no-dialog-reader` when a listed program (or the global + `wine.controller-only` setting) makes the prefix controller-only. +- The wine-access helper enforces exclusions itself: a listed program's + thread never receives the native menu/input hooks, and its windows get + no dialog reading, from the helper's first foreground poll. Controller + speech and review remain available. +- Diablo IV under Proton Hotfix (Steam app 2344520), with + `excluded-hook-programs = ['Diablo IV.exe']`: the running helper showed + `--exclude-hook-program diablo iv.exe --no-dialog-reader`, staged under + `~/.local/state/cthulhu/wine-access/helper//` for the + pressure-vessel session, and the game stayed up past the roughly + 100-second window in which full-mode sessions had crashed on + 2026-10-31. +- Two failure modes were proven the same evening: a missing TOML section + silently means full mode, and a stale helper that owns the Wine + session singleton defeats any newly launched helper regardless of + settings. + +## Settled decisions + +1. Scope of the next stage (2026-11-01): the manager trio (diagnostics + classification, spawn decision logging, live settings reload), a Wine + section in preferences, and this document. Nothing outside that set + is approved by this decision. (Widened once, by decision 5, to + include the ready-record field in the wine-access helper.) +2. Spawn logging mirrors Orca's text format: the helper-start record + carries `programs=[...] extra=[...]` with sorted program names and + the exact extra helper arguments, so both readers' logs read + identically and can be compared line for line. +3. Wine settings take effect as soon as preferences are finished (Apply), + with no reader restart. The manager reads the same live settings the + rest of the reader uses, at each poll and helper spawn, instead of + the one-time snapshot it takes at startup today. +4. A running helper keeps its current mode until its game exits. The + only mid-session change is the existing safety upgrade: if an edit + newly protects a running game, its helper restarts into the + protected mode. Removing a program or clearing the global switch + never downgrades a running helper. Rationale: helper restarts tear + down and recreate the NVDA controller endpoint, and some programs + (Mistworld is the known example) crash when that endpoint is pulled + out from under them. Restarts therefore happen only when protection + is being added, never as a side effect of unrelated edits. (For + the listed-program path, this restart is superseded by decision + 16; the no-downgrade rule stands.) +5. The helper's ready record gains a `hook_exclusions` count beside + `controls_enabled` and friends, and Cthulhu parses and logs it as a + field of the initialized record. The plain startup line stays (it is + emitted even when a helper exits early, for example against the + singleton), and Cthulhu recognizes it as info; the + invalid-exclusion line stays a warning. Older helpers without the + field report zero, which is accurate for them. This extends the + stage into the wine-access helper by explicit choice. +6. Preferences gain a Wine tab modeled on the Pronunciation page: a + "Controller-only mode for all Wine applications" checkbox and an + editable program list (tree view with New and Delete), with text + explaining that listed programs keep controller speech but lose + standard control reading. Entries are validated by the existing + settings rules at Apply. +7. Done includes physical Braille acceptance. The display is usable + again (paired over Bluetooth, so the missing charger no longer + blocks it), and the stage is not done until Wine output is checked + on the physical display alongside the speech checks. +8. The stage lands in reviewable steps, evidence first: diagnostics + and spawn logging, then live settings exercised through the TOML, + then the Wine preferences tab, then this document and the live + acceptance pass. The reader stays usable at every step, and no + intermediate step counts the stage as done. +9. The Wine tab validates entries as they are edited: a path, a blank, + or an overlong name is flagged by name in the tab and blocks Apply + until fixed or deleted. Case-insensitive duplicates collapse to a + single entry. Config validation remains the backstop; invalid + entries are never silently dropped, since a user who believes a + game is protected when nothing was saved for it is tonight's + failure repeated. +10. The Braille bar is a full Wine regression on the physical display: + review cursor, window titles, menus, and edits across several + applications, not a spot check of focus output alone. This widens + decision 7's "done" by explicit choice. +11. Every failure that regression finds blocks done, whenever the + defect was born. There is no baseline carve-out for pre-existing + failures: the stage ends with the full Wine Braille regression + passing clean, at whatever size that makes the stage. +12. No escape hatch. If a blocking Braille failure needs a redesign, + or its root cause sits in shared infrastructure rather than + Wine-specific code, it is still built inside this stage. The + stage's true size is accepted as unknown until the regression + passes clean. +13. Program names enter the Wine tab by typing only, as under Orca. + There is no running-program picker and no file browser in this + stage; a well-formed but wrong name remains possible, with the + mirrored spawn log as the after-the-fact evidence. +14. The live regression corpus is fixed by name: Diablo IV (excluded, + anti-tamper), Mistworld (controller-endpoint sensitivity), Wine + Notepad (menus and plain edits), Notepad++ (Scintilla edits), and + the Battle.net bootstrapper (UIA path). Results are recorded per + application in this document. If an application becomes unusable + for reasons unrelated to the reader, its replacement is decided + and recorded here, never silently dropped. +15. This document stays Draft through implementation and acceptance + testing. Contract acceptance settles the decisions above; the + document becomes Final only when the done checklist passes and + the per-application results are written in. +16. Exclusion is per program, enforced by the helper natively. A + listed program's presence in a prefix no longer flips the whole + helper to `--no-dialog-reader`: other programs in the same prefix + keep full hook and dialog reading while the listed one gets the + controller only. For avoidance of doubt, `--no-dialog-reader` + itself remains helper-wide for the whole prefix; a listed name + by itself must never cause Cthulhu to pass it. The global + controller-only switch still runs the whole helper with + `--no-dialog-reader`, and that wholesale mode is also the + fallback when a helper's ready record does not confirm it applied + the exclusions it was sent (for example an old helper that + ignores the flags). This supersedes the + upgrade-on-listed-appearance restart in decision 4 for the listed + path, and both readers change together; the wine-access side of + this stage therefore includes the Orca manager's spawn semantics, + not only the ready-record field. +17. A list addition reaches a running helper at the moment it + matters: if the newly listed program is discovered in a prefix + whose running helper lacks its flag, that helper restarts once in + the same mode, now carrying the flag. Additions for programs that + are not running wait for the next natural spawn. Restarts thus + happen only to add presently-needed protection, never for + prospective edits or housekeeping. +18. Both managers consume the helper's ready record at startup. If + its `hook_exclusions` count does not match the flags sent, that + helper restarts once in wholesale `--no-dialog-reader` mode, and + the manager remembers that binary as unconfirmed so later spawns + go wholesale directly. Go wires its existing diagnostics parser + into the manager; Orca reads the spawn's stderr through a bounded + forwarding path instead of only filing it. No new D-Bus protocol + surface is added for this. +19. The Wine exclusion list is global-only. The manager always reads + the active/global profile's Wine values and ignores + per-application profile switching for Wine. The Wine tab appears + only in global preferences. One list therefore governs every + prefix regardless of which application currently has focus. +20. Cthulhu and Orca keep independent Wine exclusion lists. There is + no one-time import and no live shared canonical list in this + stage. Each reader's list is maintained in its own settings + system. The maintainer plans to transition to Cthulhu full-time + relatively soon, so Cthulhu is the primary path going forward. +21. Orca is frozen as-is for this stage. The maintainer does not + intend to use Orca anymore after today, and Cthulhu is the sole + normative reader for the remaining Wine work. This supersedes + the parts of decisions 5, 16, and 18 that required both readers + to move together: no Orca manager per-program spawn semantics, + bounded Orca stderr reader, Orca test gate, or Orca relaunch + acceptance is required here. Existing Orca support stays as it + is; anyone who wants to carry it forward can do so later. The + wine-access helper ready-record field remains in scope because + Cthulhu consumes it. +22. Decision 21 is a stage-and-maintainer scope decision, not a + project-wide deprecation of Orca. This maintainer is not the + repository's sole maintainer, and the decision records only that + he will not use or carry the Orca path in this stage. It does not + preclude other maintainers from using, maintaining, or improving + Orca support. +23. No wine-access maintenance-status notice will be added for this + stage. The work is overwhelmingly Cthulhu-based; apart from any + root-cause Braille fix the regression may prove necessary, the + only planned wine-access code change is the helper ready-record + field that Cthulhu consumes. Decisions 21 and 22 do not change + Orca's project status, functionality, or availability to other + maintainers, so there is no work-relevant maintenance-status + change for wine-access documentation to announce. +24. Mixed-prefix operation remains mandatory. It is not merely a + Diablo hypothetical: the maintainer has real mixed-prefix uses, + and ordinary programs in a prefix must retain hooks and dialog + reading while a listed program in that same prefix receives only + controller support. The current silence from Wine Notepad while + Diablo IV is alive is therefore a defect against decision 16, + caused by Cthulhu adding the prefix-wide `--no-dialog-reader` + once the listed program is discovered. Removing that listed- + presence trigger is required; wholesale mode remains available + only for the global switch/environment override and the + unconfirmed-helper fallback in decision 18. +25. The scope contract below is accepted for now as the settled + stage boundary. On 2026-11-01, in this Muse Code session, the + maintainer said: "For now, I am satisfied." Per decision 15, + that acceptance does not finalize this document or authorize + implementation; it remains Draft until the done checklist passes + and the per-application results are written in. + +## Unresolved questions + +(none) + +## Scope contract (accepted; document remains Draft) + +Boundary. In Cthulhu: `internal/wine`, the Wine settings wiring in +`internal/app` and `internal/config`, a Wine page in +`internal/preferences` including `preferences.ui`, and this document. +In wine-access: the ready-record field in the helper only. For +this stage and this maintainer's work, the Orca integration is +frozen as-is under decisions 21 and 22; that is not a project-wide +Orca deprecation. No Orca manager changes, Orca test gate, or Orca +relaunch acceptance belongs to this stage. Fixes for blocking +Braille regression failures (decisions 11 and 12) may land wherever +their root cause lies, including shared Braille infrastructure. Out +of scope: staged-helper hardening parity for the Orca manager, +stale-helper retirement redesign, the `explorer.exe` classification +divergence, Nix helper candidates on the Go side, and landing either +repo's branches anywhere (commits and merges stay the maintainer's +separate acts). + +Done means, all of: + +- Cthulhu test suites pass for the touched packages, and the + wine-access helper CTest suite passes. Orca tests are not a gate. +- Diablo IV under Cthulhu: controller speech confirmed by ear, game + survives a normal session, and the start log shows the mirrored + `programs=[...] extra=[...]` record plus the exclusion count. +- An ordinary Wine application still reads standard controls in the + same setup, including inside an excluded game's own prefix while + the game is present and unaffected. +- Full Wine Braille regression on the physical display: review + cursor, window titles, menus, and edits across several + applications, passing clean with no unresolved failures regardless + of when a defect was introduced. +- Preferences round trip by keyboard: Tab and Shift+Tab through the + Wine tab, edit the list, Apply, and confirm a newly started helper + picks the change up with no reader restart. + +Nothing outside this checklist is a completion dependency. Accepting +this contract does not authorize implementation; that takes a separate +explicit request.