dan-snelson/DDM-OS-Reminder v5.3.0

DDM OS Reminder (5.3.0)

on GitHub

30-Oct-2026

• 🆕 A reminder that came due while the Mac slept could launch during a Maintenance DarkWake, before the network was ready. Both icon downloads then timed out (about 20 seconds), both icons fell back to the Finder icon, and the dialog waited on a sleeping or locked display until the user returned (Issue #172; thanks, James Anzaldua!)
  • DarkWake deferral: dor-starter.zsh no longer launches dor.zsh while pmset -g systemstate lists CPU without Graphics. It logs [NOTICE] DarkWake detected (system capabilities: …); deferring reminder launch to the next heartbeat. and leaves dor-state.plist unchanged, including LastBootReevaluation, so the due reminder runs on the first heartbeat after a full wake. Unrecognized pmset output fails open and launches as before.
  • dor.zsh repeats the check just before it builds the dialog (after any MeetingDelay wait). A DarkWake run logs [NOTICE] No reminder shown: the Mac is in a Maintenance DarkWake (system capabilities: …) and, for starter-launched runs, schedules an exact NextScheduledReminder 60 seconds later instead of the next DailyReminderTimes slot. No mode bypasses this check, so pre-deadline threshold, aggressive, and Force reminders appear at the first full wake; a Force-mode timer can no longer count down to a restart on a display nobody can see. Demo mode is unchanged.
  • Force mode checks again before each redisplay in the same run and before a timer-driven restart, so a Force dialog that began during a full wake cannot redisplay or restart after the Mac enters a Maintenance DarkWake. The run logs [NOTICE] Force restart redisplay deferred: the Mac is in a Maintenance DarkWake (system capabilities: …); no restart requested. (or Force restart timer expiry deferred: …), requests no restart, and, for starter-launched runs, schedules an exact NextScheduledReminder 60 seconds later. Clicking Restart Now still restarts.
  • Icon downloads: downloadBrandingAssets waits up to 5 seconds for scutil -r to report the macOS icon host as reachable (if it never does, both downloads are skipped and the cache and fallbacks below apply), then downloads the overlay and macOS icons in parallel with --connect-timeout 4 --max-time 10 --retry 1. Only image content counts as success, so a captive-portal page is rejected. The curl error now appears in the [ERROR] Failed to download … line instead of on a separate raw line.
  • Icon cache: each successful download is copied to root-owned /Library/Management/<rdnn>/dor-icon-macos-<major>.png (dor-icon-macos-default.png when the major version is not numeric), dor-icon-overlay-light.png, or dor-icon-overlay-dark.png (not in demo mode). When a download fails, the cached copy is used. All and Script redeployments keep the cache; Uninstall removes it.
  • Fallbacks: with no download and no cache, the macOS icon falls back to /System/Library/CoreServices/Software Update.app (then Finder.app), and the dialog shows no overlay icon instead of the Finder icon. An empty OrganizationOverlayIconURL now also shows no overlay icon. SwapOverlayAndLogo keeps the macOS icon as the primary icon when no overlay icon is available. Resources/reminderDialogPreferenceTest.zsh previews the no-overlay and SwapOverlayAndLogo fallbacks; it still hands the macOS icon URL to swiftDialog, so it does not preview the Software Update.app fallback.
  • No changes to preference keys, defaults, or DDM trust rules.
  • Not covered: a locked screen or a sleeping display while the Mac is otherwise fully awake. These still show the reminder, which the user sees on return.
• 🆕 After a reboot, macOS can re-pad a past-due deadline to about one hour after login (setPastDuePaddedEnforcementDate … (usersLoggedIn=1)), but dor-starter.zsh kept exiting quietly until the stored NextScheduledReminder, so the new deadline and its pre-deadline thresholds could pass with no reminder (Issue #165)
  • Once per boot, the first heartbeat that finds a console user other than loginwindow, _mbsetupuser, or root launches dor.zsh even when NextScheduledReminder is in the future. Heartbeats before login exit quietly, so the re-evaluation is not used up at the login window.
  • The starter records the boot in the new runtime-only dor-state.plist key LastBootReevaluation (the kern.boottime epoch) on any launch with a console user, and logs [NOTICE] Starter launch after boot; re-evaluating deadline (NextScheduledReminder: …).
  • The post-boot run re-resolves the deadline, including the existing wait of up to 5 minutes for a refreshed padded date. It then shows a reminder only when a pre-deadline threshold, aggressive mode, or Force mode is due, or when the stored schedule has come due. Otherwise it moves NextScheduledReminder earlier for a pending threshold or aggressive-mode start, never later, and logs No reminder shown: post-boot re-evaluation found no reminder due.
  • NextScheduledReminder=FALSE, dor.pid overlap protection, manual runs, and demo runs are unchanged. No changes to preferences, defaults, or DDM trust rules.
  • Not covered: logging out and back in without a reboot.
• Fixed: past-deadline aggressive mode was never scheduled when the next DailyReminderTimes slot came after the aggressive-mode start, leaving a Mac past its deadline without reminders until the next baseline slot (for example, overnight after a final pre-deadline threshold reminder at 16:25 for a 16:29 deadline) (Issue #164)
  • The aggressive-mode start (effective deadline plus AggressiveModePastDeadlineHours) is now a scheduling candidate alongside pending pre-deadline thresholds and baseline slots. The earliest wins.
  • Applies after pre-deadline threshold reminders, after regular reminders shown between the deadline and the aggressive-mode start, and to quiet-period and Update Tonight scheduling, which aggressive mode already bypasses at runtime.
  • Skipped while /Library/Management/<rdnn>/dor-aggressive-kill exists; the next run re-evaluates once support removes it.
  • Runtime re-checks aggressive mode when the dialog returns. A reminder shown before the aggressive-mode start and answered after it now schedules AggressiveModeFrequencyMinutes from that answer. Before, a pre-deadline threshold reminder left open past the aggressive-mode start (for example, the 16:25 threshold answered at 18:31) waited until the next baseline slot, and other reminders waited for the quiet period. Logged as (Scheduled aggressive-mode redisplay after late <n>-minute pre-deadline threshold acknowledgment) or (Scheduled aggressive-mode redisplay after return code <code>). The same re-check covers a dialog closed automatically for a pre-deadline threshold refresh but processed after the aggressive-mode start (for example, after sleep); a non-threshold dialog in that case logs (Scheduled aggressive-mode redisplay after dialog auto-refresh for <n>-minute pre-deadline threshold).
  • Logged as [NOTICE] Scheduled next daemon reminder for … (…: aggressive-mode start (<n> hour(s) past effective deadline)) or (Quiet-period bypass for aggressive-mode start …).
  • No changes to preferences, defaults, DDM trust rules, or suppression rules.
• Fixed: a Mac that already met its DDM declaration could still evaluate the DDM Emergency Fallback when the resolver rated its state conflict. This happened when softwareupdated logged No updates found for DDM to enforce after the Mac installed its DDM-enforced update while install.log still showed the met declaration, or when softwareupdated offered a newer macOS (Available descriptor <offered> disagrees with DDM declaration <version>), for example macOS 27.0.1 with a 27.0.1 declaration while 27.2 is available. The run logged a [WARNING] and, when dor-fallback-declaration.plist existed, evaluated the fallback. A fallback targeting a newer macOS could then show a reminder for a version DDM does not enforce.
  • When the conflict is only Declaration persisted after 'No updates found for DDM to enforce' or Available descriptor <offered> disagrees with DDM declaration <version>, and the installed macOS meets that declaration, the resolver logs at [NOTICE] (…; macOS <installed> already meets it) instead of [WARNING].
  • That case now skips fallback evaluation and logs DDM Emergency Fallback not evaluated: macOS <installed> already meets DDM-enforced macOS <version> (DDM status=conflict) when a fallback plist exists.
  • The run ends with No reminder shown: macOS <installed> already meets DDM-enforced macOS <version>; softwareupdated has nothing left to enforce (status=conflict) for a leftover declaration, or No reminder shown: macOS <installed> already meets DDM-enforced macOS <version>; the different update softwareupdated offers (macOS <offered>) is not enforced by DDM (status=conflict) for a different offered update. The different-offered-update outcome was previously logged only when no fallback was configured.
  • Resolver status stays conflict, so the DDM update check: line and both Pending-OS Extension Attributes are unchanged. A conflict between two different declarations, and missing, noMatch, and invalidVersion, still evaluate fallback.
  • No changes to preference keys, defaults, or scheduling.
• Fixed: a pre-deadline threshold reminder was recorded as delivered even when swiftDialog never showed it to the user (for example, Return Code: 1 while macOS was shutting down), so a reminder the user never saw used up that threshold for the deadline
  • Only user-interaction return codes (0, 2, 3, 4, 10, the same codes that start the quiet period) and the open-dialog refresh now add a threshold to PreDeadlineThresholdDelivered.
  • Any other return code logs [NOTICE] Pre-deadline threshold <n>-minute reminder not marked delivered; return code <code> is not a user interaction. The next run shows that threshold if it is still the latest one due, or records it in PreDeadlineThresholdSkipped once a later threshold is due.
  • A starter-launched run then schedules an exact NextScheduledReminder 60 seconds later, logged as [NOTICE] Scheduled next daemon reminder for … (Pre-deadline threshold <n>-minute reminder retry after return code <code>). Without the retry, a failed final threshold (for example, the 5-minute reminder) kept the schedule calculated before display, so the next reminder could wait until the aggressive-mode start.
  • The retry is skipped when it would land at or after the effective deadline, and for return code 9 (SIGKILL), which is usually a persistent block.
• Fixed: when a Mac woke from sleep after the effective deadline with a threshold reminder still open, the open-dialog check closed that reminder and nothing replaced it until the next scheduled run
  • Once the effective deadline has passed, the open reminder now stays on screen, logged as [NOTICE] Pre-deadline threshold <n>-minute reminder became due while a reminder dialog was open, but the effective deadline has passed; leaving the open dialog in place.
  • Before the deadline, a newly due threshold still closes the open dialog and shows the newer threshold reminder.
• Fixed: when swiftDialog exited with code 9, the runtime logged swiftDialog exited with code 9; confirm your .plist or .mobileconfig is installed: and the expected preference paths. Code 9 does not mean missing preferences: dialogcli relays the signal number when Dialog is killed, so 9 is SIGKILL, usually from a code-signature or endpoint-security block. Admins with valid preferences were sent in the wrong direction.
  • The [WARNING] now reads swiftDialog exited with code 9; Dialog was killed (SIGKILL) before <user> could respond, usually by a code-signature or endpoint-security block. Next step: …, naming a codesign --verify check on Dialog.app and security or allowlisting tools. The Expected managedPreferencesPlist / Expected localPreferencesPlist [INFO] lines are removed from this path.
  • Exit handling is unchanged: the run still ends with code 9, and the reminder is not marked as a user interaction.
  • No changes to preference keys, defaults, or scheduling.
• Fixed: launchDaemonManagement.zsh could report a failed swiftDialog install or upgrade as successful. It ignored the installer exit status, and after an upgrade it checked only that dialogcli existed, so a Mac that kept an older swiftDialog logged swiftDialog version … installed; proceeding... and finished deployment.
  • An installer failure now removes the temporary download and exits 1 with [FATAL ERROR] swiftDialog installer failed for <url>.
  • After installing, the script reads the dialogcli version again. It exits 1 with [FATAL ERROR] swiftDialog version '<version>' after install; swiftDialog 3.1.0.4994 or newer is required. when the version is empty or older than swiftDialogMinimumRequiredVersion.
  • The swiftDialog check runs before the reset, so a failed install leaves the existing deployment in place. Rerun the deployment once swiftDialog 3.1.0.4994 or later installs.
  • No changes to preference keys, defaults, or runtime behavior.
• 🆕 Re-assembling from a prior dev or test .plist / .mobileconfig into another lane carried its Assembled or TEST placeholder text into the new artifacts, so a dev configuration promoted with --lane prod still showed that text in the production .plist and .mobileconfig (Issue #168)
  • assemble.zsh now rewrites its own leading lane marker (Assembled, legacy Sample, or TEST, optionally after leading <br> tags) in imported string values to match the selected lane: removed for prod, TEST for test, and Assembled for dev.
  • Matching is case-sensitive and anchored to the start of each value, so admin copy such as Latest, Testing, or sample elsewhere in a string is never changed.
  • Logged as 🧹 Normalized lane marker in <n> imported value(s) for '<lane>' lane.
  • A prior file ending in -dev.plist or -test.plist still selects that lane automatically; pass --lane prod to promote it.
  • A valid --lane now skips filename lane inference regardless of argument order, so --lane prod after the file path no longer logs 🔎 Inferred deployment mode from prior plist: 'dev' before 📦 Deployment Mode: prod.
  • No changes to preference keys, defaults, or runtime behavior.
• Fixed: a missing or invalid --lane value (for example, --lane production) printed Defaulting to interactive prompt., then re-parsed that value as a positional RDNN, so assemble.zsh could exit 0 with artifacts named for RDNN production. assemble.zsh now exits 1 with ❌ Invalid lane: '<value>'. Valid options: dev, test, prod before importing or generating anything.
• 🆕 Resources/diagnoseReminderState.zsh (1.6.5) adds --rdnn <rdnn>, so a Mac Admin running the helper on the affected Mac no longer types up to nine paths (Issue #166)
  • Each input that is not supplied is read from its live path: the effective ScriptLog (Managed, then Local) or /var/log/<rdnn>.log, /var/log/install.log, both <rdnn>.dorm.plist preference layers, dor-state.plist, dor-fallback-declaration.plist, SoftwareUpdateDDMStatePersistence.plist, the LaunchDaemon plist, and whether dor-aggressive-kill exists.
  • Explicit flags always win. An invalid RDNN exits 64; a missing client log or install.log exits 66 and names the path. The supplied RDNN joins RDNN detection, so a mismatch is still reported as a conflict.
  • Missing optional files are reported as not present on this Mac (or unreadable on this Mac). A Mac with neither preference plist is reported with script defaults, which matches the runtime.
  • Fact-sheet and report-skeleton file statuses now read supplied (was received), not in upload, inferred (--rdnn), not present on this Mac, or unreadable on this Mac.
  • The fact sheet's Declaration candidates table now groups identical install.log candidates into one row with first seen, last seen, and count, so a full install.log no longer produces hundreds of repeated rows. The fact-sheet title links to snelson.us/ddm, and the report's redaction sentence says "raw client files" instead of "raw uploads".
  • install.log marker headings and report bullets now quote the log text they match (for example, `No updates found for DDM to enforce` lines: none), so an empty section reads as "this log line was not found" rather than as a verdict.
  • Report section 7 (Do the client log and install.log agree?) now opens with a helper table that puts the client log's last DDM update check: result (version, declared deadline, status, source) beside the latest install.log declaration span. Pre-5.2.0 logs use their Resolved DDM declaration lines. The agent still writes the Yes. / No. / Not comparable. answer.
  • Report section 8 (Likely cause and next steps) now opens with recorded evidence from the last run: its outcome, the runtime's own No reminder shown: and Next step: text, the latest user action, the latest scheduling line, and NextScheduledReminder. The agent still writes the cause and next steps.
  • Non-root runs add a note that root-only files may be unreadable; run with sudo. The helper stays read-only, the RDNN is never auto-discovered, and redaction is unchanged.
• 🆕 Resources/diagnoseReminderState.zsh adds opt-in --no-redaction, so a Mac Admin diagnosing several Macs can tell the reports apart and match them to MDM records
  • Usernames, first names, /Users paths, install.log computer names, and serial numbers appear as logged. The fact-sheet header and report section 9 say the output is not redacted.
  • The fact-sheet and report-skeleton identity tables add Computer name and Serial number rows: from this Mac (scutil --get ComputerName, IOPlatformSerialNumber) with --rdnn, otherwise from the latest install.log computer name and a labeled client-log Serial Number: line.
  • The suggested report filename adds the computer name and -unredacted, for example ddm-os-reminder-us.snelson-Mac-Lab-07-unredacted-2026-10-21-161500.md.
  • With --rdnn, the full output is also saved to /Library/Management/<rdnn>/…-unredacted-<timestamp>-fact-sheet.md (mode 0600). The helper never creates that directory; a missing, symbolic-link, non-root-owned, or unwritable directory still prints the fact sheet and exits 73. Without --rdnn, nothing is saved.
  • Default runs are unchanged: redacted, and they write nothing.
• Resources/diagnoseReminderState.zsh follows the 5.3.0 runtime changes. Checklist updated to reminderDialog.zsh 5.3.0; preference defaults are unchanged.
  • Reports LastBootReevaluation and describes the post-boot exception in its starter rule.
  • Includes DarkWake lines in the latest-run decision lines and describes the starter's DarkWake exit. A post-boot run's latest-run lines now start at the starter's Starter launch after boot line and include Post-boot re-evaluation lines, which earlier helper versions omitted.
  • Lists the macOS updates softwareupdated offered (PrimaryDescriptor: … SU: install.log lines), grouped by descriptor, version, and build with first seen, last seen, and count. A conflict from Available descriptor <offered> disagrees with DDM declaration <version> previously had no matching evidence in the fact sheet.
  • Fixed: the helper treated any script that shares ScriptLog and logs <name> (<version>): … [PRE-FLIGHT] Initiating as a DDM OS Reminder run. On a Mac where another script ran last, the fact sheet reported that script's name and version, no resolver status, and its outcome as the last run. The helper now takes the runtime script name from DDM OS Reminder log lines, counts only that script's runs and Return Codes, and names the other scripts in an identity note.
• Fixed: Resources/createSelfExtracting.zsh (2.4.1) with no ddm-os-reminder-*.zsh in Artifacts/ ran a bare ls -t, so it could encode an unrelated file from the current directory instead of stopping. It now exits with ❌ Error: No file matching 'ddm-os-reminder-*.zsh' found in …. Generated wrappers are unchanged.

What's Changed

• 5.3.0 by @dan-snelson in #175

Full Changelog: v5.2.0...v5.3.0