fix(session-notification): add grace period to prevent late events from cancelling idle notifications

[acamq]

Fixes #2012 (rebased, conflicts resolved, additional fixes applied)

---

Summary

Fixed a bug where session notifications appeared on user interrupt but not when the agent idled naturally. Added a configurable grace period to ignore late-arriving activity events that incorrectly cancelled pending notifications.

Root Cause

When the agent idles naturally:

1. session.idle fires → notification scheduled (1500ms delay)
2. Late-arriving events fire (e.g., message.updated with final metadata, tool.execute.after)
3. These trigger markSessionActivity() which cancels the notification
4. No notification appears ❌

When user interrupts:

1. session.idle fires → notification scheduled
2. No late-arriving events (session was aborted)
3. Notification fires after 1500ms ✓

Solution

Add a grace period (default 100ms) after scheduling a notification. Activity events arriving within this window are ignored—they're stale events from before the idle state, not genuine user activity.

Changes

Original PR by @crazyrabbit0:

• src/hooks/session-notification-scheduler.ts

  • Added scheduledAt Map to track when notifications are scheduled
  • Added activityGracePeriodMs config option (default: 100ms)
  • Modified markSessionActivity() to ignore activity within grace period
  • Updated all exit paths to clean up scheduledAt state

• src/hooks/session-notification.test.ts

  • Added 2 tests covering grace period behavior
  • Updated 3 existing tests with explicit activityGracePeriodMs: 0

Additional fixes:

• Rebased onto latest dev to resolve merge conflicts
• Fixed indentation issues that moved functions/tests out of scope
• Added activityGracePeriodMs to SessionNotificationConfig interface for type safety

Testing

bun test src/hooks/session-notification.test.ts

All 18 tests pass.

---

Summary by cubic

Fixes idle notifications not showing on natural idle by adding a short grace period that ignores late activity events.

• Bug Fixes

  • Added configurable activityGracePeriodMs (default 100ms) to ignore stale activity right after scheduling.
  • Tracked scheduledAt per session and cleaned up on all exit paths, respecting max session limits.
  • Exposed the option in SessionNotificationConfig.
  • Added two tests for grace behavior; updated existing tests to set grace to 0.

• Dependencies

  • Restored bun.lock from dev; no runtime changes.

^{Written for commit 9b4c826. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[acamq]

Hi @crazyrabbit0! Thank you for your contribution in #2012 — the grace period implementation is solid and addresses a real race condition in the idle notification system.

I created this new PR instead of updating the original because:

1. The original PR branch was based on a commit that had pre-existing corruption in event.ts (duplicate function declarations from a bad merge)
2. Rebasing onto latest dev resolved the issue but required a force push to your fork, which I can't do
3. There were indentation issues that moved inner functions out of scope

Additional changes I made on top of your work:

• Fixed indentation in session-notification-scheduler.ts and session-notification.test.ts
• Added activityGracePeriodMs to the SessionNotificationConfig interface for type safety

Could you please sign the CLA so we can get this merged? You can do so by following the instructions in the above comment.

Thanks again for the fix! 🙌

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Requires human review: The PR introduces a 100ms grace period that changes cancellation behavior for fast activity and includes a dependency update in the lockfile, which prevents 100% certainty of no regressions.}

[crazyrabbit0]

I have read the CLA Document and I hereby sign the CLA

[acamq]

Thank you again @crazyrabbit0! Sorry for the back-and-forth confusion with the different PRs and where to sign, but we did it in the end. Your contributions are much appreciated! I will merge this once all checks finish