cthulhu/docs/testing/wine-proton-phases.md

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; 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	Accepted and merged into hunter; not pushed
3	Wine preferences tab	wine/preferences-tab	none	Accepted and merged into hunter; not pushed
4	Live verification and final results	wine/verification	Defect branch only for a proven helper cause	Closed by maintainer as accepted with known limitations, 2026-11-02; original checklist not fully satisfied; not pushed

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.

Accepted handoff (2026-11-01)

• Session: wine-2-jefferson (fallow-puppis, 01a19a90-0c47-71a3-931e-404257a1fefe); coordinated from the master session (still-enceladus).
• Starting commit: Cthulhu a60a251 on wine/live-settings. Wine-access untouched (Cthulhu-only phase).
• Committed after maintainer acceptance: Cthulhu 9a10a15 ("Read Wine settings live at poll and spawn"), 13 files, +327/-51, then merged into hunter at the maintainer's direction. This ledger update rides a separate docs commit on the phase branch. Not pushed.
• Behavior: the manager reads a live global-only Wine snapshot once per poll and uses it for that poll's restart/spawn decisions; global applies republish it (setGlobalSettings), per-application profile switching never does. Decision 17 restart-on-addition and the absolute no-downgrade rule are preserved and now live-driven.
• Automated evidence (phase session; internal/wine, internal/config, the focused app live-settings tests, go vet, and gofmt independently re-run green by the master session at landing): race-enabled wine suite including live-source transitions; TOML → config store → global apply test proving an addition governs the same manager with no reader restart and that application-profile switching cannot change the governing list; build and brlapi-tagged wine/config suites. One internal/app failure (TestEchoSpeakerSwitchesBothVoicesTransactionally, sandbox unix-socket restriction) reproduced on clean a60a251; recorded as pre-existing environmental, as in Phase 1.
• Live evidence, by kind: installed-binary — maintainer-rebuilt Cthulhu from the phase tree. Audible speech — maintainer smoke, 2026-11-01: baseline Wine Notepad read normally beside Diablo IV; after adding Notepad itself to the exclusions and reloading the reader, Notepad no longer spoke (expected native gating); after removing it and reopening, reading returned. An attempt to edit the settings file externally while the reader stayed alive did not take effect; this was investigated and recorded as a methodological note, not a defect: neither Go nor legacy Python Cthulhu has ever auto-reloaded the main settings file on external edit (legacy reloads on explicit triggers such as preferences Apply/loadUserSettings), and decision 3's live trigger is preferences Apply, whose Wine values arrive with the Phase 3 tab. Physical input beyond launching, and Braille-display evidence: none this phase.
• Not exercised: a user-accessible no-restart Wine addition (no Wine control exists until Phase 3; the backend chain is covered by the applyNext-level test), full go test ./..., the Phase 4 live corpus and Braille regression.
• Ready for maintainer review: yes. Accepted by the maintainer on 2026-11-01 ("a good state for phase two") after the external-edit question was settled as above.

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.

Accepted handoff (2026-11-01)

• Session: wine-3-growler (vivid-antlia, 01a19aed-ae17-7ea0-8e69-0a430cf8c4ab); coordinated from the master session (still-enceladus).
• Starting commit: Cthulhu dc6a961 on wine/preferences-tab. Wine-access untouched (Cthulhu-only phase).
• Committed after maintainer acceptance: Cthulhu 75f34ea ("Add global Wine preferences tab"), 15 files, +543/-5, then merged into hunter at the maintainer's direction. This ledger update rides a separate docs commit on the phase branch. Not pushed.
• Automated evidence (phase session; preferences/config/wine suites, the focused global-apply app test, go vet, gofmt, and the harness compile independently re-run green by the master session at landing): Values round-trip and ownership, duplicate collapse, invalid entries rejected by name with prior settings intact, global Apply governing the same manager and persisting through TOML, app-scoped Apply unable to change governing/global/ app-profile Wine, build. Full internal/app shows only the pre-existing sandbox socket failure recorded in Phases 1-2 (not re-verified on a clean tree this session).
• Not exercised by the phase session: the native preferences harness could not run in its environment (Xvfb/session failures reproduced identically with the pre-Phase-3 binary, so no Phase 3 signal); the added CTHULHU_PREFS_WINE_ONLY mode is unverified. Keyboard-only round trip remains Phase 4.
• Live evidence, by kind: installed-binary — maintainer-rebuilt Cthulhu from the phase tree. Audible speech / physical input — maintainer flesh test, 2026-11-01, Diablo IV kept alive in the same prefix throughout: baseline Notepad reading; adding notepad.exe in the Wine tab and Applying (no reader restart) took effect — save/close dialog no longer spoke, a freshly launched Notepad did not read, and Diablo IV survived the addition-triggered helper restart. Removing the entry did not restore reading while Diablo kept the prefix/helper alive, which is the decision 4/17 no-downgrade rule, not a failure. Braille-display evidence: none this phase.
• Recorded caveat, carried to Phase 4 (not a Phase 3 defect): in the same live test, the already-running Notepad instance's edit text remained readable long after Apply, including after focus excursions into Diablo's menus. Master-session code inspection confirmed the mechanism: the helper's edit subclass is installed in the target process on first focus SetWindowSubclass in wine-access edit_hook.c, module pinned until the control is destroyed, so it survives the helper restart; it finds the new helper's bridge dynamically by window class, and the new helper's text-event presentation in main.cpp does not check the exclusion list, while dialog WinEvents and new foreground hooks are correctly gated. Fresh instances are fully gated. Classified as a Phase 0/1 dynamic-addition gap: exclusion is enforced at foreground-hook install and dialog presentation, but not against a pre-attached edit subclass. Note also that the subclass DLL remains mapped in the already-running process until it exits, so event gating alone cannot make an already-running anti-tamper program retroactively clean; listing before launch remains fully protected. Phase 4 must decide the remedy (at minimum, presentation-side gating of stale-subclass text events in the replacement helper, with a regression: editor focused, then listed, helper restarted, focus away and back) and record the outcome; Wine review remaining available for listed programs is accepted behavior and is not this caveat.
• Ready for maintainer review: yes. Accepted by the maintainer on 2026-11-01 with the caveats above recorded ("record these and move on").

Phase 4: live verification and final results

Status: closed by the maintainer on 2026-11-02 as accepted with known limitations, following the interim pause recorded below. The original exhaustive done checklist was not fully satisfied, and the contract is not Final. Contract decisions: 7, 8, 10, 11, 12, 14, 15, 24, subject to the maintainer closure amendment in the contract.

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.

Known starting item (recorded at Phase 3 acceptance): the pre-attached edit-subclass caveat in the Phase 3 accepted handoff above. Its root cause is already localized to wine-access (edit_hook.c subclass persistence plus ungated text-event presentation in main.cpp).

Session-model amendment, 2026-11-01: the maintainer elected to conduct Phase 4 in the master/coordinator session (still-enceladus) rather than a fresh phase session. The maintainer runs the live corpus and reports results; the master session records them in the contract and runs automated checks. No implementation is planned in this phase; if a regression needs code, a fresh narrow defect session is spawned on the relevant branch at that point, and the master session remains coordinator/recorder rather than implementer.

Maintainer disposition, 2026-11-01: deferred; do not fix in Phase 4 and do not open a wine-access defect branch for it. Rationale: tearing down helper/subclass state early risks disturbing programs that rely on the live helper's controller and review services; fresh processes are fully gated, and restarting the prefix restores the expected state. The surprise for an unsuspecting user who lists an already-running editor is acknowledged and must be recorded honestly in the Phase 4 results, not silently treated as passing. Future work item, outside this stage unless the maintainer reopens it: teach wine-access dynamic add/remove of hook exclusions inside the running helper—updating foreground gating and silencing or detaching pre-attached edit subclasses—rather than relying only on helper restart plus fresh-process semantics.

Interim results recorded through the 2026-11-02 pause (detail and evidence in the contract's Phase 4 results section, currently through d6a54fc plus this freeze record):

• Automated baseline: full Cthulhu suite passes unsandboxed; vet, parity, and brlapi-tagged suites pass. Wine-access CTest is display-environment sensitive (review-capture versus foreground-focus invert between the live desktop and bare Xvfb); a single-environment 7/7 run has not been established on this Wayland system and may need a purpose-built private compositor/XWayland harness rather than an idle live desktop.
• Passed so far live: Diablo IV, Mistworld, Wine Notepad mixed-prefix, keyboard-only preferences round trip, preliminary Braille movement/edit navigation, and basic Notepad++ navigation/editing/Braille tracking.
• Open at the pause and then superseded as closure gates by the maintainer's later accepted-with-limitations decision: the localized Wine window-title failure (no fix session or defect branch started); Battle.net login not reading, with investigation deferred by the maintainer; and completion of the physical-Braille pass, including menus. These remain real unfinished items, not passes. Cut, undo, menu return, copious Unicode, read-only mode, and a very long line in Notepad++ were not separately reported and are not claimed.
• The maintainer's debug log used to localize the title failure remains a local, uncommitted diagnostic file in the Cthulhu checkout; preserve it.

Interim Phase 4 documentation/results commits are fast-forwarded into hunter at this pause so other folks review the same state. That fast-forward is not Phase 4 acceptance. Nothing is pushed; pushing and marking the contract Final remain separate maintainer acts.

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.

Closure record, 2026-11-02: the maintainer superseded that stop boundary for this stage and closed it as accepted with known limitations, judging the original planning more expansive and pessimistic than the core objective requires. The delivered implementation and basic live behavior are accepted as working well enough. Unfinished verification and known failures remain visible in the contract and ledger as future work; they were not converted into passes. The contract was not marked Final, Phase 4 was not represented as conventionally complete, and nothing was pushed by the master session.

Fresh-session startup template

Adapt the phase number, branches, and decision list. Keep the rest verbatim unless the maintainer directs otherwise in that session.

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:

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.