Task: 2026/10/29/document-the-macos-notification-evidence-recipe-in-the-test-harness
15 KiB
macOS native-notification evidence
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
testingmarker; TDESKTOP_TEST_PROVISIONAL=1, passed withtest-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
...KeepUnEvidenceand...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>" ..., afterRequest from <LegacyConnection identifier: <id> ...> to add request(NS) orAdded 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> ...>, thenDenying message 7 from connection <LegacyConnection ...>per call (C3 also logged oneDenying message 3); - conversion to a modern client:
Added modern connection for <id> <pid> (); a legacy client logsAdded legacy connection for <id> pid: <pid>; - queued permission request:
Sending request for permission, thenAdded request <NotificationRecord app:"com.apple.notificationcenter.askpermissions" ... req:"<id>"andPresentingit; - 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.mdFacts to recheck). - Whether a read-only
UNUserNotificationCentercall converts an id (same;work/decisions.mdAlternatives 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.mdFacts 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.mdEnvironment 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.