tracking(macOS): complete platform qualification matrix

[cervantesh]

Help wanted: macOS qualification tracker

CervTerm is Windows-first and does not yet have complete macOS CI, hardware validation, accessibility evidence, or a supported package. This issue tracks the full test program required before macOS can be presented as a supported platform.

Validation workstreams

Automated baseline

• ci(macOS): add hosted build and test coverage #106 — hosted macOS build, test, vet, GLFW compile/build, and zsh PTY capture

Runtime and integration

• test(macOS): validate Unix PTY, zsh, resize, and process lifecycle #108 — Unix PTY, zsh/bash, SIGWINCH, capture, errors, and process lifecycle
• test(macOS): validate Retina, windowing, input, clipboard, and accessibility #107 — Retina/window lifecycle, keyboard/IME, clipboard, mouse/trackpad, and accessibility
• test(macOS): qualify fonts, shaping, emoji, and rendering quality #109 — system fonts, shaping, bidi/Indic, color emoji, zoom quality, and atlas pressure
• test(macOS): stress native panes, independent zoom, and rendering performance #105 — native panes, dividers, independent zoom, lifecycle stress, CPU/RAM/FPS baselines
• Help test experimental native blur on macOS and Linux compositors #104 — experimental native blur/vibrancy on real macOS hardware

Distribution

• release(macOS): define and validate app bundle, signing, notarization, and install smoke #110 — .app bundle, architecture matrix, signing, notarization, Gatekeeper, install/upgrade/uninstall smoke

Recommended coverage matrix

Please include the cells you can access; one contributor is not expected to own every device:

Dimension	Minimum useful coverage
Architecture	Apple Silicon; Intel where available
macOS	Current release plus one older supported candidate
Display	Retina; mixed-scale external display if available
Shell	/bin/zsh; explicit /bin/bash
Input	US layout plus one non-US/dead-key layout; at least one IME
Fonts	Embedded Go Mono, one Apple/system monospace face, one programming-ligature face
Workloads	shell, vim, less, top, mouse-aware TUI, Unicode/emoji output, multi-pane stress
Launch	Terminal, Finder/app bundle, quarantined downloaded artifact once packaging exists

Common evidence template

Issue/workstream:
macOS version:
Mac model / architecture / GPU / RAM:
Displays and scaling:
Keyboard layout / IME:
CervTerm commit:
Go version and build command:
Config used:
Checklist results:
Screenshots/video/captures/logs (sanitized):
Performance observations:
Unexpected behavior and reproduction steps:

Exit criteria for supported macOS status

• Required macOS CI is green and non-flaky.
• PTY/shell/lifecycle passes on Apple Silicon and has an explicit Intel disposition.
• Retina, input, clipboard, fonts, emoji, panes, zoom, and accessibility results are documented.
• No known crash, orphan-process, input-loss, coordinate-mapping, or repeated-atlas-reset blocker remains.
• Performance baselines are recorded and regressions have owners.
• Blur is either qualified or clearly kept experimental/disabled.
• A verifiable install artifact and Gatekeeper/notarization story exist, or documentation explicitly limits macOS to source builds.
• docs/manual-verification.md, support policy, and release documentation are updated with evidence-backed claims.

Please volunteer on the smallest matching child issue and link your results here.

[hernanrr]

Status update, not a closure — several exit criteria remain open, and one item is actively blocked pending a maintainer decision.

This pass used a 4-stage review pipeline per change: architecture/plan review, implementation with tests, adversarial audit via the codex CLI (model gpt-5.6-sol) as an independent reviewer, and adjudication that confirmed/rejected each finding, fixed valid P0/P1s, and logged P2s below for your evaluation.

Landed this pass

• ci(macOS): add hosted build/test coverage; fix two macOS-only bugs #231 — macOS CI job — blocked on a maturity-gate manifest re-declaration, see ci(macOS): add hosted build and test coverage #106's comment
• release(macOS): add .app bundle packaging, wire into tagged releases #232 — macOS release job + .app packaging
• Two real macOS-only bugs found and fixed: Apple Color Emoji not rendering in color, config/background watch-set falsely duplicating entries on macOS's /var symlink
• Four real bugs found and fixed in the new packaging script/release wiring before they shipped: invalid plist versions, missing platform guard, discarded zip errors, silently-arm64-only release artifact
• PTY/zsh/bash/resize/process-lifecycle automated + CLI evidence recorded (test(macOS): validate Unix PTY, zsh, resize, and process lifecycle #108)
• Mux/zoom/divider/atlas and blur (incl. real darwin cgo provider) automated test suites all green on real hardware (test(macOS): stress native panes, independent zoom, and rendering performance #105, Help test experimental native blur on macOS and Linux compositors #104)
• .app packaging script + bundle metadata, with Gatekeeper unsigned-quarantine behavior verified directly (release(macOS): define and validate app bundle, signing, notarization, and install smoke #110)

Full raw evidence: docs/validation/macos-platform-validation-2026-08-12.md (in #231).

Filed as proposals, not worked in this pass

1. Proposal: track every original path per canonical watch identity, not just one #233 — watchPathIdentity collapses distinct symlinked parent directories, dropping a real reload dependency
2. Proposal: package-macos.go should stage in a unique temp dir to avoid a concurrent-run race #234 — package-macos.go should stage in a unique temp dir to avoid a concurrent-run race
3. Proposal: macOS config discovery doesn't follow ~/Library convention #235 — macOS config discovery doesn't follow the ~/Library convention
4. Proposal: emoji-coverage startup warnings are platform-blind #236 — emoji-coverage startup warnings are platform-blind

P2 log (adversarial-audit findings, confirmed non-exploitable, deliberately deferred)

Full detail at docs/validation/macos-platform-validation-2026-08-12-p2-log.md (in #231). Summary for evaluation:

From #231's audit (internal/fontglyph/raster/, internal/frontend/glfwgl/config_watch.go):

• P2-1 — TTC header (sfntDirectoryOffset) accepts a structurally truncated collection (numFonts declared but not all offsets present). Not an OOB read; deterministic and bounded either way. Not fixed in code because the file is pinned by closed Slice 5.5c and further edits enlarge what you'd need to re-declare.
• P2-2 — dead numTables < 0 check in listSFNTTables (uint16 can never be negative). Pre-existing, unrelated to this pass's changes.
• P2-3 — watchPathIdentity is now CWD-dependent for relative paths on all platforms (was already true on Windows). In practice all watch paths reaching this function are already absolute.
• P2-4 — no canonicalization when a watched file's parent directory doesn't exist yet (EvalSymlinks fails silently). Self-correcting once the directory exists; pre-existing on Windows.

From #232's audit (scripts/package-macos.go):

• P2-5 — concurrent package-macos.go runs targeting the same -outdir race on the shared CervTerm.app staging path. Filed separately as Proposal: package-macos.go should stage in a unique temp dir to avoid a concurrent-run race #234 rather than left only in the log, since it's a real, trackable improvement.

Still open — needs a human, more hardware, or a certificate

• Apple Silicon coverage (this manual pass was Intel-only; the new CI job will run on arm64 once ci(macOS): add hosted build/test coverage; fix two macOS-only bugs #231 is unblocked, which is complementary)
• All interactive/visual GUI verification (fonts, blur, window chrome, zoom/dividers) — this automated session has no observable desktop session; the automated test suites are real signal but not a substitute for eyeballing it
• Non-US keyboard layouts, dead keys, IME composition
• VoiceOver / accessibility
• Developer ID signing + notarization
• Multi-display / mixed-scale testing
• Intel/universal-binary release coverage

Release

Once #231 and #232 are reviewed/merged (#231 specifically needs a decision on the maturity-gate pin conflict first), a tagged release will produce a macOS artifact for the first time via the new release.yml job. No release has been cut yet — waiting on those PRs so it actually contains this work.