Nudge 2.1.3 + SOFA + Grace Period Question

[ibdavet79-spec]

Hi all,

I'm looking for some clarification on the expected behaviour of allowGracePeriods and gracePeriodInstallDelay when using Nudge 2.1.3 with SOFA and:
requiredMinimumOSVersion = latest-minor

What we're trying to achieve
Our goal is for every user to receive the same 14-day onboarding/grace period from the point Nudge is deployed, regardless of how old the Mac is or when the current macOS update was released.

For example:
• User A receives Nudge today on a Mac that has never had Nudge installed.
• User B receives Nudge today on an existing Mac that is several months old.
• User C receives Nudge today after being migrated to a new Nudge deployment.

In all three cases, we'd like the user to receive a fresh 14 days from the date Nudge is deployed, rather than inheriting a deadline that has already partially elapsed because the macOS update was released some time ago.

We're therefore using:

allowGracePeriods = true
gracePeriodInstallDelay = 336
gracePeriodPath = /Library/Application Support/Nudge/gracePeriod
with a marker file created at deployment time.

Configuration
requiredMinimumOSVersion
latest-minor

allowGracePeriods

gracePeriodInstallDelay
336

gracePeriodLaunchDelay
0

gracePeriodPath
/Library/Application Support/Nudge/gracePeriod

standardMinorUpdateSLA
14

nonActivelyExploitedCVEsMinorUpdateSLA
14

activelyExploitedCVEsMinorUpdateSLA
14

What I've observed
When I first tested this configuration, it appeared to work as expected. I saw log entries along the lines of:
Device permitted for gracePeriodInstallDelay

setting date from:
...

to:
...

This led me to believe that Nudge was taking the grace-period marker timestamp and extending the required installation date accordingly.
However, after doing considerably more testing, I can no longer reproduce this behaviour.

I've tested:
• Existing Mac running Nudge 2.1.3.81860
• Freshly imaged Mac
• Configuration profile deployed before the first Nudge launch
• Grace-period marker created before the first Nudge launch
• Fresh user state
• Fresh managed preferences
• Nudge stopped before testing
• Grace-period marker recreated multiple times

The profile is definitely installed and contains:
allowGracePeriods = true
gracePeriodInstallDelay = 336
gracePeriodPath = /Library/Application Support/Nudge/gracePeriod

The marker file also definitely exists and has a fresh timestamp before Nudge launches.
What Nudge is doing

On both machines, Nudge immediately evaluates SOFA and calculates a deadline from the SOFA feed.
For example:
Setting requiredInstallationDate via SOFA to 2026-08-20 00:00:00 +0000
SOFA Matched OS Version: 15.7.9

New Nudge event detected - resetting all deferral values

On another machine:
Setting requiredInstallationDate via SOFA to 2026-08-31 00:00:00 +0000
SOFA Matched OS Version: 26.6.2

What I don't see is:
Device permitted for gracePeriodInstallDelay
or:
Device within gracePeriodLaunchDelay

I also can't find any evidence in the logs that the timestamp of the grace-period marker is influencing the SOFA-derived deadline.
Searching the Nudge logs for grace returns nothing.

My question

When using:
requiredMinimumOSVersion = latest-minor
with SOFA-driven deadlines, should gracePeriodInstallDelay modify the SOFA-derived requiredInstallationDate for a newly deployed Nudge installation?
In other words, should a newly deployed Nudge installation be able to receive a fresh 14-day grace period from the deployment/marker timestamp, even if SOFA has calculated an earlier deadline based on the macOS update release date?

Or does the SOFA-derived requiredInstallationDate take precedence, effectively preventing the grace-period logic from extending the deadline in this scenario?

I noticed the Nudge changelog/documentation indicates that the grace-period logic is evaluated after the SOFA assessment, so I'm particularly interested in understanding how those two calculations are expected to interact.

If grace periods are expected to work with latest-minor and SOFA, what log entries should I expect to see that confirm Nudge has recognised and applied the grace-period marker?

Thanks in advance — I'm mainly trying to establish whether this is expected behaviour, a configuration issue, or potentially a change/regression in the 2.1.x releases.

[erikng]

Could you try the Nudge 2.1.4.81863 prerelease and let us know whether it produces the onboarding behavior you expected?

This changes installation grace to a fixed allowance for the first event observed for a deployment. The deadline is anchored to the marker's creation date and is saved across launches, including after the marker ages out. SOFA is still evaluated first, and the logs now show both its original deadline and the effective grace deadline.

Configuration and expected timeline

Your settings should remain under userExperience:

Key	Value
allowGracePeriods	true
gracePeriodPath	/Library/Application Support/Nudge/gracePeriod
gracePeriodLaunchDelay	0 hours
gracePeriodInstallDelay	336 hours (14 days)

For illustration, assume the marker was created August 18 at 00:00 UTC, the first launch is August 18, and SOFA calculates August 20 at 00:00 UTC. These are example dates; use your test marker's actual creation time when checking your results. The required OS version and update requirements remain unchanged throughout this table.

Nudge launch (UTC)	Marker age	Launch delay	Install delay	Expected effective deadline / behavior
Aug 18, 00:00	0 hours	0	336	Sep 1, 00:00; record the first event and its deadline
Aug 19, 00:00	24 hours	0	336	Sep 1, 00:00; reuse the saved deadline
Aug 20, 00:00	48 hours	0	336	Sep 1, 00:00; passing the original SOFA deadline does not change it
Aug 21, 00:00	72 hours	0	336	Sep 1, 00:00; do not add another 14 days from this launch
Aug 31, 00:00	312 hours	0	336	Sep 1, 00:00
Sep 1, 00:00	336 hours	0	336	Sep 1, 00:00; do not revert to August 20 when the marker ages out
Sep 2, 00:00	360 hours	0	336	Sep 1, 00:00, now overdue

The effective first-event deadline is the later of the original deadline and marker creation + install delay + launch delay. Thus a later original deadline, such as September 10, stays September 10. Launch suppression is separate: with your launch delay of zero, Nudge is not suppressed by that setting.

What to inspect in the user's plist

Look in the affected logged-in user's ~/Library/Preferences/com.github.macadmins.Nudge.plist for firstRunGracePeriodState. This is internal per-user state, not a key to add to the configuration profile. It is stored as encoded plist data, so a normal plist view may display a data blob.

Run this read-only command as the affected user, without sudo, to decode it:

/usr/bin/defaults export com.github.macadmins.Nudge - \
  | /usr/bin/plutil -extract firstRunGracePeriodState raw -o - - \
  | /usr/bin/base64 -D \
  | /usr/bin/plutil -p -

For the unchanged example event, expect:

Decoded field	Expected value
markerPath	Your configured marker path
markerCreationDate	Aug 18, 00:00 UTC
firstEvent.configuredOSVersion	latest-minor
firstEvent.requiredOSVersion	The actual OS version selected by SOFA, such as 15.7.9
firstEvent.originalDeadline	Aug 20, 00:00 UTC
firstEvent.configuredDeadline	1970-01-01 when no explicit installation date is configured; this is the sentinel that allows SOFA to calculate the date
firstEvent.policy.gracePeriodLaunchDelay	0
firstEvent.policy.gracePeriodInstallDelay	336
installationDeadline	Sep 1, 00:00 UTC, unchanged across relaunches and expiry
invalidated	false, including after September 1; expiry alone does not invalidate the saved event

Changes that should end the allowance

As a separate test, after establishing the first event, change its update requirements:

Change	Expected result
Set a new deadline of August 25 for the same required OS version	Honor August 25; invalidated becomes true
Revert that deadline to August 20	Honor August 20; invalidated stays true, so September 1 is not restored
Change the required OS version, SLA, or grace-delay settings	End the installation allowance and honor the current event's deadline
Change only text or appearance	Keep the first event's saved deadline; invalidated remains false

After invalidation, the saved installationDeadline and firstEvent can still contain the original values as history. invalidated: true means that saved deadline is no longer applied.

Logs to check

Start this before launching Nudge:

/usr/bin/log stream --style compact --level info \
  --predicate 'subsystem == "com.github.macadmins.Nudge"'

Message	What it confirms
Evaluating grace periods	Actual evaluation time, original deadline, marker creation date/age, and resolved delays
Recorded first grace-period event	First-event deadline was saved
Applying first-event grace deadline	Original and effective deadlines; this should still appear after marker expiry for the same event
Installation grace ended - update requirements changed	A later event takes precedence
Installation grace remains ended for this deployment	Relaunching or reverting settings did not restart grace
First grace-period event has no installation allowance	The marker was already ineligible on first observation, or a previous event was already known

For a clean first-deployment test, use a test user without prior Nudge event history and a freshly created marker. Keep that same marker and user state throughout the relaunch/expiry tests. Touching an existing file does not reset its creation date, and deleting firstRunGracePeriodState would remove the history being tested. An older installation with a different previously recorded target version will not automatically receive a new first-event allowance when upgraded.

Please share whether the displayed deadline stays fixed, the relevant decoded fields, and the grace/SOFA log lines if anything differs. This prerelease also fixes grace-period evaluation ignoring -simulate-date, so date simulation can be used on the test machine without waiting 14 days. Avoid -demo-mode for these configuration tests because it bypasses grace periods.