[codex] Fix issue 12 runtime hardening

[cboyd0319]

Summary

Fixes #12.

This hardens the installer against partial runtime installs and misleading success states. The fixer is responsible for supplying the AGL/Qt runtime assets; if a release artifact, cache, build output, or selected Qt source cannot supply them, that is an installer invariant violation, not a user-provided dependency. The root cause was broader than the reported missing AGL stub: runtime asset invariants, helper failures, rollback behavior, repeated-install framework symlink layout, and support-bundle observability all needed stricter validation or self-heal behavior.

Changes

• Require complete fixer-supplied AGL, Qt framework, Qt plugin, and bundled dependency state before verification can pass.
• Fail early when the release artifact, cache, build output, or selected Qt source is incomplete.
• Fix Bash 3.2 rollback trap inheritance so post-backup failures roll back.
• Build AGL x86_64 slices with native clang -arch x86_64, not Rosetta-launched clang.
• Repair stale AGL framework symlinks in backup copies and avoid recreating nested framework symlinks on repeated installs.
• Preserve custom GAME_APP in watcher reapply and LaunchAgent paths.
• Restore save backups exactly rather than merging stale files over restored roots.
• Expand support bundles with sanitized installer history, runtime invariant status, backup integrity status, and required Qt archive content checks.
• Sanitize Qt package metadata and copied backup manifests; avoid backup-derived manifest filenames in support archives.
• Make default installer logs process-specific so same-second runs do not mix into one log file.
• Add focused regression coverage and update docs, runbooks, CI, and audit plans.

Validation

Current local validation passed on 2026-06-29 for commit 32e7cf4:

./tools/validate_harness.sh
./tools/test_dependency_parsing.sh
./tools/test_issue_10_regression.sh
./tools/test_issue_11_game_detection.sh
./tools/test_issue_12_agl_install_failure.sh
./tools/test_installer_rollback_regression.sh
./tools/test_support_bundle_sanitization.sh
./tools/test_backup_saves_regression.sh
./tools/test_launcher_friction.sh
./tools/test_preflight_regression.sh
./tools/test_manifest_regression.sh
./tools/test_qt_version_pinning.sh
./scripts/download_qt_frameworks.sh --check
for script in fix_worms_wmd.sh install.sh "Install Fix.command" "Worms W.M.D Fix.command" scripts/*.sh tools/*.sh; do bash -n "$script"; done
shellcheck fix_worms_wmd.sh install.sh "Install Fix.command" "Worms W.M.D Fix.command" scripts/*.sh tools/*.sh
./tools/build_release_bundle.sh --version local-support --skip-zip
clang -Wall -Wextra -Werror -arch x86_64 -dynamiclib -o /tmp/AGL_test -framework OpenGL src/agl_stub.c
git diff --check

Real non-mutating validation also passed on this macOS 27 Apple Silicon machine using the local Steam install:

./fix_worms_wmd.sh --verify
./tools/preflight_check.sh
./fix_worms_wmd.sh --dry-run
./tools/collect_diagnostics.sh --bundle --bundle-output "$tmp_dir"

Additional targeted validation passed:

• Extracted a real support bundle and verified diagnostics.txt, install-summary.txt, runtime-invariants.txt, backup-summary.txt, qt-package.txt, and numbered sanitized backup manifests are present.
• Ran a parallel --verify and --dry-run smoke and confirmed same-second invocations wrote separate log files.
• The support-bundle regression covers mixed success/error rollback logs, Qt metadata redaction, backup-manifest redaction, missing Qt checksums, and corrupt Qt archives.
• CI passed on commit 32e7cf4: Validate Scripts, ShellCheck, and Validate C Code.
• Release Bundle workflow run 28407168209 passed on commit 32e7cf4; the uploaded zip downloaded locally, passed shasum -a 256 -c, and extracted with the expected release layout.

Earlier installed-game apply and packaged artifact validation on this branch also passed after the runtime hardening changes: forced install, verify, preflight, diagnostics, launcher option 3, LaunchAgent install/check/uninstall, checksum-verified local release zip extraction, packaged forced install, and bounded launch with no recent crash report.

Remaining limits

• No real macOS 26.0.1 M1 Air was available locally.
• No real GOG Worms W.M.D install was available locally.
• Intel Homebrew under /usr/local/bin/brew was not installed on this host, so the Homebrew Qt fallback was not live-installed.

[Copilot]

Pull request overview

Hardens the Worms W.M.D macOS fixer against partial/incorrect runtime installs (AGL stub, Qt frameworks/plugins, bundled dylibs), improves rollback reliability on Bash 3.2, and expands diagnostics/support-bundle observability so “success” states better match actual runtime readiness.

Changes:

• Enforce “fixer-supplied runtime invariants” (AGL x86_64 slice, required Qt frameworks/plugins, required bundled dylibs) across installer checks, preflight, verify, watcher, and diagnostics.
• Improve rollback/reapply behavior and repeated-install self-heal (ERR trap inheritance, AGL framework symlink repair, watcher GAME_APP persistence, exact save restore semantics).
• Expand support bundle content and sanitization, and add focused regression tests + doc/runbook updates.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/watch_for_updates.sh	Treats missing required runtime pieces as “partial/missing”; forwards/persists GAME_APP for reapply and LaunchAgent installs.
tools/test_support_bundle_sanitization.sh	Extends privacy regression to cover installer-history/runtime/backup/Qt-package sections and more secret-like patterns.
tools/test_preflight_regression.sh	Adds regression cases for missing AGL binary and wrong-arch AGL.
tools/test_manifest_regression.sh	Adds regression for repairing nested/stale AGL framework symlinks.
tools/test_launcher_friction.sh	Ensures watcher reapply forwards GAME_APP and LaunchAgent plist persists/escapes it.
tools/test_issue_12_agl_install_failure.sh	New regression suite for issue #12 partial installs (AGL/Qt/plugins/dylibs/arch checks).
tools/test_issue_10_regression.sh	Adds regression for unique default log path generation.
tools/test_installer_rollback_regression.sh	New regression ensuring post-backup failures roll back correctly.
tools/test_backup_saves_regression.sh	Adds regression ensuring restore does not leave stale files not present in backup.
tools/preflight_check.sh	Tightens fix-status checks to require AGL x86_64 + required Qt frameworks/plugins.
tools/collect_diagnostics.sh	Adds runtime invariant matrix, install-history summary, backup-integrity summary, required Qt archive-content checks; strengthens sanitization.
tools/backup_saves.sh	Implements exact-root replacement restore semantics and optional non-interactive restore confirmation for tests.
SUPPORT.md	Updates support-bundle description to reflect new sanitized sections.
SECURITY.md	Updates privacy audit row to reflect expanded sanitized support bundle contents.
scripts/logging.sh	Makes default logs process-specific and collision-safe.
scripts/common.sh	Adds AGL framework symlink repair helper.
scripts/05_verify_installation.sh	Requires core Qt frameworks + plugins; upgrades wrong-arch AGL from warning to error.
scripts/04_fix_library_paths.sh	Hard-fails when built AGL stub is missing; attempts to reset AGL framework symlink layout before recreating.
scripts/03_copy_dependencies.sh	Verifies required bundled dylibs exist for prebuilt path and fails clearly if incomplete.
scripts/02_replace_qt_frameworks.sh	Preflights required Qt frameworks/binaries/plugins before destructive replacement and fails early if incomplete.
scripts/01_build_agl_stub.sh	Builds x86_64 slice using native clang -arch x86_64 rather than Rosetta-launched clang.
README.md	Updates support-bundle bullet to reflect expanded observability.
fix_worms_wmd.sh	Enables ERR trap inheritance (set -E), enforces required runtime presence, repairs AGL symlinks in backups, and surfaces helper failures instead of swallowing them.
docs/TROUBLESHOOTING.md	Adds user-facing recovery guidance for missing AGL / stale AGL symlink backup errors.
docs/TOOLS.md	Updates tool behavior docs (save restore semantics, watcher GAME_APP persistence, support bundle contents, new regression scripts).
docs/runbooks/agent-session.md	Adds new regression scripts to runbook checklist.
docs/README.md	Adds/links new exec plans for issue #12 and deep audit.
docs/INSTALL.md	Replaces manual “run helper scripts sequentially” flow with “use canonical fixer” guidance.
docs/exec-plans/README.md	Marks issue #12 and deep audit plans as completed and lists them.
docs/exec-plans/2026-06-29-issue-12-agl-stub-install.md	New completed plan documenting issue #12 analysis, decisions, and verification steps.
docs/exec-plans/2026-06-29-full-repo-deep-audit.md	New completed plan capturing repo-wide audit findings and validation evidence.
docs/design/runtime-contracts.md	Updates runtime/backup/support-bundle contracts to codify required runtime invariants and exact restore semantics.
CONTRIBUTING.md	Updates bug-report guidance to reflect expanded support bundle.
CHANGELOG.md	Adds unreleased entries describing the hardening, observability, rollback/logging, watcher, and restore fixes.
AGENTS.md	Adds new regression scripts to the agent checklist.
.github/workflows/release.yml	Sanitizes ref names for release bundle version/artifact naming to avoid /-related failures.
.github/workflows/ci.yml	Adds the new issue #12 and rollback regression tests to CI.
.github/ISSUE_TEMPLATE/install_failure.yml	Updates template wording for expanded support bundle contents.
.github/ISSUE_TEMPLATE/bug_report.yml	Updates template wording for expanded support bundle contents.