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

[crazyrabbit0]

Summary

• Fixed a bug where session notifications appeared on user interrupt but not when the agent idled naturally
• Added a 100ms grace period to ignore late-arriving activity events that incorrectly cancelled pending notifications
• Introduced activityGracePeriodMs config option (default: 100ms, configurable)

Changes

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

  • Added scheduledAt Map to track when notifications are scheduled
  • Added activityGracePeriodMs config option with 100ms default
  • Modified markSessionActivity() to return early if activity happens within grace period
  • Updated cleanupOldSessions(), cancelPendingNotification(), executeNotification(), deleteSession() to manage scheduledAt state

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

  • Added test: "should ignore activity events within grace period"
  • Added test: "should cancel notification for activity after grace period"
  • Updated 3 existing tests to use activityGracePeriodMs: 0 for cancellation behavior

Root Cause Analysis

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 ✓

Testing

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

All 13 tests pass:

• 2 new grace period tests
• 11 existing tests (3 updated for explicit activityGracePeriodMs: 0)

---

Summary by cubic

Fixes idle notifications being cancelled by late activity when a session idles naturally. Adds a 100ms grace period (configurable) so the notification still fires as expected.

• Bug Fixes

  • Ignore activity events that arrive within a short grace period after scheduling an idle notification.
  • Track scheduledAt timestamps and clean up timer/state on schedule, cancel, execute, and delete.

• New Features

  • New config: activityGracePeriodMs (default 100ms) to control the grace period.

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

[github-actions]

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

[crazyrabbit0]

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

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

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

_{Auto-approved: Tests cover the new grace period feature; all tests pass; cubic found no issues; changes match criteria of no regressions.}