Unify project update invalidation events

[TraderSamwise]

Summary

• Add a shared project API invalidation contract that maps API mutation routes to semantic view refreshes.
• Route metadata-server mutation notifications through the shared mapper, including plans, workflow, runtime, lifecycle, notifications, and team changes.
• Wire app plan resources into project_update refresh handling and document the /events compatibility rules.

Verification

• yarn vitest src/project-api-contract.test.ts src/metadata-server.test.ts
• yarn --cwd app test
• yarn typecheck
• yarn --cwd app typecheck
• yarn lint
• yarn --cwd app lint --max-warnings=0
• yarn verify:north-star
• yarn build
• pre-push: yarn verify (163 files / 2326 tests)

Summary by CodeRabbit

• New Features

  • Added support for the Plans view in app refresh and event handling.
  • Improved project updates so affected screens refresh more precisely after edits and other actions.

• Bug Fixes

  • Fixed stale plan data by ensuring plan changes trigger the correct UI refresh.
  • Reduced unnecessary refreshes in unrelated areas when project actions occur.

• Documentation

  • Updated project parity tracking to reflect broader event and refresh coverage.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jul 7, 2026 12:34am

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dc0eb4df-2104-4d9f-bf86-4ab573c96cda

📥 Commits

Reviewing files that changed from the base of the PR and between 6c570b2 and 3212ee7.

📒 Files selected for processing (3)

• src/metadata-server.ts
• src/project-api-contract.test.ts
• src/project-api-contract.ts

📝 Walkthrough

Walkthrough

Adds a "plans" project API view with a shared invalidation-group contract, updates metadata-server mutation handlers to emit route-scoped project_update views/reasons via new helpers, adjusts alert-driven invalidation to use the shared groups, and wires the app's plans registry and screen to the new refresh nonce.

Changes

Project-service events parity (plans view invalidation)

Layer / File(s)	Summary
Invalidation contract and mutation-route mapping src/project-api-contract.ts, src/project-api-contract.test.ts	Adds "plans" to PROJECT_API_VIEWS, defines PROJECT_API_VIEW_INVALIDATIONS groups, and adds/tests projectApiMutationReasonForRoute/projectApiViewsForMutationRoute route-mapping helpers.
Metadata server route-scoped notifications src/metadata-server.ts, src/metadata-server.test.ts	Introduces notifyCurrentRouteChange in handleRoute, replaces hard-coded team/runtime view arrays with invalidation groups, migrates numerous mutation handlers to the route-scoped notifier, and adds SSE tests for plans/thread/runtime mutations.
Alert-driven project_update invalidation src/project-events.ts	Replaces a hardcoded views array in the post-alert publishProjectUpdate call with PROJECT_API_VIEW_INVALIDATIONS.notifications.
App-side plans view registry and screen refresh app/stores/projectViews.ts, app/stores/projectViews.test.ts, app/app/(main)/(tabs)/(dashboard)/plans/[sessionId].tsx	Registers a "plans" entry in the app's view registry/dependencies, tests it, and subscribes PlanEditorScreen to the plans refresh nonce as an effect dependency.
North-star tracker updates docs/north-star-completion-tracker.md	Updates Epic F status to "Mostly done" with revised checklist items and new event payload compatibility rules.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant handleRoute
  participant notifyCurrentRouteChange
  participant projectApiViewsForMutationRoute
  participant notifyProjectChanged

  Client->>handleRoute: HTTP mutation (e.g. PUT /plans/:sessionId)
  handleRoute->>notifyCurrentRouteChange: invoke after mutation succeeds
  notifyCurrentRouteChange->>projectApiViewsForMutationRoute: derive views/reason from method + pathname
  projectApiViewsForMutationRoute-->>notifyCurrentRouteChange: views (e.g. ["plans"]), reason
  notifyCurrentRouteChange->>notifyProjectChanged: publish project_update(views, reason, sessionId)
  notifyProjectChanged-->>Client: SSE project_update event

Loading

Possibly related PRs

• TraderSamwise/aimux#245: Modifies the same project-api-contract* and project-events.ts invalidation views logic that this PR expands.
• TraderSamwise/aimux#328: Introduces the projectApiViewRefreshNonceFamily mechanism this PR extends to the "plans" view.
• TraderSamwise/aimux#337: Modifies the same PlanEditorScreen file and its refresh/fetch lifecycle updated here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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: consolidating project update invalidation handling into a shared system.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/core-sidecar-next-74

---

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

[TraderSamwise]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@src/project-api-contract.ts`:
- Around line 228-341: `projectApiViewsForMutationRoute` is missing
`PROJECT_API_ROUTES.livePane.interrupt` from the `agentLifecycle` invalidation
set, so live-pane interrupts only hit the default merge and don’t refresh the
right views. Update the `switch` in `projectApiViewsForMutationRoute` to include
`PROJECT_API_ROUTES.livePane.interrupt` alongside the other agent lifecycle
routes and return `PROJECT_API_VIEW_INVALIDATIONS.agentLifecycle` for it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 97ed277c-d270-4789-90a8-379049cc8b25

📥 Commits

Reviewing files that changed from the base of the PR and between 47acd66 and 6c570b2.

📒 Files selected for processing (9)

• app/app/(main)/(tabs)/(dashboard)/plans/[sessionId].tsx
• app/stores/projectViews.test.ts
• app/stores/projectViews.ts
• docs/north-star-completion-tracker.md
• src/metadata-server.test.ts
• src/metadata-server.ts
• src/project-api-contract.test.ts
• src/project-api-contract.ts
• src/project-events.ts

[vercel]

Deployment failed with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/sams-projects-de5e5436?upgradeToPro=build-rate-limit