storm/cthulhu
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Wine/Proton stage contract and phase ledger

Browse Source 
Settled decisions, scope and done checklist in wine-proton.md; execution ledger with batch amendments, the satisfied Phase 0 gate and the accepted Phase 1 handoff in wine-proton-phases.md.
This commit is contained in:
hjozwiak committed 2026-11-01 23:28:24 -05:00
1 parent 71093286c7
commit a60a251472
2 files changed
+661
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/testing/wine-proton-phases.md
+412
View File
@@ -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-<unique-suffix>` and
`wine-<phase>-<unique-suffix>`, 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 <N> 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.
docs/testing/wine-proton.md
+249
View File
@@ -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 <name>` 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/<content hash>/` 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.