ZaStoGram_desktop/Telegram/SourceFiles/test/docs/macos-notifications.md
John Preston 98a090e41f [ai] Document macOS notification evidence for the harness
Task: 2026/10/29/document-the-macos-notification-evidence-recipe-in-the-test-harness
2026-10-29 16:19:46 +04:00

15 KiB

macOS native-notification evidence

Harness guide · Helper index

Read this before a run whose evidence posts a native macOS notification through the legacy NSUserNotification backend (Platform::Notifications::Manager, NS) or the UserNotifications backend (Platform::Notifications::UNManager, UN). Citations name one of three task records under the AI repository's tasks/<task id>/: the ids task 2026/10/28/keep-peer-and-message-ids-out-of-macos-notification-identifiers, the clears task 2026/10/29/remove-macos-notifications-of-deleted-saved-messages-and-read-monoforum-sublists or the mark task 2026/10/29/keep-macos-notifications-working-after-modern-notifications-are-turned-off. A Run, Test or section cited without a file is in that task's work/test.md.

Choosing a bundle id

After a launch that constructed UNManager, usernoted records the bundle id as a modern client and refuses every later NS post from it; an id with no UN launch is accepted as a legacy client (ids task Runs 3 and 5; mark task Run 2 Tests 1 and 2). So one id serves one backend. The table reads the macbook host on 2026-10-29 under macOS 27.0.1 (mark task work/result.md Summary and task.md Facts to recheck; the clears task records no version). Recheck it before relying on it.

Bundle id Recorded state UN authorization Use for
com.tdesktop.TelegramDebug, every checkout's Debug build Modern since the ids task's first UN launch, NS refused since (ids task Run 3); mark never read 2 in every recorded reading, across rebuilds (ids task Runs 2, 4, 8; clears task Run 3) UN only
com.tdesktop.TelegramDebugNsEvidence Made by the ids task, only CFBundleIdentifier changed; delivered there (Runs 5-8) and from new clones in the clears task (Backends, Runs 2, 3; readback only); no UN launch recorded; mark never read Not measured NS
com.tdesktop.TelegramDebugLegacyEvidence ("TG Legacy Evidence") Legacy, no mark; delivered in B0-B2, B2 while other ids were marked; permission request unanswered (mark task Run 1 Test 2; Run 2 Test 2, Campaign side effects) Not measured NS
com.tdesktop.TelegramDebugProvisionalEvidence ("TG Provisional Evidence") Modern since its first launch C1; mark 1, restored after the C3 control, where NS was refused (mark task Run 2 Tests 1, 3, Campaign side effects) 3 after the provisional step, then 2 in C1 and C2, both delivered (Run 2 Tests 1, 8) UN
com.tdesktop.TelegramDebugKeepUnEvidence ("TG KeepUN Evidence") NS at A0, modern since A1, mark 1 (mark task Run 1 Test 1); its NS refusal is inferred, not measured: A3 never ran (Run 2) 1 (denied) in A1 and A1r; provisional request refused (Run 1 Test 1; Run 2 Tests 1, 8) Neither

NS leg: a new clone of ...NsEvidence, else of ...LegacyEvidence, with the option off in its sandbox and its mark absent (backend choice): a launch that selects UNManager converts the id. UN leg: the shared Debug build with the option on in its own sandbox, else a new clone of ...ProvisionalEvidence; read authorization in process (getNotificationSettingsWithCompletionHandler:) and treat anything but 2 (authorized) or 3 (provisional) as a fixture gate, not a product FAIL (mark task Run 1 Test 1, Evidence recovery 1). Make no UN call, not even a settings or delivered-list query, in a launch of a legacy-only id: whether that converts it is not measured (mark task work/decisions.md E4).

Reuse before minting. A minted id stays permanently in System Settings > Notifications and in usernoted's client records, with a defaults domain ~/Library/Preferences/<id>.plist and possibly an unanswered permission request. Deleting the clone removes none of them, and nothing in the workflow undoes a conversion (mark task work/result.md Environment side effects (owner), work/decisions.md Alternatives considered 8; ids task Campaign side effects, Performer assessment (Attempt 1)). Mint only when no id above fits, as com.tdesktop.TelegramDebug<Purpose>Evidence with CFBundleName "TG Evidence" (mark task, preamble), and report it as a side effect. Never restart usernoted, edit com.apple.ncprefs or usernoted's database, or change the defaults of an id the task does not control (mark task Run 1 Evidence recovery 1).

The permission trap. A fresh id's first NS launch queues a system "allow notifications" request: at its first legacy connection, seconds before the post, usernoted logs Sending request for permission and presents an askpermissions record; NS posts still deliver (mark task Run 1 Test 1, Performer assessment (Run 1), evidence/usernoted-excerpts.txt A0 and B0; ids task Run 5). While it stayed unanswered, a later UN launch of the id read status 1, the product's request failed with App Error: Notifications authorization error: Notifications are not allowed for this application, and the provisional step below was refused (mark task Run 1 Test 1 A1, Run 2 Test 1 A1r and Test 8). Nobody could answer on the locked console; what an answer changes is not measured. Never rely on an unanswered prompt, wait for the owner or drive the UI on a locked console (Performer assessment (Run 1)). Never put an NS leg before a UN leg on one id; keep each id on one backend.

How the app picks the backend

Platform::Notifications::Create() in platform/mac/notifications_manager_mac.mm installs UNManager when UseUNManager() in platform/mac/notifications_manager_mac_un.mm is true, else Manager. UseUNManager() needs the mac-modern-notifications option on or the bundle's TelegramUserNotificationsUsed defaults key (the mark) set, and macOS 10.14+ with a bundle identifier. UNManager::Private's constructor sets the mark before its first UNUserNotificationCenter call; the app never clears it (mark task work/decisions.md D1; Run 1 Test 3). The option is per working directory (base::options::init in core/launcher.cpp), so per sandbox; the mark is per OS user and bundle id, shared by every working directory and not inherited by another id (D1; Run 2 Tests 2, 3). defaults read <id> TelegramUserNotificationsUsed prints 1 when set and "Could not find key" or "Domain ... not found" when absent (Run 1 Test 1; Run 2 Tests 1, 3).

With the option off, deleting the mark while no copy of the id runs (defaults delete <id> TelegramUserNotificationsUsed) selects Manager again, but usernoted still refuses it: C3 was refused, and the campaign restored the mark with defaults write <id> TelegramUserNotificationsUsed -bool YES (Run 2 Test 1, Campaign side effects). Do it only as a refusal control on an evidence id the task controls, never on the shared Debug id.

With the Xcode generator the Debug bundle id is com.tdesktop.TelegramDebug (bundle_identifier in Telegram/CMakeLists.txt): one usernoted client for every checkout's Debug build on this Mac, whose NS posts usernoted already refuses (ids task Campaign side effects, Run 3). Its next UN launch of mark-aware source writes the mark; from then on mark-aware Debug launches select UNManager whatever the option says, while older source ignores the mark (mark task work/result.md Environment side effects (owner); work/decisions.md D3). Either way it serves UN legs only.

Making the clone

From the source root, with TASK_DIR set to the task folder, clone the task's own Debug build. A rebuild needs a fresh clone (clears task work/context.md Test environment, Runs 2 and 3; mark task Run 1 Clones, Run 2 Test 7) at a new path: run the whole block again, which makes a new directory under $TASK_DIR/.local/ each time. cp -R onto an existing clone nests the new bundle inside it, and the old executable still launches.

id='com.tdesktop.TelegramDebugNsEvidence'
mkdir -p "${TASK_DIR:?}/.local" &&
  clone="$(mktemp -d "$TASK_DIR/.local/clone-ns-XXXXXX")/Telegram.app" &&
  test ! -e "$clone" &&
  cp -c -R out/Debug/Telegram.app "$clone" &&
  /usr/libexec/PlistBuddy -c "Set :CFBundleIdentifier $id" \
    "$clone/Contents/Info.plist" &&
  codesign --force --sign - \
    --preserve-metadata=entitlements,flags,runtime "$clone" &&
  codesign --verify "$clone" &&
  echo "clone=$clone"

The chain stops at the first failed step; only a run that ends by printing clone=<path> made a usable clone (codesign --verify exited 0). Launch that path as $clone below. codesign -dvv "$clone" shows Identifier=<id>. For an id with a display name in the table, also Set :CFBundleName to it, as the mark task did.

Each leg gets its own ignored .local/ sandbox whose test_TelegramForcePortable is a cp -R copy of the golden; a UN leg adds "mac-modern-notifications": true to the copy's tdata/experimental_options.json, keeping other keys, never in the golden (clears task Run 2 Sandboxes; ids task Run 2). Launch the clone's executable, one clone process at a time, adding the task's --env, --deadline and --quiet flags (clears task Run 2 Launch; mark task Run 1 Launch command):

python3 .agents/skills/process-inbox/scripts/workspace.py test-run \
  --exe "$clone/Contents/MacOS/Telegram" --run-dir "$run" \
  --portable-root "$sandbox"

Launch behavior and the test loop (Test account (portable data) — hard rules) govern launch, portable data and cleanup. Deleting the clone leaves the id registered.

Provisional authorization for a never-used id

Only a campaign that mints an id for a UN leg while nobody is at the console needs this. The mark task's work/test-overlay.patch keeps it as disposable overlay code: TestKeepUnProbe::ProvisionalSeam(), with SeamAllowlisted(), SeamLogSettings(), SeamRequestProvisional() and the helpers and includes they use, in the _DEBUG block appended to Telegram/SourceFiles/platform/mac/specific_mac.mm; a forward declaration and one call right after ApplyAppNapHold() in Test::ApplyStartupOverrides() (Telegram/SourceFiles/test/test_agent.cpp). Adapt those parts into the task's own overlay, not the permanent harness. Core::Application::run() calls the overrides before startDomain(), and the seam read the dummy manager (manager_at_seam=other(type=0)), so it runs before the product's manager exists (mark task Run 1 Evidence recovery 1, Run 2 Test 8).

It reads the settings, requests UNAuthorizationOptionProvisional and reads them again, waiting at most 5 s per read and 10 s for the request (kSeamSettingsWait, kSeamRequestWait). Without -testagent (Test::Active()) it returns silently; otherwise it logs one PROVISIONAL_SEAM ... stage=gate ... run=<0|1> gate=[<first failed gate>] row and calls UN only when all of these hold:

  • the working directory has the disposable copy's testing marker;
  • TDESKTOP_TEST_PROVISIONAL=1, passed with test-run --env;
  • the running bundle id is on an allowlist of the campaign's own UN ids, never the shared Debug id (the original lists ...KeepUnEvidence and ...ProvisionalEvidence; put the new id there);
  • Platform::Notifications::UseUNManager() is true, so the product contacts UN in that launch anyway.

Keep every gate (mark task work/test-overlay.patch, work/decisions.md D5, Run 2 Tests 2 and 8). The new id's first launch ever must be this UN launch, with the option pre-seeded in its sandbox copy. In C1, the first launch of ...ProvisionalEvidence, the status went from 0 to 3, read 2 after the product's own request, and the post was delivered; C2, with no seam and the option off, read 2 and delivered (Run 2 Tests 1, 8). It does not rescue a denied id (A1r). The seam makes the first UN contact, so such a launch cannot measure the product's own (Run 2 Test 3), and C1's product request still queued an askpermissions record (Test 8).

Capturing usernoted

Run log stream --predicate 'process == "usernoted"' --debug --style syslog from before the launch until after the client exits (mark task Run 1 Capture; ids task Run 2). An absence claim needs a live stream with no gap over the whole launch (mark task work/decisions.md E5). log show is only a cross-check: about 25 minutes later the store had dropped debug lines such as Added modern connection but kept Delivering and refusal lines (mark task Run 2 Test 2). Recorded lines (mark task evidence/usernoted-excerpts.txt and Performer assessment (Run 1); ids task evidence/usernoted-legacy-modern.txt):

  • delivery: Delivering <NotificationRecord app:"<id>" ident:"<ident>" req:"<request id>" ..., after Request from <LegacyConnection identifier: <id> ...> to add request (NS) or Added request <NotificationRecord app:"<id>" ... (UN);
  • refusal: Legacy client <id> connecting to modern client. You can't mix modern clients with legacy clients., Ignoring connection <LegacyConnection identifier: <id> ...>, then Denying message 7 from connection <LegacyConnection ...> per call (C3 also logged one Denying message 3);
  • conversion to a modern client: Added modern connection for <id> <pid> (); a legacy client logs Added legacy connection for <id> pid: <pid>;
  • queued permission request: Sending request for permission, then Added request <NotificationRecord app:"com.apple.notificationcenter.askpermissions" ... req:"<id>" and Presenting it;
  • provisional grant: Authorization set for <id> to allow: YES critical: NO provisionally: YES.

Setting modern authorization [badge, sound, alert] for <id> alone is no conversion: a new legacy client logs it too (the excerpts' header). A delivery is the exact request identifier read back in process (NS deliveredNotifications; UN getDeliveredNotificationsWithCompletionHandler:, in a UN launch only) plus its Delivering line inside the post window (mark task Run 2 Test 1). Keep raw captures in the task's ignored .local/; tracked evidence quotes lines cut after req: (the excerpts' header; ids task work/test.md preamble).

Not measured

Do not mint an id to measure any of these.

  • Persistence of usernoted's modern record across a reboot or a usernoted restart, and macOS versions other than 27.0.1 (mark task task.md Facts to recheck).
  • Whether a read-only UNUserNotificationCenter call converts an id (same; work/decisions.md Alternatives considered 3).
  • Whether a new clone of an authorized evidence id keeps its authorization: the shared Debug id stayed at 2 across binaries rebuilt in place (ids task Runs 2, 4, 8; clears task Run 3), and ...KeepUnEvidence's new clone read 1, but that id was denied already (mark task Run 2 Tests 1, 7).
  • A never-used id's first UN launch without the provisional step (mark task task.md Facts to recheck: it "may meet the system permission prompt").
  • What answering a pending permission request does, and whether such requests stay in Notification Center (mark task work/result.md Environment side effects (owner); Run 2 Campaign side effects).
  • The current mark of the shared Debug id and of ...NsEvidence: no record reads it, and the mark task launched neither (same). Read it before relying on it.