Align notification next-step taxonomy

[TraderSamwise]

Summary

• add a next_step alert kind for idle turn-end notifications
• publish idle transition notifications as next-step alerts instead of generic needs-input alerts
• include branch context in notification location titles when worktree and branch are both known
• avoid duplicated reason text in notification bodies

Verification

• yarn verify
• yarn build
• pre-push yarn verify hook

Summary by CodeRabbit

• New Features
  • Introduced a new "next step" notification type that alerts users when an agent has completed a processing turn and is ready to continue. The notification integrates with existing notification policies and respects user notification settings for prompt-type alerts. Users can now receive tailored notifications when agent sessions are idle and awaiting further direction.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 15, 2026 5:25am

[coderabbitai]

Warning

Review limit reached

@TraderSamwise, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 1 hour, 47 minutes, and 32 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: df5aadf5-4ea4-41a7-8ee4-46c1191ea691

📥 Commits

Reviewing files that changed from the base of the PR and between 1275466 and b8cb6da.

📒 Files selected for processing (1)

• src/multiplexer/runtime-state.ts

📝 Walkthrough

Walkthrough

Adds "next_step" as a new AlertKind discriminator across both the app and src packages. The agent's idle-after-turn alert emission is switched from "needs_input" to "next_step", and display formatting, notification routing, suppression logic, the metadata server's POST /notify handler, the CLI, and the multiplexer dashboard flash are all updated to handle the new kind.

Changes

next_step Alert Kind

Layer / File(s)	Summary
AlertKind type contracts src/project-events.ts, app/lib/events.ts	AlertKind union extended with "next_step" in both packages.
Agent idle alert emission src/multiplexer/runtime-state.ts, src/multiplexer/runtime-state.test.ts	startStatusRefresh emits kind: "next_step" with "ready for next step" / "Agent stopped after a turn" strings instead of the prior "needs_input" payload; test expectation updated.
Alert display labels and formatting src/alert-display.ts, src/alert-display.test.ts	alertCategoryLabel, alertReasonLabel, and sessionAlertTitle gain "next_step" branches; alertLocationTitle adds branch-aware display; alertMessageBody uses punctuation-normalized comparison. New test asserts full contextualized output.
Notification routing, suppression, and CLI wiring src/notify.ts, app/lib/notification-policy.ts, src/metadata-server.ts, src/main.ts, src/multiplexer/index.ts, src/notify.test.ts, app/lib/notification-policy.test.ts	notifyAlert suppresses "next_step" when onPrompt is off; NEEDS_INPUT_KINDS includes "next_step"; POST /notify maps it with an idle-needs-input dedupe key; CLI and multiplexer dashboard flash updated. Tests cover suppression and policy mapping.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• TraderSamwise/aimux#124: Also extends AlertKind in app/lib/events.ts with a new discriminator ("interaction_request"), the same structural change made here for "next_step".
• TraderSamwise/aimux#84: Modifies the notifyAlert suppression logic in src/notify.ts, the same function extended here to handle "next_step".

Poem

🐇 A new kind has hopped into view,
"next_step" now signals the agent is through.
No longer "needs input" when a turn ends at last,
The rabbit re-labeled the idle contrast.
With branch-aware titles and punctuation trimmed neat,
The next hop is ready — let the workflow complete! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing and aligning a new 'next_step' alert kind in the notification taxonomy across the codebase.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch notification-taxonomy

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/multiplexer/runtime-state.ts (1)

148-156: 💤 Low value

Consider adding a clarifying comment about the dedupeKey prefix.

The dedupeKey uses "idle-needs-input:${session.id}" while the alert kind is now "next_step". This appears intentional for maintaining deduplication during the migration, but a brief comment would help future maintainers understand why the prefix doesn't match the kind.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/multiplexer/runtime-state.ts` around lines 148 - 156, Add a clarifying
comment in the publishAlert call that explains why the dedupeKey prefix
"idle-needs-input" differs from the alert kind "next_step". The comment should
note that this prefix choice is intentional for maintaining deduplication
consistency during the migration and help future maintainers understand that
this mismatch is not a mistake. Place the comment above the dedupeKey line to
make it clear this design choice was deliberate.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/multiplexer/runtime-state.ts`:
- Around line 148-156: Add a clarifying comment in the publishAlert call that
explains why the dedupeKey prefix "idle-needs-input" differs from the alert kind
"next_step". The comment should note that this prefix choice is intentional for
maintaining deduplication consistency during the migration and help future
maintainers understand that this mismatch is not a mistake. Place the comment
above the dedupeKey line to make it clear this design choice was deliberate.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c17cebf7-0b49-44df-adb0-f475bf8e04a0

📥 Commits

Reviewing files that changed from the base of the PR and between 22da79c and 1275466.

📒 Files selected for processing (13)

• app/lib/events.ts
• app/lib/notification-policy.test.ts
• app/lib/notification-policy.ts
• src/alert-display.test.ts
• src/alert-display.ts
• src/main.ts
• src/metadata-server.ts
• src/multiplexer/index.ts
• src/multiplexer/runtime-state.test.ts
• src/multiplexer/runtime-state.ts
• src/notify.test.ts
• src/notify.ts
• src/project-events.ts