Alpha 5: native macOS host and native BGFX client — scope and tracking

[bobtista]

Proposal

Alpha 5 delivers first-class macOS support and launches the community's native BGFX Zero Hour client against the user's retail data — no Wine. It lands the four-phase feat/macos-host → feat/native-launch stack plus the hardening items from its external review.

Notarization (#322) is not being pursued. It requires a Developer ID certificate,
which requires a paid Apple Developer Program membership, and that is not being
purchased. #354 fixes the half that needed no certificate: GenHub clears
com.apple.quarantine from the game executables it materializes, so the propagation
failure — GenHub opens, the game silently will not launch — no longer happens. What
remains is one documented step for the app bundle itself
(xattr -dr com.apple.quarantine /Applications/GenHub.app).

macOS is therefore installable with one manual step, not distributable in the
Gatekeeper sense. The signing pipeline is built and verified under an ad-hoc identity
on feat/macos-signing-notarization, unmerged, ready if that decision changes.

Scope

Definition of done: the three PRs land and #354 lands — at that point macOS is
installable with the one documented step. Notarization is explicitly out of scope; see
#322. Priority order; "PR" is which stack PR
closes it (see The mac stack below).

#	Issue	Closed by
1	#314 — Reject multi-variant manifests at ingestion	PR A
2	#315 — Validate retail archive roots before launch	PR C
3	#316 — Materialize workspace executables atomically	PR A
4	#317 — Remove DYLD_LIBRARY_PATH / LD_LIBRARY_PATH	PR C
5	#318 — Fix stderr capture EOF race	PR C
6	#319 — macOS detector must distinguish TCC denial from "none found"	PR B
7	#320 — ValidateScopes shrink-only ratchet	own PR
8	#322 — signing and notarization	dropped — needs a Developer ID; #354 covers the usable-unsigned path
9	#323 — Launch receipt + cheap revalidation	own PR
10	#324 — Engine-only launch smoke on macos-15 CI	own PR
11	#325 — Magic-byte executable classification	own PR
12	#330 — Detect installations by archive presence, not executable name	own PR
13	#333 — Zero Hour can launch with no base Generals content	blocked on engine
14	#334 — Post-spawn archive-failure detection: 500 ms window, unused [ggc] sentinel	own PR

Current status — updated 2026-08-03

The three stack PRs have all landed. PR A merged as #328, PR B as #329 (plus
#331 for the service registrations it needed), and PR C as #332. The remaining
definition-of-done item is #322 notarization.

State	Issues
Closed	#314, #315, #316, #317, #318, #319, #320, #325
PR open	#323 (#341), #334 (#340)
PR pending	#324, #330 — branches rebased onto development, PRs to follow
Not started	#322 — no branch; the blocker for public macOS distribution
Blocked	#333 — needs an engine-side signal, see below

#315, #317 and #318 shipped inside #332 exactly as the note below predicts, and
#316, #320 and #325 shipped as #338, #337 and #339. None auto-closed, so all six
were closed manually on 2026-08-03 with the merged PR and file evidence recorded on
each issue.

#333 is the one item no amount of GenHub work can close. The engine skips the
base-Generals load silently in release builds — DEBUG_ASSERTCRASH is debug-only,
and the in-tree @todo says it ought to be a release crash. GenHub cannot detect
the case from the filesystem: a Zero Hour workspace always contains *.big, so a
workspace archive check would always pass and guarantee nothing. It needs either the
engine to make the empty-installPath case observable, or a mount-count signal
GenHub can act on. Until one exists, #333 stays open regardless of milestone
progress.

#314–#319 are review findings on code that has not shipped. Their fixes are
folded into the owning branch before the PR opens, so each will close without a
visible "fixes #NNN" diff — the code reads as originally written. Each issue
carries a comment saying which PR closes it. They are kept as issues rather than PR
checklist items because they describe user-visible behaviour worth finding later.

Moved out of this milestone:

• Migrate .Files consumers to the resolved-variant model (ResolvedArtifact) #321 (.Files → ResolvedArtifact) → 7. Content Pipeline & Distribution.
  A large migration across deliverers, validators, CAS refcounting and GC. Adjacent
  to Alpha 5 — the mac stack introduces manifest variants and Reject multi-variant manifests at ingestion until .Files consumers are migrated #314 gates them — but
  not required to ship native macOS, and big enough to dominate the milestone.
  Reject multi-variant manifests at ingestion until .Files consumers are migrated #314's fail-closed gate must stay until Migrate .Files consumers to the resolved-variant model (ResolvedArtifact) #321 lands.
• Pin GitHub Actions to commit SHAs repo-wide #326 (pin Actions to SHAs) → 6. Security & Integrity Validation. Repo-wide
  supply-chain hygiene, explicitly low priority, unrelated to macOS.

Dependencies worth knowing

• Reject multi-variant manifests at ingestion until .Files consumers are migrated #314 is a stopgap for Migrate .Files consumers to the resolved-variant model (ResolvedArtifact) #321. Until the .Files → ResolvedArtifact migration lands, the ingestion gate is the only protection against a variant manifest corrupting CAS refcounting and GC. Reject multi-variant manifests at ingestion until .Files consumers are migrated #314 must land before any provider can publish a Variants manifest.
• Validate retail archive roots before launch #315 and Add engine-only launch smoke test on macos-15 CI (needs no retail data) #324 exploit the same engine property. With no readable content the engine aborts during initialisation with a generic exit 1 (see the premise correction at the bottom of this issue — an earlier revision of this bullet claimed the opposite). That is why pre-spawn validation gives a better diagnostic than the crash (Validate retail archive roots before launch #315), and why a CI smoke test needs no retail data: it asserts the documented failure path (Add engine-only launch smoke test on macos-15 CI (needs no retail data) #324).
• Remove DYLD_LIBRARY_PATH and LD_LIBRARY_PATH from native launch #317 becomes load-bearing at Playwright exclusion, inside-out signing and notarization (blocker for public macOS builds) #322. Hardened-runtime signing ignores DYLD_LIBRARY_PATH, so behaviour would change silently at notarization time if the variable is still in use.
• Materialize workspace executables atomically; current sequence can permanently brick a workspace #316 is a data-loss bug, not a tidiness one. The post-move, pre-chmod window permanently bricks a workspace, because verification never mutates.

The mac stack

Restructured from four sequential PRs into two independent PRs plus one dependent
one, and rebased onto development @ 8e07339. All three have since merged.

PR	Branch	Commits	Base	Merged as
A	feat/cross-platform-fixes	7	development	#328
B	feat/macos-host	4	development	#329, plus #331
C	feat/native-launch	16 (B + A + 4 + wiring)	A and B	#332

A and B were reviewed in parallel as intended, and C followed them.

Why this beats the original four-deep chain

The original plan chained macos-host → platform-neutral-model →
unix-filesystem → native-launch. Measured against this repo's rules, that chain
is expensive: squash-merging a parent orphans its child (it keeps the parent's
unsquashed commits and goes CONFLICTING, needing a manual retarget and rebase),
and dismiss_stale_reviews_on_push: true means every such rebase drops the
approvals. A four-deep stack pays that three times. We hit exactly this with
#305/#309 during the Alpha 4 blockers.

The two middle phases fix real Linux and Windows bugs — silent hard-link copy,
Windows paths on Linux, updater installing the wrong platform, symlink reachability
— and are not macOS work. Checking the actual coupling: of 43 files they touch,
only two tie them to the macOS layer, and the types they introduce
(MacOSGamePathProvider, UnixFileOperationsService, UnixSymlinkCapabilityProvider)
all live in the shared project, not GenHub.MacOS. The only genuinely
macOS-dependent parts are three DI registration lines plus two entries in a shared
test-assertion helper that the macOS branch creates.

Those five lines moved into a single wiring commit at the head of C, which is the
first point where both the types and the module exist. That makes A fully
standalone: 7 commits, zero GenHub.MacOS files, 1384 tests green directly on
development. C's tree is byte-identical to the original four-deep stack, so
nothing was lost or gained — 1395 tests green.

The practical win: the cross-platform bug fixes stop being hostage to macOS review,
and two of the three PRs can be reviewed at the same time.

Landing notes

1. The stack must be rebased once more after chore: alpha 4 release #229 merges. main requires
   linear history, so chore: alpha 4 release #229 lands as a squash or rebase — both mint new SHAs, and
   8e07339 will not be an ancestor of main. The rebase already done resolved
   both collisions against current code, so the second pass should be mechanical.

   Two collisions were found and are already resolved in the branches:

   • SharedViewModelModule / IGitHubTokenStorage (fix(linux): resolve optional token storage at startup #301) — anticipated, and
     trivial: sp.GetService<IGitHubTokenStorage>() is byte-identical on both
     sides, since fix(linux): resolve optional token storage at startup #301 made the same fix. Only the stack's explanatory comment
     conflicted; it was kept, as fix(linux): resolve optional token storage at startup #301's version has none.
   • ManifestDiscoveryService constructor (fix(manifest): use JSON file pattern during discovery #305/fix(manifest): continue past unavailable directories #309) — not anticipated, and
     the dangerous one. The stack adds IConfigurationProviderService to the
     constructor; fix(manifest): use JSON file pattern during discovery #305/fix(manifest): continue past unavailable directories #309 added filesystem test seams to the same constructor.
     Git auto-merges the production file with no conflict and produces code
     that does not compile (CS1729) — only the test file conflicts, so a
     mechanical resolution looks clean and then fails to build. Resolved by
     collapsing the two constructors into one with the seams as optional
     parameters, so any future dependency causes a compile error at every call
     site instead of a silent broken chain.

2. Fold the review fixes into the owning branch before opening PRs
   (Reject multi-variant manifests at ingestion until .Files consumers are migrated #314–macOS installation detector must distinguish TCC denial from no installations found #319 map to PRs as noted in the priority table above).

3. Open A and B together; open C after both land.

Say in A's description that it fixes Linux and Windows bugs and stands on its own
merits — it is not macOS-only work.

Engine-repo track

Tracked separately in the engine repository (bobtista/GeneralsGameCode, topic/trunk, upstream TheSuperHackers):

• CNC_ZH_USERDATAPATH for per-profile Options.ini
• Normalize install-path roots in GlobalData.cpp to always append the separator
• Machine-readable failure (exit code or sentinel log line) when required archives fail to mount

The third is the engine-side half of #315 and would simplify every GenHub-side mitigation.

Status

Alpha 5 opens once Alpha 4 ships. Alpha 4 readiness is tracked in #307.

The stack, as it actually landed

PR	Scope	State
#328	A — cross-platform paths, manifests, Unix workspaces	merged
#329	B — macOS host, installation detection, CI	merged
#331	macOS service registrations	merged
#332	C — native BGFX launch against retail archives	open, approved

#331 was not planned. #328 made IGamePathProvider a required dependency and #329
added the macOS DI module, but the macOS registrations reference types from the first and a
module from the second, so they could only compile once both were in. Each PR was green in
isolation and the merged state was not: GenHub.app aborted at container build and
development went red. #331 repaired it and now runs GenHub.Tests.MacOS before publish,
where the assertion had existed but sat after the smoke test and never executed.

The lesson for the remaining independent PRs: two green branches can merge into a broken
state, and no per-branch CI can see it.

Why #314, #316 and #319 are still open

Their fixes are merged — #328 carries #314 and #316, #329 carries #319 — and the Fixes
links are recorded. GitHub only auto-closes on merge to the default branch, and these
merged into development, so they will close when development reaches main at release.
They are done, not forgotten.

#332 will close #315, #317 and #318 on the same terms.

Scope added after this issue was written

• Detect retail installations by archive presence, not executable name #330 — detection-side complement to Validate retail archive roots before launch #315. Both turn on sentinel .big existence and
  should share constants; feat(launching): launch the native BGFX client against retail archives #332 introduced RetailArchiveConstants.ArchiveSearchPattern for
  exactly that. It defers the *.exe glob to Classify executables by magic bytes instead of the extensionless heuristic #325 rather than adding a second heuristic, so
  it depends on Classify executables by magic bytes instead of the extensionless heuristic #325 landing first for that part.
• Zero Hour can still launch with no base Generals content when no Generals root is declared #333 — the one archive failure neither GenHub nor the engine reports. Blocked on the
  engine: an empty Generals path skips the base load silently in release, guarded only by a
  debug assert carrying a @todo that says it should be a release crash.
• Detect engine archive failures after spawn: 500 ms window and unused [ggc] stderr sentinel #334 — GenHub's own half. The engine does report the other failures (exit 1 on both
  upstream and fork; the [ggc] ARCHIVE MOUNT FAILED stderr sentinel is fork-only, absent
  upstream on every platform), and GenHub ignores both: its immediate-exit check is a 500 ms
  window and nothing matches the sentinel it already captures.

A premise correction worth recording. #315, #324 and this issue were written on the
belief that the engine reaches its main loop with zero content and reports nothing. Verified
against bobtista/GeneralsGameCode at bobtista/topic/trunk, that is false — a bad root
aborts during initialisation with exit 1 and a ReleaseCrashInfo.txt, and an unmountable
archive also writes to stderr. Neither reaches the main loop. #324's rationale should be
re-read in that light: it is still worth doing, but as an assertion on exit code and
sentinel rather than on the process merely staying alive.

[coderabbitai]

Coding Plan

Summary

• Organize the work along the ticket's four-PR mac stack (detection → manifest model → filesystem → native launch) plus a foundational rebase/DI-validation phase and a final macOS distribution/CI phase.
• Land #314 as a fail-fast ingestion gate to protect CAS refcounting/GC, then durably fix it by migrating .Files consumers to a new provenance-aware ResolvedArtifact.
• Close the #316 data-loss window with a write-temp → verify → chmod → atomic-rename sequence and add magic-byte executable classification, while keeping verification strictly non-mutating.
• Harden native launch (retail-root validation, env-var stripping, stderr drain, persisted launch receipt) and unblock public macOS distribution via Playwright exclusion, Velopack inside-out signing/notarization, a macos-15 engine smoke test, and SHA-pinned actions.

Design Choices

Design Choice 1: Meaning of issue `#320`'s "ValidateScopes shrink-only ratchet"

Options Considered:

1. .NET DI ServiceProviderOptions.ValidateScopes/ValidateOnBuild enabled at every BuildServiceProvider() call site, enforced by a composition test that iterates every ServiceDescriptor and only ever tightens (never loosens) validation.
2. A new narrowing invariant around ContentInstallTarget scopes (install targets may only shrink, never broaden).

Chosen Option: 1

Rationale: The strings ValidateScopes/ValidateOnBuild/ratchet do not exist in the repo today, but the #301 collision note explicitly mentions folding in ValidateOnBuild and forced factory-VM construction assertions. The ticket's own #301 collision language (ValidateOnBuild, "forced factory-VM construction iterating every ServiceDescriptor") clearly points to DI-container scope/build validation, not install-target semantics.

Design Choice 2: Intended shape of the `#314` "reject multi-variant manifests" gate given the schema has no `Variants` field today

Options Considered:

1. Add a validation gate that rejects any single manifest whose Files mix content for multiple targets/variants (detected via conflicting install targets, duplicate relative paths with differing hashes, or an explicit variant marker), emitting a ValidationSeverity.Error.
2. Introduce the Variants field now and reject it wholesale until #321 migration lands.

Chosen Option: 1

Rationale: The current schema is structurally single-variant; multi-variant releases are already split into separate manifests by publisher factories. Option 1 protects CAS refcounting/GC immediately without prematurely introducing the very schema shape #321 will define, keeping #314 a true stopgap.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Stack Rebase, DI Validation Ratchet, and Composition Tests

Establishes a clean foundation for the mac stack: rebase onto post-release main, resolve the known SharedViewModelModule / IGitHubTokenStorage collision with #301, and harden DI composition validation so the whole stack builds on verified container wiring. Groups the rebase mechanics with the DI-validation ratchet (#320) because both are cross-cutting prerequisites exercised by every later phase.

Task 1: Rebase the mac stack and reconcile the `#301` collision

Resolve the duplicate SharedViewModelModule / IGitHubTokenStorage startup-crash fix.

• Rebase feat/macos-host → feat/platform-neutral-model → feat/unix-filesystem → feat/native-launch onto post-release main/development.
• Keep #301's existing fix in GenHub/GenHub/Infrastructure/DependencyInjection/SharedViewModelModule.cs and drop the stack's duplicate; ensure IGitHubTokenStorage is registered on all platforms (add a Linux registration/implementation in GenHub.Linux/Infrastructure/DependencyInjection/LinuxServicesModule.cs so GitHubTokenDialogViewModel's required dependency resolves).
• Fold the stack's stronger assertions into #301's existing test files under GenHub.Tests/GenHub.Tests.Core/Infrastructure/DependencyInjection/** rather than shipping a parallel set.

Task 2: Add the `ValidateScopes`/`ValidateOnBuild` shrink-only ratchet (`#320`)

Enable DI validation and lock it in with a composition test.

• Enable ServiceProviderOptions { ValidateScopes = true, ValidateOnBuild = true } at the BuildServiceProvider() call sites (GenHub.Windows/Program.cs, GenHub.Linux/Program.cs, and central composition in GenHub/Infrastructure/DependencyInjection/AppServices.cs).
• Add a composition test that iterates every ServiceDescriptor, forces factory-based ViewModel construction, and asserts detectors resolve non-empty — folded into #301's test scaffolding.
• Treat validation as a ratchet: the test should fail if validation is ever disabled/loosened.

🤖 Prompt for AI agents

Implement Phase 1: rebase the four-branch mac stack (`feat/macos-host` →
`feat/platform-neutral-model` → `feat/unix-filesystem` → `feat/native-launch`)
onto post-release `main`/`development`, resolve the `#301` DI collision, and add a
DI validation ratchet.

- Reconcile the duplicate `SharedViewModelModule` / `IGitHubTokenStorage` fix:
keep `#301`'s existing fix in
`GenHub/GenHub/Infrastructure/DependencyInjection/SharedViewModelModule.cs`,
remove the stack's duplicate implementation, and add/verify an
`IGitHubTokenStorage` registration on Linux in
`GenHub.Linux/Infrastructure/DependencyInjection/LinuxServicesModule.cs` so
`GitHubTokenDialogViewModel` resolves on every platform.
- Fold the stack's stronger DI assertions into `#301`'s existing test files under
`GenHub.Tests/GenHub.Tests.Core/Infrastructure/DependencyInjection/**` instead
of creating a separate parallel test set.
- Enable `ServiceProviderOptions { ValidateScopes = true, ValidateOnBuild = true
}` at every `BuildServiceProvider()` call site: `GenHub.Windows/Program.cs`,
`GenHub.Linux/Program.cs`, and the central composition root
`GenHub/Infrastructure/DependencyInjection/AppServices.cs`.
- Add a composition test that iterates every registered `ServiceDescriptor`,
forces factory-based ViewModel construction, and asserts detectors resolve to
non-empty collections; add this to the `#301` test scaffolding.
- Ensure this validation behaves as a ratchet: the test must fail if DI
validation is ever disabled or loosened in the future.

Phase 2: macOS Installation Detection (Stack PR 1 — feat/macos-host)

Introduces the macOS platform surface and makes detection able to distinguish a TCC (privacy) permission denial from a genuine "no installation found", so the UI can prompt for Full Disk Access instead of silently reporting nothing.

Task 1: Model a permission-denied detection outcome (`#319`)

Extend detection results to carry a structured access-denied state.

• Extend GenHub.Core/Models/Results/Detection/DetectionResult.cs (or add a DetectionIssueType/issues collection alongside it) to represent PermissionDenied distinctly from empty-success, mirroring the existing ValidationIssueType.AccessDenied precedent.
• Update GameInstallationDetectionOrchestrator so a permission-denied leg does not collapse into the blunt all-or-nothing failure that zeroes out Items.

Task 2: Add a macOS installation detector and platform scaffolding

Create the macOS detector that reports TCC denials explicitly.

• Add macOS detection under a new platform surface (mirroring GenHub.Linux/GameInstallations/LinuxInstallationDetector.cs), explicitly catching TCC-style UnauthorizedAccessException/IOException (errno 13) from full-disk-access-gated paths and reporting PermissionDenied.
• Register the detector via a macOS DI module following the Windows/Linux module pattern; ensure CanDetectOnCurrentPlatform gates it correctly.

🤖 Prompt for AI agents

Implement Phase 2: introduce the macOS platform surface for installation
detection and make detection distinguish a TCC permission denial from a genuine
"nothing found" result.

- Extend `GenHub.Core/Models/Results/Detection/DetectionResult.cs` (or add a
companion `DetectionIssueType`/issues collection) to represent a
`PermissionDenied` state distinct from empty-success, mirroring the existing
`ValidationIssueType.AccessDenied` precedent.
- Update `GameInstallationDetectionOrchestrator` so that a permission-denied
detection leg does not collapse into the current blunt all-or-nothing failure
path that zeroes out `Items`.
- Add a new macOS installation detector (mirroring the pattern of
`GenHub.Linux/GameInstallations/LinuxInstallationDetector.cs`) under a new
platform surface for macOS, that explicitly catches TCC-style
`UnauthorizedAccessException`/`IOException` (errno 13) raised from
full-disk-access-gated paths and reports `PermissionDenied` rather than a plain
empty result.
- Register the new detector via a macOS DI module, following the existing
Windows/Linux DI module pattern, and ensure `CanDetectOnCurrentPlatform`
correctly gates it to macOS only.

Phase 3: Manifest Ingestion Gate and .Files Migration (Stack PR 2 — feat/platform-neutral-model)

Protects CAS refcounting/GC from malformed multi-variant manifests (the #314 stopgap) and begins the durable fix by migrating .Files consumers onto a ResolvedArtifact abstraction (#321). #314 must land before any provider can publish a variant manifest.

Task 1: Reject multi-variant manifests at ingestion (`#314`)

Add a fail-fast gate against manifests that smuggle multiple variants/targets.

• Add a ValidationSeverity.Error check in GenHub/GenHub/Features/Content/Services/ContentValidator.cs (ValidateManifestStructure) that rejects a single manifest mixing content for multiple targets/variants (conflicting install targets, or duplicate RelativePath entries with differing hashes).
• Add a corresponding fail-fast assertion in GenHub/GenHub/Features/Manifest/ContentManifestBuilder.cs (Build()) so builders cannot accumulate multi-variant files.
• Ensure multi-manifest-producing factories (GeneralsOnlineManifestFactory, SuperHackersManifestFactory, CommunityOutpostManifestFactory via IPublisherManifestFactory) still emit one single-variant manifest per variant and pass the new gate.

Task 2: Introduce `ResolvedArtifact` and migrate `.Files` consumers (`#321`)

Replace direct ContentManifest.Files consumption with a resolved-artifact abstraction with correct per-variant provenance.

• Add a new ResolvedArtifact model in GenHub.Core/Models/** capturing per-file provenance (hash, source type, install target, variant/target discriminator) so CAS references map cleanly to a coherent scoped set.
• Migrate the CAS reference path (CasReferenceTracker.TrackManifestReferencesAsync/UntrackManifestAsync, fixing the track/untrack path-sanitization asymmetry) and WorkspaceManager.TrackWorkspaceCasReferencesAsync to consume ResolvedArtifact instead of raw Files.
• Migrate workspace materialization (WorkspaceStrategyBase and strategies) and launch resolution to the new abstraction, leaving the #314 gate in place as defense-in-depth.

🤖 Prompt for AI agents

Implement Phase 3: add a fail-fast multi-variant manifest ingestion gate (`#314`)
and begin migrating `.Files` consumers to a new `ResolvedArtifact` provenance
abstraction (`#321`).

- Add a `ValidationSeverity.Error` check in
`GenHub/GenHub/Features/Content/Services/ContentValidator.cs`
(`ValidateManifestStructure`) that rejects a single manifest which mixes content
for multiple targets/variants, detected via conflicting install targets or
duplicate `RelativePath` entries with differing hashes.
- Add a corresponding fail-fast assertion in
`GenHub/GenHub/Features/Manifest/ContentManifestBuilder.cs` (`Build()`) so a
manifest builder cannot accumulate multi-variant files in the first place.
- Verify that multi-manifest-producing publisher factories
(`GeneralsOnlineManifestFactory`, `SuperHackersManifestFactory`,
`CommunityOutpostManifestFactory`, all via `IPublisherManifestFactory`) still
emit exactly one single-variant manifest per variant and pass the new validation
gate.
- Add a new `ResolvedArtifact` model under `GenHub.Core/Models/**` that captures
per-file provenance: hash, source type, install target, and a variant/target
discriminator, so CAS references can map cleanly to a coherent scoped set.
- Migrate the CAS reference tracking path —
`CasReferenceTracker.TrackManifestReferencesAsync`/`UntrackManifestAsync` — to
consume `ResolvedArtifact` instead of raw `Files`, and in doing so fix the
existing track/untrack path-sanitization asymmetry; also migrate
`WorkspaceManager.TrackWorkspaceCasReferencesAsync`.
- Migrate workspace materialization (`WorkspaceStrategyBase` and its strategy
implementations) and launch resolution logic to consume the new
`ResolvedArtifact` abstraction, while leaving the `#314` validation gate in place
as defense-in-depth.

Phase 4: Atomic Workspace Materialization and Executable Classification (Stack PR 3 — feat/unix-filesystem)

Closes the data-loss window between file placement and permission-setting for materialized executables (#316) and adds content-based executable classification so extensionless/renamed binaries are handled correctly (#325). Also carries the Linux/Windows filesystem bug fixes (silent hard-link copy, Windows paths on Linux, symlink reachability) noted for this stack phase.

Task 1: Materialize workspace executables atomically (`#316`)

Eliminate the post-move, pre-chmod window that can brick a workspace.

• In GenHub/GenHub/Features/Workspace/FileOperationsService.cs (and the strategy dispatch in WorkspaceStrategyBase), adopt a write-to-temp → hash-verify → File.SetUnixFileMode (chmod) → atomic File.Move sequence so verification/execution never observes a file that exists but is not yet executable, and never a partially-written file that already looks executable.
• Reuse the atomic temp-then-move pattern already present in CasStorage.StoreObjectAsync, adding the missing chmod step before the rename.
• Keep verification strictly non-mutating: isolate/replace WorkspaceValidator's write-then-delete probe file so integrity verification does not mutate the workspace.

Task 2: Add magic-byte executable classification (`#325`)

Classify executables by file signature rather than extension/metadata alone.

• Add a new minimal-prefix-read interface + implementation (e.g., IExecutableFormatClassifier in GenHub.Core/Interfaces/** and impl under GenHub/Features/**) that reads only the first bytes and matches PE (4D 5A), ELF (7F 45 4C 46), and Mach-O/fat (FE ED FA CE / CA FE BA BE) magic bytes; centralize signatures in a new Constants file mirroring GameClientConstants.cs.
• Do not extend the whole-file IFileHashProvider/Sha256HashProvider; use a dedicated FileStream prefix read following their async/DI conventions.
• Feed the classifier into the materialization step (Task 4.1) and executable-permission derivation so extensionless/renamed binaries get the executable bit; register via GameDetectionModule.cs or a dedicated module.

🤖 Prompt for AI agents

Implement Phase 4: make workspace executable materialization atomic (`#316`) and
add magic-byte-based executable classification (`#325`). This phase also carries
related Linux/Windows filesystem bug fixes noted for this stack phase (silent
hard-link copy, Windows paths on Linux, symlink reachability).

- In `GenHub/GenHub/Features/Workspace/FileOperationsService.cs` (and the
strategy dispatch logic in `WorkspaceStrategyBase`), change the materialization
sequence to: write to a temp file → verify the hash → apply
`File.SetUnixFileMode` (chmod) → perform an atomic `File.Move`. This ensures
verification/execution never observes a file that exists on its final path but
is not yet executable, and never observes a partially-written file that already
looks executable.
- Reuse the atomic temp-then-move pattern already implemented in
`CasStorage.StoreObjectAsync`, adding the currently-missing chmod step before
the rename.
- Ensure workspace integrity verification remains strictly non-mutating: isolate
or replace `WorkspaceValidator`'s existing write-then-delete probe-file
technique so that verification never mutates the workspace.
- Add a new minimal-prefix-read abstraction, e.g. `IExecutableFormatClassifier`
under `GenHub.Core/Interfaces/**` with an implementation under
`GenHub/Features/**`, that reads only the first few bytes of a file and matches
known magic-byte signatures: PE (`4D 5A`), ELF (`7F 45 4C 46`), and Mach-O/fat
(`FE ED FA CE` / `CA FE BA BE`). Centralize these signatures in a new constants
file mirroring the style of `GameClientConstants.cs`.
- Do not extend the existing whole-file `IFileHashProvider`/`Sha256HashProvider`
abstractions for this; use a dedicated `FileStream` prefix read that follows
their existing async/DI conventions.
- Wire the classifier into the materialization step from the previous task and
into executable-permission derivation, so extensionless or renamed binaries
still receive the executable bit; register the new service via
`GameDetectionModule.cs` or a new dedicated DI module.

Phase 5: Native Launch Hardening (Stack PR 4 — feat/native-launch)

Makes native (no-Wine) launch correct and safe: validate retail archive roots before launch (#315), strip dynamic-linker env vars for native launch (#317), fix the stderr-capture EOF race (#318), and add a persisted launch receipt for cheap revalidation (#323).

Task 1: Validate retail archive roots before launch (`#315`)

Fail fast when required retail data is missing, since the engine reaches its main loop with no content and no error.

• In GenHub/GenHub/Features/Launching/GameLauncher.cs (LaunchProfileAsync, right after resolving actualInstallationPath), add a cheap existence check for required retail archives (e.g., .big files) before workspace preparation, reusing a lightweight subset of GenHub/GenHub/Features/Validation/GameInstallationValidator.cs.
• Where available, consume the engine-side machine-readable failure sentinel (tracked in the engine repo) to confirm archives mounted.

Task 2: Add stderr/stdout capture without an EOF race (`#318`)

Introduce output redirection and drain it correctly relative to process exit.

• In GenHub/GenHub/Features/GameProfiles/Infrastructure/GameProcessManager.cs, add RedirectStandardError/RedirectStandardOutput with async draining (BeginErrorReadLine/ReadToEndAsync) and ensure the drain completes before/independently of the 100 ms ProcessStartDelayMs HasExited health check, avoiding a race that truncates captured output.

Task 3: Strip `DYLD_LIBRARY_PATH` / `LD_LIBRARY_PATH` from native launch (`#317`)

Prevent profile env vars from injecting dynamic-linker paths that hardened-runtime signing will silently ignore.

• In GameProcessManager.StartProcessAsync, where configuration.EnvironmentVariables is copied into processStartInfo.EnvironmentVariables, explicitly strip/block DYLD_LIBRARY_PATH and LD_LIBRARY_PATH (and related dynamic-linker keys) for native launches so behaviour does not change silently at notarization time.

Task 4: Add a persisted launch receipt + cheap revalidation (`#323`)

Skip full workspace/CAS preflight when nothing has changed since the last successful launch.

• Add a durable LaunchReceipt model (profile ID, resolved executable path/hash, manifest IDs+versions, workspace ID, timestamp) written on successful launch in GameLauncher.LaunchProfileAsync.
• Add a lightweight comparison at the start of LaunchProfileAsync (before ResolveDependenciesWithManifestsAsync/PreflightCasCheckAsync/PrepareWorkspaceAsync) to short-circuit full revalidation when the receipt matches; persist alongside LaunchRegistry state.

🤖 Prompt for AI agents

Implement Phase 5: harden the native (no-Wine) launch pipeline by validating
retail archive roots before launch, stripping dynamic-linker environment
variables, fixing a stderr-capture EOF race, and adding a persisted launch
receipt for cheap revalidation.

- In `GenHub/GenHub/Features/Launching/GameLauncher.cs` (`LaunchProfileAsync`,
immediately after resolving `actualInstallationPath`), add a cheap existence
check for required retail archives (e.g., `.big` files) before workspace
preparation begins, reusing a lightweight subset of the existing
`GenHub/GenHub/Features/Validation/GameInstallationValidator.cs` logic. This
prevents the engine from silently reaching its main loop with no content and no
visible error. Where available, consume the engine-side machine-readable failure
sentinel (tracked in the engine repo) to confirm archives mounted correctly.
- In `GenHub/GenHub/Features/GameProfiles/Infrastructure/GameProcessManager.cs`,
add `RedirectStandardError`/`RedirectStandardOutput` with proper async draining
(`BeginErrorReadLine`/`ReadToEndAsync`), ensuring the drain completes before or
independently of the existing 100 ms `ProcessStartDelayMs` `HasExited` health
check, so the race that can truncate captured output is eliminated.
- In `GameProcessManager.StartProcessAsync`, at the point where
`configuration.EnvironmentVariables` is copied into
`processStartInfo.EnvironmentVariables`, explicitly strip/block
`DYLD_LIBRARY_PATH` and `LD_LIBRARY_PATH` (and related dynamic-linker keys) for
native launches, so profile env vars cannot inject dynamic-linker paths that
hardened-runtime signing will silently ignore at notarization time.
- Add a new durable `LaunchReceipt` model capturing profile ID, resolved
executable path/hash, manifest IDs+versions, workspace ID, and timestamp; write
this receipt on every successful launch inside
`GameLauncher.LaunchProfileAsync`.
- Add a lightweight comparison step at the start of `LaunchProfileAsync`, before
`ResolveDependenciesWithManifestsAsync`/`PreflightCasCheckAsync`/`PrepareWorkspaceAsync`
run, that short-circuits full revalidation when the current state matches the
persisted receipt; persist the receipt alongside existing `LaunchRegistry`
state.

Phase 6: macOS Distribution and CI

Delivers the public-distribution blocker (Playwright exclusion, inside-out signing, notarization — #322), an engine-only launch smoke test on macos-15 (#324, which needs no retail data), and supply-chain hardening by pinning GitHub Actions to commit SHAs (#326).

Task 1: Playwright exclusion, inside-out signing, notarization (`#322`)

Enable a signed/notarized macOS bundle via Velopack.

• Add a macOS build/pack pipeline (following the Windows/Linux Velopack vpk pattern in .github/workflows/ci.yml/release.yml) with osx-x64/osx-arm64 targets and a macOS publish profile mirroring existing .pubxml files.
• Exclude the Microsoft.Playwright package/its bundled Chromium binaries (used only by CNCLabsMapDiscoverer.cs) from the macOS .app bundle so signing/notarization succeeds.
• Wire Velopack macOS inside-out signing + Apple notarization with entitlements; document that unsigned distribution quarantines written files and Gatekeeper blocks the game binary.

Task 2: Engine-only launch smoke on `macos-15` CI (`#324`)

Verify the engine launches to its main loop with no retail data.

• Add a runs-on: macos-15 job (modeled on build-linux) gated by the existing detect-changes outputs that builds/publishes and then executes the engine binary with a timeout to confirm it launches without crashing — exploiting the same zero-content-main-loop property as #315.

Task 3: Pin GitHub Actions to commit SHAs (`#326`)

Harden the supply chain across all workflows.

• Convert every uses: step in ci.yml, deploy.yml, and release.yml from mutable version tags (e.g., @v4) to immutable commit SHAs with a trailing # vX.Y.Z comment, across all 9 distinct actions.

🤖 Prompt for AI agents

Implement Phase 6: unblock public macOS distribution, add a macOS engine smoke
test to CI, and harden CI supply-chain security.

- Add a macOS build/pack pipeline that follows the existing Windows/Linux
Velopack `vpk` pattern found in `.github/workflows/ci.yml`/`release.yml`,
targeting `osx-x64`/`osx-arm64`, with a new macOS publish profile mirroring the
existing `.pubxml` files.
- Exclude the `Microsoft.Playwright` package and its bundled Chromium binaries
(used only by `CNCLabsMapDiscoverer.cs`) from the macOS `.app` bundle so signing
and notarization can succeed.
- Wire up Velopack macOS inside-out signing plus Apple notarization with the
appropriate entitlements; document that unsigned distribution causes written
files to be quarantined and Gatekeeper to block the game binary.
- Add a new CI job with `runs-on: macos-15` (modeled on the existing
`build-linux` job) gated by the existing `detect-changes` outputs, which
builds/publishes and then runs the engine binary with a timeout to confirm it
launches to its main loop without crashing, using no retail data — exploiting
the same zero-content-main-loop property relied on by the `#315` validation work.
- Convert every `uses:` step across `ci.yml`, `deploy.yml`, and `release.yml`
from mutable version tags (e.g. `@v4`) to immutable commit SHAs, adding a
trailing `# vX.Y.Z` comment for readability, covering all 9 distinct actions
used across the workflows.

Research

GenHub is a cross-platform Avalonia app split into a platform-agnostic GenHub.Core (interfaces, models, constants, enums), the shared GenHub app project (feature services and DI modules under Features/** and Infrastructure/DependencyInjection/**), and platform projects GenHub.Windows / GenHub.Linux (with no macOS project yet).

Content is described by a flat ContentManifest whose Files (ManifestFile) list is consumed directly by CAS reference tracking (CasReferenceTracker), workspace materialization (WorkspaceManager + strategy classes), and launch (GameLauncher → GameProcessManager).

CAS "refcounting" is a mark-and-sweep over per-manifest .refs files keyed solely by manifest ID. Launch state is in-memory only (LaunchRegistry).

CI (.github/workflows/ci.yml, release.yml) builds only Windows and Linux via Velopack, with all actions pinned to mutable version tags.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: rebase the four-branch mac stack (`feat/macos-host` →
`feat/platform-neutral-model` → `feat/unix-filesystem` → `feat/native-launch`)
onto post-release `main`/`development`, resolve the `#301` DI collision, and add a
DI validation ratchet.

- Reconcile the duplicate `SharedViewModelModule` / `IGitHubTokenStorage` fix:
keep `#301`'s existing fix in
`GenHub/GenHub/Infrastructure/DependencyInjection/SharedViewModelModule.cs`,
remove the stack's duplicate implementation, and add/verify an
`IGitHubTokenStorage` registration on Linux in
`GenHub.Linux/Infrastructure/DependencyInjection/LinuxServicesModule.cs` so
`GitHubTokenDialogViewModel` resolves on every platform.
- Fold the stack's stronger DI assertions into `#301`'s existing test files under
`GenHub.Tests/GenHub.Tests.Core/Infrastructure/DependencyInjection/**` instead
of creating a separate parallel test set.
- Enable `ServiceProviderOptions { ValidateScopes = true, ValidateOnBuild = true
}` at every `BuildServiceProvider()` call site: `GenHub.Windows/Program.cs`,
`GenHub.Linux/Program.cs`, and the central composition root
`GenHub/Infrastructure/DependencyInjection/AppServices.cs`.
- Add a composition test that iterates every registered `ServiceDescriptor`,
forces factory-based ViewModel construction, and asserts detectors resolve to
non-empty collections; add this to the `#301` test scaffolding.
- Ensure this validation behaves as a ratchet: the test must fail if DI
validation is ever disabled or loosened in the future.
===============================================================================

Task: 2

Implement Phase 2: introduce the macOS platform surface for installation
detection and make detection distinguish a TCC permission denial from a genuine
"nothing found" result.

- Extend `GenHub.Core/Models/Results/Detection/DetectionResult.cs` (or add a
companion `DetectionIssueType`/issues collection) to represent a
`PermissionDenied` state distinct from empty-success, mirroring the existing
`ValidationIssueType.AccessDenied` precedent.
- Update `GameInstallationDetectionOrchestrator` so that a permission-denied
detection leg does not collapse into the current blunt all-or-nothing failure
path that zeroes out `Items`.
- Add a new macOS installation detector (mirroring the pattern of
`GenHub.Linux/GameInstallations/LinuxInstallationDetector.cs`) under a new
platform surface for macOS, that explicitly catches TCC-style
`UnauthorizedAccessException`/`IOException` (errno 13) raised from
full-disk-access-gated paths and reports `PermissionDenied` rather than a plain
empty result.
- Register the new detector via a macOS DI module, following the existing
Windows/Linux DI module pattern, and ensure `CanDetectOnCurrentPlatform`
correctly gates it to macOS only.
===============================================================================

Task: 3

Implement Phase 3: add a fail-fast multi-variant manifest ingestion gate (`#314`)
and begin migrating `.Files` consumers to a new `ResolvedArtifact` provenance
abstraction (`#321`).

- Add a `ValidationSeverity.Error` check in
`GenHub/GenHub/Features/Content/Services/ContentValidator.cs`
(`ValidateManifestStructure`) that rejects a single manifest which mixes content
for multiple targets/variants, detected via conflicting install targets or
duplicate `RelativePath` entries with differing hashes.
- Add a corresponding fail-fast assertion in
`GenHub/GenHub/Features/Manifest/ContentManifestBuilder.cs` (`Build()`) so a
manifest builder cannot accumulate multi-variant files in the first place.
- Verify that multi-manifest-producing publisher factories
(`GeneralsOnlineManifestFactory`, `SuperHackersManifestFactory`,
`CommunityOutpostManifestFactory`, all via `IPublisherManifestFactory`) still
emit exactly one single-variant manifest per variant and pass the new validation
gate.
- Add a new `ResolvedArtifact` model under `GenHub.Core/Models/**` that captures
per-file provenance: hash, source type, install target, and a variant/target
discriminator, so CAS references can map cleanly to a coherent scoped set.
- Migrate the CAS reference tracking path —
`CasReferenceTracker.TrackManifestReferencesAsync`/`UntrackManifestAsync` — to
consume `ResolvedArtifact` instead of raw `Files`, and in doing so fix the
existing track/untrack path-sanitization asymmetry; also migrate
`WorkspaceManager.TrackWorkspaceCasReferencesAsync`.
- Migrate workspace materialization (`WorkspaceStrategyBase` and its strategy
implementations) and launch resolution logic to consume the new
`ResolvedArtifact` abstraction, while leaving the `#314` validation gate in place
as defense-in-depth.
===============================================================================

Task: 4

Implement Phase 4: make workspace executable materialization atomic (`#316`) and
add magic-byte-based executable classification (`#325`). This phase also carries
related Linux/Windows filesystem bug fixes noted for this stack phase (silent
hard-link copy, Windows paths on Linux, symlink reachability).

- In `GenHub/GenHub/Features/Workspace/FileOperationsService.cs` (and the
strategy dispatch logic in `WorkspaceStrategyBase`), change the materialization
sequence to: write to a temp file → verify the hash → apply
`File.SetUnixFileMode` (chmod) → perform an atomic `File.Move`. This ensures
verification/execution never observes a file that exists on its final path but
is not yet executable, and never observes a partially-written file that already
looks executable.
- Reuse the atomic temp-then-move pattern already implemented in
`CasStorage.StoreObjectAsync`, adding the currently-missing chmod step before
the rename.
- Ensure workspace integrity verification remains strictly non-mutating: isolate
or replace `WorkspaceValidator`'s existing write-then-delete probe-file
technique so that verification never mutates the workspace.
- Add a new minimal-prefix-read abstraction, e.g. `IExecutableFormatClassifier`
under `GenHub.Core/Interfaces/**` with an implementation under
`GenHub/Features/**`, that reads only the first few bytes of a file and matches
known magic-byte signatures: PE (`4D 5A`), ELF (`7F 45 4C 46`), and Mach-O/fat
(`FE ED FA CE` / `CA FE BA BE`). Centralize these signatures in a new constants
file mirroring the style of `GameClientConstants.cs`.
- Do not extend the existing whole-file `IFileHashProvider`/`Sha256HashProvider`
abstractions for this; use a dedicated `FileStream` prefix read that follows
their existing async/DI conventions.
- Wire the classifier into the materialization step from the previous task and
into executable-permission derivation, so extensionless or renamed binaries
still receive the executable bit; register the new service via
`GameDetectionModule.cs` or a new dedicated DI module.
===============================================================================

Task: 5

Implement Phase 5: harden the native (no-Wine) launch pipeline by validating
retail archive roots before launch, stripping dynamic-linker environment
variables, fixing a stderr-capture EOF race, and adding a persisted launch
receipt for cheap revalidation.

- In `GenHub/GenHub/Features/Launching/GameLauncher.cs` (`LaunchProfileAsync`,
immediately after resolving `actualInstallationPath`), add a cheap existence
check for required retail archives (e.g., `.big` files) before workspace
preparation begins, reusing a lightweight subset of the existing
`GenHub/GenHub/Features/Validation/GameInstallationValidator.cs` logic. This
prevents the engine from silently reaching its main loop with no content and no
visible error. Where available, consume the engine-side machine-readable failure
sentinel (tracked in the engine repo) to confirm archives mounted correctly.
- In `GenHub/GenHub/Features/GameProfiles/Infrastructure/GameProcessManager.cs`,
add `RedirectStandardError`/`RedirectStandardOutput` with proper async draining
(`BeginErrorReadLine`/`ReadToEndAsync`), ensuring the drain completes before or
independently of the existing 100 ms `ProcessStartDelayMs` `HasExited` health
check, so the race that can truncate captured output is eliminated.
- In `GameProcessManager.StartProcessAsync`, at the point where
`configuration.EnvironmentVariables` is copied into
`processStartInfo.EnvironmentVariables`, explicitly strip/block
`DYLD_LIBRARY_PATH` and `LD_LIBRARY_PATH` (and related dynamic-linker keys) for
native launches, so profile env vars cannot inject dynamic-linker paths that
hardened-runtime signing will silently ignore at notarization time.
- Add a new durable `LaunchReceipt` model capturing profile ID, resolved
executable path/hash, manifest IDs+versions, workspace ID, and timestamp; write
this receipt on every successful launch inside
`GameLauncher.LaunchProfileAsync`.
- Add a lightweight comparison step at the start of `LaunchProfileAsync`, before
`ResolveDependenciesWithManifestsAsync`/`PreflightCasCheckAsync`/`PrepareWorkspaceAsync`
run, that short-circuits full revalidation when the current state matches the
persisted receipt; persist the receipt alongside existing `LaunchRegistry`
state.
===============================================================================

Task: 6

Implement Phase 6: unblock public macOS distribution, add a macOS engine smoke
test to CI, and harden CI supply-chain security.

- Add a macOS build/pack pipeline that follows the existing Windows/Linux
Velopack `vpk` pattern found in `.github/workflows/ci.yml`/`release.yml`,
targeting `osx-x64`/`osx-arm64`, with a new macOS publish profile mirroring the
existing `.pubxml` files.
- Exclude the `Microsoft.Playwright` package and its bundled Chromium binaries
(used only by `CNCLabsMapDiscoverer.cs`) from the macOS `.app` bundle so signing
and notarization can succeed.
- Wire up Velopack macOS inside-out signing plus Apple notarization with the
appropriate entitlements; document that unsigned distribution causes written
files to be quarantined and Gatekeeper to block the game binary.
- Add a new CI job with `runs-on: macos-15` (modeled on the existing
`build-linux` job) gated by the existing `detect-changes` outputs, which
builds/publishes and then runs the engine binary with a timeout to confirm it
launches to its main loop without crashing, using no retail data — exploiting
the same zero-content-main-loop property relied on by the `#315` validation work.
- Convert every `uses:` step across `ci.yml`, `deploy.yml`, and `release.yml`
from mutable version tags (e.g. `@v4`) to immutable commit SHAs, adding a
trailing `# vX.Y.Z` comment for readability, covering all 9 distinct actions
used across the workflows.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!