From e95304e7ed7f53a5ebfaa7cda0491ff7bb3d8f17 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 20 Aug 2026 03:07:06 -0700
Subject: [PATCH] docs(macos): record the revert hazard and CI's macOS test gap

Two things a reader of this module cannot otherwise know.

A revert leaves the key written in every user's domain forever. AppKit reads
the plist, not this file, so removing the code alone keeps press-and-hold
disabled for everyone who ran an affected build. The sibling period-substitution
module carries the same warning because that fix was already lost once this way.

And the real-binary test file that pins the defaults(1) exit-code semantics this
design rests on never runs in CI: the e2e workflow and both unit-test jobs are
ubuntu and windows, and the only macOS runners in the repo are build and
packaging jobs that run no tests. Those six tests plus the real-bundle e2e case
pass on a developer Mac and execute zero times in a green PR, so the comment
should not imply enforcement that is not there.

Refs #14746
---
 src/main/macos-press-and-hold-default.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/main/macos-press-and-hold-default.ts b/src/main/macos-press-and-hold-default.ts
index b4586f7ac6e..c1e04019701 100644
--- a/src/main/macos-press-and-hold-default.ts
+++ b/src/main/macos-press-and-hold-default.ts
@@ -16,6 +16,13 @@ import { writeFileAtomically } from './codex-accounts/fs-utils'
  *
  * AppKit reads the preference while the process starts, so a fresh write lands for the *next*
  * launch, not the current one.
+ *
+ * If this is ever reverted, delete the key as well — AppKit reads the plist, not this file, so
+ * removing the code alone leaves press-and-hold disabled forever for everyone who ran an affected
+ * build, with nothing left in the tree to explain it.
+ *
+ * The `defaults`-binary behaviour this relies on is pinned by the sibling test file, which runs
+ * only on a developer Mac: CI has no macOS test runner, so those tests never execute there.
  */
 
 export const PRESS_AND_HOLD_KEY = 'ApplePressAndHoldEnabled'